@unboxy/phaser-sdk 0.2.18 → 0.2.19

package/SDK-GUIDE.md

@@ -638,6 +638,7 @@ The `scene-data-architecture` agent skill has the full guidance. The `scene-data
 
 ## Changelog
 
+- **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.
 - **0.2.16** — added orientation presets. `createUnboxyGame` now accepts an `orientation: 'portrait' | 'landscape'` option as an alternative to explicit `width`/`height` (TS union — pass one or the other). New exports: `Orientation` type and `ORIENTATION_DIMENSIONS` map (`landscape: 1280×720`, `portrait: 720×1280`). Lets games declare orientation once and have a single source of truth for canvas dimensions.

package/dist/editor/EditorBridge.js

@@ -60,6 +60,36 @@ function enterEdit(game) {
     if (getEditorState(game).active)
         return;
     setEditorActive(game, true);
+    pauseActiveNonEditor(game);
+    // Launch the overlay AFTER pausing world scenes so it sits on top in render
+    // order (Phaser renders scenes in the order they were started).
+    const overlayInit = buildOverlayInit(game);
+    if (!game.scene.isActive(EDITOR_OVERLAY_KEY)) {
+        game.scene.run(EDITOR_OVERLAY_KEY, overlayInit);
+    }
+    // Send the initial scene snapshot so home-ui can populate Hierarchy /
+    // Inspector without a separate getScene round-trip.
+    postSceneSnapshot(game);
+    // Race-window catch: when home-ui sends `enter` right after iframe load
+    // (which is exactly the auto-flush rebuild path), BootScene may still be
+    // in preload / GameScene may not have started, so the synchronous pause
+    // above had nothing to pause and the snapshot found no scene file in
+    // cache yet. Re-attempt for ~3 seconds. Each attempt is cheap and stops
+    // automatically once the user exits edit mode.
+    let attempts = 0;
+    const reattempt = () => {
+        if (!getEditorState(game).active)
+            return;
+        pauseActiveNonEditor(game);
+        if (!hasPostedSnapshot(game))
+            postSceneSnapshot(game);
+        attempts += 1;
+        if (attempts < 30)
+            setTimeout(reattempt, 100);
+    };
+    setTimeout(reattempt, 100);
+}
+function pauseActiveNonEditor(game) {
     for (const scene of game.scene.getScenes(true)) {
         const key = scene.scene.key;
         if (BOOT_SCENE_KEYS.has(key))
@@ -69,19 +99,14 @@ function enterEdit(game) {
         if (scene.scene.isActive())
             scene.scene.pause();
     }
-    // Launch the overlay AFTER pausing world scenes so it sits on top in render
-    // order (Phaser renders scenes in the order they were started).
-    const overlayInit = buildOverlayInit(game);
-    game.scene.run(EDITOR_OVERLAY_KEY, overlayInit);
-    // Send the initial scene snapshot so home-ui can populate Hierarchy /
-    // Inspector without a separate getScene round-trip.
-    postSceneSnapshot(game);
 }
 function exitEdit(game) {
     if (!getEditorState(game).active)
         return;
     setEditorActive(game, false);
     setSelection(game, null);
+    // Allow next enter to re-post the snapshot (scene file may have changed).
+    delete game[SNAPSHOT_POSTED_FLAG];
     if (game.scene.isActive(EDITOR_OVERLAY_KEY)) {
         game.scene.stop(EDITOR_OVERLAY_KEY);
     }
@@ -116,6 +141,7 @@ function buildOverlayInit(game) {
     };
 }
 // --- Snapshot -------------------------------------------------------------
+const SNAPSHOT_POSTED_FLAG = '__unboxyEditorSnapshotPostedFor';
 function postSceneSnapshot(game) {
     const sceneFile = readActiveSceneFile(game);
     if (!sceneFile)
@@ -125,6 +151,10 @@ function postSceneSnapshot(game) {
         sceneId: sceneFile.id,
         sceneFile,
     });
+    game[SNAPSHOT_POSTED_FLAG] = sceneFile.id;
+}
+function hasPostedSnapshot(game) {
+    return !!game[SNAPSHOT_POSTED_FLAG];
 }
 function readActiveSceneFile(game) {
     // The active world scene cached its scene file in Phaser's JSON cache via

package/package.json

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