@unboxy/phaser-sdk 0.2.33 → 0.2.35

package/dist/scene/HudRuntime.js

@@ -140,7 +140,27 @@ function createText(ctx, entity, pos) {
     return text;
 }
 function createImage(ctx, entity, pos) {
-    const asset = ctx.resolveAsset(entity.visual.assetId);
+    let asset;
+    try {
+        asset = ctx.resolveAsset(entity.visual.assetId);
+    }
+    catch {
+        // Soft-fail when the assetId isn't in the manifest. Mirrors the world
+        // scene's createSprite missing-asset path. Wraps a Graphics in a
+        // Container so the editor's bounds-based hit-test has a sized target.
+        const w = entity.visual.width ?? 64;
+        const h = entity.visual.height ?? 64;
+        const g = ctx.scene.add.graphics();
+        g.fillStyle(0x4d2244, 0.4);
+        g.fillRect(-w / 2, -h / 2, w, h);
+        g.lineStyle(2, 0xff00ff, 0.9);
+        g.strokeRect(-w / 2, -h / 2, w, h);
+        g.lineBetween(-w / 2, -h / 2, w / 2, h / 2);
+        g.lineBetween(w / 2, -h / 2, -w / 2, h / 2);
+        const container = ctx.scene.add.container(pos.x, pos.y, [g]);
+        container.setSize(w, h);
+        return container;
+    }
     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);
