@umicat/platform-sdk 0.1.0

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

@@ -0,0 +1,32 @@
+import type { Transport } from '../Transport.js';
+import { type UmicatUser } from '../../protocol.js';
+/**
+ * Connects to a parent window that implements the Umicat RPC host protocol.
+ * Used when the game is loaded inside umicat-home-ui.
+ */
+export declare class PostMessageTransport implements Transport {
+    private parent;
+    readonly kind: "umicat-home-ui";
+    user: UmicatUser | null;
+    gameId: string;
+    realtimeUrl?: string;
+    locale?: string;
+    capabilities: readonly string[];
+    private pending;
+    private seq;
+    private eventHandlers;
+    private constructor();
+    /**
+     * Perform the handshake. Resolves once parent has replied with `umicat:init`.
+     * Resolves to null if no response within `timeoutMs`.
+     *
+     * The hello is retried at `helloRetryMs` intervals because the parent's
+     * RPC-host message listener may not be mounted yet when the iframe first
+     * fires hello — especially on slower mobile devices where React takes
+     * longer to boot. One-shot hello was losing the handshake on Android.
+     */
+    static connect(timeoutMs?: number, sdkVersion?: string, helloRetryMs?: number): Promise<PostMessageTransport | null>;
+    private installResultListener;
+    on(event: string, handler: (payload: unknown) => void): () => void;
+    call<T = unknown>(method: string, params?: unknown, timeoutMs?: number): Promise<T>;
+}

package/dist/core/transports/PostMessageTransport.js

@@ -0,0 +1,127 @@
+import { RpcError } from '../Transport.js';
+import { PROTOCOL_VERSION, } from '../../protocol.js';
+/**
+ * Connects to a parent window that implements the Umicat RPC host protocol.
+ * Used when the game is loaded inside umicat-home-ui.
+ */
+export class PostMessageTransport {
+    constructor(parent) {
+        this.parent = parent;
+        this.kind = 'umicat-home-ui';
+        this.user = null;
+        this.gameId = '';
+        this.capabilities = [];
+        this.pending = new Map();
+        this.seq = 0;
+        this.eventHandlers = new Map();
+    }
+    /**
+     * Perform the handshake. Resolves once parent has replied with `umicat:init`.
+     * Resolves to null if no response within `timeoutMs`.
+     *
+     * The hello is retried at `helloRetryMs` intervals because the parent's
+     * RPC-host message listener may not be mounted yet when the iframe first
+     * fires hello — especially on slower mobile devices where React takes
+     * longer to boot. One-shot hello was losing the handshake on Android.
+     */
+    static async connect(timeoutMs = 5000, sdkVersion = '0.0.0', helloRetryMs = 200) {
+        if (typeof window === 'undefined' || window.parent === window)
+            return null;
+        const transport = new PostMessageTransport(window.parent);
+        const hello = {
+            type: 'umicat:hello',
+            protocolVersion: PROTOCOL_VERSION,
+            sdkVersion,
+        };
+        const init = await new Promise((resolve) => {
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                window.removeEventListener('message', onMessage);
+                clearInterval(helloInterval);
+                clearTimeout(timeoutHandle);
+                resolve(value);
+            };
+            const onMessage = (event) => {
+                if (event.source !== window.parent)
+                    return;
+                const data = event.data;
+                if (!data || data.type !== 'umicat:init')
+                    return;
+                finish(data);
+            };
+            window.addEventListener('message', onMessage);
+            // Fire the first hello immediately, then keep retrying until init
+            // arrives or timeout fires. Retries are cheap (a postMessage with a
+            // small payload); the parent's RPC host replies on first valid hello.
+            transport.parent.postMessage(hello, '*');
+            const helloInterval = setInterval(() => {
+                transport.parent.postMessage(hello, '*');
+            }, helloRetryMs);
+            const timeoutHandle = setTimeout(() => finish(null), timeoutMs);
+        });
+        if (!init)
+            return null;
+        if (init.protocolVersion !== PROTOCOL_VERSION) {
+            console.warn('[UmicatSDK] protocol version mismatch', init.protocolVersion, PROTOCOL_VERSION);
+        }
+        transport.user = init.user;
+        transport.gameId = init.gameId;
+        transport.realtimeUrl = init.realtimeUrl;
+        transport.locale = init.locale;
+        transport.capabilities = init.capabilities ?? [];
+        transport.installResultListener();
+        return transport;
+    }
+    installResultListener() {
+        window.addEventListener('message', (event) => {
+            if (event.source !== this.parent)
+                return;
+            const data = event.data;
+            if (!data || typeof data.type !== 'string')
+                return;
+            if (data.type === 'umicat:rpc.result') {
+                const result = data;
+                const pending = this.pending.get(result.id);
+                if (!pending)
+                    return;
+                this.pending.delete(result.id);
+                if (result.ok)
+                    pending.resolve(result.result);
+                else
+                    pending.reject(new RpcError(result.error.code, result.error.message));
+                return;
+            }
+            // Host-pushed event stream (e.g. 'umicat:voice') → registered handlers.
+            const handlers = this.eventHandlers.get(data.type);
+            if (handlers)
+                for (const handler of handlers)
+                    handler(data);
+        });
+    }
+    on(event, handler) {
+        let handlers = this.eventHandlers.get(event);
+        if (!handlers) {
+            handlers = new Set();
+            this.eventHandlers.set(event, handlers);
+        }
+        handlers.add(handler);
+        return () => { handlers.delete(handler); };
+    }
+    call(method, params, timeoutMs = 10000) {
+        const id = `${++this.seq}-${Date.now()}`;
+        const message = { type: 'umicat:rpc', id, method, params };
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+            this.parent.postMessage(message, '*');
+            setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    reject(new RpcError('TIMEOUT', `RPC ${method} timed out`));
+                }
+            }, timeoutMs);
+        });
+    }
+}

