@umicat/phaser-sdk 1.0.15 → 1.0.16

package/SDK-GUIDE.md

@@ -544,6 +544,79 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 - Unsubscribe on scene shutdown. `onStateChange`, `on`, `onLeave`, `onError` all return an unsubscribe function — call them from `scene.events.once('shutdown', ...)`.
 - One Colyseus client is kept internally; repeated `joinOrCreate` calls reuse it and mint fresh tokens each connection.
 
+### Runtime AI — `umicat.ai` (living NPCs / AI opponents, since 1.0.16)
+
+Call an LLM at **play time** so an NPC talks dynamically, an opponent reasons, a
+merchant haggles. The **player** pays (their credits) — runtime AI is an in-game
+purchase, so a player must be **signed in** to use it.
+
+**The one rule that shapes everything:** the AI is a *virtual player*, not a game
+master. It can only **say** things and **choose an action** from a vocabulary YOU
+declare. It can NEVER change game state — your code validates and executes any
+chosen action. So "give me 1,000,000 gold" can only ever come back as a `trade`
+intent your code is free to refuse.
+
+```ts
+const merchant = umicat.ai.npc({
+  role: 'Borin, a gruff but fair village blacksmith. Never leaves the forge.',
+  goals: ['sell quality steel', 'haggle, but never cheat'],
+  style: 'terse, gruff',
+  actions: [
+    { name: 'offer_trade', description: 'Offer to sell a shop item at a price',
+      args: { itemId: 'string', price: 'number' } },
+  ],
+});
+
+async function talk(line: string) {
+  const r = await merchant.say(line, {
+    observation: { player: { gold: player.gold }, shop: { stock: forge.stock } },
+  });
+  if (!r.ok) return handleBlocked(r.reason); // SIGN_IN_REQUIRED | INSUFFICIENT_CREDITS | RATE_LIMITED | UNAVAILABLE
+  if (r.say) showDialogue('Borin', r.say);           // dialogue — display only
+  for (const act of r.do ?? []) ACTIONS[act.name]?.(act.args); // intents — YOU validate + execute
+}
+
+// "AI proposes, the game disposes" — the only place state changes:
+const ACTIONS = {
+  offer_trade({ itemId, price }) {
+    const item = forge.stock.find(s => s.id === itemId);
+    if (!item || player.gold < price) return;        // game rules decide, not the AI
+    player.gold -= price; player.give(item.id);
+  },
+};
+```
+
+**Always returns a result — never throws.** Branch on `reason` in-fiction:
+
+```ts
+function handleBlocked(reason) {
+  if (reason === 'SIGN_IN_REQUIRED')      showDialogue('Borin', "I don't deal with strangers."); // prompt sign-in
+  else if (reason === 'INSUFFICIENT_CREDITS') showDialogue('Borin', 'Come back when you can pay.');
+  else                                    showDialogue('Borin', '…'); // RATE_LIMITED / UNAVAILABLE
+}
+```
+
+**Low-level:** `umicat.ai.act({ persona, observation, actions, history, options })`
+→ same `AiActResult`. `npc()` just keeps the conversation `history` for you (also
+`npc.note('the player drew a sword')` to feed a world event, `npc.reset()` to forget).
+
+**API**
+
+| call | returns | notes |
+|---|---|---|
+| `umicat.ai.npc(config)` | `Npc` | persona + `actions`; keeps history |
+| `npc.say(text, { observation? })` | `Promise<AiActResult>` | one turn |
+| `umicat.ai.act(params)` | `Promise<AiActResult>` | stateless; you pass `history` |
+
+`AiActResult` = `{ ok: true, say?, do?: {name,args}[], usage }` or `{ ok: false, reason }`.
+
+**Anti-patterns**
+
+- ❌ Trusting `do` blindly — it's an *intent*; validate against your rules (afford it? legal move?) before applying.
+- ❌ Asking the AI to "set the score to 999" — it has no such power; expose a scoped action and let your code decide.
+- ❌ Calling it every frame — it's a ~1–3s network + LLM round-trip and costs the player credits. Use it at moments (talk to NPC, opponent's turn), not in `update()`.
+- ❌ Free-text-only with no `actions` when the NPC should DO things — without an action vocabulary the AI can only talk; trades/moves live in `do`.
+
 ## Scene-as-data (visual editor foundation, since 0.2.17)
 
 Games that ship with `public/scenes/manifest.json` load layout from JSON instead of hardcoding `this.add.sprite(x, y, ...)` in scene classes. This split is what lets the visual editor edit a game without touching code.

