@unboxy/phaser-sdk 0.2.36 → 0.2.38

package/dist/core/UnboxyGame.js

@@ -1,4 +1,5 @@
 import Phaser from 'phaser';
+import NinePatchPlugin from 'phaser3-rex-plugins/plugins/ninepatch-plugin.js';
 import { setupScreenshotListener } from '../screenshot/ScreenshotManager.js';
 import { setupRecordingListener } from '../recording/RecordingManager.js';
 import { setupEditorModeListener } from '../scene/EditorMode.js';
@@ -13,6 +14,20 @@ export function createUnboxyGame(options) {
     const { width, height } = 'orientation' in options && options.orientation
         ? ORIENTATION_DIMENSIONS[options.orientation]
         : { width: options.width, height: options.height };
+    // Auto-register rex-plugins NinePatch so HUD widgets with 9-slice asset
+    // metadata (`Asset.ninePatch`) can scale without corner distortion. Plugin
+    // exposes `scene.add.rexNinePatch(...)` factory; HudRuntime calls it on
+    // demand. Merged with any user-supplied `plugins.global` so existing
+    // rexVirtualJoystick / rexUI registrations keep working.
+    const ninePatchEntry = {
+        key: 'rexNinePatchPlugin',
+        plugin: NinePatchPlugin,
+        start: true,
+    };
+    const plugins = {
+        ...(options.plugins ?? {}),
+        global: [ninePatchEntry, ...(options.plugins?.global ?? [])],
+    };
     const config = {
         type: Phaser.AUTO,
         backgroundColor: options.backgroundColor ?? '#1a1a2e',
@@ -30,7 +45,7 @@ export function createUnboxyGame(options) {
             default: 'arcade',
             arcade: { gravity: { x: 0, y: 0 }, debug: false },
         },
-        ...(options.plugins ? { plugins: options.plugins } : {}),
+        plugins,
         // UnboxyHudScene is auto-registered alongside the game's scenes so
         // `loadWorldScene` can launch it when the active world scene's manifest
         // entry sets `hud: '<id>'`. Registered at the end so the user's scenes

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export type { ChatMessage, ChatMessageKind } from './realtime/UnboxyRoom.js';
 export { RpcError } from './core/Transport.js';
 export type { Transport, TransportKind } from './core/Transport.js';
 export type { UnboxyUser } from './protocol.js';
-export { loadWorldScene, preloadManifest, preloadSceneAssets, getManifest, SCENES_BASE, MANIFEST_PATH, } from './scene/SceneLoader.js';
+export { loadWorldScene, preloadManifest, preloadSceneAssets, applyPixelArtFilters, getManifest, SCENES_BASE, MANIFEST_PATH, } from './scene/SceneLoader.js';
 export type { LoadWorldSceneOptions } from './scene/SceneLoader.js';
 export { spawnEntity, parseColor } from './scene/spawnEntity.js';
 export type { SpawnContext, AssetResolver, RenderScriptResolver, } from './scene/spawnEntity.js';
@@ -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, } 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

@@ -14,12 +14,12 @@ export { RealtimeModule } from './realtime/RealtimeModule.js';
 export { UnboxyRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UnboxyRoom.js';
 export { RpcError } from './core/Transport.js';
 // Scene-as-data (visual editor foundation, slice 1)
-export { loadWorldScene, preloadManifest, preloadSceneAssets, getManifest, SCENES_BASE, MANIFEST_PATH, } from './scene/SceneLoader.js';
+export { loadWorldScene, preloadManifest, preloadSceneAssets, applyPixelArtFilters, getManifest, SCENES_BASE, MANIFEST_PATH, } from './scene/SceneLoader.js';
 export { spawnEntity, parseColor } from './scene/spawnEntity.js';
 export { EntityRegistry, attachEntityRegistry, getEntityRegistry, } from './scene/EntityRegistry.js';
 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,8 +1,8 @@
 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 { getManifest, SCENES_BASE } from './SceneLoader.js';
+import { applyPixelArtFilters, getManifest, SCENES_BASE } from './SceneLoader.js';
 /**
  * HUD runtime — slice 5.
  *
@@ -79,6 +79,61 @@ const LAYER_DEPTH = {
     overlay: 200,
     modal: 300,
 };
+/**
+ * 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, 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, 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
+        // missing widget. Likely cause: a host that bypassed createUnboxyGame's
+        // auto-registration (e.g. an external Phaser.Game instance).
+        // eslint-disable-next-line no-console
+        console.warn(`[unboxy/hud] rexNinePatch plugin not registered; falling back to stretched Image for asset '${asset.id}'`);
+    }
+    // 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;
+}
 /**
  * Spawn a HUD widget into the scene. The returned GameObject is recorded in
  * the entity registry so the editor + behavior code can find it by id.
@@ -161,6 +216,23 @@ function createImage(ctx, entity, pos) {
         container.setSize(w, h);
         return container;
     }
+    // 9-slice path. When the asset has `ninePatch` metadata the SDK renders via
+    // rex-plugins NinePatch (corners fixed; edges + center stretch). NinePatch
+    // requires explicit dims, so missing width/height falls back to the texture's
+    // native source dims — keeps existing data shapes (image-without-dims) working.
+    if (asset.ninePatch) {
+        const tex = ctx.scene.textures.get(asset.textureKey);
+        const src = tex?.getSourceImage();
+        const w = entity.visual.width ?? src?.width ?? 64;
+        const h = entity.visual.height ?? src?.height ?? 64;
+        const np = createImageOrNinePatch(ctx.scene, pos.x, pos.y, w, h, asset);
+        if (entity.visual.tint)
+            np.setTint?.(parseColor(entity.visual.tint));
+        if (typeof entity.visual.alpha === 'number')
+            np.setAlpha(entity.visual.alpha);
+        applyOriginFromAnchor(np, entity.anchor.side);
+        return np;
+    }
     const image = entity.visual.frame !== undefined
         ? ctx.scene.add.image(pos.x, pos.y, asset.textureKey, entity.visual.frame)
         : ctx.scene.add.image(pos.x, pos.y, asset.textureKey);
@@ -174,19 +246,16 @@ function createImage(ctx, entity, pos) {
     applyOriginFromAnchor(image, entity.anchor.side);
     return image;
 }
-function createIconButton(ctx, entity, pos) {
-    const v = entity.visual;
-    const w = v.width ?? 96;
-    const h = v.height ?? 48;
-    const fillColor = parseColor(v.fillColor ?? '#3b82f6');
-    const strokeColor = v.strokeColor === null ? null : parseColor(v.strokeColor ?? '#1e40af');
-    const strokeW = v.strokeWidth ?? 0;
-    // Container at anchor pos. Children drawn with their own origins.
-    const container = ctx.scene.add.container(pos.x, pos.y);
+/**
+ * Build the v0 colored-rect background for an icon-button (rectangle or
+ * circle). Used when `backgroundAssetId` is unset OR the referenced asset
+ * couldn't be resolved.
+ */
+function makeColoredRectBg(scene, v, w, h, fillColor, strokeColor, strokeW) {
     const bg = v.shape === 'circle'
-        ? ctx.scene.add.circle(0, 0, Math.max(w, h) / 2, fillColor)
+        ? scene.add.circle(0, 0, Math.max(w, h) / 2, fillColor)
         : (() => {
-            const r = ctx.scene.add.rectangle(0, 0, w, h, fillColor);
+            const r = scene.add.rectangle(0, 0, w, h, fillColor);
             r.setOrigin(0.5, 0.5);
             return r;
         })();
@@ -198,6 +267,40 @@ function createIconButton(ctx, entity, pos) {
             bg.setStrokeStyle(strokeW, strokeColor);
         }
     }
+    return bg;
+}
+function createIconButton(ctx, entity, pos) {
+    const v = entity.visual;
+    const w = v.width ?? 96;
+    const h = v.height ?? 48;
+    const fillColor = parseColor(v.fillColor ?? '#3b82f6');
+    const strokeColor = v.strokeColor === null ? null : parseColor(v.strokeColor ?? '#1e40af');
+    const strokeW = v.strokeWidth ?? 0;
+    // Container at anchor pos. Children drawn with their own origins.
+    const container = ctx.scene.add.container(pos.x, pos.y);
+    // Background source (textured vs. colored-rect). When `backgroundAssetId`
+    // is set we render the asset image (NinePatch when the asset has 9-slice
+    // metadata; stretched Image otherwise); colored-rect bg is the v0 fallback.
+    // The interactive surface is always the `bg` GameObject — POINTER_DOWN/UP
+    // events fire on whichever variant is active.
+    let bg;
+    let texturedBg = false;
+    if (v.backgroundAssetId) {
+        try {
+            const bgAsset = ctx.resolveAsset(v.backgroundAssetId);
+            const np = createImageOrNinePatch(ctx.scene, 0, 0, w, h, bgAsset, v.backgroundFrame);
+            np.setOrigin?.(0.5, 0.5);
+            bg = np;
+            texturedBg = true;
+        }
+        catch {
+            // Background asset missing — fall through to colored-rect.
+            bg = makeColoredRectBg(ctx.scene, v, w, h, fillColor, strokeColor, strokeW);
+        }
+    }
+    else {
+        bg = makeColoredRectBg(ctx.scene, v, w, h, fillColor, strokeColor, strokeW);
+    }
     container.add(bg);
     if (v.iconAssetId) {
         try {
@@ -230,19 +333,23 @@ function createIconButton(ctx, entity, pos) {
     // code subscribes by entity id (or role) to wire its onPress action.
     // The editor mode ignores this — input is captured by the EditorOverlay.
     bg.setInteractive({ useHandCursor: true });
+    // pressedFillColor only applies to the colored-rect bg (Rectangle/Arc have
+    // setFillStyle). Textured backgrounds render the asset's pixels directly —
+    // pressed-state visual feedback for those is v2.
+    const supportsFillSwap = !texturedBg && !!v.pressedFillColor;
     bg.on(Phaser.Input.Events.POINTER_DOWN, () => {
-        if (v.pressedFillColor) {
+        if (supportsFillSwap) {
             bg.setFillStyle?.(parseColor(v.pressedFillColor));
         }
     });
     bg.on(Phaser.Input.Events.POINTER_UP, () => {
-        if (v.pressedFillColor) {
+        if (supportsFillSwap) {
             bg.setFillStyle?.(fillColor);
         }
         ctx.scene.events.emit('hud:press', entity.id, entity);
     });
     bg.on(Phaser.Input.Events.POINTER_OUT, () => {
-        if (v.pressedFillColor) {
+        if (supportsFillSwap) {
             bg.setFillStyle?.(fillColor);
         }
     });
@@ -351,35 +458,54 @@ function createPanel(ctx, entity, pos) {
     const w = v.width ?? 200;
     const h = v.height ?? 100;
     const container = ctx.scene.add.container(pos.x, pos.y);
-    const g = ctx.scene.add.graphics();
-    container.add(g);
-    const draw = () => {
-        g.clear();
-        const radius = v.borderRadius ?? 0;
-        // Centered draw — see createProgressBar for the rationale.
-        const x0 = -w / 2;
-        const y0 = -h / 2;
-        if (v.backgroundColor) {
-            g.fillStyle(parseColor(v.backgroundColor), v.backgroundAlpha ?? 1);
-            if (radius > 0)
-                g.fillRoundedRect(x0, y0, w, h, radius);
-            else
-                g.fillRect(x0, y0, w, h);
+    // Textured-background path: when `backgroundAssetId` is set we render the
+    // asset image (NinePatch when it carries 9-slice metadata; stretched Image
+    // otherwise). The colored Graphics path below is the fallback when the
+    // asset is missing or no background asset is configured.
+    let bgRendered = false;
+    if (v.backgroundAssetId) {
+        try {
+            const bgAsset = ctx.resolveAsset(v.backgroundAssetId);
+            const np = createImageOrNinePatch(ctx.scene, 0, 0, w, h, bgAsset, v.backgroundFrame);
+            np.setOrigin?.(0.5, 0.5);
+            container.add(np);
+            bgRendered = true;
         }
-        if (v.borderColor && (v.borderWidth ?? 0) > 0) {
-            g.lineStyle(v.borderWidth ?? 1, parseColor(v.borderColor), 1);
-            if (radius > 0)
-                g.strokeRoundedRect(x0, y0, w, h, radius);
-            else
-                g.strokeRect(x0, y0, w, h);
+        catch {
+            // Background asset missing — fall through to Graphics rect.
         }
-    };
-    draw();
+    }
+    if (!bgRendered) {
+        const g = ctx.scene.add.graphics();
+        container.add(g);
+        const draw = () => {
+            g.clear();
+            const radius = v.borderRadius ?? 0;
+            // Centered draw — see createProgressBar for the rationale.
+            const x0 = -w / 2;
+            const y0 = -h / 2;
+            if (v.backgroundColor) {
+                g.fillStyle(parseColor(v.backgroundColor), v.backgroundAlpha ?? 1);
+                if (radius > 0)
+                    g.fillRoundedRect(x0, y0, w, h, radius);
+                else
+                    g.fillRect(x0, y0, w, h);
+            }
+            if (v.borderColor && (v.borderWidth ?? 0) > 0) {
+                g.lineStyle(v.borderWidth ?? 1, parseColor(v.borderColor), 1);
+                if (radius > 0)
+                    g.strokeRoundedRect(x0, y0, w, h, radius);
+                else
+                    g.strokeRect(x0, y0, w, h);
+            }
+        };
+        draw();
+        container.setData('hudRedraw', draw);
+    }
     container.setSize(w, h);
     container.setData('editorHitWidth', w);
     container.setData('editorHitHeight', h);
     applyContainerOriginShift(container, entity.anchor.side, w, h);
-    container.setData('hudRedraw', draw);
     return container;
 }
 /** Read a numeric source (static or dynamic from registry). */
@@ -528,10 +654,18 @@ export function preloadHudAssets(scene, hudScene, manifest) {
 function collectHudAssetIds(entities) {
     const ids = new Set();
     for (const e of entities) {
-        if (e.kind === 'image')
+        if (e.kind === 'image') {
             ids.add(e.visual.assetId);
-        else if (e.kind === 'icon-button' && e.visual.iconAssetId)
-            ids.add(e.visual.iconAssetId);
+        }
+        else if (e.kind === 'icon-button') {
+            if (e.visual.iconAssetId)
+                ids.add(e.visual.iconAssetId);
+            if (e.visual.backgroundAssetId)
+                ids.add(e.visual.backgroundAssetId);
+        }
+        else if (e.kind === 'panel' && e.visual.backgroundAssetId) {
+            ids.add(e.visual.backgroundAssetId);
+        }
     }
     return Array.from(ids);
 }
@@ -558,6 +692,11 @@ export async function loadHudScene(scene, hudId) {
     }
     preloadHudAssets(scene, hudScene, manifest);
     await runLoader(scene);
+    // Mirrors loadWorldScene: NEAREST filter on every `pixelArt: true` asset.
+    // HUD scene runs in its own Phaser scene with its own texture references
+    // (textures are game-global so this is mostly idempotent with the world
+    // pass, but the HUD might load image assets the world doesn't reference).
+    applyPixelArtFilters(scene, manifest);
     const registry = attachEntityRegistry(scene);
     const safeArea = hudScene.design?.safeArea ?? DEFAULT_SAFE_AREA;
     const ctx = {
@@ -783,23 +922,56 @@ export function applyHudPatch(game, entityId, patch) {
     if (patch.visual && entity.kind === 'image') {
         const v = entity.visual;
         const p = patch.visual;
-        const image = go;
-        if (typeof p.tint === 'string') {
-            v.tint = p.tint;
-            image.setTint(parseColor(v.tint));
-        }
-        else if (p.tint === null) {
-            v.tint = undefined;
-            image.clearTint();
-        }
-        if (typeof p.alpha === 'number') {
-            v.alpha = p.alpha;
-            image.setAlpha(p.alpha);
+        // 9-slice live objects are RenderTextures, not Images — setDisplaySize /
+        // setTint don't behave the same. Mirror the panel/icon-button approach:
+        // mutate the entity record + re-spawn in place. Drag-resize from the
+        // editor lands here; the rebuild keeps NinePatch geometry correct.
+        const manifest = getManifest(hud);
+        const asset = manifest.assets?.find((a) => a.id === v.assetId);
+        if (asset?.ninePatch) {
+            for (const [k, val] of Object.entries(p)) {
+                if (val !== undefined)
+                    v[k] = val;
+            }
+            const oldDepth = go.depth;
+            go.destroy();
+            reg.unregister(entityId);
+            const ctx = {
+                scene: hud,
+                registry: reg,
+                safeArea,
+                resolveAsset: (id) => {
+                    const m = getManifest(hud);
+                    const a = m.assets?.find((x) => x.id === id);
+                    if (!a)
+                        throw new Error(`[unboxy/hud] manifest has no asset with id '${id}'`);
+                    return a;
+                },
+            };
+            const fresh = spawnHudEntity(ctx, entity);
+            if (typeof oldDepth === 'number') {
+                fresh.setDepth?.(oldDepth);
+            }
         }
-        if (typeof p.width === 'number' && typeof p.height === 'number') {
-            v.width = p.width;
-            v.height = p.height;
-            image.setDisplaySize(p.width, p.height);
+        else {
+            const image = go;
+            if (typeof p.tint === 'string') {
+                v.tint = p.tint;
+                image.setTint(parseColor(v.tint));
+            }
+            else if (p.tint === null) {
+                v.tint = undefined;
+                image.clearTint();
+            }
+            if (typeof p.alpha === 'number') {
+                v.alpha = p.alpha;
+                image.setAlpha(p.alpha);
+            }
+            if (typeof p.width === 'number' && typeof p.height === 'number') {
+                v.width = p.width;
+                v.height = p.height;
+                image.setDisplaySize(p.width, p.height);
+            }
         }
     }
     if (patch.visual && (entity.kind === 'progress-bar' || entity.kind === 'panel')) {
@@ -847,6 +1019,14 @@ export function applyHudPatch(game, entityId, patch) {
             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;
         // 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

@@ -33,6 +33,33 @@ export declare function getManifest(scene: Phaser.Scene): Manifest;
  * scene that uses it is free.
  */
 export declare function preloadSceneAssets(scene: Phaser.Scene, sceneFile: SceneFile, manifest: Manifest): void;
+/**
+ * Walk every `kind=spritesheet` asset in the manifest and register each one's
+ * `animations[]` as a Phaser animation, so behavior code can call
+ * `sprite.play('walk-down')` directly. Idempotent — uses `scene.anims.exists()`
+ * to skip duplicates (Phaser's anims.create throws otherwise).
+ *
+ * <p>Animation keys are scene-global. Two sheets registering the same name
+ * (e.g. two characters both with `walk-down`) → first wins, second logs a
+ * warning. Sheets that need disambiguation should namespace their keys
+ * (e.g. `cow:walk-down`) at metadata time.
+ */
+/**
+ * Walk every asset in the manifest and apply `Phaser.Textures.FilterMode.NEAREST`
+ * to each `pixelArt: true` entry's loaded texture. Without this, pixel-art
+ * sprites render bilinear-blurred — visible immediately on imported character
+ * sheets when the agent hasn't manually set Phaser game config's `pixelArt`.
+ *
+ * <p>Idempotent: setFilter is safe to call multiple times. Skip silently when
+ * a texture isn't loaded yet (next call after that asset is requested will
+ * pick it up). Wrap in try/catch so a single bad asset doesn't block the rest
+ * of scene init.
+ *
+ * <p>Per-asset NEAREST closes the visible blur gap; the game-wide flag
+ * (`Phaser.Game.config.pixelArt` + `camera.setRoundPixels`) is a separate
+ * concern (framebuffer-stretch crispness, perf) deferred to a follow-up.
+ */
+export declare function applyPixelArtFilters(scene: Phaser.Scene, manifest: Manifest): void;
 export interface LoadWorldSceneOptions {
     /**
      * Optional render-script resolver for `code-rendered` entities. When

package/dist/scene/SceneLoader.js

@@ -126,6 +126,37 @@ function collectAssetIds(entities) {
  * warning. Sheets that need disambiguation should namespace their keys
  * (e.g. `cow:walk-down`) at metadata time.
  */
+/**
+ * Walk every asset in the manifest and apply `Phaser.Textures.FilterMode.NEAREST`
+ * to each `pixelArt: true` entry's loaded texture. Without this, pixel-art
+ * sprites render bilinear-blurred — visible immediately on imported character
+ * sheets when the agent hasn't manually set Phaser game config's `pixelArt`.
+ *
+ * <p>Idempotent: setFilter is safe to call multiple times. Skip silently when
+ * a texture isn't loaded yet (next call after that asset is requested will
+ * pick it up). Wrap in try/catch so a single bad asset doesn't block the rest
+ * of scene init.
+ *
+ * <p>Per-asset NEAREST closes the visible blur gap; the game-wide flag
+ * (`Phaser.Game.config.pixelArt` + `camera.setRoundPixels`) is a separate
+ * concern (framebuffer-stretch crispness, perf) deferred to a follow-up.
+ */
+export function applyPixelArtFilters(scene, manifest) {
+    for (const asset of manifest.assets ?? []) {
+        if (!asset.pixelArt)
+            continue;
+        if (!scene.textures.exists(asset.textureKey))
+            continue;
+        try {
+            const tex = scene.textures.get(asset.textureKey);
+            tex.setFilter(Phaser.Textures.FilterMode.NEAREST);
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn(`[unboxy/scene] failed to apply NEAREST filter to '${asset.id}': ${String(e)}`);
+        }
+    }
+}
 function registerSheetAnimations(scene, manifest) {
     const assets = manifest.assets ?? [];
     for (const asset of assets) {
@@ -249,6 +280,9 @@ export async function loadWorldScene(scene, sceneId, options = {}) {
     // Lazy preload of any new assets this scene needs, then await loader.
     preloadSceneAssets(scene, sceneFile, manifest);
     await runLoader(scene);
+    // Per-asset NEAREST filter for `pixelArt: true` entries. Must run after
+    // textures are loaded — setFilter on a missing texture is a no-op.
+    applyPixelArtFilters(scene, manifest);
     // Register Phaser animations declared in `manifest.assets[].animations`.
     // Done after texture load + before entity spawn so behavior code can call
     // `sprite.play('walk-down')` from frame 1 without manual `anims.create()`.

package/dist/scene/types.d.ts

@@ -72,7 +72,53 @@ export interface AssetRecord {
     animations?: SheetAnimation[];
     /** Default playback rate for `animations[]`. Defaults to 8. */
     fps?: number;
+    /**
+     * 9-slice cut-line metadata. Two shapes accepted:
+     *
+     * - **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 | NinePatchPerFrame;
+    /**
+     * Vision-detected pixel-art flag. When true, SDK applies
+     * `Phaser.Textures.FilterMode.NEAREST` to the texture after load so it
+     * renders crisp instead of bilinear-blurred. Population is per-source:
+     * pack-import sets it via vision; AI generation / manual upload / library
+     * backfill close their own gaps separately (see design doc 07 §8.4).
+     */
+    pixelArt?: boolean;
 }
+/** Single-image 9-slice config. Pixels from each edge to the slice line. */
+export interface NinePatchConfig {
+    leftWidth: number;
+    rightWidth: number;
+    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;
@@ -345,7 +391,27 @@ export interface HudIconButtonVisual {
     label?: string;
     /** Optional icon asset shown inside the button. */
     iconAssetId?: string;
-    /** Button shape. Default `rounded-rect`. */
+    /**
+     * Optional image asset rendered as the button background. When the
+     * referenced asset has `ninePatch` metadata, the SDK renders it via
+     * `phaser3-rex-plugins` NinePatch so corners stay fixed at any width/height;
+     * 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;
     height?: number;
@@ -389,6 +455,25 @@ export interface HudPanelVisual {
     kind: 'panel';
     width?: number;
     height?: number;
+    /**
+     * Optional image asset rendered as the panel background. When the
+     * referenced asset has `ninePatch` metadata, the SDK renders it via
+     * `phaser3-rex-plugins` NinePatch so corners stay fixed at any width/height;
+     * 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.36",
+  "version": "0.2.38",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,11 +18,13 @@
     "colyseus.js": "^0.16.0"
   },
   "peerDependencies": {
-    "phaser": "^3.60.0"
+    "phaser": "^3.60.0",
+    "phaser3-rex-plugins": "^1.80.0"
   },
   "devDependencies": {
     "jose": "^6.2.2",
     "phaser": "^3.80.0",
+    "phaser3-rex-plugins": "^1.80.20",
     "typescript": "^5.5.0"
   },
   "publishConfig": {