One of 3 main API entry points. This one provides you with the most of the BeetPx capabilities, except drawing.

BeetPx.setOnUpdate(() => {
BeetPx.logInfo(BeetPx.isAnyButtonPressed());
});

Game loop

  • get frameNumber(): number
  • Number of frames processed since game started. It gets reset to 0 when BeetPx.restart is called. It counts update calls, not draw calls.

    Usually you would use e.g. $timer instead of this low-level API.

    Returns number

  • get frameNumberOutsidePause(): number
  • Number of frames processed since game started, excluding the frames which happened during an active game pause. It gets reset to 0 when BeetPx.restart is called. It counts update calls, not draw calls.

    Usually you would use e.g. $timer instead of this low-level API.

    Returns number

  • get renderingFps(): number
  • The effective FPS (frames per second) of render calls. This does not count the update calls.

    This value is used (with some averaging, to avoid quickly changing number) in the FPS display, which is active in debug mode if BpxEngineConfig's debugMode.fpsDisplay.enabled is set to true.

    Returns number

  • Restarts the entire game.

    It is important to properly set the game initialization logic through the BeetPx.setOnStarted, so the $x.restart() will result with a properly restarted game.

    An example usage would be to implement a game pause menu, with the "restart the game" as one of available options.

    Returns void

  • The method to set a draw callback which is called every time the browser has a chance to repaint the canvas (requestAnimationFrame is used under the hood).

    The draw callback is one of 2 recommended places to use BeetPxDraw methods within (the other one is the on-started callback set by BeetPx.setOnStarted).

    Parameters

    • OptionalonDraw: (() => void)
        • (): void
        • Returns void

    Returns void

    $x.setOnStarted(() => {
    // ...
    });

    $x.setOnUpdate(() => {
    // ...
    });

    $x.setOnDraw(() => {
    $d.clearCanvas($rgb_blue);
    $d.pixel($v(10,20), $rgb_red);
    });

    $x.start({
    // ...
    });

    BpxEngineConfig.fixedTimestep

  • The method to set an on-started callback which is called every time the game is (re-)started.

    While the game starts only once, it can be restarted many time with use of BeetPx.restart. In such case, the callback is useful for clearing up the game state, so nothing from the previous gameplay remains.

    The timers, animations, and music restart on their own, there is no manual action needed.

    The on-started callback is one of 2 recommended places to use BeetPxDraw methods within (the other one is the draw callback set by BeetPx.setOnDraw).

    Parameters

    • OptionalonStarted: (() => void)
        • (): void
        • Returns void

    Returns void

    const inputManager = MySpecialInputManager();
    let gameLogic: MyComplexGameLogic;

    $x.setOnStarted(() => {
    gameLogic = new MyComplexGameLogic();
    inputManager.reset();
    });

    $x.setOnUpdate(() => {
    // ...
    });

    $x.setOnDraw(() => {
    // ...
    });

    $x.start({
    // ...
    });
  • The method to set an update callback which is called on every iteration of the game loop, on a fixed timestep.

    Parameters

    • OptionalonUpdate: (() => void)
        • (): void
        • Returns void

    Returns void

    const speed = 6;
    let player;

    $x.setOnStarted(() => {
    // ...
    });

    $x.setOnUpdate(() => {
    player.setPosition(
    player.position.mul($x.getPressedDirection()).mul(speed)
    );
    });

    $x.setOnDraw(() => {
    // ...
    });

    $x.start({
    // ...
    });

    BpxEngineConfig.fixedTimestep

Graphics

Audio

  • Gives access to the main global AudioContext.

    Typically, you wouldn't have to access to method on your own. But it might prove useful to have it in some unexpected scenario.

    Returns AudioContext

  • Mutes a given playback, denoted by its BpxAudioPlaybackId.

    Parameters

    • playbackId: number
    • Optionalopts: {
          fadeOutMillis?: number;
      }
      • OptionalfadeOutMillis?: number

    Returns void

  • Start to play a given sound, once.

    Parameters

    • soundUrl: string
    • Optionalopts: {
          muteOnStart?: boolean;
          onGamePause?: "pause" | "mute" | "ignore";
      }
      • OptionalmuteOnStart?: boolean
      • OptionalonGamePause?: "pause" | "mute" | "ignore"

    Returns number

    • A BpxAudioPlaybackId of the started playback. Can be later used to e.g. mute this playback.
  • Start to play a given sound, looped.

    Parameters

    • soundUrl: string
    • Optionalopts: {
          muteOnStart?: boolean;
          onGamePause?: "pause" | "mute" | "ignore";
      }
      • OptionalmuteOnStart?: boolean
      • OptionalonGamePause?: "pause" | "mute" | "ignore"

    Returns number

    • A BpxAudioPlaybackId of the started playback. Can be later used to e.g. mute this playback.
  • Start to play a given sound, defined by a sequence of audio samples.

    Parameters

    • soundSequence: BpxSoundSequence
    • Optionalopts: {
          muteOnStart?: boolean;
          onGamePause?: "pause" | "mute" | "ignore";
      }
      • OptionalmuteOnStart?: boolean
      • OptionalonGamePause?: "pause" | "mute" | "ignore"

    Returns number

    • A BpxAudioPlaybackId of the started playback. Can be later used to e.g. mute this playback.
  • Completely stops a given playback, denoted by its BpxAudioPlaybackId.

    Parameters

    • playbackId: number
    • Optionalopts: {
          fadeOutMillis?: number;
      }
      • OptionalfadeOutMillis?: number

    Returns void

  • Un-mutes a given playback, denoted by its BpxAudioPlaybackId.

    Parameters

    • playbackId: number
    • Optionalopts: {
          fadeInMillis?: number;
      }
      • OptionalfadeInMillis?: number

    Returns void

