Normalize character asset keys and preload playable assets

Author: gandazgul

src/assets/assetLoading.js

@@ -59,8 +59,10 @@ export function loadJsonOnce(scene, key, url) {
     if (!scene.cache.json.exists(key)) scene.load.json(key, url);
 }
 
-const IMAGE_EXTENSIONS = new Set(["jpg", "jpeg", "png", "webp", "svg"]);
-const ATLAS_EXTENSIONS = new Set(["png", "webp"]);
+const IMAGE_EXTENSIONS = new Set(["jpg", "jpeg", "png", "webp", "svg", "gif"]);
+const ATLAS_EXTENSIONS = new Set(["png", "webp", "jpg", "jpeg", "svg", "gif"]);
+
+import { characters } from "../characters/CharacterRegistry.js";
 
 /**
  * @param {string} name
@@ -82,6 +84,7 @@ function resolveAssetName(name, fallbackExtension, allowedExtensions) {
     if (ext && allowedExtensions.has(ext)) {
         return { file: name, stem: name.slice(0, -ext.length - 1) };
     }
+    // If no extension, or unrecognised extension, assume the requested fallback
     return { file: `${name}.${fallbackExtension}`, stem: name };
 }
 
@@ -244,6 +247,21 @@ export function collectChapterAssetKeys(manager, chapter) {
         keys.add(bg);
         for (const a of cfg.assets ?? []) keys.add(a);
     }
+
+    // Auto-include playable characters, as they can appear in any scene
+    for (const id of characters.playableIds()) {
+        const conf = characters.get(id);
+        if (conf?.spriteKey) keys.add(conf.spriteKey);
+        if (conf?.animationSet) {
+            for (const dir of Object.values(conf.animationSet)) {
+                if (dir.still) keys.add(dir.still);
+                if (dir.idle) keys.add(dir.idle);
+                if (dir.walk) keys.add(dir.walk);
+                if (dir.reach) keys.add(dir.reach);
+            }
+        }
+    }
+
     return keys;
 }
 

src/characters/CharacterRegistry.js

@@ -23,6 +23,45 @@
  * `animationSet` + scales/origins — a full sprite-set swap) that overrides the
  * base look. See {@link CharacterRegistry#render} and ADR 0006.
  */
+const PREFIXES = ["character_", "bg_", "sprite_", "object_"];
+
+/**
+ * @param {string | undefined} key
+ * @returns {string | undefined}
+ */
+function prefixKey(key) {
+    if (!key || typeof key !== "string") return key;
+    if (PREFIXES.some((p) => key.startsWith(p))) return key;
+    return `character_${key}`;
+}
+
+/**
+ * @param {CharacterConfig} config
+ * @returns {CharacterConfig}
+ */
+function normalizeConfig(config) {
+    const copy = { ...config };
+    if (copy.spriteKey) copy.spriteKey = prefixKey(copy.spriteKey);
+    if (copy.animationSet) {
+        copy.animationSet = { ...copy.animationSet };
+        for (const [dir, set] of Object.entries(copy.animationSet)) {
+            /** @type {any} */ (copy.animationSet)[dir] = { ...set };
+            for (const [anim, key] of Object.entries(set)) {
+                if (typeof key === "string") {
+                    /** @type {any} */ (copy.animationSet)[dir][anim] = prefixKey(key);
+                }
+            }
+        }
+    }
+    if (copy.outfits) {
+        copy.outfits = { ...copy.outfits };
+        for (const [name, outfit] of Object.entries(copy.outfits)) {
+            copy.outfits[name] = normalizeConfig(outfit);
+        }
+    }
+    return copy;
+}
+
 export class CharacterRegistry {
     constructor() {
         /** @type {Map<string, CharacterConfig>} */
@@ -37,8 +76,9 @@ export class CharacterRegistry {
      * @param {string} id @param {CharacterConfig} config
      */
     register(id, config) {
-        this._chars.set(id, config);
-        if (config.playable && this._defaultPlayer === null) this._defaultPlayer = id;
+        const normalized = normalizeConfig(config);
+        this._chars.set(id, normalized);
+        if (normalized.playable && this._defaultPlayer === null) this._defaultPlayer = id;
         return this;
     }
 

src/scene/AdventureScene.js

@@ -128,7 +128,23 @@ export class AdventureScene extends Phaser.Scene {
 
     collectAssetKeys() {
         const cfg = this.sceneConfig;
-        return [...Object.values(cfg.backgroundsByChapter ?? {}), ...(cfg.assets ?? [])];
+        const keys = [...Object.values(cfg.backgroundsByChapter ?? {}), ...(cfg.assets ?? [])];
+
+        // Auto-include playable characters
+        for (const id of characters.playableIds()) {
+            const conf = characters.get(id);
+            if (conf?.spriteKey) keys.push(conf.spriteKey);
+            if (conf?.animationSet) {
+                for (const dir of Object.values(conf.animationSet)) {
+                    if (dir.still) keys.push(dir.still);
+                    if (dir.idle) keys.push(dir.idle);
+                    if (dir.walk) keys.push(dir.walk);
+                    if (dir.reach) keys.push(dir.reach);
+                }
+            }
+        }
+
+        return keys;
     }
 
     preload() {