@unboxy/phaser-sdk 0.2.43 → 0.2.44

package/SDK-GUIDE.md

@@ -775,6 +775,69 @@ For now there's no built-in action binding (no `behavior: { type: 'pause-game' }
 
 A colored rectangle with optional border + rounded corners. Use as a visual frame behind groups of HUD widgets (no children layout in v1 — child widgets are sibling entities; you align them with anchor + offset).
 
+### Textured backgrounds for `icon-button` and `panel` (since 0.2.37)
+
+Both `icon-button` and `panel` accept an asset image as the background instead of the default colored fill. Three flavors, each stretchable with crisp corners via the SDK's built-in 9-slice renderer:
+
+**1. Single-image 9-slice** (since 0.2.37) — manifest asset is `kind: 'image'` with `ninePatch: { leftWidth, rightWidth, topHeight, bottomHeight }`. The whole texture slices into 9 regions; corners stay native, edges + middle stretch.
+
+```json
+{
+  "kind": "icon-button",
+  "visual": {
+    "kind": "icon-button",
+    "label": "Start",
+    "width": 240, "height": 64,
+    "backgroundAssetId": "button-panel"
+  }
+}
+```
+
+**2. Per-frame on a uniform grid** (since 0.2.38) — manifest asset is `kind: 'spritesheet'` with `ninePatch: { perFrame: {...} }`. Used when every cell of a button-pack sheet is the same size and shares the same corner radius (typical itch.io packs). Pair with `backgroundFrame: <cell index>` to pick which cell.
+
+```json
+{
+  "visual": {
+    "kind": "icon-button",
+    "backgroundAssetId": "button-pack",
+    "backgroundFrame": 3
+  }
+}
+```
+
+**3. Region atlas** (since 0.2.42) — manifest asset is `kind: 'atlas'` + `atlasFormat: 'json'` + `atlasPath: '...'`. The atlas JSON file carries named frame rects, each optionally with its own inline `ninePatch`. Pair with `backgroundRegion: '<frame name>'` to pick the region. Mutually exclusive with `backgroundFrame` — when both are set, `backgroundRegion` wins.
+
+```json
+{
+  "visual": {
+    "kind": "icon-button",
+    "backgroundAssetId": "ui-buttons",
+    "backgroundRegion": "btn-primary-idle"
+  }
+}
+```
+
+Atlas JSON shape — Phaser-native JSON-Hash with an optional per-frame `ninePatch` field that Phaser's parser ignores but the SDK reads via a side-cache:
+
+```json
+{
+  "frames": {
+    "btn-primary-idle": {
+      "frame":      { "x": 7, "y": 9, "w": 18, "h": 30 },
+      "sourceSize": { "w": 18, "h": 30 },
+      "ninePatch":  { "leftWidth": 4, "rightWidth": 4, "topHeight": 4, "bottomHeight": 4 }
+    },
+    "btn-primary-pressed": {
+      "frame":      { "x": 39, "y": 9, "w": 18, "h": 30 },
+      "sourceSize": { "w": 18, "h": 30 }
+    }
+  },
+  "meta": { "image": "ui-buttons.png", "size": { "w": 128, "h": 96 }, "scale": "1" }
+}
+```
+
+The Region Editor in the home-ui (visual editor slice 10) writes this shape for you — drag-tag named regions on a single PNG, optionally toggle 9-slice per region, save. Regions without `ninePatch` render as plain stretched images of that region; regions with `ninePatch` render via the 9-slice path.
+
 ### Dynamic bindings — driving the HUD from gameplay
 
 For values that change during play (score, HP, timer, lives), use **Phaser's game registry** as the bridge. The HUD widget references a `binding` key; gameplay code calls `this.registry.set(key, value)` and the HUD auto-refreshes.
@@ -801,9 +864,145 @@ The visual editor's `World/HUD` toggle pauses the active world scene and lets th
 
 For game code, the editor is invisible — you write HUD scene JSON the same way regardless of whether the user uses the editor.
 