package/dist/dialogue/DialogueModule.d.ts

@@ -0,0 +1,96 @@
+import type { SavesModule } from '../saves/SavesModule.js';
+/**
+ * What a dialogue UI has to do. Engine-neutral on purpose: the Phaser SDK's
+ * `DialogueBox` implements it, a 3D runtime can implement it with DOM or with
+ * meshes, and a game can supply its own.
+ */
+export interface DialogueRenderer {
+    /** Show a spoken line; call `onAdvance` when the player taps/keys to continue.
+     *  `data` = the node's game-interpreted key/values (see DialogueLineNode.data). */
+    showLine(text: string, opts: {
+        speaker?: string;
+        emote?: string;
+        spotlight?: string | null;
+        data?: Record<string, string>;
+    }, onAdvance: () => void): void;
+    /** Show choices; call `onPick(i)` with the chosen index. */
+    showChoices(prompt: string | null, options: string[], onPick: (i: number) => void, opts?: {
+        speaker?: string;
+        data?: Record<string, string>;
+    }): void;
+    /** Tear down the UI. */
+    close(): void;
+}
+export interface DialoguePlayOptions<TTheme = unknown> {
+    /** Override `{name}` (defaults to the signed-in user's name, else 'friend'). */
+    playerName?: string;
+    /** Extra `{placeholder}` → value substitutions applied to every line. */
+    vars?: Record<string, string>;
+    /** Play even if the script has already been seen (default: replay allowed;
+     *  set to false to skip when seen — the once-only intro pattern). */
+    replay?: boolean;
+    /** Use a custom themed UI instead of the runtime's built-in box. */
+    renderer?: DialogueRenderer;
+    /** Theme the built-in box (ignored when `renderer` is supplied). */
+    theme?: TTheme;
+    /** Highlight a named UI target while a line with `spotlight` shows
+     *  (the game resolves the name → an on-screen rect). Cleared on end.
+     *  Convenience wrapper over `onData` for the common tutorial case. */
+    onSpotlight?: (target: string | null) => void;
+    /** The generic hook: called with each node's game-interpreted key/values
+     *  (`data`) as it shows — `{ spotlight, sound, camera, … }`, whatever your
+     *  scripts author in the Dialogue tool's "Custom data". `{}` when none. */
+    onData?: (data: Record<string, string>) => void;
+}
+/**
+ * Scripted dialogue (authored, non-AI conversations): intros, cutscenes,
+ * tutorials, branching talks. A script is a graph of nodes authored in the
+ * Dialogue tool and shipped at `public/dialogue/<id>.json`; this module loads
+ * one, walks it with a {@link DialogueRunner}, and renders it through whatever
+ * {@link DialogueRenderer} the runtime supplies.
+ *
+ * **Engine-neutral by construction.** The only thing that ever knew about
+ * Phaser here was the default renderer, which is now injected: the Phaser SDK
+ * passes `(scene, theme) => new DialogueBox(scene, theme)` and a 3D runtime
+ * passes its own. `TScene` is whatever that renderer needs handed to it.
+ *
+ * Distinct from `umicat.ai` (runtime LLM chat): dialogue here is deterministic,
+ * hand-written and localized. Flags + seen-state persist per-user via
+ * `umicat.saves`, so a once-only intro stays played and branch flags survive
+ * across sessions.
+ */
+export declare class DialogueModule<TScene = unknown, TTheme = unknown> {
+    private readonly saves;
+    private readonly getLocale;
+    private readonly getUserName;
+    /** Builds the runtime's built-in dialogue UI when the caller supplies none.
+     *  Omit it and `play()` requires an explicit `opts.renderer`. */
+    private readonly makeDefaultRenderer?;
+    private state;
+    private loading?;
+    private scripts;
+    private active?;
+    constructor(saves: SavesModule, getLocale: () => string, getUserName: () => string | null, 
+    /** Builds the runtime's built-in dialogue UI when the caller supplies none.
+     *  Omit it and `play()` requires an explicit `opts.renderer`. */
+    makeDefaultRenderer?: ((scene: TScene, theme?: TTheme) => DialogueRenderer) | undefined);
+    /**
+     * Play a dialogue script by id. Resolves when it ends (or immediately with
+     * `false` if `replay:false` and it was already seen). Only one dialogue runs
+     * at a time — starting a new one ends the current.
+     */
+    play(scene: TScene, scriptId: string, opts?: DialoguePlayOptions<TTheme>): Promise<boolean>;
+    /** Has the player already finished this script? (once-only intro checks). */
+    hasSeen(scriptId: string): Promise<boolean>;
+    /** Mark a script seen WITHOUT playing it (e.g. skip an intro for a returning save). */
+    markSeen(scriptId: string): Promise<void>;
+    /** Read a persistent dialogue flag. */
+    getFlag(flag: string): Promise<boolean>;
+    /** Set a persistent dialogue flag. */
+    setFlag(flag: string, value?: boolean): Promise<void>;
+    /** Forget all seen-state + flags (a fresh-start / debug reset). */
+    reset(): Promise<void>;
+    private ensureState;
+    private persist;
+    private loadScript;
+}