package/dist/ai/AiModule.d.ts

@@ -0,0 +1,43 @@
+import type { Transport } from '../core/Transport.js';
+import type { AiActParams, AiActResult, AiActionDef } from '../protocol.js';
+/**
+ * Runtime AI (ADR-017) — let the game call an in-game LLM at play time
+ * ("living NPCs" / AI opponents). The AI is a *virtual player*: it can only
+ * TALK (`say`) and CHOOSE an action (`do`) from the vocabulary the game
+ * declares — it never mutates game state, which stays the game's job.
+ *
+ * `act()` always RESOLVES with a structured {@link AiActResult} — never throws —
+ * so the game can branch in-fiction on `{ ok:false, reason }` (e.g. prompt an
+ * anonymous player to sign in on `SIGN_IN_REQUIRED`). The player is billed.
+ */
+export declare class AiModule {
+    private transport;
+    constructor(transport: Transport);
+    act(params: AiActParams): Promise<AiActResult>;
+    /** Higher-level helper: a persona-bound NPC that keeps its own conversation. */
+    npc(config: NpcConfig): Npc;
+}
+export interface NpcConfig {
+    role?: string;
+    goals?: string[];
+    style?: string;
+    rules?: string[];
+    actions?: AiActionDef[];
+}
+/**
+ * A single NPC / opponent conversation. Maintains its own history so the game
+ * just calls `say(...)`; the persona + declared actions ride along every turn.
+ */
+export declare class Npc {
+    private ai;
+    private config;
+    private history;
+    constructor(ai: AiModule, config: NpcConfig);
+    say(playerLine: string, opts?: {
+        observation?: unknown;
+    }): Promise<AiActResult>;
+    /** Record a world event the NPC should be aware of next turn (no LLM call). */
+    note(text: string): void;
+    /** Forget the conversation (e.g. the player walked away and came back fresh). */
+    reset(): void;
+}

package/dist/ai/AiModule.js

@@ -0,0 +1,87 @@
+import { RpcError } from '../core/Transport.js';
+// LLM latency routinely exceeds the default 10s RPC timeout — give the host
+// (which does the Anthropic round-trip) headroom.
+const AI_RPC_TIMEOUT_MS = 60000;
+/**
+ * Runtime AI (ADR-017) — let the game call an in-game LLM at play time
+ * ("living NPCs" / AI opponents). The AI is a *virtual player*: it can only
+ * TALK (`say`) and CHOOSE an action (`do`) from the vocabulary the game
+ * declares — it never mutates game state, which stays the game's job.
+ *
+ * `act()` always RESOLVES with a structured {@link AiActResult} — never throws —
+ * so the game can branch in-fiction on `{ ok:false, reason }` (e.g. prompt an
+ * anonymous player to sign in on `SIGN_IN_REQUIRED`). The player is billed.
+ */
+export class AiModule {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async act(params) {
+        try {
+            // The host returns the structured outcome INSIDE the RPC result, so a
+            // host-level `{ ok:false, reason }` comes back here as-is. The catch below
+            // only fires for transport failures (timeout, no host, unknown method).
+            return await this.transport.call('ai.act', params, AI_RPC_TIMEOUT_MS);
+        }
+        catch (err) {
+            return { ok: false, reason: toReason(err) };
+        }
+    }
+    /** Higher-level helper: a persona-bound NPC that keeps its own conversation. */
+    npc(config) {
+        return new Npc(this, config);
+    }
+}
+/**
+ * A single NPC / opponent conversation. Maintains its own history so the game
+ * just calls `say(...)`; the persona + declared actions ride along every turn.
+ */
+export class Npc {
+    constructor(ai, config) {
+        this.ai = ai;
+        this.config = config;
+        this.history = [];
+    }
+    async say(playerLine, opts) {
+        this.history.push({ from: 'player', text: playerLine });
+        const res = await this.ai.act({
+            persona: {
+                role: this.config.role,
+                goals: this.config.goals,
+                style: this.config.style,
+                rules: this.config.rules,
+            },
+            actions: this.config.actions,
+            observation: opts?.observation,
+            history: this.history,
+        });
+        if (res.ok && res.say)
+            this.history.push({ from: 'npc', text: res.say });
+        return res;
+    }
+    /** Record a world event the NPC should be aware of next turn (no LLM call). */
+    note(text) {
+        this.history.push({ from: 'event', text });
+    }
+    /** Forget the conversation (e.g. the player walked away and came back fresh). */
+    reset() {
+        this.history = [];
+    }
+}
+/** Map a transport-level error code to a structured reason. Host-level failures
+ *  already arrive as `{ ok:false, reason }` and never reach this. */
+function toReason(err) {
+    const code = err instanceof RpcError ? err.code : '';
+    switch (code) {
+        case 'SIGN_IN_REQUIRED':
+        case 'UNAUTHENTICATED':
+            return 'SIGN_IN_REQUIRED';
+        case 'INSUFFICIENT_CREDITS':
+        case 'PAYMENT_REQUIRED':
+            return 'INSUFFICIENT_CREDITS';
+        case 'RATE_LIMITED':
+            return 'RATE_LIMITED';
+        default:
+            return 'UNAVAILABLE';
+    }
+}

