@unboxy/phaser-sdk 0.2.3 → 0.2.4

package/SDK-GUIDE.md

@@ -6,8 +6,10 @@ Reference for AI agents building games on the Unboxy platform. Tracks the **inst
 
 - `createUnboxyGame(options)` — Phaser.Game factory with platform defaults (screenshot + recording wired up)
 - `UnboxyScene` — optional base scene with `createButton`, `shakeCamera`, `flashCamera` helpers
-- `Unboxy.init()` — platform services: identity, save data
-- (future: leaderboards, multiplayer lobbies)
+- `Unboxy.init()` — platform services entry point
+- `unboxy.saves` — **per-user** key-value store (only the owner sees/writes their data)
+- `unboxy.gameData` — **per-game** key-value store (read by anyone; write requires auth)
+- (future: multiplayer lobbies)
 
 ## Platform services
 
@@ -124,6 +126,63 @@ const saved = await unboxy.saves.get<number>('highScore').catch(() => null);
 this.highScore = typeof saved === 'number' ? saved : 0;
 ```
 
+### Game data — `unboxy.gameData`
+
+Same API shape as `saves`, but **game-scope**: one value per key, shared by all players of the game. Use it for things the whole playerbase sees — scoreboards, shared inventories, tournament state, level-of-the-day.
+
+```ts
+// Read — public. Works for anonymous visitors.
+type Entry = { name: string; score: number; at: number };
+const board = await unboxy.gameData.get<Entry[]>('leaderboard') ?? [];
+
+// Write — requires an authenticated user. Throws RpcError('UNAUTHENTICATED') otherwise.
+// Safe append: read + modify + write with ifVersion to avoid clobbering
+// concurrent writers (two players finishing at the same time).
+const { value: current, version } = await unboxy.gameData
+  .get<Entry[]>('leaderboard')
+  .then((v) => ({ value: v ?? [], version: null as number | null }))  // null means "not yet written"
+
+async function submitScore(name: string, score: number) {
+  if (!unboxy.isAuthenticated) return;             // skip for anonymous
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const raw = await unboxy.gameData.get<Entry[]>('leaderboard');
+    const list = Array.isArray(raw) ? raw : [];
+    const next = [...list, { name, score, at: Date.now() }]
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 100);                              // cap to top 100 so we don't blow the 100 KB limit
+    try {
+      await unboxy.gameData.set('leaderboard', next);
+      return;                                      // success
+    } catch (err: any) {
+      if (err?.code !== 'VERSION_MISMATCH') throw err;
+      // another writer landed first — re-read and retry
+    }
+  }
+}
+```
+
+### Saves vs. gameData — which one?
+
+| Need | Use | Why |
+|---|---|---|
+| My personal high score | `saves` | Only I write it, only I read it. Anonymous-friendly (localStorage fallback). |
+| Progress through levels | `saves` | Per-user private state. |
+| Character / loadout choice | `saves` | Per-user. |
+| Scoreboard visible to everyone | `gameData` | Multiple users write; anyone reads. |
+| Today's puzzle / daily challenge | `gameData` | Single global value read by all players. |
+| Shared tournament bracket | `gameData` | Shared mutable state across players. |
+| Player name in a chat log | `gameData` | But consider size caps — chat is noisy. |
+| Current frame's enemy positions | *neither* — transient, don't persist | Wastes quota and confuses state after refresh. |
+
+Rule of thumb: if two different players would write to the same key, it's `gameData`. If a write from player A should never be visible to player B, it's `saves`.
+
+### Concurrency + size (gameData specifics)
+
+- **List writes race.** If two players append to `leaderboard` simultaneously, one overwrites the other's work. Use `ifVersion` for read-modify-write. On `VERSION_MISMATCH`, re-read and retry.
+- **Truncate.** A single key caps at 100 KB — roughly 500-1000 compact JSON entries. Keep lists bounded (top N, drop older), or shard across keys.
+- **Reads are cheap and public.** No auth needed — even logged-out players see `gameData`. Don't put anything secret here.
+- **Trust is thin.** The backend stores what you write, verbatim. A player with devtools could submit any JSON. For casual games this is fine; for competitive stakes, a future typed leaderboards API with server-side validation is the right fix.
+
 ## Anti-patterns (don't do these)
 
 - Do **not** call `Unboxy.init()` inside a scene. Initialize at module load in `main.ts` and export the promise.
@@ -131,9 +190,12 @@ this.highScore = typeof saved === 'number' ? saved : 0;
 - Do **not** save on every frame / every score tick. Debounce or only save on meaningful events (game over, level clear).
 - Do **not** store large binary blobs (images, audio) as save values — use a dedicated blob API when it ships.
 - Do **not** use `localStorage` directly for persistent data when `unboxy.saves` is available — you'll lose cross-device sync when we ship provisional accounts.
+- Do **not** put secrets, private messages, or per-user data in `gameData` — it's public. That's `saves`.
+- Do **not** write to `gameData` on every score tick either — submit once at game-over or level-clear.
 
 ## Changelog
 
+- **0.2.4** — added `unboxy.gameData` module (game-scope key-value store for scoreboards, shared state)
 - **0.2.3** — anonymous users now use localStorage even inside a host (was throwing UNAUTHENTICATED when calling `saves` in home-ui without login)
 - **0.2.2** — added `SDK-GUIDE.md`
 - **0.2.1** — added `Unboxy.init`, `unboxy.user`, `unboxy.saves`, Transport abstraction (PostMessage + LocalStorage backends)

package/dist/core/Unboxy.d.ts

@@ -1,5 +1,6 @@
 import type { TransportKind } from './Transport.js';
 import { SavesModule } from '../saves/SavesModule.js';
+import { GameDataModule } from '../gamedata/GameDataModule.js';
 import type { UnboxyUser } from '../protocol.js';
 export interface UnboxyInitOptions {
     /** Handshake timeout in ms when running inside a host. Default 2000. */
@@ -20,6 +21,7 @@ export interface UnboxyInitOptions {
 export declare class Unboxy {
     private transport;
     readonly saves: SavesModule;
+    readonly gameData: GameDataModule;
     private constructor();
     /** The current authenticated user, or `null` if anonymous / standalone. */
     get user(): UnboxyUser | null;

package/dist/core/Unboxy.js

@@ -1,8 +1,9 @@
 import { PostMessageTransport } from './transports/PostMessageTransport.js';
 import { LocalStorageTransport } from './transports/LocalStorageTransport.js';
 import { SavesModule } from '../saves/SavesModule.js';
+import { GameDataModule } from '../gamedata/GameDataModule.js';
 // Kept in sync with package.json on each publish.
-const SDK_VERSION = '0.2.3';
+const SDK_VERSION = '0.2.4';
 /**
  * Unboxy platform services bound to the current (game, user).
  *
@@ -13,14 +14,19 @@ const SDK_VERSION = '0.2.3';
 export class Unboxy {
     constructor(transport) {
         this.transport = transport;
-        // Saves are per-user. When the viewer is anonymous (no logged-in user),
-        // route save calls to localStorage even if a host is attached — the host
-        // backend requires auth, so forwarding would 401. Other module surfaces
-        // (future leaderboards, etc.) can still use the primary transport.
+        // Saves are per-user. When the viewer is anonymous, route save calls to
+        // localStorage even if a host is attached — the backend requires auth,
+        // so forwarding would 401. Games see the same `unboxy.saves` API either
+        // way and don't have to branch on auth state.
         const savesTransport = transport.user === null
             ? new LocalStorageTransport(transport.gameId || 'anonymous')
             : transport;
         this.saves = new SavesModule(savesTransport);
+        // gameData is game-scope: reads are public (anonymous OK), only writes
+        // need auth. The primary transport handles both; if it's a LocalStorage
+        // fallback (standalone mode) that also works — the module speaks the
+        // same RPC interface.
+        this.gameData = new GameDataModule(transport);
     }
     /** The current authenticated user, or `null` if anonymous / standalone. */
     get user() { return this.transport.user; }

package/dist/core/transports/LocalStorageTransport.d.ts

@@ -11,11 +11,12 @@ export declare class LocalStorageTransport implements Transport {
     readonly user: UnboxyUser | null;
     constructor(gameId: string);
     call<T = unknown>(method: string, params?: unknown): Promise<T>;
-    private prefix;
+    private savesPrefix;
+    private gameDataPrefix;
     private read;
     private write;
-    private savesGet;
-    private savesSet;
-    private savesDelete;
-    private savesList;
+    private kvGet;
+    private kvSet;
+    private kvDelete;
+    private kvList;
 }

package/dist/core/transports/LocalStorageTransport.js

@@ -12,18 +12,23 @@ export class LocalStorageTransport {
     }
     async call(method, params) {
         switch (method) {
-            case 'saves.get': return this.savesGet(params);
-            case 'saves.set': return this.savesSet(params);
-            case 'saves.delete': return this.savesDelete(params);
-            case 'saves.list': return this.savesList();
+            case 'saves.get': return this.kvGet(this.savesPrefix(), params);
+            case 'saves.set': return this.kvSet(this.savesPrefix(), params);
+            case 'saves.delete': return this.kvDelete(this.savesPrefix(), params);
+            case 'saves.list': return this.kvList(this.savesPrefix());
+            case 'gameData.get': return this.kvGet(this.gameDataPrefix(), params);
+            case 'gameData.set': return this.kvSet(this.gameDataPrefix(), params);
+            case 'gameData.delete': return this.kvDelete(this.gameDataPrefix(), params);
+            case 'gameData.list': return this.kvList(this.gameDataPrefix());
             default: throw new RpcError('UNKNOWN_METHOD', `Unknown method: ${method}`);
         }
     }
-    prefix() { return `unboxy:saves:${this.gameId}:`; }
-    read(key) {
+    savesPrefix() { return `unboxy:saves:${this.gameId}:`; }
+    gameDataPrefix() { return `unboxy:gameData:${this.gameId}:`; }
+    read(prefix, key) {
         if (typeof localStorage === 'undefined')
             return null;
-        const raw = localStorage.getItem(this.prefix() + key);
+        const raw = localStorage.getItem(prefix + key);
         if (!raw)
             return null;
         try {
@@ -33,41 +38,40 @@ export class LocalStorageTransport {
             return null;
         }
     }
-    write(key, rec) {
+    write(prefix, key, rec) {
         if (typeof localStorage === 'undefined')
             throw new RpcError('UNAVAILABLE', 'localStorage unavailable');
-        localStorage.setItem(this.prefix() + key, JSON.stringify(rec));
+        localStorage.setItem(prefix + key, JSON.stringify(rec));
     }
-    savesGet({ key }) {
-        const rec = this.read(key);
+    kvGet(prefix, { key }) {
+        const rec = this.read(prefix, key);
         return rec ? { value: rec.value, version: rec.version } : { value: null, version: null };
     }
-    savesSet({ key, value, ifVersion }) {
-        const existing = this.read(key);
+    kvSet(prefix, { key, value, ifVersion }) {
+        const existing = this.read(prefix, key);
         if (ifVersion !== undefined && existing && existing.version !== ifVersion) {
             throw new RpcError('VERSION_MISMATCH', `Expected version ${ifVersion} but stored is ${existing.version}`);
         }
         const next = { value, version: (existing?.version ?? 0) + 1 };
-        this.write(key, next);
+        this.write(prefix, key, next);
         return { version: next.version };
     }
-    savesDelete({ key }) {
+    kvDelete(prefix, { key }) {
         if (typeof localStorage === 'undefined')
             return { deleted: false };
-        const full = this.prefix() + key;
+        const full = prefix + key;
         const existed = localStorage.getItem(full) !== null;
         localStorage.removeItem(full);
         return { deleted: existed };
     }
-    savesList() {
+    kvList(prefix) {
         if (typeof localStorage === 'undefined')
             return { keys: [] };
         const keys = [];
-        const p = this.prefix();
         for (let i = 0; i < localStorage.length; i++) {
             const k = localStorage.key(i);
-            if (k && k.startsWith(p))
-                keys.push(k.slice(p.length));
+            if (k && k.startsWith(prefix))
+                keys.push(k.slice(prefix.length));
         }
         return { keys };
     }

package/dist/gamedata/GameDataModule.d.ts

@@ -0,0 +1,45 @@
+import type { Transport } from '../core/Transport.js';
+/**
+ * Game-scope key-value store shared by all players of a game.
+ *
+ * Unlike `unboxy.saves` (per-user), `gameData` lives at the game level — one
+ * value per key, visible to everyone. Reads are public (anonymous players
+ * see the same data). Writes require an authenticated user; calling
+ * `set()` or `delete()` when `unboxy.user === null` throws an `RpcError`
+ * with code `UNAUTHENTICATED`.
+ *
+ * Typical uses: scoreboards, shared inventories, tournament state, level
+ * of the day. Values are opaque JSON — primitive, object, or collection.
+ *
+ * Trust model (see SDK-GUIDE.md for details):
+ *   - The backend does not enforce invariants INSIDE a value. If you store
+ *     a list and append your entry, you own the read-modify-write loop —
+ *     including not mutating other players' entries, truncating to cap
+ *     the list size, and retrying on 409 conflicts.
+ *   - Use `ifVersion` to avoid lost updates when concurrent writes race.
+ *
+ * Quotas (enforced at the backend):
+ *   - 100 KB per value
+ *   - 1 MB total per game
+ *   - 64 keys per game
+ */
+export declare class GameDataModule {
+    private transport;
+    constructor(transport: Transport);
+    /** Read the value under `key`. Returns `null` if unset. Public — works for anonymous viewers. */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Write `value` under `key`. Requires an authenticated user.
+     * @param options.ifVersion — only succeed if the stored version matches; otherwise throws
+     *   an RpcError with code `VERSION_MISMATCH`. Use this to implement safe read-modify-write
+     *   loops for list values (scoreboards, shared lists).
+     * @returns the new version number.
+     */
+    set(key: string, value: unknown, options?: {
+        ifVersion?: number;
+    }): Promise<number>;
+    /** Delete the value at `key`. Requires an authenticated user. */
+    delete(key: string): Promise<boolean>;
+    /** List all keys that have a value set for this game. Public. */
+    list(): Promise<string[]>;
+}

package/dist/gamedata/GameDataModule.js

@@ -0,0 +1,59 @@
+/**
+ * Game-scope key-value store shared by all players of a game.
+ *
+ * Unlike `unboxy.saves` (per-user), `gameData` lives at the game level — one
+ * value per key, visible to everyone. Reads are public (anonymous players
+ * see the same data). Writes require an authenticated user; calling
+ * `set()` or `delete()` when `unboxy.user === null` throws an `RpcError`
+ * with code `UNAUTHENTICATED`.
+ *
+ * Typical uses: scoreboards, shared inventories, tournament state, level
+ * of the day. Values are opaque JSON — primitive, object, or collection.
+ *
+ * Trust model (see SDK-GUIDE.md for details):
+ *   - The backend does not enforce invariants INSIDE a value. If you store
+ *     a list and append your entry, you own the read-modify-write loop —
+ *     including not mutating other players' entries, truncating to cap
+ *     the list size, and retrying on 409 conflicts.
+ *   - Use `ifVersion` to avoid lost updates when concurrent writes race.
+ *
+ * Quotas (enforced at the backend):
+ *   - 100 KB per value
+ *   - 1 MB total per game
+ *   - 64 keys per game
+ */
+export class GameDataModule {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Read the value under `key`. Returns `null` if unset. Public — works for anonymous viewers. */
+    async get(key) {
+        const res = await this.transport.call('gameData.get', { key });
+        return (res?.value ?? null);
+    }
+    /**
+     * Write `value` under `key`. Requires an authenticated user.
+     * @param options.ifVersion — only succeed if the stored version matches; otherwise throws
+     *   an RpcError with code `VERSION_MISMATCH`. Use this to implement safe read-modify-write
+     *   loops for list values (scoreboards, shared lists).
+     * @returns the new version number.
+     */
+    async set(key, value, options) {
+        const res = await this.transport.call('gameData.set', {
+            key,
+            value,
+            ifVersion: options?.ifVersion,
+        });
+        return res.version;
+    }
+    /** Delete the value at `key`. Requires an authenticated user. */
+    async delete(key) {
+        const res = await this.transport.call('gameData.delete', { key });
+        return res.deleted;
+    }
+    /** List all keys that have a value set for this game. Public. */
+    async list() {
+        const res = await this.transport.call('gameData.list');
+        return res.keys;
+    }
+}

package/dist/index.d.ts

@@ -6,7 +6,8 @@ export { setupRecordingListener } from './recording/RecordingManager.js';
 export { Unboxy } from './core/Unboxy.js';
 export type { UnboxyInitOptions } from './core/Unboxy.js';
 export { SavesModule } from './saves/SavesModule.js';
+export { GameDataModule } from './gamedata/GameDataModule.js';
 export { RpcError } from './core/Transport.js';
 export type { Transport, TransportKind } from './core/Transport.js';
 export type { UnboxyUser } from './protocol.js';
-export { PROTOCOL_VERSION, type HelloMessage, type InitMessage, type RpcRequestMessage, type RpcResultOk, type RpcResultError, type HostToSdkMessage, type SdkToHostMessage, type RpcErrorPayload, type RpcMethod, type SavesGetParams, type SavesGetResult, type SavesSetParams, type SavesSetResult, type SavesDeleteParams, type SavesDeleteResult, type SavesListResult, } from './protocol.js';
+export { PROTOCOL_VERSION, type HelloMessage, type InitMessage, type RpcRequestMessage, type RpcResultOk, type RpcResultError, type HostToSdkMessage, type SdkToHostMessage, type RpcErrorPayload, type RpcMethod, type SavesGetParams, type SavesGetResult, type SavesSetParams, type SavesSetResult, type SavesDeleteParams, type SavesDeleteResult, type SavesListResult, type GameDataGetParams, type GameDataGetResult, type GameDataSetParams, type GameDataSetResult, type GameDataDeleteParams, type GameDataDeleteResult, type GameDataListResult, } from './protocol.js';

package/dist/index.js

@@ -8,5 +8,6 @@ export { setupRecordingListener } from './recording/RecordingManager.js';
 // Platform services (v0.2.1+)
 export { Unboxy } from './core/Unboxy.js';
 export { SavesModule } from './saves/SavesModule.js';
+export { GameDataModule } from './gamedata/GameDataModule.js';
 export { RpcError } from './core/Transport.js';
 export { PROTOCOL_VERSION, } from './protocol.js';

package/dist/protocol.d.ts

@@ -40,7 +40,7 @@ export interface RpcResultError {
     error: RpcErrorPayload;
 }
 export type HostToSdkMessage = InitMessage | RpcResultOk | RpcResultError;
-export type RpcMethod = 'saves.get' | 'saves.set' | 'saves.delete' | 'saves.list';
+export type RpcMethod = 'saves.get' | 'saves.set' | 'saves.delete' | 'saves.list' | 'gameData.get' | 'gameData.set' | 'gameData.delete' | 'gameData.list';
 export interface SavesGetParams {
     key: string;
 }
@@ -65,3 +65,27 @@ export type SavesDeleteResult = {
 export interface SavesListResult {
     keys: string[];
 }
+export interface GameDataGetParams {
+    key: string;
+}
+export interface GameDataGetResult {
+    value: unknown | null;
+    version: number | null;
+}
+export interface GameDataSetParams {
+    key: string;
+    value: unknown;
+    ifVersion?: number;
+}
+export interface GameDataSetResult {
+    version: number;
+}
+export interface GameDataDeleteParams {
+    key: string;
+}
+export type GameDataDeleteResult = {
+    deleted: boolean;
+};
+export interface GameDataListResult {
+    keys: string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboxy/phaser-sdk",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",