@unboxy/phaser-sdk 0.2.20 → 0.2.21

package/SDK-GUIDE.md

@@ -638,6 +638,8 @@ The `scene-data-architecture` agent skill has the full guidance. The `scene-data
 
 ## Changelog
 
+- **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/editor/EditorBridge.js

@@ -1,5 +1,6 @@
+import Phaser from 'phaser';
 import { getEntityRegistry } from '../scene/EntityRegistry.js';
-import { parseColor } from '../scene/spawnEntity.js';
+import { parseColor, spawnEntity } from '../scene/spawnEntity.js';
 import { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './EditorOverlayScene.js';
 import { getEditorState, setEditorActive, setSelection, } from './EditorState.js';
 /**
@@ -53,6 +54,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 +158,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];
 }
@@ -292,6 +309,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

@@ -24,7 +24,7 @@ export { EntityRegistry, attachEntityRegistry, getEntityRegistry, } from './scen
 export { setupEditorModeListener, isEditMode } from './scene/EditorMode.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/protocol.d.ts

@@ -108,12 +108,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/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)}`);
@@ -122,6 +124,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.21",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",