@unboxy/phaser-sdk 0.2.37 → 0.2.38

package/dist/index.d.ts

@@ -27,6 +27,6 @@ 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, EditorSetEditModeMessage, EditorSelectionRectMessage, 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, TriggerShape, WorldVisual, SpriteVisual, PrimitiveVisual, PrimitiveRectVisual, PrimitiveCircleVisual, CodeRenderedVisual, HudEntity, HudEntityKind, HudEntityBase, HudTextEntity, HudImageEntity, HudIconButtonEntity, HudProgressBarEntity, HudPanelEntity, HudVisual, HudTextVisual, HudImageVisual, HudIconButtonVisual, HudProgressBarVisual, HudPanelVisual, HudTextSource, HudNumberSource, HudLayer, Transform, Anchor, AnchorSide, NinePatchConfig, } from './scene/types.js';
+export { SCHEMA_VERSION, isPerFrameNinePatch, } 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, HudEntity, HudEntityKind, HudEntityBase, HudTextEntity, HudImageEntity, HudIconButtonEntity, HudProgressBarEntity, HudPanelEntity, HudVisual, HudTextVisual, HudImageVisual, HudIconButtonVisual, HudProgressBarVisual, HudPanelVisual, HudTextSource, HudNumberSource, HudLayer, Transform, Anchor, AnchorSide, NinePatchConfig, NinePatchPerFrame, } 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/index.js

@@ -21,5 +21,5 @@ 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';
+export { SCHEMA_VERSION, isPerFrameNinePatch, } from './scene/types.js';
 export { PROTOCOL_VERSION, } from './protocol.js';

package/dist/scene/HudRuntime.js

@@ -1,5 +1,5 @@
 import Phaser from 'phaser';
-import { SCHEMA_VERSION, } from './types.js';
+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';
@@ -80,21 +80,44 @@ const LAYER_DEPTH = {
     modal: 300,
 };
 /**
- * Render an image asset at (x, y) sized to (width, height). When the asset
- * carries `ninePatch` metadata, uses `phaser3-rex-plugins`' NinePatch (corners
- * fixed, edges + center stretch); otherwise falls back to a regular Image
- * scaled with `setDisplaySize`. Caller owns origin/anchor — both Image and
- * NinePatch (which extends RenderTexture) expose `setOrigin`. Returns the
- * created GameObject already added to the scene's display list.
+ * Render an image (or one cell of a uniform-grid spritesheet) at (x, y) sized
+ * to (width, height). When the asset carries `ninePatch` metadata, uses
+ * `phaser3-rex-plugins`' NinePatch (corners fixed, edges + center stretch);
+ * otherwise falls back to a regular Image scaled with `setDisplaySize`.
+ *
+ * Two ninePatch shapes accepted:
+ *   - Single image (slice 7.5): `asset.ninePatch` is a `NinePatchConfig`. The
+ *     whole texture slices into 9 regions.
+ *   - Per-frame on a uniform-grid sheet (slice 7.6): `asset.ninePatch` is
+ *     `{ perFrame: NinePatchConfig }`. The shared cuts apply to whichever
+ *     frame the caller picks via `frame`. Common case: itch.io button packs
+ *     where every cell is a different button color/state with the same
+ *     corner radius.
+ *
+ * Caller owns origin/anchor — both Image and NinePatch (which extends
+ * RenderTexture) expose `setOrigin`. Returns the created GameObject already
+ * added to the scene's display list.
  */
-function createImageOrNinePatch(scene, x, y, width, height, asset) {
+function createImageOrNinePatch(scene, x, y, width, height, asset, frame) {
     if (asset.ninePatch) {
         const np = asset.ninePatch;
+        const isPerFrame = isPerFrameNinePatch(np);
+        const cuts = isPerFrame ? np.perFrame : np;
         const factory = scene.add.rexNinePatch;
         if (factory) {
+            const columns = [cuts.leftWidth, undefined, cuts.rightWidth];
+            const rows = [cuts.topHeight, undefined, cuts.bottomHeight];
+            // Per-frame uses rex's 9-arg `(scene, x, y, w, h, key, baseFrame, cols, rows)`
+            // form — baseFrame scopes the slicing to that one cell of the spritesheet.
+            // rex types baseFrame as string; Phaser accepts either string or number
+            // for spritesheet frame access, but passing String() satisfies the typed
+            // overload on rex's side.
+            if (isPerFrame) {
+                return factory.call(scene.add, x, y, width, height, asset.textureKey, String(frame ?? 0), columns, rows);
+            }
             // Middle column/row left undefined → that segment stretches to fill
             // the remaining space between the two fixed-width edges.
-            return factory.call(scene.add, x, y, width, height, asset.textureKey, [np.leftWidth, undefined, np.rightWidth], [np.topHeight, undefined, np.bottomHeight]);
+            return factory.call(scene.add, x, y, width, height, asset.textureKey, columns, rows);
         }
         // Plugin not registered — degrade to a stretched Image rather than crash
         // an entire HUD render. Symptom is "corners distort on resize", not a
@@ -103,7 +126,11 @@ function createImageOrNinePatch(scene, x, y, width, height, asset) {
         // eslint-disable-next-line no-console
         console.warn(`[unboxy/hud] rexNinePatch plugin not registered; falling back to stretched Image for asset '${asset.id}'`);
     }
-    const image = scene.add.image(x, y, asset.textureKey);
+    // Fallback: plain Image. Frame index threaded through for spritesheet
+    // 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);
     image.setDisplaySize(width, height);
     return image;
 }
@@ -261,7 +288,7 @@ 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);
+            const np = createImageOrNinePatch(ctx.scene, 0, 0, w, h, bgAsset, v.backgroundFrame);
             np.setOrigin?.(0.5, 0.5);
             bg = np;
             texturedBg = true;
@@ -439,7 +466,7 @@ 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);
+            const np = createImageOrNinePatch(ctx.scene, 0, 0, w, h, bgAsset, v.backgroundFrame);
             np.setOrigin?.(0.5, 0.5);
             container.add(np);
             bgRendered = true;
