@unboxy/phaser-sdk 0.2.21 → 0.2.23

package/SDK-GUIDE.md

@@ -638,6 +638,7 @@ 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).

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,6 +1,7 @@
 import Phaser from 'phaser';
 import { getEntityRegistry } from '../scene/EntityRegistry.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';
 /**
@@ -208,15 +209,15 @@ function hitTest(game, worldX, worldY) {
     let topmost = null;
     let topmostDepth = -Infinity;
     for (const go of registry.all()) {
-        const withBounds = go;
-        if (typeof withBounds.getBounds !== 'function')
+        const r = entityHitRect(go);
+        if (!r)
             continue;
-        const r = withBounds.getBounds();
         if (worldX < r.x || worldX > r.x + r.width)
             continue;
         if (worldY < r.y || worldY > r.y + r.height)
             continue;
-        const depth = typeof withBounds.depth === 'number' ? withBounds.depth : 0;
+        const withDepth = go;
+        const depth = typeof withDepth.depth === 'number' ? withDepth.depth : 0;
         if (depth >= topmostDepth) {
             topmostDepth = depth;
             topmost = go;
@@ -224,6 +225,37 @@ function hitTest(game, worldX, worldY) {
     }
     return topmost;
 }
+/**
+ * Compute a hit-test rectangle for a spawned entity in world coords.
+ *
+ * 1. If the entity has `editorHitWidth` / `editorHitHeight` set in data
+ *    (code-rendered entities — Graphics has no intrinsic bounds), use
+ *    those centered on the entity's x/y.
+ * 2. Otherwise fall back to Phaser's `getBounds()` (works for Sprite,
+ *    Rectangle, Arc, Container — anything with a Size component).
+ *
+ * Returns null if neither path yields a usable rect.
+ */
+function entityHitRect(go) {
+    const hitW = go.getData('editorHitWidth');
+    const hitH = go.getData('editorHitHeight');
+    if (typeof hitW === 'number' && typeof hitH === 'number') {
+        const positioned = go;
+        return {
+            x: positioned.x - hitW / 2,
+            y: positioned.y - hitH / 2,
+            width: hitW,
+            height: hitH,
+        };
+    }
+    const withBounds = go;
+    if (typeof withBounds.getBounds !== 'function')
+        return null;
+    const r = withBounds.getBounds();
+    if (r.width === 0 && r.height === 0)
+        return null;
+    return { x: r.x, y: r.y, width: r.width, height: r.height };
+}
 function findRegistry(game) {
     for (const scene of game.scene.getScenes(false)) {
         const reg = getEntityRegistry(scene);
@@ -242,6 +274,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);
@@ -252,6 +285,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;

package/dist/editor/EditorOverlayScene.js

@@ -190,10 +190,24 @@ export class EditorOverlayScene extends Phaser.Scene {
     }
 }
 function computeBounds(go) {
-    // Most game objects implement getBounds; Container does too.
+    // Code-rendered entities stash hit dimensions on data because Phaser
+    // Graphics has no intrinsic bounds. Use those when present.
+    const hitW = go.getData('editorHitWidth');
+    const hitH = go.getData('editorHitHeight');
+    if (typeof hitW === 'number' && typeof hitH === 'number') {
+        const positioned = go;
+        return {
+            x: positioned.x - hitW / 2,
+            y: positioned.y - hitH / 2,
+            width: hitW,
+            height: hitH,
+        };
+    }
     const withBounds = go;
     if (typeof withBounds.getBounds !== 'function')
         return null;
     const r = withBounds.getBounds();
+    if (r.width === 0 && r.height === 0)
+        return null;
     return { x: r.x, y: r.y, width: r.width, height: r.height };
 }

package/dist/index.d.ts

@@ -22,6 +22,8 @@ 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, EditorCreateEntityMessage, EditorDeleteEntityMessage, EditorSdkToHostMessage, } 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>;

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

@@ -94,14 +94,45 @@ function createGroup(ctx, entity) {
     return container;
 }
 function createCodeRendered(ctx, entity) {
+    const w = entity.visual.width ?? 64;
+    const h = entity.visual.height ?? 64;
     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(-w / 2, -h / 2, w, h);
+        ph.lineStyle(2, 0xff8800, 0.9);
+        ph.strokeRect(-w / 2, -h / 2, w, h);
+        sizeForHitTest(ph, w, h);
+        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);
+    sizeForHitTest(g, w, h);
+    // Stash data needed for live re-render from EditorBridge.applyEdit.
+    g.setData('renderScriptPath', entity.visual.script);
+    g.setData('renderScriptParams', params);
     return g;
 }
+/**
+ * Phaser Graphics doesn't track its drawn area — `getBounds()` returns
+ * a 0×0 rect because the Graphics class doesn't include the Size/Origin
+ * mixins. Rather than fight Phaser's class hierarchy with method casts,
+ * stash the editor hit area on the GameObject's data manager. The editor
+ * overlay reads these before falling back to `getBounds()`. The implicit
+ * convention: hit area is centered on the GameObject's x/y, matching how
+ * render scripts conventionally draw around (0, 0).
+ */
+function sizeForHitTest(g, width, height) {
+    g.setData('editorHitWidth', width);
+    g.setData('editorHitHeight', height);
+}
 function applyTransform(go, t) {
     // Most game objects implement Transform; Container does too. Cast through
     // a permissive shape so this works for sprite/rect/circle/container alike.

package/dist/scene/types.d.ts

@@ -116,6 +116,14 @@ export interface CodeRenderedVisual {
     /** Path to render script, e.g. `"src/visuals/boss-renderer.ts"`. */
     script: string;
     params?: Record<string, unknown>;
+    /**
+     * Optional bounds used for editor hit-testing (click + drag) and the
+     * selection rectangle. Phaser Graphics has no intrinsic size, so we set
+     * it explicitly. Defaults to 64×64 centered on the entity. The agent can
+     * override per-entity when the script draws something larger or smaller.
+     */
+    width?: number;
+    height?: number;
 }
 export type WorldVisual = SpriteVisual | PrimitiveVisual | CodeRenderedVisual;
 export type WorldEntityKind = 'sprite' | 'primitive' | 'code-rendered' | 'group' | 'tilemap' | 'trigger';

package/package.json

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