@unboxy/phaser-sdk 0.2.41 → 0.2.43

package/dist/editor/EditorBridge.js

@@ -49,7 +49,7 @@ function handleMessage(game, msg) {
             postSceneSnapshot(game);
             break;
         case 'unboxy:editor:applyEdit':
-            applyEdit(game, msg.entityId, msg.patch);
+            void applyEdit(game, msg.entityId, msg.patch, msg.manifestAsset);
             break;
         case 'unboxy:editor:setSelection':
             setSelection(game, msg.entityIds[0] ?? null);
@@ -429,7 +429,30 @@ function findRegistry(game) {
     return undefined;
 }
 // --- applyEdit ------------------------------------------------------------
-function applyEdit(game, entityId, patch) {
+async function applyEdit(game, entityId, patch, manifestAsset) {
+    // Lazy-load + manifest-upsert path. When the host's Inspector picks a Bg
+    // image asset that the iframe never preloaded (e.g. a per-game upload that
+    // was never dragged into the scene) OR an asset whose `kind` just flipped
+    // (e.g. region-atlas — slice 10 — flipping from 'image' to 'atlas'), the
+    // host pipelines the new manifest entry along with the patch so the
+    // resulting re-spawn sees a consistent runtime state. Without this, the
+    // re-spawn reads the stale cached manifest and falls back to the
+    // colored-rect placeholder.
+    if (manifestAsset) {
+        const targetScene = getEditorMode(game) === 'hud'
+            ? game.scene.getScene(UNBOXY_HUD_SCENE_KEY)
+            : findWorldScene(game);
+        if (targetScene) {
+            try {
+                upsertCachedManifestAsset(targetScene, manifestAsset);
+                await ensureAssetLoaded(targetScene, manifestAsset);
+            }
+            catch (e) {
+                console.warn('[unboxy/editor] applyEdit asset upsert/load failed:', e);
+                // Fall through — applyHudPatch will render its placeholder.
+            }
+        }
+    }
     // HUD mode — patches modify anchor / HUD-visual fields. World-style
     // transform / sprite-tint patches don't apply to HUD widgets, so we
     // dispatch through a HUD-specific helper that knows the widget kinds.
@@ -625,6 +648,51 @@ async function createEntity(game, entity, manifestAsset) {
         console.warn('[unboxy/editor] spawnEntity failed:', e);
     }
 }
+/**
+ * Merge an asset record into the scene's cached manifest (the one
+ * {@code getManifest(scene)} returns). Used by applyEdit's pipelined-asset
+ * path so subsequent re-spawns see the updated entry (kind / atlasPath /
+ * atlasFormat / ninePatch / etc.) without a full scene reload.
+ *
+ * <p>The manifest object lives in `scene.cache.json` and is shared by
+ * reference — mutating its `assets[]` is sufficient. We replace in place
+ * when an entry with the same id exists (so a stale {@code kind: 'image'}
+ * gets fully overwritten by a fresh {@code kind: 'atlas'} record).
+ */
+function upsertCachedManifestAsset(scene, asset) {
+    let manifest;
+    try {
+        manifest = getManifest(scene);
+    }
+    catch {
+        return; // manifest not in cache — nothing to merge against
+    }
+    if (!manifest.assets)
+        manifest.assets = [];
+    const idx = manifest.assets.findIndex((a) => a.id === asset.id);
+    if (idx >= 0)
+        manifest.assets[idx] = asset;
+    else
+        manifest.assets.push(asset);
+}
+/**
+ * Idempotent asset-loaded check: returns immediately if the texture is in
+ * the cache. For atlas-format assets, ALSO ensures the per-frame ninePatch
+ * sidecar JSON is loaded so the SDK's region-9-slice path can read it back.
+ */
+function ensureAssetLoaded(scene, asset) {
+    if (asset.kind === 'audio')
+        return Promise.resolve();
+    const needsTexture = !scene.textures.exists(asset.textureKey);
+    const sidecarKey = `unboxy:atlas-ninepatch:${asset.textureKey}`;
+    const needsSidecar = asset.kind === 'atlas' &&
+        asset.atlasFormat === 'json' &&
+        !!asset.atlasPath &&
+        !scene.cache.json.exists(sidecarKey);
+    if (!needsTexture && !needsSidecar)
+        return Promise.resolve();
+    return loadAssetIntoScene(scene, asset);
+}
 function loadAssetIntoScene(scene, asset) {
     return new Promise((resolve, reject) => {
         if (scene.textures.exists(asset.textureKey)) {
@@ -673,6 +741,13 @@ function loadAssetIntoScene(scene, asset) {
                 }
                 else if (asset.atlasPath) {
                     scene.load.atlas(asset.textureKey, asset.path, asset.atlasPath);
+                    // Also fetch the raw JSON into the side-cache for per-region
+                    // ninePatch lookups (slice 10). Phaser's atlas parser drops
+                    // unknown per-frame fields, so we keep the original JSON around.
+                    const sidecarKey = `unboxy:atlas-ninepatch:${asset.textureKey}`;
+                    if (!scene.cache.json.exists(sidecarKey)) {
+                        scene.load.json(sidecarKey, asset.atlasPath);
+                    }
                 }
                 break;
             case 'audio':

package/dist/protocol.d.ts

@@ -130,6 +130,21 @@ export interface EditorApplyEditMessage {
     type: 'unboxy:editor:applyEdit';
     entityId: string;
     patch: EditorEntityPatch;
+    /**
+     * Optional asset record to upsert into the iframe's manifest cache + lazy-
+     * load before the patch applies. Mirrors {@link EditorCreateEntityMessage}'s
+     * `manifestAsset` field. Used by the Inspector's Bg-image picker when the
+     * user picks an asset whose manifest entry needs flipping (e.g. region
+     * atlases — visual editor slice 10 — where the existing manifest entry
+     * was {@code kind: 'image'} but the asset is now atlas-format).
+     *
+     * <p>When present, the bridge:
+     *   1. Merges the asset into {@code scene.cache.json}'s manifest record
+     *   2. Lazy-loads the texture (and atlas-ninepatch sidecar JSON when
+     *      {@code kind: 'atlas' + atlasFormat: 'json'})
+     *   3. Applies the entity patch
+     */
+    manifestAsset?: unknown;
 }
 export interface EditorSetSelectionMessage {
     type: 'unboxy:editor:setSelection';

package/dist/scene/HudRuntime.js

@@ -2,7 +2,7 @@ import Phaser from 'phaser';
 import { SCHEMA_VERSION, isPerFrameNinePatch, } from './types.js';
 import { attachEntityRegistry, getEntityRegistry, } from './EntityRegistry.js';
 import { parseColor } from './spawnEntity.js';
-import { applyPixelArtFilters, getManifest, SCENES_BASE } from './SceneLoader.js';
+import { applyPixelArtFilters, getAtlasFrameNinePatch, getManifest, SCENES_BASE, } from './SceneLoader.js';
 /**
  * HUD runtime — slice 5.
  *
@@ -99,13 +99,26 @@ const LAYER_DEPTH = {
  * added to the scene's display list.
  */
 function createImageOrNinePatch(scene, x, y, width, height, asset, frame) {
+    // Region-atlas path (slice 10) — when the asset is an atlas-format texture
+    // AND the caller picks a frame by string name, per-region ninePatch
+    // metadata may live in the atlas JSON. Phaser drops unknown per-frame
+    // fields on parse, so we read from the side-cache stashed at preload.
+    if (asset.kind === 'atlas' && asset.atlasFormat === 'json' && typeof frame === 'string') {
+        const cuts = getAtlasFrameNinePatch(scene, asset.textureKey, frame);
+        if (cuts) {
+            return createCustomNinePatch(scene, x, y, width, height, asset, cuts, frame);
+        }
+        // Atlas frame without 9-slice metadata → plain stretched Image of that
+        // region. Falls through to the generic fallback below.
+    }
     if (asset.ninePatch) {
         const np = asset.ninePatch;
         const cuts = isPerFrameNinePatch(np) ? np.perFrame : np;
         return createCustomNinePatch(scene, x, y, width, height, asset, cuts, frame);
     }
-    // Fallback: plain Image. Frame index threaded through for spritesheet
-    // assets so per-cell rendering still works without 9-slice.
+    // Fallback: plain Image. Frame (number index or string atlas-name) threaded
+    // through for spritesheet / atlas assets so per-cell rendering still works
+    // without 9-slice.
     const image = frame !== undefined
         ? scene.add.image(x, y, asset.textureKey, frame)
         : scene.add.image(x, y, asset.textureKey);
@@ -139,8 +152,9 @@ function createImageOrNinePatch(scene, x, y, width, height, asset, frame) {
 function createCustomNinePatch(scene, x, y, width, height, asset, cuts, frame) {
     const texKey = asset.textureKey;
     const texture = scene.textures.get(texKey);
-    // Per-frame variant: look up the specified cell's source rect. Single
-    // image: the texture's `__BASE` frame covers the entire image.
+    // Per-frame variant: look up the specified cell's source rect (number for
+    // uniform-grid sheets, atlas-name string for region atlases). Single image
+    // uses the texture's `__BASE` frame covering the whole image.
     const baseFrame = frame !== undefined
         ? texture.get(frame)
         : texture.get('__BASE');
@@ -373,7 +387,10 @@ function createIconButton(ctx, entity, pos) {
     if (v.backgroundAssetId) {
         try {
             const bgAsset = ctx.resolveAsset(v.backgroundAssetId);
-            const np = createImageOrNinePatch(ctx.scene, 0, 0, w, h, bgAsset, v.backgroundFrame);
+            // Region-atlas name (string) wins when both are set; uniform-grid index
+            // (number) is the fallback for slice 7.6 button packs.
+            const bgFrame = v.backgroundRegion ?? v.backgroundFrame;
+            const np = createImageOrNinePatch(ctx.scene, 0, 0, w, h, bgAsset, bgFrame);
             np.setOrigin?.(0.5, 0.5);
             bg = np;
             texturedBg = true;
@@ -551,7 +568,8 @@ function createPanel(ctx, entity, pos) {
     if (v.backgroundAssetId) {
         try {
             const bgAsset = ctx.resolveAsset(v.backgroundAssetId);
-            const np = createImageOrNinePatch(ctx.scene, 0, 0, w, h, bgAsset, v.backgroundFrame);
+            const bgFrame = v.backgroundRegion ?? v.backgroundFrame;
+            const np = createImageOrNinePatch(ctx.scene, 0, 0, w, h, bgAsset, bgFrame);
             np.setOrigin?.(0.5, 0.5);
             container.add(np);
             bgRendered = true;
@@ -732,6 +750,13 @@ export function preloadHudAssets(scene, hudScene, manifest) {
             }
             else if (asset.atlasPath && asset.atlasFormat === 'json') {
                 scene.load.atlas(asset.textureKey, asset.path, asset.atlasPath);
+                // Also fetch the raw JSON into the side-cache so per-frame
+                // `ninePatch` metadata (which Phaser drops on parse) is readable at
+                // spawn time via `getAtlasFrameNinePatch`. See SceneLoader.ts.
+                const sidecarKey = `unboxy:atlas-ninepatch:${asset.textureKey}`;
+                if (!scene.cache.json.exists(sidecarKey)) {
+                    scene.load.json(sidecarKey, asset.atlasPath);
+                }
             }
         }
     }

package/dist/scene/SceneLoader.d.ts

@@ -60,6 +60,18 @@ export declare function preloadSceneAssets(scene: Phaser.Scene, sceneFile: Scene
  * concern (framebuffer-stretch crispness, perf) deferred to a follow-up.
  */
 export declare function applyPixelArtFilters(scene: Phaser.Scene, manifest: Manifest): void;
+/**
+ * Look up per-frame 9-slice metadata for an atlas-format asset. Returns the
+ * `NinePatchConfig` declared inline on the named frame in the atlas JSON, or
+ * `undefined` if the asset isn't an atlas, the cache miss happened, or the
+ * frame has no `ninePatch` entry (plain stretched draw).
+ */
+export declare function getAtlasFrameNinePatch(scene: Phaser.Scene, textureKey: string, frameName: string): {
+    leftWidth: number;
+    rightWidth: number;
+    topHeight: number;
+    bottomHeight: number;
+} | undefined;
 export interface LoadWorldSceneOptions {
     /**
      * Optional render-script resolver for `code-rendered` entities. When

package/dist/scene/SceneLoader.js

@@ -196,6 +196,55 @@ function registerSheetAnimations(scene, manifest) {
         }
     }
 }
+/**
+ * Atlas-json side-cache key. Phaser's `scene.load.atlas()` loads + parses the
+ * JSON but drops unknown per-frame fields (e.g. `ninePatch`) — they don't
+ * survive into the Phaser Frame object. To consume them at runtime we ALSO
+ * fetch the raw JSON via `scene.load.json()` and stash it under this key so
+ * `getAtlasFrameNinePatch` can read it back.
+ *
+ * Used by region-atlas assets (visual editor slice 10) where each tagged
+ * region can carry its own 9-slice cuts.
+ */
+function atlasNinePatchCacheKey(textureKey) {
+    return `unboxy:atlas-ninepatch:${textureKey}`;
+}
+function queueAtlasNinePatchSidecar(scene, asset) {
+    if (!asset.atlasPath)
+        return;
+    const cacheKey = atlasNinePatchCacheKey(asset.textureKey);
+    if (scene.cache.json.exists(cacheKey))
+        return;
+    scene.load.json(cacheKey, asset.atlasPath);
+}
+/**
+ * Look up per-frame 9-slice metadata for an atlas-format asset. Returns the
+ * `NinePatchConfig` declared inline on the named frame in the atlas JSON, or
+ * `undefined` if the asset isn't an atlas, the cache miss happened, or the
+ * frame has no `ninePatch` entry (plain stretched draw).
+ */
+export function getAtlasFrameNinePatch(scene, textureKey, frameName) {
+    const cacheKey = atlasNinePatchCacheKey(textureKey);
+    if (!scene.cache.json.exists(cacheKey))
+        return undefined;
+    const raw = scene.cache.json.get(cacheKey);
+    const entry = raw?.frames?.[frameName];
+    const np = entry?.ninePatch;
+    if (!np)
+        return undefined;
+    if (typeof np.leftWidth !== 'number' ||
+        typeof np.rightWidth !== 'number' ||
+        typeof np.topHeight !== 'number' ||
+        typeof np.bottomHeight !== 'number') {
+        return undefined;
+    }
+    return {
+        leftWidth: np.leftWidth,
+        rightWidth: np.rightWidth,
+        topHeight: np.topHeight,
+        bottomHeight: np.bottomHeight,
+    };
+}
 function queueAssetLoad(scene, asset) {
     if (scene.textures.exists(asset.textureKey))
         return;
@@ -235,6 +284,7 @@ function queueAssetLoad(scene, asset) {
             }
             else {
                 scene.load.atlas(asset.textureKey, asset.path, asset.atlasPath);
+                queueAtlasNinePatchSidecar(scene, asset);
             }
             return;
         case 'audio':

package/dist/scene/types.d.ts

@@ -408,9 +408,18 @@ export interface HudIconButtonVisual {
     /**
      * For uniform-grid spritesheet backgrounds (slice 7.6): index of the cell
      * to render. Defaults to 0 when omitted. Ignored when the background asset
-     * is a single image.
+     * is a single image. Mutually exclusive with `backgroundRegion` — when both
+     * are set, the SDK picks `backgroundRegion` (atlas-name lookup wins).
      */
     backgroundFrame?: number;
+    /**
+     * For region-atlas backgrounds (slice 10): name of the atlas frame to
+     * render. Used when the referenced asset is `kind: 'atlas'` + `atlasFormat:
+     * 'json'` — the region atlas can carry per-frame `ninePatch` metadata, in
+     * which case the SDK 9-slices each region independently. Mutually exclusive
+     * with `backgroundFrame`.
+     */
+    backgroundRegion?: string;
     /** Button shape. Default `rounded-rect`. Ignored when backgroundAssetId is set. */
     shape?: 'rounded-rect' | 'circle';
     width?: number;
@@ -471,9 +480,14 @@ export interface HudPanelVisual {
     /**
      * For uniform-grid spritesheet backgrounds (slice 7.6): index of the cell
      * to render. Defaults to 0 when omitted. Ignored when the background asset
-     * is a single image.
+     * is a single image. Mutually exclusive with `backgroundRegion`.
      */
     backgroundFrame?: number;
+    /**
+     * For region-atlas backgrounds (slice 10): name of the atlas frame to
+     * render. See `HudIconButtonVisual.backgroundRegion` for semantics.
+     */
+    backgroundRegion?: string;
     /** Solid fill colour. Falls back to a transparent panel if omitted. */
     backgroundColor?: string;
     /** Background alpha (independent of widget-level alpha). */

package/package.json

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