Skip to main content

App lifecycle

JestSDK.lifecycle reports when the game document is hidden or shown and when the player asks to leave through Jest's platform controls.

Connect to these signals after SDK initialization. Each signal supports multiple connections; disconnect during teardown:

func _ready():
    await JestSDK.init_sdk()

    JestSDK.lifecycle.hidden.connect(_on_hidden)
    JestSDK.lifecycle.shown.connect(_on_shown)
    JestSDK.lifecycle.exit_requested.connect(_on_exit_requested)


func _on_hidden():
    game.pause()
    audio.pause()


func _on_shown():
    game.resume()
    audio.resume()


func _on_exit_requested():
    save_progress()


func _exit_tree():
    JestSDK.lifecycle.hidden.disconnect(_on_hidden)
    JestSDK.lifecycle.shown.disconnect(_on_shown)
    JestSDK.lifecycle.exit_requested.disconnect(_on_exit_requested)

Keep connections active for the game lifetime, then disconnect during teardown.

JestSDK.lifecycle.hidden​

Emitted when the browser changes the game document from visible to hidden, such as when the player switches tabs, backgrounds the browser, or locks the device. It is not emitted for the document's initial visibility state.

Use it to pause the game loop, physics, animation, and audio.

hidden and shown are the SDK's surface for the browser document's visibilitychange event, and Jest adds nothing to when they fire. A game that also observes browser visibility another way sees every transition twice, so pick one source.

JestSDK.lifecycle.shown​

Emitted when the game document changes from hidden back to visible. It is not emitted on initial startup; await JestSDK.init_sdk() is the startup boundary.

Use it to resume work stopped by hidden, refresh time-sensitive state, and reconcile elapsed time.

JestSDK.lifecycle.exit_requested​

Emitted when the platform begins an exit flow, including its exit control and browser Back or mobile swipe-back navigation that Jest can intercept. It is emitted at the start of that flow — usually as the exit confirmation appears — and always before the player has answered it.

The player can still choose to stay, so this is an opportunity to save and not a shutdown notice. Do not tear down state, free resources, or stop the game loop from the connected function; the session frequently continues. It is also emitted more than once in a session whenever a player asks to leave, backs out, and asks again, so keep connected functions idempotent and expect to save again later.

Connected functions cannot cancel the exit or hold the game open past the player's confirmation. What they do get is the interval between the request and that confirmation, which is ordinary runtime rather than a teardown window. Start the save when the signal is emitted.

This signal only represents an exit flow the platform can intercept. Closing the tab, terminating the browser, or an operating-system shutdown may not produce a final signal. Back navigation that leaves the Jest document directly, such as returning to an external referral page, may not produce one either. A few in-platform flows also navigate without a confirmation, in which case the signal is emitted with no interval behind it.

Ordering​

The signals are independent, not steps in a teardown sequence. Visibility comes from the browser and the exit request comes from the platform, so there is no guaranteed ordering between them and no pair is mutually exclusive. A platform exit emits exit_requested with no visibility change; backgrounding the browser emits hidden with no exit request; locking the device while the exit confirmation is open emits both, in whichever order the browser reports. A signal that is not emitted is not evidence that the other one failed.

Saving on exit​

Treat this signal as the last of several saves rather than the only one. player.set_value sends the update to the Jest page, which performs the storage write. That page outlives the game document, so an update already on its way is not lost when the game is torn down. An update is not sent immediately while an earlier one is still unacknowledged — it goes out with the next message — so a set_value issued at the very end of the exit interval can still go down with the document. Persist progress as the player earns it, and use this signal to capture whatever has changed since the last save.