# GammaSDK — full documentation

> Official SDK and developer docs for building HTML5 games on Gamma Games — coins, cloud save, player profiles, and a canonical coin value. Package: @swiftware/gamma-sdk.

# Introduction

# GammaSDK

**GammaSDK** lets your HTML5 game talk to **Gamma Games** — the player's coins,
cloud-synced save data, public profile, and the canonical Gamma Coin value.

There are two ways to integrate, and this site covers both:

- **The package** — [`@swiftware/gamma-sdk`](https://www.npmjs.com/package/@swiftware/gamma-sdk),
  a tiny, typed, promise-first wrapper. **Recommended for almost everyone.** It
  handles ready-waiting, the offline fallback, and ships a dev mock so you can
  build and test outside the app.
- **Manual** — call the raw `window.GammaSDK` bridge directly, no build step. See
  [Manual integration](./manual-integration.md).

## What you can do

| Capability | Package | Notes |
|---|---|---|
| Read / spend / earn coins | `getCoins`, `spendCoins`, `earnCoins` | Server-authoritative, atomic |
| Cloud save | `gamma.storage` | Account-bound, `localStorage` fallback |
| Player profile | `getPlayer` | Public fields only |
| Canonical coin value | `getCoinValue`, `coinsToUsd`, `formatCoins` | Shared by every game |

## The golden rule

> **Coins only work inside the Gamma Games app.** That's where the real,
> server-authoritative bridge is injected. Outside the app the SDK is **inert** by
> default — guard coin features on `gamma.isInApp` and keep an offline path. See
> [App-only & offline](./guides/app-only-and-offline.md).

## Next steps

- [Install](./getting-started/install.md) the package or drop-in script.
- [Quickstart](./getting-started/quickstart.md) — integrate in 3 steps.
- [Integrate with AI](./ai-integration.mdx) — copy one prompt into your AI tool.

---

# Install

# Install

## With a bundler (npm)

```bash
npm install @swiftware/gamma-sdk
```

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

The package ships ESM, CJS, and TypeScript types — works with Vite, webpack,
Rollup, esbuild, Next.js, etc.

## No build step (drop-in script)

If your game is plain HTML/JS with no bundler, use the single drop-in file. It
exposes a global `gamma`:

```html
<script src="https://cdn.jsdelivr.net/npm/@swiftware/gamma-sdk/dist/gamma-sdk.min.js"></script>
<script>
  gamma.ready().then(() => {
    gamma.getCoins().then((balance) => console.log('Balance:', balance));
  });
</script>
```

You can also self-host the file — copy `dist/gamma-sdk.min.js` from the package
next to your game and reference it locally.

## Requirements

- Any modern browser. The SDK is ~6 KB minified.
- Host app **GammaSDK ≥ 1.1.0** for `getCoinValue` (older hosts fall back to
  sensible defaults automatically).

Next: [Quickstart →](./quickstart.md)

---

# Quickstart

# Quickstart

Integrate the SDK in three steps.

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

// 1. Wait until the SDK has settled (real host in-app, or fallback outside it).
await gamma.ready();

// 2. Load the player's save (account-bound in-app, localStorage outside).
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 the whole happy path. The rest of the docs are detail.

## A more complete boot sequence

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

async function boot() {
  await gamma.ready();

  if (gamma.isInApp) {
    const player = await gamma.getPlayer();
    if (player) greet(player.displayName);
  }

  await gamma.storage.init();
  const save = (await gamma.storage.load()) ?? defaultState();
  applyState(save);

  startGame();
}

boot();
```

## Things to remember

- **Coins only work inside the Gamma Games app.** Outside it, coin calls return
  `{ok: false, error: 'no_transport'}`. Gate features on `gamma.isInApp`. See
  [App-only & offline](../guides/app-only-and-offline.md).
- **Never grant a reward before** `spendCoins` resolves with `ok: true`.
- **Include a `schemaVersion`** in every saved object so you can migrate later.
- **Test outside the app** with the opt-in [dev mock](../guides/dev-mock.md).

Prefer to let an AI do it? See [Integrate with AI](../ai-integration.mdx).

---

# Coins

# Coins

Gamma Coins are the player's real, server-authoritative balance. The SDK never
trusts the client: every spend/earn is validated and applied on the server.

## Read the balance

```js
const balance = await gamma.getCoins(); // number (0 outside the app)
```

Cheap to call — read it whenever you need the current value rather than caching.

## Spend coins

```js
const res = await gamma.spendCoins(50, 'extra_life');
if (res.ok) {
  grantExtraLife();           // only now
} else {
  showError(res.error);       // e.g. 'insufficient_coins'
}
```

- `amount` — integer, `1..10000`
- `reason` — lowercase `[a-z0-9_]+`, ≤ 64 chars (e.g. `extra_life`, `power_up_shield`)

Result shape:

```ts
{ ok: boolean; newBalance?: number; spent?: number; balance?: number; error?: string }
```

> **Never grant the reward before the promise resolves with `ok: true`.** The
> operation is atomic and server-authoritative — assume nothing until you get the
> result.

## Earn coins

Award coins for an in-game accomplishment:

```js
const res = await gamma.earnCoins(5, 'checkpoint');
if (res.ok) showToast('+5 coins!');
```

- `amount` — integer, `1..100` per call
- The server enforces a hard cap of **2000 coins earned from all games per user
  per hour**; excess returns `{ok: false, error: 'rate_limited'}`.

Result shape:

```ts
{ ok: boolean; newBalance?: number; earned?: number; error?: string }
```

## Use semantic reasons

The `reason` is stored in the coin audit log. Use descriptive identifiers so spend
patterns can be analysed:

- ✅ `extra_life`, `power_up_shield`, `skin_dragon`, `revive`
- ❌ `buy`, `x`, `item1`

## Outside the app

`getCoins()` returns `0` and `spendCoins`/`earnCoins` return
`{ok: false, error: 'no_transport'}` unless you enable the
[dev mock](./dev-mock.md). Always keep an offline path — see
[App-only & offline](./app-only-and-offline.md).

See also the full [API reference](../api-reference.md) and [error codes](../error-codes.md).

---

# Coin value

# Coin value

Every integrated game shares **one canonical coin value**, so you can price in-game
items and show real-world worth consistently. It's served from the Gamma Games
backend and can change without you shipping a new build.

## Read it

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

Type:

```ts
interface CoinValue {
  usdPerCoin: number;
  currencyCode: string;
  displayName: string;
  symbol: string;
  iconUrl: string | null;
}
```

The value is cached after the first read for the session.

## Helpers

```js
await gamma.coinsToUsd(100);  // 1.00  — amount × usdPerCoin
await gamma.formatCoins(50);  // "50 GC" — uses the symbol
```

## Pricing example

```js
const {usdPerCoin, symbol} = await gamma.getCoinValue();

function priceLabel(coins) {
  const usd = (coins * usdPerCoin).toFixed(2);
  return `${coins} ${symbol} (≈ $${usd})`;
}

priceLabel(250); // "250 GC (≈ $2.50)"
```

## Compatibility

`getCoinValue` requires host app **GammaSDK ≥ 1.1.0**. On older hosts the call
fails internally and the package returns the **default value**
(`usdPerCoin: 0.01`, `USD`, `Gamma Coins`, `GC`) so your UI never breaks. Outside
the app it also returns the default (it's just a display constant, not an economy
operation).

---

# Progress & saves

# Progress & saves

The SDK gives you account-bound cloud save with an automatic offline fallback. Use
the built-in `gamma.storage` adapter — it handles the boilerplate (ready-waiting,
fallback, and one-shot migration of an old `localStorage` save into the account).

## The adapter (recommended)

```js
await gamma.storage.init();                 // resolve host once
const state = (await gamma.storage.load())  // account-bound in-app, localStorage outside
  ?? {schemaVersion: 1};

// ... play ...

await gamma.storage.save(state);            // returns true on success
```

- **In-app:** reads/writes the player's account, synced across devices.
- **Outside the app:** transparently uses `localStorage`, so offline play works.
- **First in-app launch:** if there's a legacy `localStorage` save and no account
  save yet, it migrates the local save into the account once, then clears it.

Set the localStorage key (and other options) before the first call:

```js
gamma.configure({storageKey: 'mygame_save'});
```

## Always include a `schemaVersion`

Every persisted payload should carry an integer `schemaVersion` so future game
versions can migrate old saves forward without corrupting them.

```js
const CURRENT_SCHEMA = 3;

function migrate(state) {
  if (state.schemaVersion < 2) {
    state.coinsEarned = 0;            // field added in v2
    state.schemaVersion = 2;
  }
  if (state.schemaVersion < 3) {
    state.levels = state.stages ?? {}; // renamed in v3
    delete state.stages;
    state.schemaVersion = 3;
  }
  return state;
}

const raw = await gamma.storage.load();
const state = migrate(raw ?? {schemaVersion: CURRENT_SCHEMA});
```

## What to save (and what not to)

Save **derived, durable** state:

- ✅ Level number, per-level stars, unlock flags, cosmetic choices, counters
- ✅ Quest/mission progress, tutorial completion
- ✅ Settings the player explicitly changes (music on/off, control scheme)

Do **not** save **reconstructible, transient** state:

- ❌ Sprite positions, velocities, particle buffers, audio cursors
- ❌ Camera offsets, UI animation state
- ❌ Any cached coin balance — call [`getCoins`](./coins.md) when you need it

## Save cadence & limits

- **Debounce** routine saves (≈1000 ms trailing); save at meaningful milestones.
- **Force-save** on `visibilitychange → hidden` / `pagehide` — mobile can kill the
  page at any time.

```js
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') gamma.storage.save(state);
});
```

- Max encoded save size: **100 KB**. If you're close, you're probably persisting
  reconstructible state (see above) — compact into ids/bitfields.

## Low-level API

`gamma.storage` is built on `gamma.loadProgress()` / `gamma.saveProgress(data)`,
which talk to the account directly (no localStorage fallback). Prefer the adapter
unless you need full control. See the [API reference](../api-reference.md).

---

# Player

# Player

Read the player's non-sensitive public profile to personalise your game.

```js
const player = await gamma.getPlayer();
if (player) {
  greet(player.displayName); // "Welcome back, Alex!"
}
```

Type:

```ts
interface Player {
  id: string;
  displayName: string;
  avatar: string | null;
  frame: string | null;
  isSubscribed: boolean;
}
```

Returns `null` when unavailable (e.g. outside the app, or no authenticated user).

> **Privacy:** `getPlayer` never returns email, phone, coin balance, or any other
> sensitive field. Use it only for personalisation. For the balance, call
> [`getCoins`](./coins.md).

---

# App-only & offline

# App-only & offline

The single most important thing to understand about the SDK:

> **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** by default.

## What "inert" means

When the game runs outside the Gamma Games app and the [dev mock](./dev-mock.md)
is not enabled:

| Call | Result outside the app |
|---|---|
| `getCoins()` | `0` |
| `spendCoins(...)` | `{ok: false, error: 'no_transport'}` |
| `earnCoins(...)` | `{ok: false, error: 'no_transport'}` |
| `getCoinValue()` | default value (display constant) |
| `getPlayer()` | `null` |
| `gamma.storage.*` | **works** — falls back to `localStorage` |

Nothing can fake or spend real coins outside the app, by design.

## Always gate on `isInApp`

After `gamma.ready()`, check `gamma.isInApp`:

```js
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
  // (e.g. let the player continue for free, or hide the coin shop).
}
```

`gamma.storage` keeps working everywhere, so progress/saves are unaffected — only
the coin economy is app-gated.

## Why it's built this way

- The coin **balance lives on the server**; the game can only *ask* to spend, and
  the server validates against the authenticated user.
- The host supplies the user identity — the game never sends it and can't spoof it.
- Outside the app there's no authenticated session, so there's nothing to spend.

See [Limits & security](../limits-and-security.md) for the full model.

---

# Dev mock (testing)

# Dev mock

The mock lets you build and test your game in a plain browser — with no Gamma Games
app — by simulating the bridge locally. It is **off by default** and **never
touches real balances**: state is in-memory, mirrored to `localStorage` so it
survives a reload.

## Enable it

Call `configure({mock: ...})` **before** `gamma.ready()`:

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

gamma.configure({
  readyTimeoutMs: 1500,          // how long to wait for a real host first
  storageKey: 'mygame_save',     // localStorage key for the progress fallback
  mock: true,                    // ← enable; or pass an object to seed values
});

await gamma.ready();
console.log(gamma.isInApp);      // always false with the mock; true only in-app
```

