@unboxy/phaser-sdk 0.2.40 → 0.2.42

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);
+                }
             }
         }
     }
@@ -1093,25 +1118,19 @@ export function applyHudPatch(game, entityId, patch) {
         }
     }
     if (patch.visual && entity.kind === 'icon-button') {
-        // Icon-button is a Container — visual patches require a small refresh.
-        // For v1 we just patch the entity record + label/colour fields cheaply;
-        // wholesale re-spawn lands in slice 5.5 if we add live re-styling.
+        // Icon-button is a Container — visual patches re-spawn the container
+        // in place. Use a generic loop to copy every patched field into the
+        // entity record so we don't have to enumerate fields here every time
+        // the schema grows. Older fields kept as explicit for clarity below
+        // are now subsumed by this loop but left commented as a reminder.
         const v = entity.visual;
         const p = patch.visual;
-        if (typeof p.label === 'string')
-            v.label = p.label;
-        if (typeof p.fillColor === 'string')
-            v.fillColor = p.fillColor;
-        if (typeof p.iconAssetId === 'string')
-            v.iconAssetId = p.iconAssetId;
-        if (typeof p.backgroundAssetId === 'string')
-            v.backgroundAssetId = p.backgroundAssetId;
-        else if (p.backgroundAssetId === null)
-            v.backgroundAssetId = undefined;
-        if (typeof p.backgroundFrame === 'number')
-            v.backgroundFrame = p.backgroundFrame;
-        else if (p.backgroundFrame === null)
-            v.backgroundFrame = undefined;
+        for (const [k, val] of Object.entries(p)) {
+            if (val === null)
+                delete v[k];
+            else if (val !== undefined)
+                v[k] = val;
+        }
         // Patches that change the rendered visual deeply (label, colour, icon)
         // re-render by destroying + re-spawning the container in place.
         const reg2 = reg;

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.40",
+  "version": "0.2.42",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",