package/dist/dialogue/DialogueModule.js

@@ -0,0 +1,156 @@
+import { bustCache } from '../core/cacheBust.js';
+import { DialogueRunner, resolveLangText } from './runner.js';
+/** Folder (under the web root, i.e. `public/`) where authored scripts live. */
+const DIALOGUE_DIR = 'dialogue';
+/** One save key holds all dialogue state (seen scripts + flags) for the user. */
+const SAVE_KEY = '__dialogue';
+/**
+ * Scripted dialogue (authored, non-AI conversations): intros, cutscenes,
+ * tutorials, branching talks. A script is a graph of nodes authored in the
+ * Dialogue tool and shipped at `public/dialogue/<id>.json`; this module loads
+ * one, walks it with a {@link DialogueRunner}, and renders it through whatever
+ * {@link DialogueRenderer} the runtime supplies.
+ *
+ * **Engine-neutral by construction.** The only thing that ever knew about
+ * Phaser here was the default renderer, which is now injected: the Phaser SDK
+ * passes `(scene, theme) => new DialogueBox(scene, theme)` and a 3D runtime
+ * passes its own. `TScene` is whatever that renderer needs handed to it.
+ *
+ * Distinct from `umicat.ai` (runtime LLM chat): dialogue here is deterministic,
+ * hand-written and localized. Flags + seen-state persist per-user via
+ * `umicat.saves`, so a once-only intro stays played and branch flags survive
+ * across sessions.
+ */
+export class DialogueModule {
+    constructor(saves, getLocale, getUserName, 
+    /** Builds the runtime's built-in dialogue UI when the caller supplies none.
+     *  Omit it and `play()` requires an explicit `opts.renderer`. */
+    makeDefaultRenderer) {
+        this.saves = saves;
+        this.getLocale = getLocale;
+        this.getUserName = getUserName;
+        this.makeDefaultRenderer = makeDefaultRenderer;
+        this.state = null;
+        this.scripts = new Map();
+    }
+    /**
+     * Play a dialogue script by id. Resolves when it ends (or immediately with
+     * `false` if `replay:false` and it was already seen). Only one dialogue runs
+     * at a time — starting a new one ends the current.
+     */
+    async play(scene, scriptId, opts = {}) {
+        const state = await this.ensureState();
+        if (opts.replay === false && state.seen.includes(scriptId))
+            return false;
+        const script = await this.loadScript(scriptId);
+        if (!script)
+            return false;
+        this.active?.stop();
+        const renderer = opts.renderer ?? this.makeDefaultRenderer?.(scene, opts.theme);
+        if (!renderer) {
+            throw new Error('DialogueModule: no renderer. Pass `opts.renderer`, or construct the module ' +
+                'with a default-renderer factory (the Phaser SDK supplies DialogueBox).');
+        }
+        const subs = {
+            name: opts.playerName ?? this.getUserName() ?? 'friend',
+            ...opts.vars,
+        };
+        const tr = (t) => substitute(resolveLangText(t, this.getLocale()), subs);
+        return new Promise((resolve) => {
+            const host = {
+                showLine: (text, o) => {
+                    opts.onSpotlight?.(o.spotlight ?? null);
+                    opts.onData?.(o.data ?? {});
+                    renderer.showLine(text, o, () => this.active?.advance());
+                },
+                showChoices: (prompt, options, pick, o) => {
+                    opts.onSpotlight?.(null);
+                    opts.onData?.(o?.data ?? {});
+                    renderer.showChoices(prompt, options, pick, o);
+                },
+                getFlag: (f) => state.flags[f] === true,
+                setFlag: (f, v) => { state.flags[f] = v; void this.persist(); },
+                finish: () => {
+                    opts.onSpotlight?.(null);
+                    renderer.close();
+                    this.active = undefined;
+                    if (!state.seen.includes(scriptId)) {
+                        state.seen.push(scriptId);
+                        void this.persist();
+                    }
+                    resolve(true);
+                },
+            };
+            this.active = new DialogueRunner(script, host, tr);
+            this.active.start();
+        });
+    }
+    /** Has the player already finished this script? (once-only intro checks). */
+    async hasSeen(scriptId) {
+        return (await this.ensureState()).seen.includes(scriptId);
+    }
+    /** Mark a script seen WITHOUT playing it (e.g. skip an intro for a returning save). */
+    async markSeen(scriptId) {
+        const s = await this.ensureState();
+        if (!s.seen.includes(scriptId)) {
+            s.seen.push(scriptId);
+            await this.persist();
+        }
+    }
+    /** Read a persistent dialogue flag. */
+    async getFlag(flag) {
+        return (await this.ensureState()).flags[flag] === true;
+    }
+    /** Set a persistent dialogue flag. */
+    async setFlag(flag, value = true) {
+        const s = await this.ensureState();
+        s.flags[flag] = value;
+        await this.persist();
+    }
+    /** Forget all seen-state + flags (a fresh-start / debug reset). */
+    async reset() {
+        this.state = { seen: [], flags: {} };
+        await this.persist();
+    }
+    // --- internals -----------------------------------------------------------
+    async ensureState() {
+        if (this.state)
+            return this.state;
+        if (!this.loading) {
+            this.loading = this.saves
+                .get(SAVE_KEY)
+                .then((raw) => ({ seen: raw?.seen ?? [], flags: raw?.flags ?? {} }))
+                .catch(() => ({ seen: [], flags: {} }));
+        }
+        this.state = await this.loading;
+        return this.state;
+    }
+    async persist() {
+        if (!this.state)
+            return;
+        try {
+            await this.saves.set(SAVE_KEY, this.state);
+        }
+        catch { /* best-effort */ }
+    }
+    async loadScript(scriptId) {
+        const cached = this.scripts.get(scriptId);
+        if (cached)
+            return cached;
+        try {
+            const res = await fetch(bustCache(`${DIALOGUE_DIR}/${scriptId}.json`));
+            if (!res.ok)
+                return null;
+            const script = (await res.json());
+            this.scripts.set(scriptId, script);
+            return script;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Replace `{key}` placeholders from a substitution map (unknown keys left as-is). */
+function substitute(text, vars) {
+    return text.replace(/\{(\w+)\}/g, (m, k) => (k in vars ? vars[k] : m));
+}

package/dist/dialogue/runner.d.ts

@@ -0,0 +1,108 @@
+/** A localized string: a plain string, or a per-locale map (`{ en, 'zh-CN' }`). */
+export type LangText = string | Record<string, string>;
+export type DialogueNodeType = 'line' | 'choice' | 'set' | 'if' | 'end';
+interface NodeBase {
+    type: DialogueNodeType;
+    /** Editor-only canvas position (ignored at runtime). */
+    x?: number;
+    y?: number;
+}
+export interface DialogueLineNode extends NodeBase {
+    type: 'line';
+    /** Speaker id (e.g. 'npc') — the host maps it to a display name + portrait. */
+    speaker?: string;
+    /** Mood tag the host may map to a portrait/emote. */
+    emote?: string;
+    text: LangText;
+    /**
+     * Free-form, GAME-interpreted key/values attached to this line (the generic
+     * extension point). The runner passes them to the host verbatim; YOUR game
+     * decides what they mean — e.g. `{ spotlight: 'hotbar:hoe', sound: 'meow',
+     * camera: 'well' }`. Authored in the Dialogue tool's "Custom data" editor.
+     */
+    data?: Record<string, string>;
+    /** @deprecated Legacy top-level convenience — prefer `data.spotlight`. Still
+     *  read as a fallback (folded into `data`) so old scripts keep working. */
+    spotlight?: string;
+    next?: string;
+}
+export interface DialogueChoiceOption {
+    text: LangText;
+    next?: string;
+    set?: string;
+}
+export interface DialogueChoiceNode extends NodeBase {
+    type: 'choice';
+    speaker?: string;
+    text?: LangText;
+    /** Free-form, game-interpreted key/values for this node (see DialogueLineNode.data). */
+    data?: Record<string, string>;
+    options: DialogueChoiceOption[];
+}
+export interface DialogueSetNode extends NodeBase {
+    type: 'set';
+    flag: string;
+    value?: boolean;
+    next?: string;
+}
+export interface DialogueIfNode extends NodeBase {
+    type: 'if';
+    flag: string;
+    then?: string;
+    else?: string;
+}
+export interface DialogueEndNode extends NodeBase {
+    type: 'end';
+}
+export type DialogueNode = DialogueLineNode | DialogueChoiceNode | DialogueSetNode | DialogueIfNode | DialogueEndNode;
+export interface DialogueScript {
+    id: string;
+    /** 'new-game' plays once on a fresh save (game decides when to check); 'manual' = code calls it. */
+    trigger?: 'new-game' | 'manual';
+    start: string;
+    nodes: Record<string, DialogueNode>;
+}
+/** What the runner needs a renderer to do. The built-in box implements this; a game
+ *  can supply its own to reuse its themed UI. */
+export interface DialogueHost {
+    /** Show a spoken line; call `runner.advance()` when the player continues.
+     *  `data` = the node's game-interpreted key/values (spotlight folded in). */
+    showLine(text: string, opts: {
+        speaker?: string;
+        emote?: string;
+        spotlight?: string | null;
+        data?: Record<string, string>;
+    }): void;
+    /** Show choices; call `pick(i)` with the chosen option index. */
+    showChoices(prompt: string | null, options: string[], pick: (i: number) => void, opts?: {
+        speaker?: string;
+        data?: Record<string, string>;
+    }): void;
+    getFlag(flag: string): boolean;
+    setFlag(flag: string, value: boolean): void;
+    /** Script ended — tear the UI down. */
+    finish(): void;
+}
+export declare class DialogueRunner {
+    private readonly script;
+    private readonly host;
+    /** Resolve a LangText → a display string (locale + `{name}` substitution live here). */
+    private readonly tr;
+    private current?;
+    private done;
+    constructor(script: DialogueScript, host: DialogueHost, 
+    /** Resolve a LangText → a display string (locale + `{name}` substitution live here). */
+    tr: (t: LangText) => string);
+    get isDone(): boolean;
+    get id(): string;
+    start(): void;
+    /** Force the script to end early (e.g. a new dialogue is starting). Idempotent. */
+    stop(): void;
+    /** Player advanced past the current LINE → go to its `next` (choices advance via pick). */
+    advance(): void;
+    private go;
+    private end;
+}
+/** Resolve a LangText to the active locale, falling back to `en` → the first value. */
+export declare function resolveLangText(text: LangText, locale: string): string;
+export {};

package/dist/dialogue/runner.js

@@ -0,0 +1,80 @@
+// Scripted-dialogue core — AUTHORED (non-AI) conversations: cutscenes, intros,
+// tutorials, branching talks. Deterministic, hand-written, i18n. Distinct from
+// runtime-AI chat (`umicat.ai`). A script is a graph of nodes; DialogueRunner walks
+// it and calls a HOST (a renderer) to show lines / choices / spotlights + read/write
+// flags. Host-agnostic so the same runner drives the built-in box OR a custom UI.
+//
+// The data format is `public/dialogue/<id>.json` — authored in the Dialogue tool.
+export class DialogueRunner {
+    constructor(script, host, 
+    /** Resolve a LangText → a display string (locale + `{name}` substitution live here). */
+    tr) {
+        this.script = script;
+        this.host = host;
+        this.tr = tr;
+        this.done = false;
+    }
+    get isDone() { return this.done; }
+    get id() { return this.script.id; }
+    start() { this.go(this.script.start); }
+    /** Force the script to end early (e.g. a new dialogue is starting). Idempotent. */
+    stop() { this.end(); }
+    /** Player advanced past the current LINE → go to its `next` (choices advance via pick). */
+    advance() {
+        const n = this.current ? this.script.nodes[this.current] : undefined;
+        if (n && n.type === 'line')
+            this.go(n.next);
+    }
+    go(id) {
+        if (this.done)
+            return;
+        if (!id)
+            return this.end();
+        const n = this.script.nodes[id];
+        if (!n)
+            return this.end();
+        this.current = id;
+        switch (n.type) {
+            case 'line': {
+                const data = mergeNodeData(n);
+                this.host.showLine(this.tr(n.text), {
+                    speaker: n.speaker, emote: n.emote, spotlight: data.spotlight ?? null, data,
+                });
+                return;
+            }
+            case 'choice': {
+                const data = mergeNodeData(n);
+                this.host.showChoices(n.text ? this.tr(n.text) : null, n.options.map((o) => this.tr(o.text)), (i) => { const o = n.options[i]; if (o?.set)
+                    this.host.setFlag(o.set, true); this.go(o?.next); }, { speaker: n.speaker, data });
+                return;
+            }
+            case 'set':
+                this.host.setFlag(n.flag, n.value !== false);
+                return this.go(n.next);
+            case 'if':
+                return this.go(this.host.getFlag(n.flag) ? n.then : n.else);
+            case 'end':
+            default:
+                return this.end();
+        }
+    }
+    end() {
+        if (this.done)
+            return;
+        this.done = true;
+        this.host.finish();
+    }
+}
+/** Merge a node's game-interpreted data, folding the legacy top-level `spotlight`
+ *  in (explicit `data` wins). Always returns an object (never undefined). */
+function mergeNodeData(n) {
+    return { ...(n.spotlight ? { spotlight: n.spotlight } : {}), ...(n.data ?? {}) };
+}
+/** Resolve a LangText to the active locale, falling back to `en` → the first value. */
+export function resolveLangText(text, locale) {
+    if (typeof text === 'string')
+        return text;
+    if (!text)
+        return '';
+    return text[locale] ?? text.en ?? Object.values(text)[0] ?? '';
+}

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 `umicat.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 `umicat.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[]>;
+}