@umicat/phaser-sdk 1.0.16 → 1.0.18

package/SDK-GUIDE.md

@@ -79,9 +79,14 @@ if (umicat) {
   umicat.isAuthenticated; // boolean
   umicat.gameId;          // stable platform-issued game id
   umicat.host;            // 'umicat-home-ui' | 'standalone' | 'discord' (future)
+  umicat.locale;          // player's UI language, e.g. 'en' | 'zh-CN' (string)
 }
 ```
 
+`umicat.locale` (since 1.0.17) is the player's preferred language from the host —
+default your game's UI + AI-NPC language to it instead of asking. For multi-language
+games + the **CJK font handling** that avoids tofu boxes, see the `game-i18n` skill.
+
 ### Save data — `umicat.saves`
 
 Per-user key-value store scoped to `(gameId, userId)`. Backed by the Umicat backend when authenticated, by localStorage when standalone/anonymous — **the API is identical either way**. Games should never branch on auth state for save logic.
@@ -600,11 +605,48 @@ function handleBlocked(reason) {
 → 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).
 
+#### Playbooks — keep persona + strategy out of code (since 1.0.18)
+
+For anything past a one-line shopkeeper, write the NPC's **persona + strategy as
+natural language** in `public/playbooks/<name>.md` and reference it by name. Code
+keeps owning the **action vocabulary** (what the NPC *can* do) and the handlers
+that validate + execute; the playbook owns **who it is and how it plays** (what to
+do, when, why). You tune behavior by editing the `.md` — no code change, and a
+non-coder can do it.
+
+`public/playbooks/wolf.md`:
+```md
+You are a Werewolf, secretly on the wolf team. Your partner is another wolf.
+
+Goal: survive to the end. Never reveal your team.
+- By day, blend in. Sound like a worried villager hunting wolves.
+- Cast suspicion subtly — agree with the room, then nudge it toward a villager.
+- If accused, stay calm; over-defending looks guilty. Deflect to someone quieter.
+- Don't out your partner; don't obviously defend them either.
+```
+
+```ts
+const wolf = umicat.ai.npc({
+  playbook: 'wolf',                       // → public/playbooks/wolf.md
+  actions: [                              // the vocabulary stays in code
+    { name: 'vote', description: 'Vote to eliminate a player', args: { target: 'string' } },
+  ],
+});
+const r = await wolf.say('It is day. Discuss.', { observation: { alive, votesSoFar } });
+```
+
+The host resolves the playbook under the game's own id, so pass **only the name** —
+a player can't point it at another game. The playbook is content *inside* the
+game's fiction: the platform safety rules and your `actions` still bound it; it
+can't grant powers your code didn't declare. One playbook per NPC keeps each call
+focused (a Werewolf game has `wolf.md` / `seer.md` / `villager.md`, loaded per
+speaker). Edit + re-publish to ship a behavior change.
+
 **API**
 
 | call | returns | notes |
 |---|---|---|
-| `umicat.ai.npc(config)` | `Npc` | persona + `actions`; keeps history |
+| `umicat.ai.npc(config)` | `Npc` | `playbook` (or inline persona) + `actions`; keeps history |
 | `npc.say(text, { observation? })` | `Promise<AiActResult>` | one turn |
 | `umicat.ai.act(params)` | `Promise<AiActResult>` | stateless; you pass `history` |
 

package/dist/ai/AiModule.d.ts

@@ -18,6 +18,13 @@ export declare class AiModule {
     npc(config: NpcConfig): Npc;
 }
 export interface NpcConfig {
+    /**
+     * Name of a playbook shipped at `public/playbooks/<name>.md` (ADR-018) — the
+     * NPC's persona + strategy as editable natural language, kept OUT of code.
+     * Preferred over the inline `role`/`goals`/`style` for any non-trivial
+     * character (you can tune behavior by editing the `.md`, no code change).
+     */
+    playbook?: string;
     role?: string;
     goals?: string[];
     style?: string;

package/dist/ai/AiModule.js

@@ -45,6 +45,7 @@ export class Npc {
     async say(playerLine, opts) {
         this.history.push({ from: 'player', text: playerLine });
         const res = await this.ai.act({
+            playbook: this.config.playbook,
             persona: {
                 role: this.config.role,
                 goals: this.config.goals,

package/dist/core/Transport.d.ts

@@ -19,6 +19,9 @@ export interface Transport {
      * `umicat.rooms.*` is unavailable in that case.
      */
     readonly realtimeUrl?: string;
+    /** The player's preferred language (BCP-47-ish, e.g. 'en', 'zh-CN'). The host
+     *  provides it at handshake; standalone falls back to the browser locale. */
+    readonly locale?: string;
     /** `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>;

