# 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.