@swiftware/gamma-sdk

The easy way to connect your HTML5 game to Gamma Games — coins, cloud save, player info, and the canonical Gamma Coin value. Fully typed, works inside the app, and falls back to a dev mock so you can build and test in a plain browser.

No API key. No user_id/game_id to manage. The app supplies identity; you just call methods.

Install

With a bundler (npm):

npm install @swiftware/gamma-sdk

import { gamma } from '@swiftware/gamma-sdk';

No build step (drop-in): copy dist/gamma-sdk.min.js next to your game and add one tag — it exposes a global gamma:

<script src="gamma-sdk.min.js"></script>

3 steps to integrate

// 1. Wait until the SDK is usable (real host in-app, dev mock outside it).
await gamma.ready();

// 2. Load the player's save (account-bound in-app, localStorage as fallback).
await gamma.storage.init();
const state = (await gamma.storage.load()) ?? { schemaVersion: 1 };

// 3. Use coins / save progress. Only grant a reward when `ok` is true.
const res = await gamma.spendCoins(50, 'extra_life');
if (res.ok) grantExtraLife();

await gamma.storage.save(state);

That's it. Everything below is optional detail.

Gamma Coin value

Every integrated game shares one canonical coin value, so you can price items and show real-world worth consistently:

const v = await gamma.getCoinValue();
// { usdPerCoin: 0.01, currencyCode: 'USD',
//   displayName: 'Gamma Coins', symbol: 'GC', iconUrl: null }

await gamma.coinsToUsd(100);   // 1.00   (100 coins = $1.00)
await gamma.formatCoins(50);   // "50 GC"

The value is served from the backend and cached after first read — it can change without you shipping a new build. Requires host app SDK ≥ 1.1.0; older hosts fall back to defaults automatically.

API

| Method | Returns | |---|---| | gamma.ready() | Promise<void> — resolves when usable | | gamma.isInApp | boolean — true when the real host is present | | gamma.getCoins() | Promise<number> | | gamma.spendCoins(amount, reason) | { ok, newBalance?, spent?, balance?, error? } | | gamma.earnCoins(amount, reason) | { ok, newBalance?, earned?, error? } | | gamma.getCoinValue() | Promise<CoinValue> | | gamma.coinsToUsd(amount) | Promise<number> | | gamma.formatCoins(amount) | Promise<string> | | gamma.getPlayer() | Promise<Player \| null> | | gamma.storage.init() / load() / save(state) | progress adapter | | gamma.loadProgress() / saveProgress(data) | low-level (prefer storage) |

Rules that matter:

• amount for spendCoins is 1..10000; for earnCoins it's 1..100.
• reason must match ^[a-z0-9_]+$, ≤ 64 chars (e.g. "extra_life").
• Never grant a reward before spendCoins resolves with ok: true.
• Include an integer schemaVersion in every saved object so you can migrate saves between game versions. Max encoded save size: 100 KB.

The integration is only effective inside Gamma Games

By design, coins only work inside the Gamma Games app. That's where the host injects the real, server-authoritative bridge. Outside the app (your own website, another portal, a plain dev browser) the SDK is inert: coin calls resolve to { ok: false, error: 'no_transport' } and getCoins() returns 0. Nothing can fake or spend real coins outside the app.

So always gate coin features on gamma.isInApp and keep an offline path:

await gamma.ready();
if (gamma.isInApp) {
  const res = await gamma.spendCoins(50, 'extra_life');
  if (res.ok) grantExtraLife();
} else {
  // Running outside Gamma Games — use your own offline behaviour.
}

gamma.storage keeps working everywhere — it uses the account inside the app and falls back to localStorage outside it — so progress/saves are unaffected.

Dev mock (opt-in, for local testing only)

The mock is off by default. Enable it explicitly to build and test your game in a plain browser without the app. It is local-only and never touches real balances:

gamma.configure({
  readyTimeoutMs: 1500,            // how long to wait for the real host
  storageKey: 'mygame_save',       // localStorage key for progress fallback
  mock: true,                      // or: { coins: 500, coinValue: { usdPerCoin: 0.02 } }
});
await gamma.ready();
console.log(gamma.isInApp); // always false with the mock; true only in-app

⚠️ Don't ship mock enabled. In production, leave it off so the integration stays inert outside Gamma Games.

Open examples/test-game.html after npm run build to exercise every method.

Build

npm install
npm run build      # → dist/: ESM, CJS, gamma-sdk.min.js (IIFE), .d.ts
npm run typecheck

For the full bridge contract, error codes, security model, and the low-level window.GammaSDK reference (for integrators not using this package), see docs/GAMMA_SDK.md in the main repo.