Seed specific values with the object form:

```js
gamma.configure({
  mock: {
    coins: 500,
    coinValue: {usdPerCoin: 0.02},
    player: {displayName: 'Dev Player'},
  },
});
```

With the mock enabled, `getCoins`, `spendCoins`, `earnCoins`, `saveProgress`,
`loadProgress`, `getPlayer`, and `getCoinValue` all work against the local
simulation — including the same validation the real bridge enforces (amount/reason
limits, insufficient balance, etc.).

## :warning: Don't ship it enabled

In production, leave the mock **off** so the integration stays inert outside the
Gamma Games app (see [App-only & offline](./app-only-and-offline.md)). A good
pattern:

```js
gamma.configure({mock: import.meta.env.DEV}); // only in local dev
```

## Interactive test harness

A ready-made harness that exercises every method is included with the package and
mirrored here: [open the test harness](pathname:///examples/test-game.html). It shows an
"in-app" vs "dev mock" badge and logs every SDK response.

---

# API reference

# API reference

The package exposes a single `gamma` object. All methods are promise-first.

```js
import {gamma} from '@swiftware/gamma-sdk';
// drop-in: global `gamma`
```

## Lifecycle

| Member | Signature | Description |
|---|---|---|
| `gamma.configure(config)` | `(config: GammaConfig) => void` | Set options **before** the first call (timeout, storage key, dev mock). |
| `gamma.ready()` | `() => Promise<void>` | Resolve once the SDK has settled (real host, or fallback outside the app). Idempotent. |
| `gamma.isInApp` | `boolean` | `true` only when the real Gamma Games host is present. Check after `ready()`. |

```ts
interface GammaConfig {
  readyTimeoutMs?: number;            // default 1500
  storageKey?: string;                // default 'gamma_save'
  mock?: boolean | {                  // off by default
    coins?: number;
    player?: Partial<Player>;
    coinValue?: Partial<CoinValue>;
  };
}
```

## Coins

| Method | Signature |
|---|---|
| `getCoins()` | `() => Promise<number>` |
| `spendCoins(amount, reason)` | `(number, string) => Promise<SpendResult>` |
| `earnCoins(amount, reason)` | `(number, string) => Promise<EarnResult>` |

```ts
interface SpendResult { ok: boolean; newBalance?: number; spent?: number; balance?: number; error?: GammaErrorCode }
interface EarnResult  { ok: boolean; newBalance?: number; earned?: number; error?: GammaErrorCode }
```

- `spendCoins` amount: `1..10000`. `earnCoins` amount: `1..100`.
- `reason`: `^[a-z0-9_]+$`, ≤ 64 chars.

## Coin value

| Method | Signature |
|---|---|
| `getCoinValue()` | `() => Promise<CoinValue>` |
| `coinsToUsd(amount)` | `(number) => Promise<number>` |
| `formatCoins(amount)` | `(number) => Promise<string>` |

```ts
interface CoinValue {
  usdPerCoin: number;
  currencyCode: string;
  displayName: string;
  symbol: string;
  iconUrl: string | null;
}
```

## Player

| Method | Signature |
|---|---|
| `getPlayer()` | `() => Promise<Player \| null>` |

```ts
interface Player {
  id: string;
  displayName: string;
  avatar: string | null;
  frame: string | null;
  isSubscribed: boolean;
}
```

## Progress

| Member | Signature | Notes |
|---|---|---|
| `gamma.storage.init()` | `() => Promise<boolean>` | Resolve host once; returns `isInApp`. |
| `gamma.storage.ready()` | `() => boolean` | Whether the host is resolved. |
| `gamma.storage.load()` | `() => Promise<ProgressData \| null>` | Account in-app, `localStorage` outside. |
| `gamma.storage.save(state)` | `(ProgressData) => Promise<boolean>` | Returns `true` on success. |
| `gamma.loadProgress()` | `() => Promise<ProgressData \| null>` | Low-level, account-only. |
| `gamma.saveProgress(data)` | `(ProgressData) => Promise<boolean>` | Low-level, account-only. Max 100 KB encoded. |

`ProgressData` is any JSON-serialisable object — include an integer
`schemaVersion`.

## Raw bridge equivalents

The package wraps `window.GammaSDK` (callback-style). If you integrate manually,
see [Manual integration](./manual-integration.md) for the raw method shapes and the
underlying `{success, ...}` result objects.

---

# Manual integration

# Manual integration (raw `window.GammaSDK`)

If you can't use the [`@swiftware/gamma-sdk`](./getting-started/install.md) 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:

```js
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`.

```js
// 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:

```js
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:

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

## Reference constants

```text
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](./error-codes.md) and [limits & security](./limits-and-security.md)
for the rest of the contract.

---

# Integrate with AI

# Integrate with AI

Let your AI coding tool (Claude Code, Cursor, Copilot, ChatGPT, …) wire the SDK
into your game for you. **Copy the prompt below**, paste it into your assistant
alongside your game's code, and let it apply the integration. It's a complete,
self-contained spec — the assistant doesn't need to read anything else.

```
You are integrating the Gamma Games SDK (`@swiftware/gamma-sdk`) into an existing
HTML5 game. Follow this specification exactly. Do not invent methods or behavior
that is not stated here.

# What the SDK is

`@swiftware/gamma-sdk` is a small, typed, promise-first wrapper around a bridge
(`window.GammaSDK`) that the Gamma Games app injects into the game's WebView at
runtime. It exposes the player's coins, account-bound cloud save, public profile,
and a canonical coin value. There is no API key. The host supplies the user
identity — the game never sends it.

CRITICAL RULE: Coins only work INSIDE the Gamma Games app. Outside the app the SDK
is inert by default (coin calls return `{ok:false, error:'no_transport'}`,
`getCoins()` returns 0). The game MUST still run outside the app using its own
offline behavior. `gamma.storage` always works (it falls back to localStorage).

# Install

If the project uses a bundler:
    npm install @swiftware/gamma-sdk
    import { gamma } from '@swiftware/gamma-sdk';

If the project is plain HTML/JS with no bundler, add the drop-in script (exposes a
global `gamma`):

# The integration contract — do exactly this

1. On boot, call `await gamma.ready()` once before using any SDK feature.
2. Gate every coin feature on `gamma.isInApp`. When false, use the game's existing
   offline behavior (do not call spend/earn expecting success).
3. Route player-progress storage through `gamma.storage` (load on boot, save at
   milestones). Keep any existing localStorage logic as the offline fallback — the
   adapter already handles that.
4. Replace any in-game currency that represents real Gamma Coins with
   `gamma.spendCoins` / `gamma.earnCoins`. Only grant the reward INSIDE the result
   when `ok === true`. Leave purely game-internal resources alone.
5. Include an integer `schemaVersion` field in every saved object.
6. Do NOT enable the dev mock in production builds.

# API (all promise-first)

    gamma.configure(config)            // call BEFORE ready(); see config below
    await gamma.ready()                // resolves when settled; idempotent
    gamma.isInApp                       // boolean — true only inside the app

    await gamma.getCoins()             // number (0 outside the app)
    await gamma.spendCoins(amount, reason)
        // amount: int 1..10000; reason: /^[a-z0-9_]+$/, <=64 chars
        // -> { ok, newBalance?, spent?, balance?, error? }
    await gamma.earnCoins(amount, reason)
        // amount: int 1..100; server caps 2000 coins/user/hour
        // -> { ok, newBalance?, earned?, error? }

    await gamma.getCoinValue()
        // -> { usdPerCoin, currencyCode, displayName, symbol, iconUrl }
    await gamma.coinsToUsd(amount)     // number
    await gamma.formatCoins(amount)    // string, e.g. "50 GC"

    await gamma.getPlayer()            // { id, displayName, avatar, frame, isSubscribed } | null

    await gamma.storage.init()         // resolve host once; returns isInApp
    await gamma.storage.load()         // ProgressData | null
    await gamma.storage.save(state)    // boolean
    // low-level (prefer storage): gamma.loadProgress(), gamma.saveProgress(data)

GammaConfig:
    {
      readyTimeoutMs?: number,         // default 1500
      storageKey?: string,             // default 'gamma_save'
      mock?: boolean | { coins?, player?, coinValue? }  // OFF by default; dev only
    }

# Error codes (in `error`)

insufficient_coins | invalid_amount | invalid_reason | data_too_large |
serialization_error | rate_limited | user_not_found | network_error |
internal_error | timeout | unknown_type | no_transport

# Canonical example

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

    async function boot() {
      await gamma.ready();
      await gamma.storage.init();
      const state = (await gamma.storage.load()) ?? { schemaVersion: 1 };
      applyState(state);

      if (gamma.isInApp) {
        const player = await gamma.getPlayer();
        if (player) greet(player.displayName);
      }
      startGame();
    }

    async function buyExtraLife() {
      if (!gamma.isInApp) { return offerOfflineContinue(); }
      const res = await gamma.spendCoins(50, 'extra_life');
      if (res.ok) grantExtraLife();
      else showError(res.error);   // never show the raw code to the player
    }

    function onProgressChanged(state) {
      gamma.storage.save(state);   // debounce in real code; force-save on visibilitychange->hidden
    }

# Guardrails — do NOT

- Grant a reward before `spendCoins` resolves with `ok === true`.
- Read coins without checking `gamma.isInApp` (outside the app they're inert).
- Cache the coin balance for longer than a single user action — call getCoins again.
- Send user_id / game_id / tokens from the game — the host supplies identity.
- Remove the offline/localStorage fallback — it is load-bearing.
- Invent methods that are not in this spec (no getFriends, showAd, leaderboards…).
- Ship with `mock` enabled.

# Your task

Locate where the game (a) boots, (b) reads/writes progress in localStorage, and
(c) mutates any currency that maps to real Gamma Coins. Apply the contract above to
those sites only, keeping the offline path intact. Then summarize the changes you
made and list any spots where you were unsure whether an in-game resource maps to
real Gamma Coins.
```

## Machine-readable docs

These docs are also published in formats built for LLMs and crawlers:

- [`/llms.txt`](pathname:///llms.txt) — an index of the docs with links (per
  [llmstxt.org](https://llmstxt.org)).
- [`/llms-full.txt`](pathname:///llms-full.txt) — the entire documentation as a
  single markdown file you can paste into a model's context.
- Every doc page has a **Copy as Markdown** button plus **Ask ChatGPT**, **Ask
  Claude**, and **Ask Perplexity** buttons that open the page in your assistant.

## Prefer to do it by hand?

Follow the [Quickstart](./getting-started/quickstart.md), or the
[Manual integration](./manual-integration.md) guide for the raw `window.GammaSDK`
bridge.

---

# Error codes

# Error codes

When a call fails, the package returns `{ok: false, error: '<code>'}` (or the raw
bridge returns `{success: false, error: '<code>'}`). Never show the raw code to the
player — translate it to a friendly message.

| Code | Meaning | What to do |
|---|---|---|
| `insufficient_coins` | Player doesn't have enough | Show a "need X more coins" message |
| `invalid_amount` | Amount ≤ 0, non-integer, or over the cap | Fix the call site |
| `invalid_reason` | Reason failed the regex / length check | Use `[a-z0-9_]+`, ≤ 64 chars |
| `invalid_data` | `saveProgress` data wasn't a JSON object | Pass a plain object |
| `data_too_large` | `saveProgress` payload > 100 KB | Compact your state; don't retry |
| `serialization_error` | Save data wasn't JSON-serialisable | Remove functions / circular refs |
| `save_failed` | Backend rejected the save | Transient — retry with backoff |
| `rate_limited` | Too many calls / earn cap hit | Back off and retry later |
| `forbidden` | Call wasn't for the signed-in player | Don't pass user ids; let the app own identity |
| `user_not_found` | No authenticated user | Fall back to offline mode |
| `network_error` | Request to the backend failed | Transient — retry with backoff |
| `internal_error` | Unexpected bridge error | Report to the Gamma team |
| `dispatch_error` | Bridge transport failed to send | Treat as `network_error` |
| `empty_response` | Bridge returned nothing | Treat as `network_error` |
| `timeout` | Bridge didn't respond in 30 s | Treat as `network_error` |
| `unknown_type` | Unknown message type (SDK/app mismatch) | Update your SDK / check the call |
| `no_transport` | Running outside the app, mock disabled | Use [`isInApp`](./guides/app-only-and-offline.md) and an offline path |

```ts
type GammaErrorCode =
  | 'insufficient_coins' | 'invalid_amount' | 'invalid_reason'
  | 'invalid_data' | 'data_too_large' | 'serialization_error'
  | 'save_failed' | 'rate_limited' | 'forbidden'
  | 'user_not_found' | 'network_error' | 'internal_error'
  | 'dispatch_error' | 'empty_response'
  | 'timeout' | 'unknown_type' | 'no_transport';
```

---

# Limits & security

# Limits & security

## Limits

| Limit | Value |
|---|---|
| `spendCoins` amount per call | `1..10000` |
| `earnCoins` amount per call | `1..100` |
| `earnCoins` per user per hour | 2000 coins |
| `saveProgress` payload size | 100 KB encoded |
| SDK messages per minute | 60 |
| Reason format | `^[a-z0-9_]+$`, ≤ 64 chars |
| Bridge response timeout | 30 s |

All limits are enforced on the server with the same values shown above — the
client can't raise them, even by calling the backend directly.

## Why your game can't cheat

- **Coins are server-authoritative.** Your game can only *request* a spend or earn;
  the server validates it and applies the change. The balance never lives in the game.
- **Identity comes from the authenticated session.** The game never sends a user id.
  The coin RPCs derive the player from the signed-in session and reject any request
  that targets a different account (`forbidden`), so a player can't grant or drain
  anyone's coins — including their own outside of gameplay.
- **Spends are atomic.** Rapid or concurrent calls can't double-spend.
- **Saves are per-player.** Row-level security ties every save to the signed-in
  player; no one can read or write another player's save.
- **Inert outside the app.** With no app session there's nothing to spend — see
  [App-only & offline](./guides/app-only-and-offline.md).

## Platform note

Coins and progress sync are live in the native app (Android/iOS) and on the web
for games served from the Gamma Games origin. A game loaded from a third-party
origin on the web can't be wired to the host securely, so the SDK reports
`isInApp === false` there and your offline fallback runs — see
[App-only & offline](./guides/app-only-and-offline.md).

---

# Testing

# Testing

## Test outside the app with the dev mock

Enable the [dev mock](./guides/dev-mock.md) and run your game in a plain browser.
Then use the included interactive harness to exercise every method:

👉 [Open the test harness](pathname:///examples/test-game.html)

It shows an **in-app** vs **dev mock** badge and logs each SDK response, with
buttons for `getCoins`, `spendCoins`, `earnCoins`, `getCoinValue`, `getPlayer`,
and `storage` save/load.

## Pre-submission checklist

Before submitting your game to Gamma Games, verify:

- [ ] Game loads and plays **without** the SDK (outside the app)
- [ ] After `gamma.ready()`, coin features are gated on `gamma.isInApp`
- [ ] `getCoins` shows the correct balance in-app
- [ ] `spendCoins` deducts and grants the reward only on `ok: true`
- [ ] `spendCoins` over the balance shows an error, balance unchanged
- [ ] Invalid `reason` (uppercase/spaces) is rejected
- [ ] `getCoinValue` returns `usdPerCoin` + display metadata
- [ ] `gamma.storage.save` persists across app restarts (in-app) and reloads (offline)
- [ ] `gamma.storage.load` returns `null` for a fresh player
- [ ] Saves stay under 100 KB and carry a `schemaVersion`
- [ ] The game shows friendly messages, never raw error codes
- [ ] The dev mock is **disabled** in the production build