@unboxy/phaser-sdk 0.2.35 → 0.2.37

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';
@@ -28,5 +28,5 @@ 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 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 { 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,7 +14,7 @@ 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';

package/dist/scene/HudRuntime.js

@@ -2,7 +2,7 @@ import Phaser from 'phaser';
 import { SCHEMA_VERSION, } 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,34 @@ const LAYER_DEPTH = {
     overlay: 200,
     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.
+ */
+function createImageOrNinePatch(scene, x, y, width, height, asset) {
+    if (asset.ninePatch) {
+        const np = asset.ninePatch;
+        const factory = scene.add.rexNinePatch;
+        if (factory) {
+            // 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]);
+        }
+        // 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}'`);
+    }
+    const image = 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 +189,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 +219,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 +240,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);
+            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 +306,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 +431,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);
+            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 +627,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 +665,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 +895,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 +992,10 @@ 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;
         // 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) {
@@ -172,12 +203,29 @@ function queueAssetLoad(scene, asset) {
         case 'image':
             scene.load.image(asset.textureKey, asset.path);
             return;
-        case 'spritesheet':
-            if (!asset.spriteSheetConfig) {
-                throw new Error(`[unboxy/scene] asset '${asset.id}' kind=spritesheet missing spriteSheetConfig`);
+        case 'spritesheet': {
+            // Tolerant config resolution: prefer nested `spriteSheetConfig`, fall
+            // back to top-level `frameWidth/frameHeight/margin/spacing` if the
+            // agent put them there (common typo — both shapes appear in real
+            // workspaces). Soft-fail with warning when neither shape provides
+            // frame dims so the rest of the scene still boots.
+            const cfg = asset.spriteSheetConfig
+                ?? (asset.frameWidth && asset.frameHeight
+                    ? {
+                        frameWidth: asset.frameWidth,
+                        frameHeight: asset.frameHeight,
+                        margin: asset.margin,
+                        spacing: asset.spacing,
+                    }
+                    : null);
+            if (!cfg) {
+                // eslint-disable-next-line no-console
+                console.warn(`[unboxy/scene] asset '${asset.id}' kind=spritesheet missing spriteSheetConfig (and no top-level frameWidth/frameHeight); skipping load`);
+                return;
             }
-            scene.load.spritesheet(asset.textureKey, asset.path, asset.spriteSheetConfig);
+            scene.load.spritesheet(asset.textureKey, asset.path, cfg);
             return;
+        }
         case 'atlas':
             if (!asset.atlasPath || !asset.atlasFormat) {
                 throw new Error(`[unboxy/scene] asset '${asset.id}' kind=atlas missing atlasPath/atlasFormat`);
@@ -232,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

@@ -42,6 +42,15 @@ export interface AssetRecord {
         margin?: number;
         spacing?: number;
     };
+    /**
+     * Top-level convenience fields. When the agent writes a spritesheet asset
+     * entry, it commonly puts these at the top level instead of nested in
+     * `spriteSheetConfig` — both shapes are now accepted by the loader.
+     */
+    frameWidth?: number;
+    frameHeight?: number;
+    margin?: number;
+    spacing?: number;
     /** For `atlas`: companion atlas file path (xml or json). */
     atlasPath?: string;
     /** `'xml'` (Starling) or `'json'` (TexturePacker). */
@@ -63,6 +72,34 @@ export interface AssetRecord {
     animations?: SheetAnimation[];
     /** 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.
+     *
+     * <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.
+     */
+    ninePatch?: NinePatchConfig;
+    /**
+     * 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;
 }
 export interface SheetAnimation {
     /** Phaser animation key — used as `sprite.play('<name>')`. */
@@ -336,7 +373,16 @@ 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).
+     */
+    backgroundAssetId?: string;
+    /** Button shape. Default `rounded-rect`. Ignored when backgroundAssetId is set. */
     shape?: 'rounded-rect' | 'circle';
     width?: number;
     height?: number;
@@ -380,6 +426,15 @@ 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.
+     */
+    backgroundAssetId?: 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.35",
+  "version": "0.2.37",
   "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": {