@unboxy/phaser-sdk 0.2.34 → 0.2.36

package/dist/scene/SceneLoader.js

@@ -115,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;
@@ -122,12 +172,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`);
@@ -182,6 +249,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/types.d.ts

@@ -42,10 +42,48 @@ 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). */
     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.34",
+  "version": "0.2.36",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",