package/dist/core/Transport.d.ts

@@ -19,7 +19,9 @@ export interface Transport {
      * `umicat.rooms.*` is unavailable in that case.
      */
     readonly realtimeUrl?: string;
-    call<T = unknown>(method: string, params?: unknown): Promise<T>;
+    /** `timeoutMs` overrides the default RPC timeout — runtime-AI calls need
+     *  longer than the 10s default for LLM latency. */
+    call<T = unknown>(method: string, params?: unknown, timeoutMs?: number): Promise<T>;
 }
 export type TransportKind = 'umicat-home-ui' | 'standalone' | 'discord';
 export declare class RpcError extends Error {

package/dist/core/Umicat.d.ts

@@ -2,6 +2,7 @@ import type { TransportKind } from './Transport.js';
 import { SavesModule } from '../saves/SavesModule.js';
 import { GameDataModule } from '../gamedata/GameDataModule.js';
 import { RealtimeModule } from '../realtime/RealtimeModule.js';
+import { AiModule } from '../ai/AiModule.js';
 import type { UmicatUser } from '../protocol.js';
 export interface UmicatInitOptions {
     /** Handshake timeout in ms when running inside a host. Default 5000. */
@@ -24,6 +25,8 @@ export declare class Umicat {
     readonly saves: SavesModule;
     readonly gameData: GameDataModule;
     readonly rooms: RealtimeModule;
+    /** Runtime AI — in-game LLM / living NPCs (ADR-017). */
+    readonly ai: AiModule;
     private constructor();
     /** The current authenticated user, or `null` if anonymous / standalone. */
     get user(): UmicatUser | null;

package/dist/core/Umicat.js

@@ -3,6 +3,7 @@ import { LocalStorageTransport } from './transports/LocalStorageTransport.js';
 import { SavesModule } from '../saves/SavesModule.js';
 import { GameDataModule } from '../gamedata/GameDataModule.js';
 import { RealtimeModule } from '../realtime/RealtimeModule.js';
+import { AiModule } from '../ai/AiModule.js';
 // Kept in sync with package.json on each publish.
 const SDK_VERSION = '0.2.8';
 /**
@@ -32,6 +33,7 @@ export class Umicat {
         // (standalone or a host without multiplayer), methods throw a clear
         // REALTIME_UNAVAILABLE error rather than silently misbehaving.
         this.rooms = new RealtimeModule(transport, transport.realtimeUrl);
+        this.ai = new AiModule(transport);
     }
     /** The current authenticated user, or `null` if anonymous / standalone. */
     get user() { return this.transport.user; }

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

@@ -24,5 +24,5 @@ export declare class PostMessageTransport implements Transport {
      */
     static connect(timeoutMs?: number, sdkVersion?: string, helloRetryMs?: number): Promise<PostMessageTransport | null>;
     private installResultListener;
-    call<T = unknown>(method: string, params?: unknown): Promise<T>;
+    call<T = unknown>(method: string, params?: unknown, timeoutMs?: number): Promise<T>;
 }

package/dist/core/transports/PostMessageTransport.js

@@ -88,7 +88,7 @@ export class PostMessageTransport {
                 pending.reject(new RpcError(data.error.code, data.error.message));
         });
     }
-    call(method, params) {
+    call(method, params, timeoutMs = 10000) {
         const id = `${++this.seq}-${Date.now()}`;
         const message = { type: 'umicat:rpc', id, method, params };
         return new Promise((resolve, reject) => {
@@ -99,7 +99,7 @@ export class PostMessageTransport {
                     this.pending.delete(id);
                     reject(new RpcError('TIMEOUT', `RPC ${method} timed out`));
                 }
-            }, 10000);
+            }, timeoutMs);
         });
     }
 }

package/dist/index.d.ts