-## Anti-patterns (don't do these)
+## Collision + Y-sort (visual editor slice 8, since 0.2.44)
+
+Two new fields on `AssetRecord` give per-asset collision shapes and footprint
+anchors for top-down draw-order sorting. The SDK consumes them automatically
+at sprite spawn time. `applyAssetHitbox` is also exported for behavior code
+that attaches a physics body after spawn.
+
+### `Asset.hitbox` — collision body shape
+
+Per-asset rect (in v1) in source-pixel coordinates relative to the
+asset's frame top-left. Two shapes:
+
+```ts
+// Single — one body across all frames (trees, walls, idle characters)
+hitbox: { kind: 'rect', x: 8, y: 24, w: 16, h: 8 }
+
+// Per-frame — combat sheets where attack frames need a wider hitbox
+hitbox: {
+  default: { kind: 'rect', x: 8, y: 24, w: 16, h: 8 },
+  frames: {
+    8:  { kind: 'rect', x: 0, y: 16, w: 32, h: 16 },
+    9:  { kind: 'rect', x: 0, y: 16, w: 32, h: 16 },
+    10: { kind: 'rect', x: 0, y: 16, w: 32, h: 16 },
+    11: { kind: 'rect', x: 0, y: 16, w: 32, h: 16 }
+  }
+}
+```
+
+`kind: 'rect'` is the only valid value in v1; `'circle'` is reserved for v2
+and the union widens as a pure addition. The `isPerFrameHitbox(hitbox)` type
+guard narrows the union.
+
+### `Asset.depthAnchor` — Y-sort footprint pixel
+
+```ts
+depthAnchor: { x: 16, y: 28 }   // pixel within frame 0 the SDK aligns sprite.y with
+```
+
+The SDK applies `sprite.setOrigin(x / frameW, y / frameH)` at spawn so the
+sprite's world `y` equals the world y of this pixel. Typical: feet for
+characters, trunk base for trees, foundation midpoint for buildings.
+
+### `applyAssetHitbox(sprite, asset)` — apply at runtime
+
+Called automatically by `createSprite` at scene boot. **Also callable** by
+behavior code after attaching a body later:
+
+```ts
+import { applyAssetHitbox } from '@unboxy/phaser-sdk';
+
+const player = registry.getById('player');
+const asset = manifest.assets.find(a => a.id === player.getData('assetId'));
+
+scene.physics.add.existing(player);
+applyAssetHitbox(player, asset);   // reads asset.hitbox, applies to body
+```
+
+Semantics:
+
+- **No-op (silent)** when `asset.hitbox` is unset. Safe to call defensively.
+- **Dev-warn (NOT throw)** when called on a sprite without a physics body.
+  Most likely cause: call order — `scene.physics.add.existing(sprite)` must
+  come first.
+- **For per-frame hitboxes**: installs an `ANIMATION_UPDATE` listener that
+  swaps `body.setSize`/`setOffset` on every frame change during animation
+  playback. Idempotent — re-applying tears down the old listener first.
+
+**v1 caveat**: manual `sprite.setFrame(idx)` calls outside of animation
+playback do NOT swap the body. Combat sheets are animation-driven, so this
+rarely bites in practice.
+
+### Scene-level `ySort: true` — per-frame depth sort
+
+```json
+// public/scenes/world/main.json
+{
+  "schemaVersion": 1,
+  "id": "main",
+  "type": "world",
+  "ySort": true,
+  "entities": [ ... ]
+}
+```
+
+When set, `loadWorldScene` installs a per-frame update hook that walks the
+entity registry and assigns `sprite.depth = sprite.y` to every entity.
+**Per-game cost**: O(n) per frame; 200 entities at 60 FPS = 12,000
+`setDepth` calls/sec — well within Phaser's render budget.
+
+Two opt-out mechanisms (orthogonal, cover different intents):
+
+```ts
+// explicit constant depth → ySort skips the entity entirely
+{ "transform": { "x": 100, "y": 100, "depth": 1000 } }   // cloud always on top
+
+// behavior-managed depth → ySort doesn't touch the entity
+{ "transform": { "x": 100, "y": 100 }, "properties": { "skipYSort": true } }
+```
+
+### The conditional rule (when to call `applyAssetHitbox`)
+
+```ts
+const asset = manifest.assets.find(a => a.id === sprite.getData('assetId'));
+scene.physics.add.existing(sprite);
+
+if (asset?.hitbox) {
+  applyAssetHitbox(sprite, asset);          // metadata is source of truth
+} else {
+  sprite.body.setSize(30, 20);              // hardcode from gameplay intent
+  sprite.body.setOffset(5, 5);
+}
+```
+
+Both paths are correct depending on context:
+
+- **`applyAssetHitbox` path** — sprite uses an Asset that has `hitbox`
+  metadata. Pack import sets it via vision; users refine via the Hitbox
+  Editor. Hardcoding `setSize` afterward would override the user's
+  authored values.
+- **Hardcode path** — primitive sprites (`scene.add.rectangle`), AI-gen
+  images with no vision pass, chat-only games with no scene-as-data
+  manifest. There's nothing to apply; hardcoding is the right answer.
+
+The `asset-hitbox-physics` agent skill (in
+`plugins/unboxy-phaser/skills/asset-hitbox-physics/SKILL.md`) walks through
+this decision tree with worked examples.
+
+### Authoring metadata (the editor surface)
+
+Users author `hitbox` + `depthAnchor` in the home-ui's Hitbox Editor modal —
+launched from the Assets panel's per-card hover button (green hitbox icon).
+Supports both Same-for-all-frames and Per-frame overrides modes, with a
+frame strip + override-dot indicators for the per-frame case.
+
+Vision pre-fills the single-shape form at pack-import time for character /
+tree / building / rock / decoration subjects (narrow trunk for trees, foot
+footprint for characters, foundation for buildings).
+
 
-- Do **not** call `Unboxy.init()` inside a scene. Initialize at module load in `main.ts` and export the promise.
 - Do **not** block scene creation on `unboxyReady`. Games must cold-start immediately; hydrate when the promise resolves.
 - Do **not** save on every frame / every score tick. Debounce or only save on meaningful events (game over, level clear).
 - Do **not** store large binary blobs (images, audio) as save values — use a dedicated blob API when it ships.
@@ -813,6 +1012,7 @@ For game code, the editor is invisible — you write HUD scene JSON the same way
 
 ## Changelog
 
