AI-agent context

A drop-in briefing your AI assistant can read to use @gamee/sdk correctly on the first try.

TL;DR#

@gamee/sdk is a typed, promise-based JavaScript bridge between an HTML5 game and the GAMEE platform (web iframe, iOS WKWebView, Android WebView). The wire protocol is identical across all three hosts; the SDK picks the right transport at boot. Games declare capabilities at init() time; gated methods reject synchronously if the capability is missing.

import { gamee } from '@gamee/sdk';

await gamee.init({ capabilities: ['saveState', 'rewardedAds'] });
gamee.gameReady();
gamee.on('start', () => game.run());
gamee.on('pause', () => game.pause());

Glossary#

Imports#

// Default singleton — what most games use:
import { gamee } from '@gamee/sdk';

// Fresh instance — for tests or multi-game setups:
import { createSdk } from '@gamee/sdk';
const sdk = createSdk({ allowedOrigins: ['https://games.gameeapp.com'] });

// Errors:
import { GameeError } from '@gamee/sdk';

// Types you'll commonly need:
import type {
  Capability,
  Platform,
  Environment,
  GameContext,
  InitOptions,
  GameInitResponse,
  MissionData,
  GameOverData,
  PurchaseDetails,
  PurchaseResult,
  RewardedLoadResult,
  RewardedResult,
  GameeEvents,
  GameeEventName,
  GameeErrorCode,
  PlatformBridge,
  BridgeListener,
  SdkOptions,
} from '@gamee/sdk';

IIFE script-tag: <script src="…/gamee-sdk.iife.js"></script> — exposes window.Gamee with Gamee.gamee, Gamee.createSdk, Gamee.GameeError.

Public API — every method#

Returns Promise<T> unless noted. Cap = capability required at init.

Lifecycle#

Save state#

Score & missions#

Commerce#

Rewarded ads#

Analytics#

Introspection#

Events#

gamee.on(event, handler) // returns an unsubscribe function
gamee.off(event, handler?) // drop one handler, or all if no fn passed

Listeners that throw are caught and logged; one bad handler can’t starve the others. Subscribe before calling gameReady() or you may miss the first start.

Capabilities#

type Capability = 'saveState' | 'rewardedAds' | 'logEvents' | 'missions' | 'gems';

Calling a gated method without its capability throws CAPABILITY_MISSING synchronously, before anything reaches the wire. The error is a GameeError with .code, .method, .message.

Removed (relative to legacy gamee-js): replay, ghostMode, socialData, playerData, platformExtraLife (useExtraLife event still exists, just ungated).

GameInitResponse#

{
  environment: 'production' | 'development';
  platform: 'web' | 'mobile_web' | 'ios' | 'android';
  country: string;       // ISO 3166-1 alpha-2 ('US', 'CZ', …)
  locale: string;        // BCP-47 ('en-US', 'cs-CZ', …)
  gameContext: 'normal' | 'battle' | 'mission';
  sound: boolean;
  noAds?: boolean;
  saveState?: string;     // previously saved state (stringified JSON the game wrote)
  initData?: string;      // deep-link payload (stringified JSON)
  missionData?: MissionData; // present when gameContext === 'mission'
}

The SDK validates that environment, platform, country, locale, gameContext, sound are present. Missing fields cause the init Promise to reject with BRIDGE_ERROR.

Errors#

Every failure mode is a GameeError with one of seven code values:

GameeError has .name === 'GameeError', .code, .method?, .message, .cause?. Branch on .code, never on .message.

try {
  await gamee.gameSaveState({ level: 3 });
} catch (err) {
  if (err instanceof GameeError && err.code === 'CAPABILITY_MISSING') {
    // declare 'saveState' in init()
  }
}

Behavior gotchas#

• Signal methods (gameReady, gameStart, gameOver, gameSaveState, updateScore, updateMissionProgress, requestPause, logEvent) return Promise<void> but resolve immediately — they don’t wait for the platform’s ack. Validation errors surface as Promise rejections. If you don’t await or .catch(), they become unhandled-rejection events.
• Data-returning methods (purchaseItemWithGems, loadRewardedVideo, showRewardedVideo) DO wait for the platform’s reply and can hit BRIDGE_TIMEOUT / BRIDGE_ERROR.
• init() is single-shot. Second call → INVALID_STATE. Use createSdk() for a fresh instance in tests.
• Subscribe before gameReady() or you’ll miss the first start event.
• saveState is a string on the wire. The SDK auto-stringifies objects. The platform sends it back via initResponse.saveState exactly as it was saved.
• updateScore truncates non-integer scores to Math.trunc(score).
• messageId is wire-internal — games never see it.