@@ -478,7 +498,12 @@ export function preloadHudAssets(scene, hudScene, manifest) {
     for (const id of ids) {
         const asset = manifest.assets?.find((a) => a.id === id);
         if (!asset) {
-            throw new Error(`[unboxy/hud] HUD scene '${hudScene.id}' references assetId '${id}' but the manifest has no such asset`);
+            // Soft-fail: warn + continue. createImage / createIconButton render
+            // a placeholder when the asset is unresolvable. Mirrors the world
+            // scene's preloadSceneAssets soft-fail (SceneLoader.ts).
+            // eslint-disable-next-line no-console
+            console.warn(`[unboxy/hud] HUD scene '${hudScene.id}' references assetId '${id}' but the manifest has no such asset; widget will render as a placeholder`);
+            continue;
         }
         if (scene.textures.exists(asset.textureKey))
             continue;

package/dist/scene/SceneLoader.js

@@ -84,7 +84,15 @@ export function preloadSceneAssets(scene, sceneFile, manifest) {
             continue;
         const asset = state.assetsById.get(id);
         if (!asset) {
-            throw new Error(`[unboxy/scene] scene '${sceneFile.id}' references assetId '${id}' but the manifest has no such asset`);
+            // Soft-fail: warn, continue. The downstream spawn path renders a
+            // magenta "?" placeholder for the offending entity so the user sees
+            // *where* a missing asset would have been, without losing every
+            // other entity in the scene. Common cause is the editor adding a
+            // sprite that references an asset whose manifest entry never got
+            // synced (e.g. AssetShelf drag without manifest update).
+            // eslint-disable-next-line no-console
+            console.warn(`[unboxy/scene] scene '${sceneFile.id}' references assetId '${id}' but the manifest has no such asset; entity will render as a placeholder`);
+            continue;
         }
         queueAssetLoad(scene, asset);
         state.requestedAssetIds.add(id);
@@ -107,6 +115,56 @@ function collectAssetIds(entities) {
         walk(e);
     return Array.from(ids);
 }
+/**
+ * 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.
+ */
+function registerSheetAnimations(scene, manifest) {
+    const assets = manifest.assets ?? [];
+    for (const asset of assets) {
+        if (asset.kind !== 'spritesheet')
+            continue;
+        if (!asset.animations || asset.animations.length === 0)
+            continue;
+        if (!scene.textures.exists(asset.textureKey))
+            continue; // not loaded — skip
+        const defaultFps = asset.fps && asset.fps > 0 ? asset.fps : 8;
+        for (const anim of asset.animations) {
+            if (!anim.name)
+                continue;
+            if (scene.anims.exists(anim.name)) {
+                // Don't error out on collision — first registration wins.
+                // eslint-disable-next-line no-console
+                console.warn(`[unboxy/scene] animation key '${anim.name}' already registered; skipping (asset '${asset.id}'). Disambiguate by renaming in the asset's animations metadata.`);
+                continue;
+            }
+            const fps = anim.fps && anim.fps > 0 ? anim.fps : defaultFps;
+            const loop = anim.loop !== false; // default true
+            try {
+                scene.anims.create({
+                    key: anim.name,
+                    frames: scene.anims.generateFrameNumbers(asset.textureKey, {
+                        start: anim.from,
+                        end: anim.to,
+                    }),
+                    frameRate: fps,
+                    repeat: loop ? -1 : 0,
+                });
+            }
+            catch (e) {
+                // eslint-disable-next-line no-console
+                console.warn(`[unboxy/scene] failed to register animation '${anim.name}' on '${asset.id}': ${String(e)}`);
+            }
+        }
+    }
+}
 function queueAssetLoad(scene, asset) {
     if (scene.textures.exists(asset.textureKey))
         return;
@@ -174,6 +232,10 @@ 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);
+    // 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()`.
+    registerSheetAnimations(scene, manifest);
     // Spawn entities.
     const registry = attachEntityRegistry(scene);
     const ctx = {

package/dist/scene/spawnEntity.js

@@ -36,7 +36,18 @@ export function spawnEntity(ctx, entity) {
 }
 function createSprite(ctx, entity) {
     const v = entity.visual;
-    const asset = ctx.resolveAsset(v.assetId);
+    let asset;
+    try {
+        asset = ctx.resolveAsset(v.assetId);
+    }
+    catch (e) {
+        // Soft-fail when the assetId isn't in the manifest. SceneLoader's
+        // preloadSceneAssets logged the warning; here we render a clear
+        // magenta-bordered "?" placeholder so the entity is still visible
+        // and selectable in the editor. Same pattern as createCodeRendered's
+        // missing-render-script path.
+        return missingAssetPlaceholder(ctx, v.assetId);
+    }
     // Phaser's add.sprite handles both plain images and atlas/spritesheet
     // textures uniformly when given (key, frame). For plain images, frame
     // is undefined and Phaser uses the default frame.
@@ -51,6 +62,29 @@ function createSprite(ctx, entity) {
         sprite.setFlipY(true);
     return sprite;
 }
+/**
+ * Magenta "?" placeholder for an entity whose assetId isn't in the manifest.
+ * Drawn as a Graphics so the editor's hit-test (which uses getBounds) lands
+ * on the visible square. Mirrors createCodeRendered's missing-script path.
+ */
+function missingAssetPlaceholder(ctx, assetId) {
+    const w = 64;
+    const h = 64;
+    const g = ctx.scene.add.graphics();
+    g.fillStyle(0x4d2244, 0.4);
+    g.fillRect(-w / 2, -h / 2, w, h);
+    g.lineStyle(2, 0xff00ff, 0.9);
+    g.strokeRect(-w / 2, -h / 2, w, h);
+    // Diagonal "no entry" lines + a "?" text so it's obvious from a glance.
+    g.lineBetween(-w / 2, -h / 2, w / 2, h / 2);
+    g.lineBetween(w / 2, -h / 2, -w / 2, h / 2);
+    // Phaser Graphics has no intrinsic size — sizeForHitTest sets bounds so
+    // the editor's hit-test (which uses getBounds) can find this entity.
+    sizeForHitTest(g, w, h);
+    g.setDataEnabled();
+    g.setData('unboxyMissingAssetId', assetId);
+    return g;
+}
 function createPrimitive(ctx, entity) {
     const v = entity.visual;
     if (v.kind === 'rect')

package/dist/scene/types.d.ts

@@ -46,6 +46,35 @@ export interface AssetRecord {
     atlasPath?: string;
     /** `'xml'` (Starling) or `'json'` (TexturePacker). */
     atlasFormat?: 'xml' | 'json';
+    /**
+     * For `spritesheet`: named animation ranges. SDK auto-registers these as
+     * Phaser anims at preload, so behavior code can call
+     * `sprite.play('walk-down')` without manual `anims.create()` setup.
+     *
+     * <p>Pack import populates this from vision detection (4-direction RPG /
+     * sidescroller / multi-action layouts) or from Aseprite `frameTags`. The
+     * agent can also add/edit entries by hand when wiring a sheet asset.
+     *
+     * <p>Animation keys are scene-global in Phaser; if two sheets register
+     * the same name, the second registration is skipped with a warning.
+     * Disambiguate by namespacing the name (e.g. `cow-walk-down`) when
+     * collisions matter.
+     */
+    animations?: SheetAnimation[];
+    /** Default playback rate for `animations[]`. Defaults to 8. */
+    fps?: number;
+}
+export interface SheetAnimation {
+    /** Phaser animation key — used as `sprite.play('<name>')`. */
+    name: string;
+    /** First frame index, inclusive. */
+    from: number;
+    /** Last frame index, inclusive. */
+    to: number;
+    /** When true, Phaser registers with `repeat: -1`. Defaults to true. */
+    loop?: boolean;
+    /** Override the asset-level fps for this specific animation. */
+    fps?: number;
 }
 export interface Manifest {
     schemaVersion: number;

package/package.json

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