@umicat/phaser-sdk 1.0.17 → 1.0.18

package/SDK-GUIDE.md

@@ -605,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/protocol.d.ts

@@ -933,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.17",
+  "version": "1.0.18",
   "description": "Umicat Phaser 3 SDK — game infrastructure for the Umicat platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",