package/dist/core/Umicat.d.ts

@@ -33,6 +33,9 @@ export declare class Umicat {
     get isAuthenticated(): boolean;
     /** Stable game identifier issued by the host. May be a placeholder when standalone. */
     get gameId(): string;
+    /** The player's preferred language (e.g. 'en', 'zh-CN'). Use it to default the
+     *  game's UI + AI NPC language. See the game-i18n skill. */
+    get locale(): string;
     /** Which transport Umicat.init() selected. Useful for debugging. */
     get host(): TransportKind;
     /**

package/dist/core/Umicat.js

@@ -40,6 +40,9 @@ export class Umicat {
     get isAuthenticated() { return this.transport.user !== null; }
     /** Stable game identifier issued by the host. May be a placeholder when standalone. */
     get gameId() { return this.transport.gameId; }
+    /** The player's preferred language (e.g. 'en', 'zh-CN'). Use it to default the
+     *  game's UI + AI NPC language. See the game-i18n skill. */
+    get locale() { return this.transport.locale ?? 'en'; }
     /** Which transport Umicat.init() selected. Useful for debugging. */
     get host() { return this.transport.kind; }
     /**

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

@@ -9,6 +9,7 @@ export declare class LocalStorageTransport implements Transport {
     readonly gameId: string;
     readonly kind: "standalone";
     readonly user: UmicatUser | null;
+    readonly locale: string;
     constructor(gameId: string);
     call<T = unknown>(method: string, params?: unknown): Promise<T>;
     private savesPrefix;

package/dist/core/transports/LocalStorageTransport.js

@@ -9,6 +9,8 @@ export class LocalStorageTransport {
         this.gameId = gameId;
         this.kind = 'standalone';
         this.user = null;
+        // No host to tell us the player's language — best-effort from the browser.
+        this.locale = (typeof navigator !== 'undefined' && navigator.language) ? navigator.language : 'en';
     }
     async call(method, params) {
         switch (method) {

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

@@ -10,6 +10,7 @@ export declare class PostMessageTransport implements Transport {
     user: UmicatUser | null;
     gameId: string;
     realtimeUrl?: string;
+    locale?: string;
     private pending;
     private seq;
     private constructor();

package/dist/core/transports/PostMessageTransport.js

@@ -68,6 +68,7 @@ export class PostMessageTransport {
         transport.user = init.user;
         transport.gameId = init.gameId;
         transport.realtimeUrl = init.realtimeUrl;
+        transport.locale = init.locale;
         transport.installResultListener();
         return transport;
     }

package/dist/protocol.d.ts

@@ -28,6 +28,12 @@ export interface InitMessage {
      * here after fetching a JWT via the 'realtime.getToken' RPC.
      */
     realtimeUrl?: string;
+    /**
+     * The player's preferred language (the host's UI locale, e.g. 'en', 'zh-CN',
+     * 'ja'). Lets a game default its UI + AI NPC language to the player's without
+     * asking. Absent in standalone mode → SDK falls back to the browser locale.
+     */
+    locale?: string;
 }
 export interface RpcResultOk {
     type: 'umicat:rpc.result';
@@ -927,6 +933,14 @@ export interface AiActOptions {
     temperature?: number;
 }
 export interface AiActParams {
+    /**
+     * Name of a playbook shipped with the game at `public/playbooks/<name>.md`
+     * (ADR-018) — a natural-language behavior pack (persona + strategy) the platform
+     * loads and injects. Pass just the NAME; the host resolves it under the game's
+     * own id (tamper-resistant). Supplies the character behavior; can be combined
+     * with `persona` (the playbook leads, `persona` augments).
+     */
+    playbook?: string;
     persona?: AiPersona;
     /** Arbitrary game-defined JSON of what the AI perceives this turn. */
     observation?: unknown;

package/package.json

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