@@ -996,6 +1023,10 @@ export function applyHudPatch(game, entityId, patch) {
             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;
         // 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/types.d.ts

@@ -73,18 +73,22 @@ export interface AssetRecord {
     /** Default playback rate for `animations[]`. Defaults to 8. */
     fps?: number;
     /**
-     * For `image`: 9-slice cut-line metadata. When present, HUD widgets that
-     * render this asset (image / icon-button background / panel background)
-     * scale via `phaser3-rex-plugins` NinePatch instead of plain stretched
-     * Image — corners stay fixed, edges + center stretch. Pack-import vision
-     * captures these on UI button/panel imports; users can edit in the Adjust
-     * modal at import time.
+     * 9-slice cut-line metadata. Two shapes accepted:
      *
-     * <p>Single-image only in v1 (slice 7.5). Per-frame 9-slice on uniform-grid
-     * sheets (e.g. `Square Buttons 26x26.png`) is v2 — see
-     * `unboxy-design/features/visual-editor/07-asset-pack-import.md` §7.9.
+     * - **Single image** (slice 7.5) — `NinePatchConfig` directly. Used on
+     *   `kind: 'image'` assets like a single button/panel background. All four
+     *   corner widths apply to the image as a whole.
+     * - **Per-frame on a uniform grid** (slice 7.6) — `{ perFrame: NinePatchConfig }`.
+     *   Used on `kind: 'spritesheet'` assets where every cell is its own
+     *   stretchable button/panel sharing the same corner radius (typical
+     *   itch.io UI button packs, e.g. `Square Buttons 26x26.png`). The HUD
+     *   widget references which cell to render via `backgroundFrame`.
+     *
+     * Per-cell keyed config (`{ perFrame: Record<number, NinePatchConfig> }`)
+     * is deferred to v3 per design 07 §7.9.5 — promote only when a real pack
+     * needs different corner radii on different cells.
      */
-    ninePatch?: NinePatchConfig;
+    ninePatch?: NinePatchConfig | NinePatchPerFrame;
     /**
      * Vision-detected pixel-art flag. When true, SDK applies
      * `Phaser.Textures.FilterMode.NEAREST` to the texture after load so it
@@ -101,6 +105,20 @@ export interface NinePatchConfig {
     topHeight: number;
     bottomHeight: number;
 }
+/**
+ * Per-frame 9-slice config (slice 7.6). One shared `NinePatchConfig` applied
+ * to every frame of a uniform-grid spritesheet. Covers ~95% of itch.io UI
+ * button packs, where each cell is a different button color/state but all
+ * share the same corner radius.
+ */
+export interface NinePatchPerFrame {
+    perFrame: NinePatchConfig;
+}
+/**
+ * Type guard — true when `ninePatch` is the per-frame variant. Lets call
+ * sites that only need to handle one shape stay narrow.
+ */
+export declare function isPerFrameNinePatch(np: NinePatchConfig | NinePatchPerFrame | undefined): np is NinePatchPerFrame;
 export interface SheetAnimation {
     /** Phaser animation key — used as `sprite.play('<name>')`. */
     name: string;
@@ -380,8 +398,19 @@ export interface HudIconButtonVisual {
      * otherwise the image is stretched to the widget's size. When set, the
      * colored-rect bg below (fillColor / strokeColor / shape) is ignored, and
      * `pressedFillColor` no-ops (no fill swap on a textured bg in v1).
+     *
+     * For uniform-grid spritesheet assets with `ninePatch.perFrame` set
+     * (slice 7.6), pair this with `backgroundFrame` to pick which cell to
+     * render — common case is a button-pack sheet where every cell is a
+     * different button color/state.
      */
     backgroundAssetId?: string;
+    /**
+     * 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.
+     */
+    backgroundFrame?: number;
     /** Button shape. Default `rounded-rect`. Ignored when backgroundAssetId is set. */
     shape?: 'rounded-rect' | 'circle';
     width?: number;
@@ -433,8 +462,18 @@ export interface HudPanelVisual {
      * otherwise the image is stretched to the widget's size. When set,
      * `backgroundColor` / `backgroundAlpha` / `borderColor` / `borderWidth` are
      * ignored — the asset image carries its own pixels.
+     *
+     * For uniform-grid spritesheet assets with `ninePatch.perFrame` set
+     * (slice 7.6), pair this with `backgroundFrame` to pick which cell to
+     * render.
      */
     backgroundAssetId?: string;
+    /**
+     * 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.
+     */
+    backgroundFrame?: number;
     /** Solid fill colour. Falls back to a transparent panel if omitted. */
     backgroundColor?: string;
     /** Background alpha (independent of widget-level alpha). */

package/dist/scene/types.js

@@ -8,3 +8,10 @@
  * code-rendered visuals will land in later slices.
  */
 export const SCHEMA_VERSION = 1;
+/**
+ * Type guard — true when `ninePatch` is the per-frame variant. Lets call
+ * sites that only need to handle one shape stay narrow.
+ */
+export function isPerFrameNinePatch(np) {
+    return !!np && 'perFrame' in np;
+}

package/package.json

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