Assets

  • Retrieves a previously fetched image.

    Usually, you wouldn't need to directly call this method, as the image retrieval happens under the hood for operations like sprite drawing.

    Parameters

    • imageUrl: string

    Returns BpxImageAsset

    BpxEngineConfig'a assets

  • Retrieves a previously fetched JSON.

    Right now there is no API which would make use of the fetched JSON under the hood.

    Example use case for this method is when you develop your game level in LDtk and want to read the level's file in the game code.

    Parameters

    • jsonUrl: string

    Returns BpxJsonAsset

    BpxEngineConfig'a assets

  • Retrieves a previously fetched sound.

    Usually, you wouldn't need to directly call this method, as the sound retrieval happens under the hood for operations like music playing.

    Parameters

    • soundUrl: string

    Returns BpxSoundAsset

    BpxEngineConfig'a assets

Game input

  • Returns a 2D vector where:

    • X=-1 means the up is pressed,
    • X=0 means neither up nor down is pressed or both are pressed at the same time,
    • X=1 means the down is pressed,
    • Y=-1 means the left is pressed,
    • Y=0 means neither left nor right is pressed or both are pressed at the same time,
    • Y=1 means the right is pressed.

    Returns BpxVector2d

    this.position += $x.getPressedDirection().mul(this.speed);
    
  • Tells what input methods were used in the last game loop iteration.

    Might be used to render in-game indications what button to press, with their sprites chosen based on which input method was recently used.

    Returns Set<BpxGameInputMethod>

  • Tells whether any of the game buttons is pressed right now.

    Returns boolean

    For a list of available game buttons check BpxGameButtonName

  • Tells whether a current device has touch capabilities.

    Returns boolean

  • Allows to enable repeating for a given button. Repeating means if the user presses the button for a longer timer, the "just pressed" state is detected first after firstRepeatFrames frames, then repetitively after loopedRepeatFrames frames.

    Parameters

    • button: BpxGameButtonName
    • repeating: {
          firstRepeatFrames: null | number;
          loopedRepeatFrames: null | number;
      }
      • firstRepeatFrames: null | number
      • loopedRepeatFrames: null | number

    Returns void

  • Tells whether any of the game buttons changed from released to pressed in the recent game loop iteration.

    Returns boolean

    For a list of available game buttons check BpxGameButtonName

  • Tells whether a given game button changed from released to pressed in the recent game loop iteration.

    Parameters

    Returns boolean

  • Tells whether a given game button changed from pressed to released in the recent game loop iteration.

    Parameters

    Returns boolean

Game pause

Storage

  • Allows to completely remove the previously persisted data.

    Returns void

Full screen

  • Tells whether it is possible to enter full screen on the current device and browser.

    It might be used e.g. for implementing a pause menu action to toggle full screen.

    Returns boolean

  • Tells whether the game is currently in a full screen mode.

    It might be used e.g. for implementing a pause menu action to toggle full screen.

    Returns boolean

  • Requests the game to either enter or exit the full screen mode.

    It might be used e.g. for implementing a pause menu action to toggle full screen.

    Returns void

Logging

  • Prints to the console on the error level, with use of console.error.

    You can implement BpxPrintDebug on a given object if you want it to be printed out in a custom way.

    Parameters

    • Rest...args: unknown[]

    Returns void

  • Prints to the console on the info level, with use of console.info.

    You can implement BpxPrintDebug on a given object if you want it to be printed out in a custom way.

    Parameters

    • Rest...args: unknown[]

    Returns void

  • Prints to the console on the warn level, with use of console.warn.

    You can implement BpxPrintDebug on a given object if you want it to be printed out in a custom way.

    Parameters

    • Rest...args: unknown[]

    Returns void

Debug

  • get debug(): boolean
  • Let's you know whether the debug mode is on or off. To be used in combination with:

    • BpxEngineConfig's debugMode.available set to true
    • ; key used to toggle the debug mode on/off

    Returns boolean