Events

Every platform → game event, payload, and what your game has to do.

The platform pushes events to your game over the same bridge it uses for RPC. You subscribe with gamee.on(name, handler), which returns an unsubscribe function:

const off = gamee.on('pause', () => game.pause());
// later, e.g. on game-over screen:
off();

You can also remove handlers explicitly:

gamee.off('pause'); // drop ALL pause handlers
gamee.off('pause', myHandler); // drop a specific handler

Listeners that throw are caught and logged; they don’t break the dispatch loop, and one bad handler can’t starve the others.

Subscribe before you call gameReady(). The platform won’t fire start, pause, etc. until after init() resolves — but the moment you call gameReady() it may dispatch immediately.

start#

The platform signals that a new run can begin. May fire more than once per session (first run, restart, replay).

gamee.on('start', ({ gameSeed, resetState }) => {
  if (resetState) clearLocalProgress();
  beginRun(gameSeed); // gameSeed is a string when the platform sends one
});

pause#

The platform wants the game suspended (incoming call, app went to background, user tapped pause overlay). Stop the game loop and silence audio. Do not assume requestAnimationFrame will keep firing — on iOS/Android it may not.

gamee.on('pause', () => {
  running = false;
  audio.silence();
});

Payload: undefined.

resume#

The platform says it’s safe to continue. Restart your loop and unmute audio if it was paused (not muted) before.

gamee.on('resume', () => {
  running = true;
  audio.unsilence();
  requestAnimationFrame(loop);
});

Payload: undefined.

mute / unmute#

The user toggled audio in the platform UI. Only audio — the game loop keeps running.

gamee.on('mute', () => audio.mute());
gamee.on('unmute', () => audio.unmute());

Payloads: undefined.

Distinction from pause: pause stops everything (logic + audio), mute only silences audio.

useExtraLife#

The platform granted an extra life — usually after the player watched a rewarded ad or paid with gems. Resume from where the player ended (or the last save point) instead of starting a fresh run.

gamee.on('useExtraLife', () => {
  player.respawnAtLastCheckpoint();
});

Payload: undefined.

submit#

The platform requests an immediate score finalization (e.g. timed round expired). Finalize the current score and call gamee.gameOver(...).

gamee.on('submit', () => {
  gamee.updateScore({ score, playTime, checksum });
  gamee.gameOver({ saveStateData: snapshot() });
});

Payload: undefined.

avatarAnimation#

The platform wants the in-game avatar to play an animation (e.g. dance, wave, celebrate). Game decides how to render.

gamee.on('avatarAnimation', ({ animationType }) => {
  avatar.play(animationType);
});

avatarUpdate#

The platform pushes a new avatar (URL, blob, or whatever the platform chose to send). Refresh your in-game UI.

gamee.on('avatarUpdate', ({ avatar }) => {
  ui.setAvatar(avatar);
});

miningEventUpdate#

Used by mining-themed promo events. The platform sends a snapshot of the current mining config; the game applies any visual upgrades.

gamee.on('miningEventUpdate', ({ miningEvent }) => {
  rig.applyConfig(miningEvent);
});

At a glance#