@umicat/phaser-sdk 1.0.17 → 1.0.19

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/editor/EditorBridge.js

@@ -79,7 +79,7 @@ function handleMessage(game, msg) {
             applyPanZoomToWorld(game, msg);
             break;
         case 'umicat:editor:createEntity':
-            void createEntity(game, msg.entity, msg.manifestAsset);
+            void createEntity(game, msg.entity, msg.manifestAsset, msg.tilemapFile);
             break;
         case 'umicat:editor:deleteEntity':
             deleteEntity(game, msg.entityId);
@@ -1206,7 +1206,7 @@ function applyVisualPatch(go, v) {
  * the host would have to coordinate a build before showing a dropped
  * sprite, which defeats the point of drag-to-place.
  */
-async function createEntity(game, entity, manifestAsset) {
+async function createEntity(game, entity, manifestAsset, tilemapFile) {
     // HUD mode dispatches to the HUD-runtime spawner (slice 5). The host
     // sends HudEntity records (not WorldEntity), so we type-erase.
     if (getEditorMode(game) === 'hud') {
@@ -1288,13 +1288,26 @@ async function createEntity(game, entity, manifestAsset) {
         // dropped tilemap renders LIVE without a save+reload round-trip.
         const tilemapId = entity.tilemapId;
         if (tilemapId) {
-            try {
-                await loadTilemapFileIntoScene(sceneRef, tilemapId);
+            const key = tilemapFileCacheKey(tilemapId);
+            // Prefer the host-supplied file CONTENT (the workspace truth). The dist
+            // copy that `loadTilemapFileIntoScene` fetches is STALE until the next
+            // game build, so a freshly-authored/edited tilemap 404s there → magenta
+            // placeholder until save+rebuild. Injecting the passed content renders it
+            // LIVE. Fall back to the dist fetch when the host didn't supply it.
+            if (tilemapFile) {
+                if (sceneRef.cache.json.exists(key))
+                    sceneRef.cache.json.remove(key);
+                sceneRef.cache.json.add(key, tilemapFile);
             }
-            catch (e) {
-                console.warn('[umicat/editor] createEntity: tilemap-ref file load failed:', e);
+            else {
+                try {
+                    await loadTilemapFileIntoScene(sceneRef, tilemapId);
+                }
+                catch (e) {
+                    console.warn('[umicat/editor] createEntity: tilemap-ref file load failed:', e);
+                }
             }
-            const file = sceneRef.cache.json.get(tilemapFileCacheKey(tilemapId));
+            const file = sceneRef.cache.json.get(key);
             for (const layer of file?.layers ?? []) {
                 for (const tid of layer.tilesetIds ?? []) {
                     queueIfMissing(resolveById(tid));

package/dist/protocol.d.ts

@@ -194,6 +194,15 @@ export interface EditorCreateEntityMessage {
     entity: unknown;
     /** Asset record to add to runtime cache before spawn. Omit if assetId is already loaded. */
     manifestAsset?: unknown;
+    /**
+     * For a `tilemap-ref`: the standalone tilemap file's CONTENT (the parsed
+     * `public/tilemaps/{id}.json`). The host fetches it from the WORKSPACE
+     * (current truth) and passes it so the SDK injects it into the JSON cache
+     * directly. Without this the SDK fetches the file from the deployed dist,
+     * which is STALE until the next game build — so a freshly-authored/edited
+     * tilemap renders as the magenta placeholder until save+reload.
+     */
+    tilemapFile?: unknown;
 }
 export interface EditorDeleteEntityMessage {
     type: 'umicat:editor:deleteEntity';
@@ -933,6 +942,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.19",
   "description": "Umicat Phaser 3 SDK — game infrastructure for the Umicat platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",