Skip to main content

Lifecycle Events

The Lifecycle module offers a comprehensive suite of events that developers can utilize to manage game flow, from initialization to conclusion. These events are instrumental in creating a seamless and interactive gaming experience.

For a detailed exploration of the API, visit the game lifecycle documentation.

Engaging with the game lifecycle involves handling events such as:

  • The game becoming ready to play;

  • The start of the game;

  • Score changes and updates;

  • The start of a level;

  • The end of a level;

  • The end of the game session.

Supported Events​

Arkadium's Game SDK supports a variety of lifecycle events, each serving a distinct purpose in the game's lifecycle:

onTestReady - Indicates the game is loaded and ready for interaction.

important

Always make sure to call the onTestReady() event once the game is ready to be shown to the user. Failing to do so will prevent the Game Loading overlay from being removed on the Arena, and the user will not be able to interact with the game.

onGameStart - Marks the beginning of gameplay.

onChangeScore - Triggers before the game concludes to update scores.

onLevelStart - Sent when a level starts.

onLevelEnd - Sent when a level ends.

onGameEnd - Signifies the end of the game session.

caution

Properly handling these events is crucial for a fluid game experience and for maintaining game state integrity.

Events Overview​

Game Ready (onTestReady)​

This event signals that the game has loaded what's needed for the player to start playing the game and ready for the first user interaction.

await sdk.lifecycle.onTestReady();

Game Start (onGameStart)​

The onGameStart event marks the beginning of the player's active gameplay session. This event is triggered in one of two scenarios:

  • When the player clicks a Play button to start the game
  • When the player makes their first in-game move (in cases where the game automatically redirects the player to gameplay without requiring a Play button click)
caution

Important: Only one onGameStart event should be sent per game load. If a player returns to the title screen and starts a new game, do not trigger another onGameStart event.

await sdk.lifecycle.onGameStart();

Score Change (onChangeScore)​

It should be sent when the user achieves a new score. This score will be used to show the user in a leaderboard, in the cases where that functionality is supported on the Platform side. The argument represents the score with type number.

await sdk.lifecycle.onChangeScore(1234);

Level Start (onLevelStart)​

Should be sent when a level starts.

// start of level 1
await sdk.lifecycle.onLevelStart(1);

Level End (onLevelEnd)​

Should be sent when a level ends.

// end of level 1
await sdk.lifecycle.onLevelEnd(1);

Game End (onGameEnd)​

Marks the completion of the game session, meaning this is sent when the user will no longer play the game.

caution

Similar to the onGameStart event, there should only be one onGameEnd event per game load.

await sdk.lifecycle.onGameEnd();

Registering Event Callback​

In some flows, the Arena might need to control the game flow by pausing and resuming the game. The game will need to implement it's own pause/resume logic and register it as an event callback. There are 2 events to which the game will need to register callbacks: GAME_PAUSE and GAME_RESUME. Below there are examples on how to register these callbacks.

sdk.lifecycle.registerEventCallback(sdk.lifecycle.LifecycleEvent.GAME_PAUSE, () => {
    // logic to PAUSE game goes here
});
sdk.lifecycle.registerEventCallback(sdk.lifecycle.LifecycleEvent.GAME_RESUME, () => {
    // logic to RESUME game goes here
});

Conclusion​

Leveraging the Game Lifecycle events effectively ensures that players enjoy a coherent and engaging gaming experience, from start to finish. These events allow for precise control over the game flow, enhancing interactivity and player satisfaction.