SDK options (createSdk(opts))#

interface SdkOptions {
  allowedOrigins?: readonly string[] | '*'; // postMessage origin allowlist for the web bridge. Default: '*' with first-use warning.
  requestTimeoutMs?: number; // default 30_000
  maxPendingRequests?: number; // default 256 (data-returning calls only)
  silentMode?: boolean; // suppress runtime warnings
  bridge?: PlatformBridge; // inject a custom bridge (used by emulator + MockBridge)
}

Wire format#

One envelope shape, both directions:

// Game → Platform request
{ "request":  { "method": "init", "messageId": 0, "data": { "version": "1.0.0", "capabilities": { "saveState": true } } } }

// Platform → Game response (data) — replies to a request
{ "response": { "messageId": 0, "data": { /* … */ } } }

// Platform → Game response (error)
{ "response": { "messageId": 0, "error": { "code": "…", "message": "…" } } }

// Platform → Game event (looks like a request; SDK auto-acks)
{ "request": { "method": "pause", "messageId": 7, "data": null } }

messageId is a non-negative integer (number) that increments by 1 per outbound message within a single SDK instance (starts at 0). Wire-compatible with legacy gamee-js clients. It correlates request ↔ response. init’s wire data.capabilities is an object map ({ saveState: true }), not an array — game-facing API uses arrays for ergonomics, the SDK transforms.

@gamee/sdk-test-utils#

Sister package shipping MockBridge for game test suites. Inject it instead of the real bridge.

import { describe, expect, test, beforeEach } from 'vitest';
import { createSdk, type GameeSDK } from '@gamee/sdk';
import { MockBridge } from '@gamee/sdk-test-utils';

let mock: MockBridge;
let sdk: GameeSDK;

beforeEach(() => {
  mock = new MockBridge();
  sdk = createSdk({ bridge: mock });
});

test('updateScore reaches the wire with the right shape', async () => {
  await sdk.init({ capabilities: [] });
  sdk.updateScore({ score: 420, playTime: 12, checksum: 'sum' });
  expect(mock.requests.find((r) => r.method === 'updateScore')?.data).toMatchObject({
    score: 420,
    currentPlayTime: 12,
    gameChecksum: 'sum',
  });
});

MockBridge API#

Common test recipes#

// 1. Platform replies with success.
mock.expect('showRewardedVideo').respondWith({ videoPlayed: true });
const r = await sdk.showRewardedVideo();
expect(r.videoPlayed).toBe(true);

// 2. Platform rejects.
mock.expect('purchaseItemWithGems').rejectWith({ code: 'BRIDGE_ERROR', message: 'insufficient gems' });
await expect(sdk.purchaseItemWithGems({ gemsCost: 99, itemName: 'X' })).rejects.toThrow('insufficient gems');

// 3. Capability gate is sync.
expect(() => sdk.gameSaveState({ x: 1 })).toThrow(/CAPABILITY_MISSING|saveState/);

// 4. Drive a platform-initiated event.
let paused = false;
sdk.on('pause', () => {
  paused = true;
});
mock.emit('pause');
expect(paused).toBe(true);

// 5. Force a timeout.
sdk = createSdk({ bridge: mock, requestTimeoutMs: 50 });
await sdk.init({ capabilities: ['rewardedAds'] });
mock.expect('showRewardedVideo').leavePending();
await expect(sdk.showRewardedVideo()).rejects.toMatchObject({ code: 'BRIDGE_TIMEOUT' });

Quick reference for code generation#

When generating game code that uses this SDK, default to:

1. await gamee.init({ capabilities: [...] }) — list every capability the game’s logic touches; otherwise gated calls throw.
2. gamee.on(event, handler) before gamee.gameReady().
3. Synchronous-feeling fire-and-forget for telemetry: gamee.updateScore(...), gamee.logEvent(...) — no need to await.
4. await for data-returning calls: loadRewardedVideo, showRewardedVideo, purchaseItemWithGems.
5. Error handling: try { await … } catch (err) { if (err instanceof GameeError) … } with err.code branching.
6. Tests: inject MockBridge via createSdk({ bridge: mock }). Never use the singleton in tests.