Get it · v3.1.0 Download SDK Try it Open emulator

Changelog

Notable changes between SDK versions.

Versions follow semver. Format borrows from Keep a Changelog. The currently shipping version is shown in the Get it button on every page of these docs and is always whatever packages/sdk/package.json reports at build time.

When something in here surprises you mid-upgrade, check Migrating from gamee-js — most breaking changes from the legacy SDK are documented there in detail.

Unreleased#

Nothing yet.

v3.1.0 — 2026-09-17#

Note. The 3.1.0 build was refreshed on 2026-09-24 to add the showRewardedVideo place option below. A 3.1.0 zip downloaded before that date does not have it — re-download from Install.

Added#

  • showRewardedVideo takes an optional place. Label where in the game the ad was triggered from — gamee.showRewardedVideo({ place: 'savelife' }) or the shorthand gamee.showRewardedVideo('savelife'). The platform records the label with the ad so ad performance can be compared per place; it never changes which ad is shown. Names are yours to choose: 1–20 characters of a–z, A–Z, 0–9, -, anything else rejects with VALIDATION. Omitted / null keeps sending data: null, so existing games and platform builds are unaffected. New exported type ShowRewardedVideoOptions. See Methods → showRewardedVideo.

Fixed#

  • iPad and Mac in the GAMEE iOS app no longer hang on BRIDGE_TIMEOUT. iPadOS WKWebView reports a desktop Macintosh user agent (iPadOS 13+), and so does the iOS app running on Apple Silicon Macs. 3.0.0 detected the platform from the user agent first, mistook both for web, picked the postMessage bridge, and init() timed out after 30 s. Rebuild the game against 3.1.0 — the iOS app itself is unchanged. See Troubleshooting.

Changed#

  • Platform detection checks the native bridge handle before the user agent. createBridge() resolves ios whenever window.webkit.messageHandlers.callbackHandler is installed and android whenever window._toDevice is, regardless of the user agent. The 3.0.0 user-agent rules remain as a fallback for browser embeds. See Architecture → Platform detection.
  • Android detection no longer depends on the gamee/X.Y.Z user-agent suffix. The Android app may send a stock WebView user agent to games on 3.1.0 or newer. Never sniff the UA for gamee — read sdk.platform after init() instead.
  • Versioned downloads. Every release is served as gamee-sdk-<version>.zip next to the latest gamee-sdk.zip, and the zip unpacks into a gamee-sdk/ folder that carries a package.json with its version. See Install → Which version do I have?.

v3.0.0 — 2026-05-13#

The first stable release of the rewritten SDK. Wire-compatible with the legacy gamee-js platforms (iOS, Android, web), but the JavaScript surface is breaking — there is no compatibility shim.

Note. 3.0.0 was rebuilt several times under the same version number before versioned downloads existed. The final 3.0.0 build (2026-09-15) contains everything below, including the Later 3.0.0 builds items. If your copy predates that, purchaseItemWithGems may still use the old { success } reply and userId may be missing — upgrade to 3.1.0.

Later 3.0.0 builds#

Added#

  • GameInitResponse.userId — optional numeric GAMEE user id of the player, passed through from the platform’s init reply. The emulator’s Init tab has a matching field (empty by default, which omits it). See Methods → GameInitResponse.

Fixed#

  • purchaseItemWithGems matches the platform’s purchase contract. 3.0.0 typed the reply as { success } and sent only gemsCost / itemName. The platform replies with { purchaseStatus, gemsLeft? } and expects the legacy gamee-js details payload, so PurchaseDetails now carries gemsCost, itemName, itemImage (base64), silentPurchase, and an optional developerPayload (a JSON string, sent as-is), and PurchaseResult is { purchaseStatus, gemsLeft? }. Breaking for games on an earlier 3.0.0 build: add the two new required fields and branch on result.purchaseStatus instead of result.success. The emulator mirrors the contract — it shows the item image, honours silentPurchase, and charges a configurable gem balance that comes back as gemsLeft. See Methods → purchaseItemWithGems.

Changed#

  • Platform contract: showRewardedVideo and purchaseItemWithGems are no longer wrapped in pause / resume. Older platform builds sent pause before the ad / purchase dialog and resume after the reply. Current builds pause their own gameplay-time counter internally and dispatch neither event. Games must freeze their loop/audio/input before the call and thaw once the promise settles. The emulator mirrors this (no events around either dialog) and its protocol lint now flags updateScore / updateMissionProgress sent while an ad or purchase is pending. See player-paced calls → lifecycle.

Added#

  • Typed Promise API. Every method returns a Promise<T>; every event payload is typed.
  • Capability system. Declare every gated feature (saveState, rewardedAds, logEvents, missions, gems, platformExtraLife) in init({ capabilities }). Gated methods reject synchronously with CAPABILITY_MISSING when the capability is missing. See Capabilities.
  • Typed errors. Every failure is a GameeError with a branchable code. The seven codes (VALIDATION, CAPABILITY_MISSING, BRIDGE_TIMEOUT, BRIDGE_ERROR, BRIDGE_OVERFLOW, INVALID_STATE, NOT_SUPPORTED) form an exhaustive union.
  • hasPlatformContext() synchronous utility — returns true only when the page is loaded inside a GAMEE host (iframe, iOS WKWebView, Android WebView). Guard your boot with it. See Utilities.
  • sdk.platform getter — read the current platform after init() resolves.
  • @gamee/sdk-test-utils — MockBridge for unit-testing games without a real platform. See Unit testing.
  • Bundled emulator with a live bridge-traffic panel. Open from any docs page or /emulator.
  • Local validation — logEvent (24 char name / 160 char value cap), updateScore (finite score, non-negative playTime), and updateMissionProgress ([0, 100] range) all validate at the call site.
  • SdkOptions — allowedOrigins, requestTimeoutMs, maxPendingRequests, silentMode, custom bridge. See Configuration.
  • AI-agent briefing. Drop the llm-context bundle into your repo (as CLAUDE.md, .cursor/rules/, AGENTS.md, …) and your AI tool gets every method, event, error code, and wire detail in context. Also discoverable at /llms.txt and /llms-full.txt for tools that follow the llmstxt.org convention.

Changed#

  • init() is one-shot per SDK instance. A second call rejects with INVALID_STATE. Use createSdk() to spin up a fresh instance (mostly in tests). See Methods → init is one-shot.
  • Subscribe before gameReady(). The SDK no longer queues events for late subscribers. See Events → subscribe first.
  • Events auto-ack. You no longer call ev.detail.callback() — the SDK acknowledges every inbound event itself.
  • Method signatures. gameOver, updateScore, logEvent, and others now take a single options object (with sugar shorthands for the common case). The full mapping is in the migration guide.

Removed#

  • gamee.controller.* — games are fullscreen; wire DOM input yourself. See the controllers → native input table.
  • gamee.share() — was a stub in gamee-js.
  • gamee.gameLoadingProgress() — render your own loading UI.
  • gamee.requestPlayerData(), gamee.requestPlayerReplay(), gamee.requestPlayerSaveState(), gamee.requestSocial(), gamee.requestBattleData() — no platform support. Read initResponse.gameContext for battle/mission context instead.
  • Capabilities ghostMode, replay, playerData, socialData — the platform retired the underlying features.
  • Events ghostShow / ghostHide — gone with ghostMode.

Wire protocol#

The wire protocol is unchanged from gamee-js. Existing host implementations (iOS, Android, web) need no updates. The wire-level field names are documented in Architecture → four traffic patterns.