+- **0.2.44** — visual editor slice 8: depth + asymmetric collision. New fields `AssetRecord.hitbox` (single rect or per-frame overrides) + `AssetRecord.depthAnchor` (footprint pixel for Y-sort). New scene flag `WorldScene.ySort: boolean` (per-frame `setDepth(y)` hook). New SDK export `applyAssetHitbox(sprite, asset)` — silent no-op without metadata, dev-warn on missing body, idempotent `ANIMATION_UPDATE` listener install for per-frame variants. New type guard `isPerFrameHitbox`. Two new editor protocol messages — `unboxy:editor:assetUpdate { asset }` (broadcast hitbox/anchor edits to running iframe; re-applies to every spawned instance, no scene reload) + `unboxy:editor:setDebugOverlay { showHitboxes }` (toggle the EditorOverlayScene's per-frame hitbox + anchor draw). See "Collision + Y-sort" chapter. Pairs with: backend `PATCH /games/{id}/assets/{aid}/hitbox`, vision detection in pack import (character/tree/building/rock/decoration subjects), Hitbox Editor modal in home-ui, `asset-hitbox-physics` agent skill teaching the conditional rule.
 - **0.2.33** — docs: HUD scenes chapter added to this guide (covers slice-5 widget kinds, anchor model, dynamic bindings via `scene.registry`, `hud:press` event). Existing workspaces pick this up via `npm update @unboxy/phaser-sdk`.
 - **0.2.32** — fix: 9-grid anchor side change in the visual editor moved container-based widgets (icon-button, progress-bar, panel) far from the new corner. `applyHudPatch` now re-applies the origin shift that compensates for containers having no `setOrigin`.
 - **0.2.31** — fix: progress-bar and panel widgets drew their Graphics rect from `(0, 0)` instead of centered, so the visual was offset by `(w/2, h/2)` from the editor's selection rect. Both now draw centered.

package/dist/editor/EditorBridge.js

@@ -1,10 +1,10 @@
 import Phaser from 'phaser';
 import { getEntityRegistry } from '../scene/EntityRegistry.js';
-import { parseColor, spawnEntity } from '../scene/spawnEntity.js';
+import { applyAssetHitbox, parseColor, spawnEntity } from '../scene/spawnEntity.js';
 import { resolveRenderScript } from '../scene/renderScripts.js';
 import { getManifest } from '../scene/SceneLoader.js';
 import { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './EditorOverlayScene.js';
-import { getEditorState, setEditorActive, setSelection, getSelection, getEditorMode, setEditorMode, } from './EditorState.js';
+import { getEditorState, setEditorActive, setSelection, getSelection, getEditorMode, setEditorMode, setDebugOverlayState, } from './EditorState.js';
 import { applyHudPatch, createHudEntityInScene, deleteHudEntityFromScene, findHudRegistry, findHudSceneFile, UNBOXY_HUD_SCENE_KEY, } from '../scene/HudRuntime.js';
 /**
  * EditorBridge wires the host (home-ui) to the iframe's Phaser game during
@@ -76,6 +76,14 @@ function handleMessage(game, msg) {
             setSelection(game, null);
             postSelectionRect(game);
             break;
+        case 'unboxy:editor:assetUpdate':
+            // Slice 8 — Asset-level live update for hitbox / depthAnchor edits.
+            void handleAssetUpdate(game, msg.asset);
+            break;
+        case 'unboxy:editor:setDebugOverlay':
+            // Slice 8 — "Show hitboxes" debug overlay toggle.
+            setDebugOverlay(game, { showHitboxes: msg.showHitboxes });
+            break;
     }
 }
 // --- Enter / exit ---------------------------------------------------------
@@ -485,6 +493,72 @@ async function applyEdit(game, entityId, patch, manifestAsset) {
     if (getSelection(game) === entityId)
         postSelectionRect(game);
 }
+// --- Slice 8: asset-level live update ------------------------------------
+/**
+ * Handle an `unboxy:editor:assetUpdate` postMessage — used by the Hitbox
+ * Editor to push freshly-saved hitbox / depthAnchor metadata into the
+ * running iframe without a scene reload.
+ *
+ * Flow:
+ *   1. Upsert the asset into the iframe's cached manifest (so future spawns
+ *      see the new metadata).
+ *   2. Lazy-load texture if it isn't cached yet (defensive — Hitbox Editor
+ *      is typically opened on already-loaded assets, but the same code path
+ *      is reused if a user edits hitbox on an asset that was never in this
+ *      scene's manifest).
+ *   3. Walk the entity registry, find every sprite with `entityAssetId`
+ *      matching the updated asset's id, and re-apply `setOrigin` (from new
+ *      depthAnchor) + `applyAssetHitbox` (which is idempotent and re-installs
+ *      the per-frame listener cleanly).
+ *
+ * HUD-mode is a no-op — HUD widgets don't carry world hitboxes / depthAnchors.
+ * The Hitbox Editor is launched only on world-scene assets.
+ */
+async function handleAssetUpdate(game, asset) {
+    if (getEditorMode(game) === 'hud')
+        return;
+    const scene = findWorldScene(game);
+    if (!scene)
+        return;
+    try {
+        upsertCachedManifestAsset(scene, asset);
+        await ensureAssetLoaded(scene, asset);
+    }
+    catch (e) {
+        console.warn('[unboxy/editor] assetUpdate upsert/load failed:', e);
+        return;
+    }
+    const registry = findRegistry(game);
+    if (!registry)
+        return;
+    for (const go of registry.all()) {
+        if (go.getData('entityAssetId') !== asset.id)
+            continue;
+        const sprite = go;
+        // Re-apply origin from new depthAnchor (no-op if anchor unset; spawn-time
+        // default origin of 0.5/0.5 stays). Cleared anchor reverts to center.
+        if (asset.depthAnchor) {
+            const frameW = sprite.width || 1;
+            const frameH = sprite.height || 1;
+            sprite.setOrigin?.(asset.depthAnchor.x / frameW, asset.depthAnchor.y / frameH);
+        }
+        else if (typeof sprite.setOrigin === 'function') {
+            sprite.setOrigin(0.5, 0.5);
+        }
+        // Re-apply hitbox. Idempotent — tears down the prior per-frame listener
+        // before installing the new one. Silent no-op when sprite has no body.
+        applyAssetHitbox(sprite, asset);
+    }
+}
+// --- Slice 8: debug overlay toggle ---------------------------------------
+/**
+ * Forward the "Show hitboxes" toggle into the editor overlay scene. The
+ * overlay reads this flag each frame from the editor state attached to the
+ * Phaser game (see EditorState.setDebugOverlay).
+ */
+function setDebugOverlay(game, state) {
+    setDebugOverlayState(game, state);
+}
 /**
  * Re-render a code-rendered entity's visual when its params change.
  * Slice 3.5 — Inspector params editor produces these patches.

package/dist/editor/EditorOverlayScene.d.ts

@@ -70,6 +70,23 @@ export declare class EditorOverlayScene extends Phaser.Scene {
     private handlePointerMove;
     private handlePointerUp;
     update(): void;
+    /**
+     * Walks the world entity registry and draws each sprite's `hitbox` rect +
+     * `depthAnchor` crosshair (when present on the entity's Asset). Sprites
+     * without metadata get nothing drawn — chat-only Workflow A respect.
+     *
+     * Per-frame mode: reads the sprite's CURRENT frame index and looks up the
+     * override (falls back to default) so the rendered rect tracks what the
+     * SDK is actually applying to the body at runtime.
+     */
+    private drawHitboxDebug;
+    /**
+     * For per-frame hitboxes, pick the shape the SDK would currently be
+     * applying — the override for the playing frame, falling back to default.
+     * For single-shape hitboxes, just return the rect.
+     */
+    private resolveCurrentHitboxShape;
+    private findWorldSceneInstance;
     /**
      * Find the world scene's main camera so the overlay can mirror it.
      * In edit mode, the world scene is paused but its camera state is what

package/dist/editor/EditorOverlayScene.js

@@ -1,7 +1,9 @@
 import Phaser from 'phaser';
 import { getEntityRegistry } from '../scene/EntityRegistry.js';
 import { findHudEntity, findHudRegistry, UNBOXY_HUD_SCENE_KEY, } from '../scene/HudRuntime.js';
-import { getEditorState, startDrag, clearDrag, getDrag, getSelection, getEditorMode, } from './EditorState.js';
+import { isPerFrameHitbox } from '../scene/types.js';
+import { getManifest } from '../scene/SceneLoader.js';
+import { getEditorState, startDrag, clearDrag, getDrag, getSelection, getEditorMode, getDebugOverlayState, } from './EditorState.js';
 /**
  * Editor overlay — slice 2.
  *
@@ -24,6 +26,16 @@ const SELECTION_ALPHA = 1;
 const SELECTION_LINE_WIDTH = 2;
 const WORLD_BOUNDS_COLOR = 0x888888;
 const WORLD_BOUNDS_ALPHA = 0.5;
+// Slice 8: "Show hitboxes" debug overlay colors. Green for hitboxes (matches
+// Hitbox Editor canvas), cyan for depth-anchor crosshairs (distinct + visible
+// on most sprite backgrounds).
+const HITBOX_FILL_COLOR = 0x33dd55;
+const HITBOX_FILL_ALPHA = 0.25;
+const HITBOX_STROKE_COLOR = 0x22aa44;
+const HITBOX_STROKE_ALPHA = 0.9;
+const ANCHOR_COLOR = 0x00d0ff;
+const ANCHOR_ALPHA = 1;
+const ANCHOR_CROSS_LEN = 6;
 export class EditorOverlayScene extends Phaser.Scene {
     constructor() {
         super({ key: EDITOR_OVERLAY_KEY });
@@ -215,6 +227,100 @@ export class EditorOverlayScene extends Phaser.Scene {
                 }
             }
         }
+        // Slice 8: "Show hitboxes" debug overlay. Only renders in world mode;
+        // HUD widgets don't carry world hitboxes.
+        if (getEditorMode(this.game) !== 'hud' && getDebugOverlayState(this.game).showHitboxes) {
+            this.drawHitboxDebug();
+        }
+    }
+    /**
+     * Walks the world entity registry and draws each sprite's `hitbox` rect +
+     * `depthAnchor` crosshair (when present on the entity's Asset). Sprites
+     * without metadata get nothing drawn — chat-only Workflow A respect.
+     *
+     * Per-frame mode: reads the sprite's CURRENT frame index and looks up the
+     * override (falls back to default) so the rendered rect tracks what the
+     * SDK is actually applying to the body at runtime.
+     */
+    drawHitboxDebug() {
+        const registry = this.findEntityRegistry();
+        if (!registry)
+            return;
+        const worldScene = this.findWorldSceneInstance();
+        const manifest = worldScene ? getManifest(worldScene) : undefined;
+        if (!manifest)
+            return;
+        const assetsById = new Map();
+        for (const asset of manifest.assets ?? []) {
+            assetsById.set(asset.id, asset);
+        }
+        for (const go of registry.all()) {
+            const assetId = go.getData('entityAssetId');
+            if (!assetId)
+                continue; // primitives / code-rendered / group — skip
+            const asset = assetsById.get(assetId);
+            if (!asset)
+                continue;
+            const sprite = go;
+            const frameW = sprite.frame?.width ?? sprite.width ?? 0;
+            const frameH = sprite.frame?.height ?? sprite.height ?? 0;
+            if (frameW === 0 || frameH === 0)
+                continue;
+            // Top-left corner of the frame in world coords (compensate for origin
+            // shift so the source-pixel coordinate space lands on the sprite's
+            // actual rendered position).
+            const originX = sprite.originX ?? 0.5;
+            const originY = sprite.originY ?? 0.5;
+            const frameLeft = sprite.x - frameW * originX;
+            const frameTop = sprite.y - frameH * originY;
+            if (asset.hitbox) {
+                const shape = this.resolveCurrentHitboxShape(asset, sprite);
+                if (shape) {
+                    this.graphics.fillStyle(HITBOX_FILL_COLOR, HITBOX_FILL_ALPHA);
+                    this.graphics.fillRect(frameLeft + shape.x, frameTop + shape.y, shape.w, shape.h);
+                    this.graphics.lineStyle(1, HITBOX_STROKE_COLOR, HITBOX_STROKE_ALPHA);
+                    this.graphics.strokeRect(frameLeft + shape.x, frameTop + shape.y, shape.w, shape.h);
+                }
+            }
+            if (asset.depthAnchor) {
+                const ax = frameLeft + asset.depthAnchor.x;
+                const ay = frameTop + asset.depthAnchor.y;
+                this.graphics.lineStyle(1, ANCHOR_COLOR, ANCHOR_ALPHA);
+                this.graphics.lineBetween(ax - ANCHOR_CROSS_LEN, ay, ax + ANCHOR_CROSS_LEN, ay);
+                this.graphics.lineBetween(ax, ay - ANCHOR_CROSS_LEN, ax, ay + ANCHOR_CROSS_LEN);
+            }
+        }
+    }
+    /**
+     * For per-frame hitboxes, pick the shape the SDK would currently be
+     * applying — the override for the playing frame, falling back to default.
+     * For single-shape hitboxes, just return the rect.
+     */
+    resolveCurrentHitboxShape(asset, sprite) {
+        const h = asset.hitbox;
+        if (!h)
+            return undefined;
+        if (isPerFrameHitbox(h)) {
+            const idx = sprite.anims?.currentFrame?.index;
+            if (typeof idx === 'number' && h.frames[idx])
+                return h.frames[idx];
+            return h.default;
+        }
+        return h;
+    }
+    findWorldSceneInstance() {
+        for (const scene of this.game.scene.getScenes(false)) {
+            const key = scene.scene.key;
+            if (key === EDITOR_OVERLAY_KEY)
+                continue;
+            if (key === UNBOXY_HUD_SCENE_KEY)
+                continue;
+            if (key === 'BootScene' || key === 'Boot')
+                continue;
+            // First non-overlay non-HUD non-Boot scene is the world scene.
+            return scene;
+        }
+        return undefined;
     }
     /**
      * Find the world scene's main camera so the overlay can mirror it.

package/dist/editor/EditorState.d.ts

@@ -12,6 +12,14 @@
  * Toggled by host via `unboxy:editor:setEditMode`.
  */
 export type EditorMode = 'world' | 'hud';
+/**
+ * Editor debug-overlay flags (slice 8). Toggled by the host via
+ * `unboxy:editor:setDebugOverlay`; read each frame by EditorOverlayScene.
+ */
+export interface EditorDebugOverlayState {
+    /** Draw hitbox rects + depth-anchor crosshairs on sprites with metadata. */
+    showHitboxes: boolean;
+}
 interface EditorStateShape {
     active: boolean;
     selectedId: string | null;
@@ -34,6 +42,7 @@ interface EditorStateShape {
             y: number;
         };
     } | null;
+    debugOverlay: EditorDebugOverlayState;
 }
 /**
  * Accept any object — we only use a single internal symbol-style key, so
@@ -55,4 +64,6 @@ export declare function startDrag(game: AnyObject, entityId: string, startWorld:
 }): void;
 export declare function clearDrag(game: AnyObject): void;
 export declare function getDrag(game: AnyObject): EditorStateShape['drag'];
+export declare function getDebugOverlayState(game: AnyObject): EditorDebugOverlayState;
+export declare function setDebugOverlayState(game: AnyObject, patch: Partial<EditorDebugOverlayState>): void;
 export {};

package/dist/editor/EditorState.js

@@ -15,7 +15,13 @@ export function getEditorState(game) {
     const existing = b[KEY];
     if (existing)
         return existing;
-    const fresh = { active: false, selectedId: null, mode: 'world', drag: null };
+    const fresh = {
+        active: false,
+        selectedId: null,
+        mode: 'world',
+        drag: null,
+        debugOverlay: { showHitboxes: false },
+    };
     b[KEY] = fresh;
     return fresh;
 }
@@ -43,3 +49,10 @@ export function clearDrag(game) {
 export function getDrag(game) {
     return getEditorState(game).drag;
 }
+export function getDebugOverlayState(game) {
+    return getEditorState(game).debugOverlay;
+}
+export function setDebugOverlayState(game, patch) {
+    const state = getEditorState(game).debugOverlay;
+    Object.assign(state, patch);
+}

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export type { Transport, TransportKind } from './core/Transport.js';
 export type { UnboxyUser } from './protocol.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 { spawnEntity, parseColor, applyAssetHitbox } from './scene/spawnEntity.js';
 export type { SpawnContext, AssetResolver, RenderScriptResolver, } from './scene/spawnEntity.js';
 export { EntityRegistry, attachEntityRegistry, getEntityRegistry, } from './scene/EntityRegistry.js';
 export { setupEditorModeListener, isEditMode } from './scene/EditorMode.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, 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 { SCHEMA_VERSION, isPerFrameNinePatch, isPerFrameHitbox, } 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, HitboxRect, HitboxPerFrame, DepthAnchor, } 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

@@ -15,11 +15,11 @@ export { UnboxyRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT
 export { RpcError } from './core/Transport.js';
 // Scene-as-data (visual editor foundation, slice 1)
 export { loadWorldScene, preloadManifest, preloadSceneAssets, applyPixelArtFilters, getManifest, SCENES_BASE, MANIFEST_PATH, } from './scene/SceneLoader.js';
-export { spawnEntity, parseColor } from './scene/spawnEntity.js';
+export { spawnEntity, parseColor, applyAssetHitbox } 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, isPerFrameNinePatch, } from './scene/types.js';
+export { SCHEMA_VERSION, isPerFrameNinePatch, isPerFrameHitbox, } from './scene/types.js';
 export { PROTOCOL_VERSION, } from './protocol.js';

package/dist/protocol.d.ts

@@ -191,7 +191,42 @@ export interface EditorSetEditModeMessage {
     type: 'unboxy:editor:setEditMode';
     mode: 'world' | 'hud';
 }
-export type EditorHostToSdkMessage = EditorEnterMessage | EditorExitMessage | EditorGetSceneMessage | EditorApplyEditMessage | EditorSetSelectionMessage | EditorPanZoomMessage | EditorCreateEntityMessage | EditorDeleteEntityMessage | EditorSetEditModeMessage;
+/**
+ * Asset-level live update (slice 8 — hitbox / depthAnchor editing).
+ *
+ * When the user edits an Asset's hitbox or depthAnchor in the Hitbox Editor
+ * modal, the change is at the asset level — not tied to a specific entity
+ * patch. The host sends this message; the bridge:
+ *   1. Upserts the asset into the iframe's cached manifest
+ *   2. Walks the entity registry, finds every sprite entity using this asset
+ *      (matched via `entityAssetId` data-manager stash), and re-applies
+ *      `setOrigin(depthAnchor)` + `applyAssetHitbox` to each
+ *
+ * Unlike `applyEdit`, this is NOT scoped to a single entity — one asset edit
+ * can affect dozens of in-scene sprites simultaneously.
+ */
+export interface EditorAssetUpdateMessage {
+    type: 'unboxy:editor:assetUpdate';
+    /** Full AssetRecord — replaces the existing manifest entry. */
+    asset: unknown;
+}
+/**
+ * Debug overlay toggle (slice 8 — "Show hitboxes" diagnostic).
+ *
+ * When the user toggles the scene-panel checkbox, the host sends this
+ * message. The overlay scene draws each sprite's hitbox rect (semi-
+ * transparent green) + depth-anchor crosshair (cyan ✚) for entities whose
+ * asset has those metadata fields set. Sprites without metadata get
+ * nothing drawn — chat-only Workflow A respect.
+ *
+ * Edit-mode only — complements Phaser's runtime `physics.world.createDebugGraphic`
+ * (which is the Play-mode tool), doesn't replace it.
+ */
+export interface EditorSetDebugOverlayMessage {
+    type: 'unboxy:editor:setDebugOverlay';
+    showHitboxes: boolean;
+}
+export type EditorHostToSdkMessage = EditorEnterMessage | EditorExitMessage | EditorGetSceneMessage | EditorApplyEditMessage | EditorSetSelectionMessage | EditorPanZoomMessage | EditorCreateEntityMessage | EditorDeleteEntityMessage | EditorSetEditModeMessage | EditorAssetUpdateMessage | EditorSetDebugOverlayMessage;
 export interface EditorSceneLoadedMessage {
     type: 'unboxy:editor:sceneLoaded';
     sceneId: string;

package/dist/scene/SceneLoader.js

@@ -350,6 +350,14 @@ export async function loadWorldScene(scene, sceneId, options = {}) {
         spawnEntity(ctx, entity);
     // Configure camera.
     applyCamera(scene, sceneFile, registry);
+    // Slice 8: install per-frame Y-sort hook when the scene opts in. Walks
+    // the entity registry every frame and sets `sprite.depth = sprite.y` so
+    // closer-to-camera sprites overlap farther ones. Two opt-out signals
+    // (explicit transform.depth or properties.skipYSort) keep specific
+    // entities on their constant layer.
+    if (sceneFile.ySort) {
+        installYSortHook(scene, registry);
+    }
     // Auto-launch the HUD scene attached to this world (slice 5). Imported
     // lazily to avoid pulling HudRuntime into worlds that don't need it.
     if (ref.hud) {
@@ -399,6 +407,43 @@ function resolveAsset(manifest, assetId) {
     }
     return asset;
 }
+/**
+ * Slice 8: per-frame Y-sort. Walks the entity registry and assigns
+ * `setDepth(y)` to every sprite/primitive/code-rendered entity that hasn't
+ * opted out via explicit `transform.depth` or `properties.skipYSort`.
+ *
+ * Iteration scope is the registry, not `scene.children.list` — registry
+ * holds slice-1 entities only (no editor overlay graphics, no transient
+ * Graphics drawn by behavior code). Cost is O(n) per frame where n =
+ * entity count; well within budget for a 200-entity top-down scene at
+ * 60 FPS.
+ *
+ * Opt-out priority:
+ * 1. `entity.transform.depth` is a number → that constant wins permanently;
+ *    setDepth never overwrites. For "cloud always on top," "tilemap at
+ *    -1000," etc.
+ * 2. `entity.properties.skipYSort: true` → behavior code manages depth;
+ *    ySort doesn't touch the entity.
+ *
+ * Both checks read from the data manager (stashed by `tagGameObject` in
+ * spawnEntity.ts) to avoid round-tripping to the scene file every frame.
+ */
+function installYSortHook(scene, registry) {
+    scene.events.on(Phaser.Scenes.Events.UPDATE, () => {
+        for (const go of registry.all()) {
+            const transform = go.getData('entityTransform');
+            if (typeof transform?.depth === 'number')
+                continue;
+            const props = go.getData('entityProperties');
+            if (props?.skipYSort)
+                continue;
+            const target = go;
+            if (typeof target.y === 'number' && target.setDepth) {
+                target.setDepth(target.y);
+            }
+        }
+    });
+}
 function applyCamera(scene, sceneFile, registry) {
     const cam = scene.cameras.main;
     const cfg = sceneFile.camera ?? {};

package/dist/scene/spawnEntity.d.ts

@@ -28,3 +28,30 @@ export declare function spawnEntity(ctx: SpawnContext, entity: WorldEntity): Pha
  * suitable for Phaser's color APIs.
  */
 export declare function parseColor(input: string): number;
+/**
+ * Apply the asset's `hitbox` metadata to a sprite's physics body.
+ *
+ * Called automatically at spawn from `createSprite`; ALSO callable by
+ * behavior code that attaches a body later (e.g. the agent's physics skill
+ * does `scene.physics.add.existing(sprite); applyAssetHitbox(sprite, asset);`).
+ *
+ * Semantics:
+ * - **No-op (silent)** when `asset.hitbox` is unset — that's the chat-only
+ *   path (primitives, AI-gen images without vision metadata). Workflow A
+ *   in design doc 09 §4.4 is unaffected.
+ * - **Dev-warn (NOT throw)** when called on a sprite without a physics body.
+ *   The most likely agent mistake is calling this BEFORE
+ *   `scene.physics.add.existing(sprite)`; the warning surfaces in the
+ *   iframe console for the agent's post-turn diagnostic loop.
+ * - **Per-frame variant** installs an `ANIMATION_UPDATE` listener that
+ *   swaps `body.setSize/setOffset` on every frame change during anim
+ *   playback. Listener is idempotent — calling `applyAssetHitbox` twice
+ *   on the same sprite tears down the prior listener before installing a
+ *   new one (handles asset hot-reload + Inspector live-edits).
+ *
+ * Caveat: per-frame swap fires on `Phaser.Animations.Events.ANIMATION_UPDATE`
+ * only, which means manual `sprite.setFrame(idx)` calls outside of animation
+ * playback do NOT swap the body. v1 accepts this — combat sheets are
+ * animation-driven. A `setFrame` wrapper is a v2 candidate.
+ */
+export declare function applyAssetHitbox(sprite: Phaser.GameObjects.Sprite, asset: AssetRecord): void;

package/dist/scene/spawnEntity.js

@@ -1,3 +1,5 @@
+import Phaser from 'phaser';
+import { isPerFrameHitbox, } from './types.js';
 /**
  * Spawn one entity into the scene and register it. Returns the created
  * GameObject so callers (notably `spawnEntity` itself, recursing on a
@@ -60,6 +62,21 @@ function createSprite(ctx, entity) {
         sprite.setFlipX(true);
     if (v.flipY)
         sprite.setFlipY(true);
+    // Slice 8: depth anchor → setOrigin so sprite.y aligns with the asset's
+    // footprint pixel (feet, trunk base, etc.). Without this, ySort compares
+    // geometric centers — characters draw behind walls they're standing in
+    // front of. Phaser's sprite.width / .height reflect frame dims (not the
+    // whole spritesheet texture).
+    if (asset.depthAnchor) {
+        const frameW = sprite.width || 1;
+        const frameH = sprite.height || 1;
+        sprite.setOrigin(asset.depthAnchor.x / frameW, asset.depthAnchor.y / frameH);
+    }
+    // Slice 8: apply asset.hitbox to the physics body IF a body exists. We do
+    // NOT auto-add a body — the agent's physics skill / behavior code decides
+    // when to wire collision. This call is a no-op when asset.hitbox is unset
+    // (chat-only Workflow A path stays untouched).
+    applyAssetHitbox(sprite, asset);
     return sprite;
 }
 /**
@@ -188,6 +205,17 @@ function tagGameObject(go, entity) {
         go.setData('entityRole', entity.role);
     if (entity.properties)
         go.setData('entityProperties', entity.properties);
+    // Slice 8: ySort loop reads transform.depth to skip explicit-depth entities.
+    // Stash the transform on the GO's data manager to avoid a round-trip back
+    // to the scene file every frame.
+    go.setData('entityTransform', entity.transform);
+    // Slice 8: assetUpdate handler walks the registry to find all instances of
+    // an asset whose hitbox/anchor changed. Stash the assetId for sprite
+    // entities so the lookup is O(n) on the registry rather than a per-entity
+    // re-parse of the scene file.
+    if (entity.kind === 'sprite') {
+        go.setData('entityAssetId', entity.visual.assetId);
+    }
 }
 /**
  * Trigger stub renderer — slice 3. Renders the trigger zone as a
@@ -263,3 +291,76 @@ export function parseColor(input) {
         return parseInt(trimmed.slice(2), 16);
     return parseInt(trimmed, 16);
 }
+// --- Slice 8: hitbox application -----------------------------------------
+const HITBOX_LISTENER_KEY = 'unboxyHitboxListener';
+/**
+ * Apply the asset's `hitbox` metadata to a sprite's physics body.
+ *
+ * Called automatically at spawn from `createSprite`; ALSO callable by
+ * behavior code that attaches a body later (e.g. the agent's physics skill
+ * does `scene.physics.add.existing(sprite); applyAssetHitbox(sprite, asset);`).
+ *
+ * Semantics:
+ * - **No-op (silent)** when `asset.hitbox` is unset — that's the chat-only
+ *   path (primitives, AI-gen images without vision metadata). Workflow A
+ *   in design doc 09 §4.4 is unaffected.
+ * - **Dev-warn (NOT throw)** when called on a sprite without a physics body.
+ *   The most likely agent mistake is calling this BEFORE
+ *   `scene.physics.add.existing(sprite)`; the warning surfaces in the
+ *   iframe console for the agent's post-turn diagnostic loop.
+ * - **Per-frame variant** installs an `ANIMATION_UPDATE` listener that
+ *   swaps `body.setSize/setOffset` on every frame change during anim
+ *   playback. Listener is idempotent — calling `applyAssetHitbox` twice
+ *   on the same sprite tears down the prior listener before installing a
+ *   new one (handles asset hot-reload + Inspector live-edits).
+ *
+ * Caveat: per-frame swap fires on `Phaser.Animations.Events.ANIMATION_UPDATE`
+ * only, which means manual `sprite.setFrame(idx)` calls outside of animation
+ * playback do NOT swap the body. v1 accepts this — combat sheets are
+ * animation-driven. A `setFrame` wrapper is a v2 candidate.
+ */
+export function applyAssetHitbox(sprite, asset) {
+    if (!asset.hitbox)
+        return;
+    const body = sprite.body;
+    if (!body) {
+        // eslint-disable-next-line no-console
+        console.warn(`[unboxy/scene] applyAssetHitbox called on a sprite with no physics ` +
+            `body (asset=${asset.id}). Call scene.physics.add.existing(sprite) ` +
+            `first, or this is a no-op.`);
+        return;
+    }
+    // Tear down any previously installed per-frame listener so re-applying is
+    // idempotent. The listener reference is stashed on the sprite's data
+    // manager because Phaser's emitter needs the exact function reference to
+    // remove it.
+    const prior = sprite.getData(HITBOX_LISTENER_KEY);
+    if (prior) {
+        sprite.off(Phaser.Animations.Events.ANIMATION_UPDATE, prior);
+        sprite.setData(HITBOX_LISTENER_KEY, undefined);
+    }
+    if (isPerFrameHitbox(asset.hitbox)) {
+        // Apply the default shape immediately — covers the current frame plus
+        // every frame not present in the overrides map.
+        applyShape(body, asset.hitbox.default);
+        const overrides = asset.hitbox.frames;
+        const defaultShape = asset.hitbox.default;
+        const listener = (_anim, frame) => {
+            applyShape(body, overrides[frame.index] ?? defaultShape);
+        };
+        sprite.setData(HITBOX_LISTENER_KEY, listener);
+        sprite.on(Phaser.Animations.Events.ANIMATION_UPDATE, listener);
+    }
+    else {
+        applyShape(body, asset.hitbox);
+    }
+}
+/**
+ * Internal helper that maps a HitboxRect to Phaser's body API. v1 handles
+ * `kind: 'rect'` only; v2 will widen the union to `HitboxRect | HitboxCircle`
+ * and branch on `shape.kind` — see design doc 09 §9.2.1.
+ */
+function applyShape(body, shape) {
+    body.setSize(shape.w, shape.h);
+    body.setOffset(shape.x, shape.y);
+}

package/dist/scene/types.d.ts

@@ -97,6 +97,41 @@ export interface AssetRecord {
      * backfill close their own gaps separately (see design doc 07 §8.4).
      */
     pixelArt?: boolean;
+    /**
+     * Per-asset collision body metadata (slice 8 — see design doc 09).
+     *
+     * Two shapes:
+     * - `HitboxRect` — single rect shared across every frame (top-down
+     *   characters with constant foot footprint, trees, buildings, walls).
+     * - `HitboxPerFrame` — `default` rect plus per-frame overrides indexed by
+     *   frame number. Used for melee combat where an attack-swing frame's
+     *   hitbox extends to where the tool reaches (Sprout Lands chop-the-tree
+     *   case). The SDK installs an `ANIMATION_UPDATE` listener that swaps
+     *   `body.setSize/setOffset` per frame during animation playback.
+     *
+     * v1 ships `kind: 'rect'` only. v2 adds `'circle'` as a pure forward-compat
+     * extension — see design doc 09 §9.2.1.
+     *
+     * Consumed by `applyAssetHitbox(sprite, asset)` at spawn time AND callable
+     * by behavior code after attaching a body. No-op if the sprite has no body.
+     */
+    hitbox?: HitboxRect | HitboxPerFrame;
+    /**
+     * Asset-wide footprint anchor (slice 8 — see design doc 09 §2).
+     *
+     * Pixel within the asset's frame (top-left = 0,0) that defines where the
+     * sprite "touches the ground." SDK applies as
+     * `sprite.setOrigin(x / frameW, y / frameH)` at spawn, so `sprite.y` in
+     * world space equals the world y of the anchor pixel — perfect for ySort
+     * (`sprite.depth = sprite.y`).
+     *
+     * Typical values: character feet (e.g. `(16, 28)` on a 32×32 cell), tree
+     * trunk base, building foundation midpoint. Decorations / centered objects
+     * leave unset → Phaser default origin (0.5, 0.5) → ySort by geometric
+     * center (acceptable fallback; the scene panel surfaces a warning when
+     * ySort is on and some sprite assets lack anchor).
+     */
+    depthAnchor?: DepthAnchor;
 }
 /** Single-image 9-slice config. Pixels from each edge to the slice line. */
 export interface NinePatchConfig {
@@ -119,6 +154,74 @@ export interface NinePatchPerFrame {
  * sites that only need to handle one shape stay narrow.
  */
 export declare function isPerFrameNinePatch(np: NinePatchConfig | NinePatchPerFrame | undefined): np is NinePatchPerFrame;
+/**
+ * Rectangular hitbox in source-pixel coordinates (top-left = 0,0 within the
+ * asset's frame). Consumed by the SDK at sprite spawn time as
+ * `body.setSize(w, h)` + `body.setOffset(x, y)` when a physics body exists.
+ *
+ * v1 is the only supported `kind`. v2 adds `'circle'` (see design doc 09
+ * §9.2.1 for the full forward-compat migration story); polygon is v3+.
+ */
+export interface HitboxRect {
+    kind: 'rect';
+    /** Top-left x of the hitbox in source pixels. */
+    x: number;
+    /** Top-left y of the hitbox in source pixels. */
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * v2 — placeholder doc only. NOT in v1 schema. When v2 adds circle, this
+ * interface lands and the `AssetRecord.hitbox` + `HitboxPerFrame.default` /
+ * `.frames` unions widen to include it. v1 backend validation whitelists
+ * `kind in ['rect']`; v2 widens the whitelist. All v1 data stays valid.
+ *
+ *   interface HitboxCircle {
+ *     kind: 'circle';
+ *     x: number;       // center x in source-pixel coords of frame 0
+ *     y: number;       // center y in source-pixel coords of frame 0
+ *     radius: number;
+ *   }
+ */
+/**
+ * Per-frame hitbox configuration. The `default` shape applies to every frame
+ * not present in `frames`; entries in `frames` override per frame index.
+ *
+ * This default+overrides model matches how combat sheets decompose — most
+ * frames share one hitbox (idle / walk / hurt at the feet), only attack-swing
+ * frames need a wider shape that reaches to where the tool / weapon visually
+ * extends. The motivating Sprout Lands case: 16-frame character sheet where
+ * frames 8–11 are an axe swing reaching ~16 pixels sideways past the foot.
+ *
+ * Discriminator: `'default' in hitbox` (HitboxRect has `kind` instead).
+ */
+export interface HitboxPerFrame {
+    default: HitboxRect;
+    /** Frame index → override shape. Frames absent fall back to `default`. */
+    frames: Record<number, HitboxRect>;
+}
+/**
+ * Type guard — true when `hitbox` is the per-frame variant. Used by SDK
+ * runtime to decide whether to install an `ANIMATION_UPDATE` listener that
+ * swaps body shape per frame.
+ */
+export declare function isPerFrameHitbox(h: HitboxRect | HitboxPerFrame | undefined): h is HitboxPerFrame;
+/**
+ * Depth anchor — pixel within the asset's frame (top-left = 0,0) that defines
+ * the sprite's footprint position. The SDK applies it at spawn as
+ * `sprite.setOrigin(x / frameW, y / frameH)` so the sprite's world `y` aligns
+ * with the world position of this pixel. ySort then compares foot positions
+ * directly via `sprite.depth = sprite.y` without per-asset offset math.
+ *
+ * Asset-wide — shared across all frames of a spritesheet. Per-frame variation
+ * is not in scope (footprint position doesn't change across animations even
+ * when hitbox shape does).
+ */
+export interface DepthAnchor {
+    x: number;
+    y: number;
+}
 export interface SheetAnimation {
     /** Phaser animation key — used as `sprite.play('<name>')`. */
     name: string;
@@ -337,6 +440,25 @@ export interface WorldScene {
     world: WorldSceneConfig;
     camera?: CameraConfig;
     entities: WorldEntity[];
+    /**
+     * Scene-level Y-sort opt-in (slice 8 — see design doc 09 §2.2).
+     *
+     * When `true`, the SDK installs a per-frame update hook in `loadWorldScene`
+     * that walks the entity registry and sets `sprite.depth = sprite.y` so
+     * closer-to-camera sprites overlap farther ones. Default `false` —
+     * side-scrollers, single-screen arcade, and chat-only Workflow A games
+     * don't pay the per-frame cost.
+     *
+     * Two opt-out mechanisms (orthogonal, cover different intents):
+     * - `entity.transform.depth` set to a number → that constant wins, ySort
+     *   skips the entity. For "cloud always on top," "tilemap at -1000," etc.
+     * - `entity.properties.skipYSort: true` → ySort doesn't touch the entity's
+     *   depth at all. For behavior code that manages depth dynamically.
+     *
+     * Top-down RPG / farming / iso / city-builder / MOBA / 2.5D platformer
+     * are the target genres.
+     */
+    ySort?: boolean;
     metadata?: {
         tags?: string[];
         author?: string;

package/dist/scene/types.js

@@ -15,3 +15,11 @@ export const SCHEMA_VERSION = 1;
 export function isPerFrameNinePatch(np) {
     return !!np && 'perFrame' in np;
 }
+/**
+ * Type guard — true when `hitbox` is the per-frame variant. Used by SDK
+ * runtime to decide whether to install an `ANIMATION_UPDATE` listener that
+ * swaps body shape per frame.
+ */
+export function isPerFrameHitbox(h) {
+    return !!h && 'default' in h;
+}

package/package.json

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