Methods

Every game → platform call, its arguments, return value, and capability requirements.

These are the calls your game makes on the SDK. They come in two shapes:

• Signals — fire-and-forget. Return Promise<void> that resolves immediately; the platform’s ack is not awaited. Validation errors surface as Promise rejections, so if you neither await nor .catch() them they become unhandled rejections. Examples: gameReady, gameStart, gameOver, updateScore, gameSaveState, updateMissionProgress, requestPause, logEvent.
• Data-returning — return a Promise<T> that resolves with the platform’s reply. Can hit BRIDGE_TIMEOUT (default 30 s) or BRIDGE_ERROR. Always await them. Examples: init, purchaseItemWithGems, loadRewardedVideo, showRewardedVideo.

Gated methods (those that require a capability) throw CAPABILITY_MISSING synchronously before anything reaches the wire if the capability wasn’t declared at init() time. See Capabilities for the full matrix and Error handling for GameeError codes.

For events the platform pushes to your game (pause, resume, start, …), see Events.

init#

Declares the capability set the game needs and resolves with the platform’s GameInitResponse (locale, country, save state, deep-link data, mission config). Must be called once per SDK instance; a second call throws INVALID_STATE.

const initData = await gamee.init({
  capabilities: ['saveState', 'rewardedAds'],
});

console.log(initData.locale, initData.country);
if (initData.saveState) restoreFrom(JSON.parse(initData.saveState));
if (initData.initData) handleDeepLink(JSON.parse(initData.initData));

Returns Promise<GameInitResponse>. The SDK checks that the platform returned a real object with all required fields — anything missing surfaces as BRIDGE_ERROR.

GameInitResponse#

This is the init data every game receives — the platform’s response to init(). Read it once from the resolved init promise; it’s also available afterwards as gamee.initResponse.

MissionData#

Both saveState and initData come over the wire as strings. The platform hands them back exactly as the game (or the deep-link origin) supplied them. The SDK does not parse them.

gameReady#

Tells the platform the first frame is rendered and the game is interactive. After this resolves the platform may immediately dispatch start / pause etc., so subscribe via gamee.on(...) before calling this.

gamee.on('start', beginRun);
gamee.gameReady();

No arguments. Signal — returns Promise<void> that resolves immediately.

gameStart#

Signals that a new run is starting (often paired with the platform’s start event, called after the game has set up its run state).

gamee.gameStart();

No arguments. Signal.

gameOver#

Ends the current run. Send any state you want preserved for the next session in saveStateData; the SDK stringifies non-string values for you.

gamee.gameOver({
  saveStateData: { highScore: score, unlockedLevels: 3 },
  rewardIds: ['legendary-chest-12345'],
  metadata: { runDurationMs: 42_318, deathCause: 'spike' },
});

Signal. Calling with no arg (gamee.gameOver()) sends an empty payload.

gameSaveState#

Persist arbitrary state outside of a gameOver. Use this for checkpoints, mid-run autosaves, or settings the player changed in-game.

await gamee.gameSaveState({ level: 3, coins: 420 });

Capability: saveState. Calling without it throws CAPABILITY_MISSING.

Signal. The wire method is saveState (not gameSaveState) — relevant only if you’re inspecting the bridge traffic.

updateScore#

Push the player’s current score to the platform. Designed to be called frequently (per checkpoint or even per frame); the SDK doesn’t throttle.

Pass a number for the score-only shorthand, or an options object when you also want to send playTime, checksum, or metadata. Fields you don’t pass are omitted from the wire payload entirely.

// Score only (shorthand)
gamee.updateScore(100);

// Or with the full options object
gamee.updateScore({
  score,
  playTime: (performance.now() - startedAt) / 1000,
  checksum: 'mychecksum',
  metadata: { combo: 3 },
});

Argument: number | UpdateScoreOptions. Passing a number is sugar for { score: <number> }.

UpdateScoreOptions:

Signal. Validation failures reject the returned promise with VALIDATION.

updateMissionProgress#

Report progress on the current mission (gameContext === 'mission'). The platform uses this for progress UI; you still need to call gameOver when the run actually ends.

gamee.updateMissionProgress(42); // 42%

Capability: missions.

Signal.

requestPause#

The game is asking the platform to enter the paused state (e.g. the player opened an in-game menu). The platform will typically reply by dispatching the pause event — handle the pause logic in that event handler.

gamee.requestPause();

No arguments. Signal.

Don’t confuse this with the pause event, which is the platform telling your game to pause (incoming call, app backgrounded, …).

logEvent#

Custom analytics ping. The platform forwards these into its analytics pipeline.

Pass a string for the name-only shorthand, or an options object when you also want to send a value. If you omit value, the wire payload only carries the event name.

// Name only (shorthand)
gamee.logEvent('boss_defeated');

// Or with the full options object
gamee.logEvent({ name: 'boss_defeated', value: 'level_3' });

Argument: string | LogEventOptions. Passing a string is sugar for { name: <string> }.

LogEventOptions:

Capability: logEvents.

Signal. Both length caps are enforced locally and reject with VALIDATION.

purchaseItemWithGems#

Spend the player’s in-game gem currency on an item. Data-returning — await it.

const result = await gamee.purchaseItemWithGems({
  gemsCost: 50,
  itemName: 'extra_life',
});

if (result.success) grantExtraLife();

Argument (PurchaseDetails):

Returns Promise<PurchaseResult>:

Capability: gems. Can reject with BRIDGE_TIMEOUT or BRIDGE_ERROR.

loadRewardedVideo#

Prefetch a rewarded video ad. Call this when you anticipate showing one soon (e.g. right after a death) so the ad is ready when the player taps “watch”.

const { videoLoaded } = await gamee.loadRewardedVideo();
if (videoLoaded) ui.showWatchAdButton();

No arguments. Returns Promise<RewardedLoadResult>:

Capability: rewardedAds. Can reject with BRIDGE_TIMEOUT / BRIDGE_ERROR.

showRewardedVideo#

Show the prefetched rewarded video. Resolves once the player either watched the ad through to the end (videoPlayed: true) or skipped/closed it (videoPlayed: false).

const { videoPlayed } = await gamee.showRewardedVideo();
if (videoPlayed) grantReward();

No arguments. Returns Promise<RewardedResult>:

Capability: rewardedAds. Can reject with BRIDGE_TIMEOUT / BRIDGE_ERROR.

At a glance#