Skip to main content

Manual integration (raw window.GammaSDK)

If you can't use the @swiftware/gamma-sdk package (no bundler, or you want zero dependencies), you can call the raw bridge that the Gamma Games app injects as window.GammaSDK. There's no <script> tag, no build step, and no API key — the host injects it automatically when your game runs inside the app.

The package is recommended: it wraps everything below in a typed, promise-first API and adds the offline fallback and dev mock. Use the raw bridge only if you have a reason to.

Capability detection​

The bridge exists only inside the Gamma Games app. Always guard:

function hasGammaSDK() {
  return !!(window.GammaSDK && window.GammaSDK.ready);
}

// The SDK may inject before or after your code runs:
if (hasGammaSDK()) {
  start();
} else {
  window.addEventListener('gammasdkready', start);
}

Methods​

All methods are callback-style; result always has a success boolean. Each method is also mirrored under window.GammaSDK.promises.* for async/await.

// Coins
GammaSDK.getCoins((r) => {/* {success, balance} */});
GammaSDK.spendCoins(50, 'extra_life', (r) => {/* {success, newBalance, spent} | {success:false, error, balance?} */});
GammaSDK.earnCoins(5, 'checkpoint', (r) => {/* {success, newBalance, earned} */});

// Coin value (host ≥ 1.1.0)
GammaSDK.getCoinValue((r) => {/* {success, coinValue: {usdPerCoin, currencyCode, displayName, symbol, iconUrl}} */});

// Progress (keyed on user + game, last-write-wins, ≤100 KB)
GammaSDK.saveProgress({level: 12, schemaVersion: 1}, (r) => {/* {success, sizeBytes} */});
GammaSDK.loadProgress((r) => {/* {success, data} — data may be null */});

// Player (public fields only)
GammaSDK.getPlayer((r) => {/* {success, player: {id, displayName, avatar, frame, isSubscribed}} */});

Promise form:

const r = await GammaSDK.promises.spendCoins(30, 'revive');
if (r.success) grantRevive();

Offline fallback​

Because the bridge is absent outside the app, keep a localStorage path for progress so the same build still runs elsewhere:

function saveState(state) {
  if (hasGammaSDK()) GammaSDK.saveProgress(state);
  else localStorage.setItem('mygame_save', JSON.stringify(state));
}

Reference constants​

Global:          window.GammaSDK
Readiness flag:  window.GammaSDK.ready        // boolean
Ready event:     'gammasdkready' on window
Version:         window.GammaSDK.version      // '1.1.0'

Methods (callback-style; also on window.GammaSDK.promises):
  getCoins(cb)
  spendCoins(amount:int 1..10000, reason:/^[a-z0-9_]+$/, cb)
  earnCoins(amount:int 1..100,    reason:/^[a-z0-9_]+$/, cb)
  saveProgress(data:JSON, cb)      // ≤100 KB encoded
  loadProgress(cb)
  getPlayer(cb)
  getCoinValue(cb)                 // host ≥ 1.1.0

See error codes and limits & security for the rest of the contract.

Ask:View .md