API reference

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

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().

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>

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>

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

Player

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

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 for the raw method shapes and the underlying {success, ...} result objects.