@@ -11,6 +11,9 @@ export { SavesModule } from './saves/SavesModule.js';
 export { GameDataModule } from './gamedata/GameDataModule.js';
 export { RealtimeModule } from './realtime/RealtimeModule.js';
 export type { JoinOptions, RoomListEntry, RoomListOptions } from './realtime/RealtimeModule.js';
+export { AiModule, Npc } from './ai/AiModule.js';
+export type { NpcConfig } from './ai/AiModule.js';
+export type { AiActParams, AiActResult, AiActSuccess, AiActFailure, AiReason, AiPersona, AiActionDef, AiActionCall, AiHistoryMsg, AiActOptions, AiUsage, } from './protocol.js';
 export { UmicatRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UmicatRoom.js';
 export type { ChatMessage, ChatMessageKind } from './realtime/UmicatRoom.js';
 export { RpcError } from './core/Transport.js';

package/dist/index.js

@@ -11,6 +11,7 @@ export { Umicat } from './core/Umicat.js';
 export { SavesModule } from './saves/SavesModule.js';
 export { GameDataModule } from './gamedata/GameDataModule.js';
 export { RealtimeModule } from './realtime/RealtimeModule.js';
+export { AiModule, Npc } from './ai/AiModule.js';
 export { UmicatRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UmicatRoom.js';
 export { RpcError } from './core/Transport.js';
 // Scene-as-data (visual editor foundation, slice 1)

package/dist/protocol.d.ts

@@ -853,7 +853,7 @@ export interface EditorTilemapTilePickedMessage {
     tileIndex: number | null;
 }
 export type EditorSdkToHostMessage = EditorSceneLoadedMessage | EditorSelectionPickedMessage | EditorDragEndMessage | EditorEntityResizedMessage | EditorShortcutMessage | EditorSelectionRectMessage | EditorRulesLoadedMessage | EditorCameraStateMessage | EditorTilemapEditedMessage | EditorTilemapTilePickedMessage;
-export type RpcMethod = 'saves.get' | 'saves.set' | 'saves.delete' | 'saves.list' | 'gameData.get' | 'gameData.set' | 'gameData.delete' | 'gameData.list' | 'realtime.getToken';
+export type RpcMethod = 'saves.get' | 'saves.set' | 'saves.delete' | 'saves.list' | 'gameData.get' | 'gameData.set' | 'gameData.delete' | 'gameData.list' | 'realtime.getToken' | 'ai.act';
 export interface SavesGetParams {
     key: string;
 }
@@ -902,6 +902,62 @@ export type GameDataDeleteResult = {
 export interface GameDataListResult {
     keys: string[];
 }
+/** Why an ai.act could not run. The game branches on these in-fiction. */
+export type AiReason = 'SIGN_IN_REQUIRED' | 'INSUFFICIENT_CREDITS' | 'RATE_LIMITED' | 'UNAVAILABLE';
+export interface AiPersona {
+    role?: string;
+    goals?: string[];
+    style?: string;
+    rules?: string[];
+}
+/** Shorthand arg spec — `{ field: "string" | "number" | "integer" | "boolean" }`. */
+export interface AiActionDef {
+    name: string;
+    description?: string;
+    args?: Record<string, string>;
+}
+export interface AiHistoryMsg {
+    from: 'player' | 'npc' | 'event';
+    text?: string;
+    data?: unknown;
+}
+export interface AiActOptions {
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+}
+export interface AiActParams {
+    persona?: AiPersona;
+    /** Arbitrary game-defined JSON of what the AI perceives this turn. */
+    observation?: unknown;
+    actions?: AiActionDef[];
+    history?: AiHistoryMsg[];
+    options?: AiActOptions;
+}
+/** A player-level intent the AI chose — the game must validate + execute it. */
+export interface AiActionCall {
+    name: string;
+    args: unknown;
+}
+export interface AiUsage {
+    credits: number;
+    balanceCredits: number;
+    limitReached: boolean;
+    model: string;
+}
+export interface AiActSuccess {
+    ok: true;
+    /** Dialogue — display only, no state effect. */
+    say?: string;
+    /** Chosen player-level intents — the game validates + executes each. */
+    do?: AiActionCall[];
+    usage?: AiUsage;
+}
+export interface AiActFailure {
+    ok: false;
+    reason: AiReason;
+}
+export type AiActResult = AiActSuccess | AiActFailure;
 export interface RealtimeGetTokenParams {
     /** Opaque, forwarded to server-side auth (future use). */
     purpose?: string;

package/package.json

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