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>;
    challenge?: Partial<ChallengeContext>;
  };
}

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;
}

Challenges

Host ≥ 1.2.0. See the Friend challenges guide.

Method	Signature
gamma.challenges.getActive()	() => Promise<ChallengeContext | null>
gamma.challenges.submitScore(value)	(number) => Promise<{ ok: boolean; error?: GammaErrorCode | string }>
gamma.challenges.complete(result)	(ChallengeResult) => Promise<ChallengeCompleteResult>

type ChallengeType = 'high_score' | 'fastest_time' | 'level_streak';

interface ChallengeContext {
  challengeId: number;
  type: ChallengeType;
  mode: 'live' | 'async';
  param: Record<string, unknown>;
  wagerCoins: number;
  deadline: string | null;            // ISO timestamp
  myRole: 'challenger' | 'opponent';
  opponent: { displayName: string; avatar: string | null } | null;
}

interface ChallengeResult { score?: number; timeMs?: number; streak?: number }

interface ChallengeCompleteResult {
  ok: boolean;
  settled?: boolean;                  // true once both players finished
  outcome?: 'won' | 'lost' | 'tie' | 'pending_opponent';
  potCoins?: number;                  // coins won (winner only)
  error?: GammaErrorCode | string;
}

• getActive() returns null for a normal session and on hosts < 1.2.0 — one build runs everywhere.
• complete() is accepted once per attempt; later calls return already_completed. Set the result key matching the type: high_score → {score}, fastest_time → {timeMs}, level_streak → {streak}.
• submitScore() is throttled host-side — safe to call on every score change.

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.