@unboxy/phaser-sdk 0.2.20 → 0.2.22

package/SDK-GUIDE.md

@@ -638,6 +638,9 @@ The `scene-data-architecture` agent skill has the full guidance. The `scene-data
 
 ## Changelog
 
+- **0.2.22** — render-script registry wired (visual editor slice 3.5). `createUnboxyGame` accepts a new `renderScripts: Record<path, RenderScriptModule>` option; templates build it via `import.meta.glob('./visuals/*.ts', { eager: true })`. `loadWorldScene` falls back to that registry when no explicit `resolveRenderScript` is passed, so games don't have to plumb it through every scene call. Missing scripts no longer crash the scene boot — `spawnEntity` renders a clear orange-bordered "?" placeholder instead and tags the GameObject with `renderScriptMissing` for debug. `applyEdit` now handles `visual.params` patches on `code-rendered` entities by re-calling render with merged params (live editor preview as you tune in the Inspector). New exports: `RenderScriptModule`, `setRenderScriptRegistry`, `getRenderScriptRegistry`, `resolveRenderScript`. Pairs with the `phaser-render-script` agent skill which teaches the pure-function contract.
+- **0.2.21** — visual editor slice 3 (drag-to-place). Formalized trigger + tilemap entity data shapes (TriggerEntity now has `shape: rect|circle`, `description`, `targets[]`; TilemapEntity has `tileSize`, `size`, `layers[]`). spawnEntity renders both as placeholders (trigger = semi-transparent cyan rect/circle, tilemap = translucent grid sketch — full features ship in slices 5+6). New protocol: `unboxy:editor:createEntity { entity, manifestAsset? }` (host-side drag-to-place spawns entity at world coord; lazy-loads asset texture if needed) + `unboxy:editor:deleteEntity { entityId }` (Backspace + undo of create). `sceneLoaded` now also carries the manifest snapshot so home-ui can mutate the asset table when a new asset gets dropped on the canvas.
+- **0.2.20** — added editor shortcut forwarding (Cmd+Z/Y/S land in iframe when canvas focused; SDK posts back to host via `unboxy:editor:shortcut`). Without this, native shortcuts didn't reach the host's keydown listener after the user clicked the canvas.
 - **0.2.19** — fix: editor `enter` arriving while BootScene is still preloading (the post-flush iframe-rebuild path) had nothing to pause, so the world scene resumed running freely once it started up. Now the bridge re-attempts the pause + scene snapshot for ~3 seconds after enter, catching the scene as it transitions from BootScene → GameScene. Snapshot is also re-posted once a scene file lands in cache. Surfaced when slice-2's auto-flush rebuilt the iframe and the user found the sprite started moving again post-save (2026-05-07).
 - **0.2.18** — added editor bridge (visual editor slice 2). Replaces the slice-1 `unboxy:setEditMode` message with a full editor protocol: `unboxy:editor:enter`/`:exit` (toggles edit mode + launches the overlay scene), `:applyEdit` (mutates a live entity from the host), `:setSelection` (host pushes selection), `:panZoom` (editor camera control), plus SDK→host `:sceneLoaded` (initial snapshot), `:pickEntity` (pointer-down selection), `:dragEnd` (entity dragged to new position). New module `src/editor/` with `EditorOverlayScene` (high-depth Phaser.Scene drawing selection rect + world bounds, capturing pointer events) and `EditorBridge` (postMessage handler + applyEdit logic). New exports: `setupEditorBridge`, `EditorOverlayScene`, `EDITOR_OVERLAY_KEY`, plus all editor protocol types. `setupEditorModeListener` is preserved as a thin wrapper that delegates to the bridge so existing `createUnboxyGame` wiring continues to work. Pairs with home-ui's new Hierarchy + Inspector panels and `useEditorDraft` hook.
 - **0.2.17** — added scene-as-data foundation (visual editor slice 1). New exports: `loadWorldScene`, `preloadManifest`, `getManifest`, `preloadSceneAssets`, `spawnEntity`, `EntityRegistry`, `attachEntityRegistry`, `getEntityRegistry`, `setupEditorModeListener`, `isEditMode`, `parseColor`, `SCHEMA_VERSION`, plus all schema types (`Manifest`, `WorldScene`, `WorldEntity`, `Transform`, `AssetRecord`, etc.). New games that ship with `public/scenes/manifest.json` load entities + camera config from JSON; `GameScene.ts` becomes a generic loader that calls `await loadWorldScene(this, sceneId)`. `createUnboxyGame` now also wires `setupEditorModeListener` so the host (home-ui) can pause active scenes via `postMessage({ type: 'unboxy:setEditMode', enabled: boolean })`. Purely additive — existing scene-as-code games are unaffected. Migration to scene-as-data is opt-in via the `scene-data-migration` agent skill.

package/dist/core/UnboxyGame.d.ts

@@ -1,5 +1,6 @@
 import Phaser from 'phaser';
 import { type Orientation } from '../orientation.js';
+import { RenderScriptModule } from '../scene/renderScripts.js';
 interface UnboxyGameBaseOptions {
     /** Phaser scene classes to register */
     scenes: (new (...args: any[]) => Phaser.Scene)[];
@@ -11,6 +12,13 @@ interface UnboxyGameBaseOptions {
     physics?: Phaser.Types.Core.PhysicsConfig;
     /** Phaser plugin registrations (e.g. `phaser3-rex-plugins` virtual joystick) */
     plugins?: Phaser.Types.Core.PluginObject;
+    /**
+     * Map of render-script paths → modules that export `render(g, params)`.
+     * Templates build this via `import.meta.glob('./visuals/*.ts', { eager: true })`.
+     * Used by `code-rendered` entities and consumed inside `loadWorldScene`.
+     * Optional — games without code-rendered visuals can omit it.
+     */
+    renderScripts?: Record<string, RenderScriptModule>;
 }
 /**
  * Either pass `orientation` (preset dims from ORIENTATION_DIMENSIONS) OR

package/dist/core/UnboxyGame.js

@@ -3,6 +3,7 @@ import { setupScreenshotListener } from '../screenshot/ScreenshotManager.js';
 import { setupRecordingListener } from '../recording/RecordingManager.js';
 import { setupEditorModeListener } from '../scene/EditorMode.js';
 import { ORIENTATION_DIMENSIONS } from '../orientation.js';
+import { setRenderScriptRegistry, } from '../scene/renderScripts.js';
 /**
  * Create an Unboxy-enhanced Phaser game instance.
  * Includes built-in integrations: screenshot capture, preserveDrawingBuffer, etc.
@@ -36,5 +37,8 @@ export function createUnboxyGame(options) {
     setupScreenshotListener(game);
     setupRecordingListener(game);
     setupEditorModeListener(game);
+    if (options.renderScripts) {
+        setRenderScriptRegistry(game, options.renderScripts);
+    }
     return game;
 }

package/dist/editor/EditorBridge.js

@@ -1,5 +1,7 @@
+import Phaser from 'phaser';
 import { getEntityRegistry } from '../scene/EntityRegistry.js';
-import { parseColor } from '../scene/spawnEntity.js';
+import { parseColor, spawnEntity } from '../scene/spawnEntity.js';
+import { resolveRenderScript } from '../scene/renderScripts.js';
 import { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './EditorOverlayScene.js';
 import { getEditorState, setEditorActive, setSelection, } from './EditorState.js';
 /**
@@ -53,6 +55,12 @@ function handleMessage(game, msg) {
         case 'unboxy:editor:panZoom':
             applyPanZoom(game, msg);
             break;
+        case 'unboxy:editor:createEntity':
+            void createEntity(game, msg.entity, msg.manifestAsset);
+            break;
+        case 'unboxy:editor:deleteEntity':
+            deleteEntity(game, msg.entityId);
+            break;
     }
 }
 // --- Enter / exit ---------------------------------------------------------
@@ -151,9 +159,19 @@ function postSceneSnapshot(game) {
         type: 'unboxy:editor:sceneLoaded',
         sceneId: sceneFile.id,
         sceneFile,
+        manifest: readActiveManifest(game),
     });
     game[SNAPSHOT_POSTED_FLAG] = sceneFile.id;
 }
+function readActiveManifest(game) {
+    for (const scene of game.scene.getScenes(false)) {
+        const cache = scene.cache.json;
+        const m = cache.entries?.entries?.['unboxy:manifest'];
+        if (m)
+            return m;
+    }
+    return undefined;
+}
 function hasPostedSnapshot(game) {
     return !!game[SNAPSHOT_POSTED_FLAG];
 }
@@ -225,6 +243,7 @@ function applyEdit(game, entityId, patch) {
         return;
     applyTransformPatch(go, patch.transform);
     applyVisualPatch(go, patch.visual);
+    applyCodeRenderedParamsPatch(game, go, patch.visual?.params);
     if (patch.role !== undefined) {
         if (patch.role === null)
             go.setData('entityRole', undefined);
@@ -235,6 +254,27 @@ function applyEdit(game, entityId, patch) {
         go.setData('entityProperties', patch.properties);
     }
 }
+/**
+ * Re-render a code-rendered entity's visual when its params change.
+ * Slice 3.5 — Inspector params editor produces these patches.
+ *
+ * No-op for non-code-rendered entities (no renderScriptPath in data) so
+ * sprite/primitive patches that incidentally include `visual.params` (the
+ * type allows it) flow through harmlessly.
+ */
+function applyCodeRenderedParamsPatch(game, go, newParams) {
+    if (newParams === undefined)
+        return;
+    const scriptPath = go.getData('renderScriptPath');
+    if (!scriptPath)
+        return; // not a code-rendered entity
+    const render = resolveRenderScript(game, scriptPath);
+    if (!render)
+        return;
+    const g = go;
+    render(g, newParams);
+    go.setData('renderScriptParams', newParams);
+}
 function applyTransformPatch(go, t) {
     if (!t)
         return;
@@ -292,6 +332,150 @@ function applyVisualPatch(go, v) {
         }
     }
 }
+// --- Create / delete ------------------------------------------------------
+/**
+ * Spawn a new entity into the active world scene. Slice 3.
+ *
+ * If the entity references an asset whose texture isn't yet in the Phaser
+ * cache, we lazy-load it before spawn — same pattern as SceneLoader's
+ * preloadSceneAssets, but on a single asset and at edit time. Without this
+ * 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) {
+    const scene = findWorldScene(game);
+    if (!scene) {
+        console.warn('[unboxy/editor] createEntity: no world scene to spawn into');
+        return;
+    }
+    const registry = getEntityRegistry(scene);
+    if (!registry) {
+        console.warn('[unboxy/editor] createEntity: world scene has no entity registry');
+        return;
+    }
+    // Lazy-load texture if needed (sprite + asset not yet in cache).
+    if (manifestAsset &&
+        entity.kind === 'sprite' &&
+        !scene.textures.exists(manifestAsset.textureKey)) {
+        await loadAssetIntoScene(scene, manifestAsset);
+    }
+    const ctx = {
+        scene,
+        registry,
+        resolveAsset: (id) => {
+            // For ad-hoc creation we may not have full manifest access. Rely on
+            // the host to have stamped the right textureKey/path into the asset
+            // we received via manifestAsset; fallback to a synthetic record so
+            // spawnEntity can still find a textureKey.
+            if (manifestAsset && manifestAsset.id === id)
+                return manifestAsset;
+            throw new Error(`[unboxy/editor] createEntity: asset '${id}' not in manifest payload — host must include manifestAsset`);
+        },
+        resolveRenderScript: undefined,
+    };
+    try {
+        spawnEntity(ctx, entity);
+    }
+    catch (e) {
+        console.warn('[unboxy/editor] spawnEntity failed:', e);
+    }
+}
+function loadAssetIntoScene(scene, asset) {
+    return new Promise((resolve, reject) => {
+        if (scene.textures.exists(asset.textureKey)) {
+            resolve();
+            return;
+        }
+        const onComplete = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (file) => {
+            if (file.key !== asset.textureKey)
+                return;
+            cleanup();
+            reject(new Error(`failed to load asset ${asset.id}: ${file.url}`));
+        };
+        const cleanup = () => {
+            scene.load.off(Phaser.Loader.Events.FILE_COMPLETE, perFileComplete);
+            scene.load.off(Phaser.Loader.Events.FILE_LOAD_ERROR, onError);
+            scene.load.off(Phaser.Loader.Events.COMPLETE, onComplete);
+        };
+        const perFileComplete = (key) => {
+            if (key === asset.textureKey) {
+                cleanup();
+                resolve();
+            }
+        };
+        scene.load.on(Phaser.Loader.Events.FILE_COMPLETE, perFileComplete);
+        scene.load.on(Phaser.Loader.Events.FILE_LOAD_ERROR, onError);
+        scene.load.on(Phaser.Loader.Events.COMPLETE, onComplete);
+        switch (asset.kind) {
+            case 'image':
+                scene.load.image(asset.textureKey, asset.path);
+                break;
+            case 'spritesheet':
+                if (asset.spriteSheetConfig) {
+                    scene.load.spritesheet(asset.textureKey, asset.path, asset.spriteSheetConfig);
+                }
+                else {
+                    scene.load.image(asset.textureKey, asset.path);
+                }
+                break;
+            case 'atlas':
+                if (asset.atlasPath && asset.atlasFormat === 'xml') {
+                    scene.load.atlasXML(asset.textureKey, asset.path, asset.atlasPath);
+                }
+                else if (asset.atlasPath) {
+                    scene.load.atlas(asset.textureKey, asset.path, asset.atlasPath);
+                }
+                break;
+            case 'audio':
+                scene.load.audio(asset.textureKey, asset.path);
+                break;
+            default:
+                cleanup();
+                reject(new Error(`unsupported asset kind for editor lazy-load: ${asset.kind}`));
+                return;
+        }
+        if (!scene.load.isLoading())
+            scene.load.start();
+    });
+}
+function deleteEntity(game, entityId) {
+    const scene = findWorldScene(game);
+    if (!scene)
+        return;
+    const registry = getEntityRegistry(scene);
+    if (!registry)
+        return;
+    const go = registry.byId(entityId);
+    if (!go)
+        return;
+    // Remove from registry by clearing + rebuilding the entries we care about.
+    // The slice-1 EntityRegistry doesn't expose a direct removeById; the
+    // simplest thing is to destroy the GameObject and let stale registry
+    // entries dangle until the next scene reload (post-flush). Slice 3.5
+    // can add an explicit `registry.unregister` if it becomes a problem.
+    go.destroy();
+    // Drop selection if it pointed at this entity.
+    const sel = game;
+    const state = sel['__unboxyEditorState'];
+    if (state && state.selectedId === entityId)
+        state.selectedId = null;
+}
+function findWorldScene(game) {
+    for (const scene of game.scene.getScenes(false)) {
+        const key = scene.scene.key;
+        if (BOOT_SCENE_KEYS.has(key))
+            continue;
+        if (key === EDITOR_OVERLAY_KEY)
+            continue;
+        if (getEntityRegistry(scene))
+            return scene;
+    }
+    return undefined;
+}
 // --- Pan / zoom -----------------------------------------------------------
 function applyPanZoom(game, msg) {
     // Apply to BOTH the world scene's camera (so the entity rendering moves)

package/dist/index.d.ts

@@ -22,9 +22,11 @@ export { spawnEntity, parseColor } from './scene/spawnEntity.js';
 export type { SpawnContext, AssetResolver, RenderScriptResolver, } from './scene/spawnEntity.js';
 export { EntityRegistry, attachEntityRegistry, getEntityRegistry, } from './scene/EntityRegistry.js';
 export { setupEditorModeListener, isEditMode } from './scene/EditorMode.js';
+export { setRenderScriptRegistry, getRenderScriptRegistry, resolveRenderScript, } from './scene/renderScripts.js';
+export type { RenderScriptModule } from './scene/renderScripts.js';
 export { setupEditorBridge } from './editor/EditorBridge.js';
 export { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './editor/EditorOverlayScene.js';
-export type { EditorEntityPatch, EditorEnterMessage, EditorExitMessage, EditorGetSceneMessage, EditorApplyEditMessage, EditorSetSelectionMessage, EditorPanZoomMessage, EditorHostToSdkMessage, EditorSceneLoadedMessage, EditorSelectionPickedMessage, EditorDragEndMessage, EditorShortcutMessage, EditorSdkToHostMessage, } from './protocol.js';
+export type { EditorEntityPatch, EditorEnterMessage, EditorExitMessage, EditorGetSceneMessage, EditorApplyEditMessage, EditorSetSelectionMessage, EditorPanZoomMessage, EditorHostToSdkMessage, EditorSceneLoadedMessage, EditorSelectionPickedMessage, EditorDragEndMessage, EditorShortcutMessage, EditorCreateEntityMessage, EditorDeleteEntityMessage, EditorSdkToHostMessage, } from './protocol.js';
 export { SCHEMA_VERSION, } from './scene/types.js';
-export type { Manifest, SceneRef, HudRef, AssetRecord, AssetKind, SceneType, SceneFile, WorldScene, HudScene, WorldSceneConfig, CameraConfig, WorldEntity, WorldEntityKind, NonGroupWorldEntity, SpriteEntity, PrimitiveEntity, CodeRenderedEntity, GroupEntity, TilemapEntity, TriggerEntity, WorldVisual, SpriteVisual, PrimitiveVisual, PrimitiveRectVisual, PrimitiveCircleVisual, CodeRenderedVisual, Transform, Anchor, AnchorSide, } from './scene/types.js';
+export type { Manifest, SceneRef, HudRef, AssetRecord, AssetKind, SceneType, SceneFile, WorldScene, HudScene, WorldSceneConfig, CameraConfig, WorldEntity, WorldEntityKind, NonGroupWorldEntity, SpriteEntity, PrimitiveEntity, CodeRenderedEntity, GroupEntity, TilemapEntity, TriggerEntity, TriggerShape, WorldVisual, SpriteVisual, PrimitiveVisual, PrimitiveRectVisual, PrimitiveCircleVisual, CodeRenderedVisual, Transform, Anchor, AnchorSide, } from './scene/types.js';
 export { PROTOCOL_VERSION, type HelloMessage, type InitMessage, type RpcRequestMessage, type RpcResultOk, type RpcResultError, type HostToSdkMessage, type SdkToHostMessage, type RpcErrorPayload, type RpcMethod, type SavesGetParams, type SavesGetResult, type SavesSetParams, type SavesSetResult, type SavesDeleteParams, type SavesDeleteResult, type SavesListResult, type GameDataGetParams, type GameDataGetResult, type GameDataSetParams, type GameDataSetResult, type GameDataDeleteParams, type GameDataDeleteResult, type GameDataListResult, type RealtimeGetTokenParams, type RealtimeGetTokenResult, } from './protocol.js';

package/dist/index.js

@@ -18,6 +18,7 @@ export { loadWorldScene, preloadManifest, preloadSceneAssets, getManifest, SCENE
 export { spawnEntity, parseColor } from './scene/spawnEntity.js';
 export { EntityRegistry, attachEntityRegistry, getEntityRegistry, } from './scene/EntityRegistry.js';
 export { setupEditorModeListener, isEditMode } from './scene/EditorMode.js';
+export { setRenderScriptRegistry, getRenderScriptRegistry, resolveRenderScript, } from './scene/renderScripts.js';
 export { setupEditorBridge } from './editor/EditorBridge.js';
 export { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './editor/EditorOverlayScene.js';
 export { SCHEMA_VERSION, } from './scene/types.js';

package/dist/protocol.d.ts

@@ -74,6 +74,12 @@ export interface EditorEntityPatch {
         fillColor?: string;
         strokeColor?: string | null;
         strokeWidth?: number;
+        /**
+         * For `code-rendered` entities — the entire params object replaces
+         * `visual.params`. SDK re-calls `render(g, params)` on receipt.
+         * Slice 3.5.
+         */
+        params?: Record<string, unknown>;
     };
     role?: string | null;
     properties?: Record<string, unknown>;
@@ -108,12 +114,35 @@ export interface EditorPanZoomMessage {
     /** If true, deltas are added to current scroll. */
     relative?: boolean;
 }
-export type EditorHostToSdkMessage = EditorEnterMessage | EditorExitMessage | EditorGetSceneMessage | EditorApplyEditMessage | EditorSetSelectionMessage | EditorPanZoomMessage;
+/**
+ * Create a new entity in the active scene (slice 3 — drag-to-place).
+ * The SDK picks an asset record from `manifestAsset` (if present) so the
+ * texture can be lazy-loaded before spawn. Position can be supplied as
+ * world coords (preferred — host computed via 1:1 mapping in slice 3) or
+ * skipped if the entity already carries a transform.
+ */
+export interface EditorCreateEntityMessage {
+    type: 'unboxy:editor:createEntity';
+    /** Full entity record. transform.x/y is authoritative. */
+    entity: unknown;
+    /** Asset record to add to runtime cache before spawn. Omit if assetId is already loaded. */
+    manifestAsset?: unknown;
+}
+export interface EditorDeleteEntityMessage {
+    type: 'unboxy:editor:deleteEntity';
+    entityId: string;
+}
+export type EditorHostToSdkMessage = EditorEnterMessage | EditorExitMessage | EditorGetSceneMessage | EditorApplyEditMessage | EditorSetSelectionMessage | EditorPanZoomMessage | EditorCreateEntityMessage | EditorDeleteEntityMessage;
 export interface EditorSceneLoadedMessage {
     type: 'unboxy:editor:sceneLoaded';
     sceneId: string;
     /** Snapshot of the world scene file's current entities + camera. */
     sceneFile: unknown;
+    /**
+     * Snapshot of the manifest (asset table + scene list). Slice 3+ — home-ui
+     * needs this to mutate the manifest when drag-to-place adds a new asset.
+     */
+    manifest?: unknown;
 }
 export interface EditorSelectionPickedMessage {
     /** Pointer-down on an entity in the canvas — host should update selection. */

package/dist/scene/SceneLoader.js

@@ -2,6 +2,7 @@ import Phaser from 'phaser';
 import { SCHEMA_VERSION, } from './types.js';
 import { spawnEntity } from './spawnEntity.js';
 import { attachEntityRegistry } from './EntityRegistry.js';
+import { resolveRenderScript } from './renderScripts.js';
 /**
  * Where scene files live in the workspace and at runtime. The Vite build
  * copies `public/` to the served root, so paths are origin-relative
@@ -179,7 +180,8 @@ export async function loadWorldScene(scene, sceneId, options = {}) {
         scene,
         registry,
         resolveAsset: (id) => resolveAsset(manifest, id),
-        resolveRenderScript: options.resolveRenderScript,
+        resolveRenderScript: options.resolveRenderScript ??
+            ((path) => resolveRenderScript(scene.game, path)),
     };
     for (const entity of sceneFile.entities)
         spawnEntity(ctx, entity);

package/dist/scene/renderScripts.d.ts

@@ -0,0 +1,53 @@
+import Phaser from 'phaser';
+/**
+ * Render-script module shape — slice 3.5.
+ *
+ * Spec: `unboxy-design/features/visual-editor/02-render-scripts.md`.
+ *
+ * A `code-rendered` entity references a render script by path. The script's
+ * `render` is a **pure function** that draws into a Phaser Graphics object
+ * given a parameters object. The function:
+ *
+ *   - Calls `g.clear()` first (idempotent re-renders).
+ *   - Has no time/random dependency (motion is in tween system, not here).
+ *   - Holds no module state.
+ *
+ * Optional exports the editor / SDK uses if present:
+ *
+ *   - `defaultParams` — used as a starting point for new entities.
+ *   - `paramSchema`   — drives the Inspector's auto-generated UI (slice 4+).
+ *
+ * The script registry is built by the template (`import.meta.glob`), passed
+ * to `createUnboxyGame({ renderScripts })`, and resolved by path string at
+ * spawn time. Path strings in scene files match the registry keys exactly:
+ * usually `src/visuals/<name>.ts`.
+ */
+export interface RenderScriptModule<P extends Record<string, unknown> = Record<string, unknown>> {
+    render: (g: Phaser.GameObjects.Graphics, params: P) => void;
+    defaultParams?: P;
+    paramSchema?: unknown;
+}
+/**
+ * Stash a render-script registry on the Phaser game so `loadWorldScene` /
+ * `EditorBridge.applyEdit` can find it without explicit plumbing.
+ *
+ * The map's keys are absolute paths matching what scene files reference
+ * (e.g. `src/visuals/coin.ts`). Templates that build via `import.meta.glob`
+ * commonly produce relative keys like `./visuals/coin.ts`; the resolver
+ * normalises trailing slashes / leading `./` so both shapes work.
+ */
+export declare function setRenderScriptRegistry(game: Phaser.Game, scripts: Record<string, RenderScriptModule>): void;
+export declare function getRenderScriptRegistry(game: Phaser.Game): Record<string, RenderScriptModule> | undefined;
+/**
+ * Returns the `render` function for a script path, or undefined if no
+ * matching module is registered. The matcher is forgiving:
+ *
+ *   - exact match (`src/visuals/coin.ts`)
+ *   - leading `./` stripped (`./visuals/coin.ts` matches `src/visuals/coin.ts`)
+ *   - filename-only fallback so renames in the registry that drop the
+ *     `src/` prefix still resolve.
+ *
+ * The forgiveness lets templates use whatever import.meta.glob shape they
+ * find natural without forcing a one-true-key convention.
+ */
+export declare function resolveRenderScript(game: Phaser.Game, scriptPath: string): ((g: Phaser.GameObjects.Graphics, params: Record<string, unknown>) => void) | undefined;

package/dist/scene/renderScripts.js

@@ -0,0 +1,67 @@
+const REGISTRY_KEY = '__unboxyRenderScriptRegistry';
+/**
+ * Stash a render-script registry on the Phaser game so `loadWorldScene` /
+ * `EditorBridge.applyEdit` can find it without explicit plumbing.
+ *
+ * The map's keys are absolute paths matching what scene files reference
+ * (e.g. `src/visuals/coin.ts`). Templates that build via `import.meta.glob`
+ * commonly produce relative keys like `./visuals/coin.ts`; the resolver
+ * normalises trailing slashes / leading `./` so both shapes work.
+ */
+export function setRenderScriptRegistry(game, scripts) {
+    const bag = game;
+    bag[REGISTRY_KEY] = scripts;
+}
+export function getRenderScriptRegistry(game) {
+    const bag = game;
+    return bag[REGISTRY_KEY];
+}
+/**
+ * Returns the `render` function for a script path, or undefined if no
+ * matching module is registered. The matcher is forgiving:
+ *
+ *   - exact match (`src/visuals/coin.ts`)
+ *   - leading `./` stripped (`./visuals/coin.ts` matches `src/visuals/coin.ts`)
+ *   - filename-only fallback so renames in the registry that drop the
+ *     `src/` prefix still resolve.
+ *
+ * The forgiveness lets templates use whatever import.meta.glob shape they
+ * find natural without forcing a one-true-key convention.
+ */
+export function resolveRenderScript(game, scriptPath) {
+    const registry = getRenderScriptRegistry(game);
+    if (!registry)
+        return undefined;
+    // Direct hit.
+    if (registry[scriptPath])
+        return registry[scriptPath].render;
+    // Try common normalisations.
+    const candidates = candidateKeys(scriptPath);
+    for (const c of candidates) {
+        if (registry[c])
+            return registry[c].render;
+    }
+    // Filename-only fallback.
+    const filename = scriptPath.split('/').pop();
+    if (filename) {
+        for (const key of Object.keys(registry)) {
+            if (key.endsWith('/' + filename) || key === filename) {
+                return registry[key].render;
+            }
+        }
+    }
+    return undefined;
+}
+function candidateKeys(scriptPath) {
+    const out = [];
+    const trimmed = scriptPath.replace(/^\.\//, '');
+    out.push(trimmed);
+    // src/visuals/coin.ts → ./visuals/coin.ts
+    if (trimmed.startsWith('src/'))
+        out.push('./' + trimmed.slice(4));
+    // visuals/coin.ts → src/visuals/coin.ts
+    if (!trimmed.startsWith('src/') && !trimmed.startsWith('./')) {
+        out.push('src/' + trimmed);
+    }
+    return out;
+}

package/dist/scene/spawnEntity.js

@@ -19,9 +19,11 @@ export function spawnEntity(ctx, entity) {
             go = createCodeRendered(ctx, entity);
             break;
         case 'tilemap':
-            throw new Error(`[unboxy/scene] tilemap entity ('${entity.id}') not supported in slice 1 — see 06-tilemap.md`);
+            go = createTilemapStub(ctx, entity);
+            break;
         case 'trigger':
-            throw new Error(`[unboxy/scene] trigger entity ('${entity.id}') not supported in slice 1 — see 03-world-editor.md`);
+            go = createTriggerStub(ctx, entity);
+            break;
         default: {
             const exhaustive = entity;
             throw new Error(`[unboxy/scene] unknown entity kind: ${JSON.stringify(exhaustive)}`);
@@ -94,10 +96,25 @@ function createGroup(ctx, entity) {
 function createCodeRendered(ctx, entity) {
     const render = ctx.resolveRenderScript?.(entity.visual.script);
     if (!render) {
-        throw new Error(`[unboxy/scene] code-rendered entity '${entity.id}' references '${entity.visual.script}' but no render-script resolver was provided — render scripts land in a later slice (see 02-render-scripts.md)`);
+        // Slice 3.5: render scripts have a registry now, but a missing entry
+        // shouldn't crash the whole scene boot — the agent might be writing
+        // the script in a follow-up turn. Render a clear "?" placeholder so
+        // the user sees the entity exists but the visual is unresolved.
+        const ph = ctx.scene.add.graphics();
+        ph.fillStyle(0x666666, 0.4);
+        ph.fillRect(-16, -16, 32, 32);
+        ph.lineStyle(2, 0xff8800, 0.9);
+        ph.strokeRect(-16, -16, 32, 32);
+        // Annotate so editor / debug overlays can identify.
+        ph.setData('renderScriptMissing', entity.visual.script);
+        return ph;
     }
     const g = ctx.scene.add.graphics();
-    render(g, entity.visual.params ?? {});
+    const params = entity.visual.params ?? {};
+    render(g, params);
+    // Stash data needed for live re-render from EditorBridge.applyEdit.
+    g.setData('renderScriptPath', entity.visual.script);
+    g.setData('renderScriptParams', params);
     return g;
 }
 function applyTransform(go, t) {
@@ -122,6 +139,61 @@ function tagGameObject(go, entity) {
     if (entity.properties)
         go.setData('entityProperties', entity.properties);
 }
+/**
+ * Trigger stub renderer — slice 3. Renders the trigger zone as a
+ * semi-transparent fill with cyan tint per design 03 §8.2 (in edit mode it
+ * is always visible; at play time the SDK will hide it once slice 5 wires
+ * the behavior layer).
+ */
+function createTriggerStub(ctx, entity) {
+    const TINT = 0x00bfff; // cyan-ish "neutral trigger" per design
+    const FILL_ALPHA = 0.25;
+    const STROKE_ALPHA = 0.7;
+    if (entity.shape.kind === 'rect') {
+        const r = ctx.scene.add.rectangle(0, 0, entity.shape.width, entity.shape.height, TINT, FILL_ALPHA);
+        r.setStrokeStyle(1.5, TINT, STROKE_ALPHA);
+        return r;
+    }
+    // circle
+    const c = ctx.scene.add.circle(0, 0, entity.shape.radius, TINT, FILL_ALPHA);
+    c.setStrokeStyle(1.5, TINT, STROKE_ALPHA);
+    return c;
+}
+/**
+ * Tilemap stub renderer — slice 3. Draws a translucent grid sketch of the
+ * tilemap's bounds + cell lines so the user can see where the tilemap is
+ * and how big it is. Real tilemap rendering (with tilesets, autotile,
+ * Y-sort, etc.) lands in slice 6.
+ */
+function createTilemapStub(ctx, entity) {
+    const g = ctx.scene.add.graphics();
+    const w = entity.size.width * entity.tileSize.width;
+    const h = entity.size.height * entity.tileSize.height;
+    g.fillStyle(0xffffff, 0.04);
+    g.fillRect(0, 0, w, h);
+    // Outer border
+    g.lineStyle(2, 0xaaaaaa, 0.6);
+    g.strokeRect(0, 0, w, h);
+    // Cell grid — only draw if cells aren't too tiny (perf cap).
+    if (entity.tileSize.width >= 8 && entity.size.width * entity.size.height < 4000) {
+        g.lineStyle(1, 0xaaaaaa, 0.15);
+        for (let i = 1; i < entity.size.width; i++) {
+            const x = i * entity.tileSize.width;
+            g.beginPath();
+            g.moveTo(x, 0);
+            g.lineTo(x, h);
+            g.strokePath();
+        }
+        for (let i = 1; i < entity.size.height; i++) {
+            const y = i * entity.tileSize.height;
+            g.beginPath();
+            g.moveTo(0, y);
+            g.lineTo(w, y);
+            g.strokePath();
+        }
+    }
+    return g;
+}
 /**
  * Accepts `'#rrggbb'`, `'rrggbb'`, or `'0xrrggbb'` and returns a number
  * suitable for Phaser's color APIs.

package/dist/scene/types.d.ts

@@ -149,19 +149,59 @@ export interface GroupEntity extends WorldEntityBase {
     children: NonGroupWorldEntity[];
 }
 /**
- * v1 placeholder — schema slot reserved so future slices can layer in
- * tilemap/trigger without a schemaVersion bump. Loader currently throws
- * on these kinds so an unmigrated game can't silently render nothing.
+ * Tilemap entity — slice 3 ships a stub renderer (placeholder rectangle).
+ * Full tilemap painting + autotile lands in slice 6 (06-tilemap.md).
  */
 export interface TilemapEntity extends WorldEntityBase {
     kind: 'tilemap';
-    /** Opaque tilemap payload — defined in `06-tilemap.md`. */
-    data: unknown;
+    tileSize: {
+        width: number;
+        height: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    layers: Array<{
+        id: string;
+        name?: string;
+        tilesetIds?: string[];
+        z?: number;
+        /** 2D array of tile ids; null cells == empty. */
+        data?: Array<Array<string | null>>;
+        visible?: boolean;
+        locked?: boolean;
+        autotile?: {
+            kind: 'wang-4bit';
+            rules?: 'auto-detected' | unknown;
+        };
+        ySort?: boolean;
+    }>;
 }
+export type TriggerShape = {
+    kind: 'rect';
+    width: number;
+    height: number;
+} | {
+    kind: 'circle';
+    radius: number;
+};
+/**
+ * Trigger entity — slice 3 ships a stub renderer (semi-transparent rect/circle
+ * with the design's cyan tint). Full behavior wiring (description / targets /
+ * behavior script) lands in slice 5 (03-world-editor.md §8).
+ */
 export interface TriggerEntity extends WorldEntityBase {
     kind: 'trigger';
-    /** Opaque trigger payload — defined in `03-world-editor.md`. */
-    data: unknown;
+    shape: TriggerShape;
+    /** User-facing label shown in Hierarchy + on canvas. */
+    description?: string;
+    /** Entity ids this trigger affects. Slice 5 wires the relationship UI. */
+    targets?: string[];
+    /** Optional path to behavior script. Slice 5 fills this in. */
+    behaviorScript?: string;
+    /** Optional preset name (open-door / damage-zone / scene-transition / spawner / heal). */
+    preset?: string;
 }
 export type NonGroupWorldEntity = SpriteEntity | PrimitiveEntity | CodeRenderedEntity | TilemapEntity | TriggerEntity;
 export type WorldEntity = NonGroupWorldEntity | GroupEntity;

package/package.json

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