Improve character switching and wanderers

- add game-agnostic switch fallback and position handoff
- support spawning multiple opt-in idle wanderers
- document wanderer behavior and config options

Author: gandazgul

docs/characters.md

@@ -17,6 +17,7 @@ characters.register("hero", {
     animationScales: { "hero-walk-front": 0.5 },   // per-animation scale overrides
     animationOrigins: { "hero-side": { x: 0.5, y: 1 } },
     playable: true,              // ← this character is player-controllable
+    wanderer: true,              // ← if inactive, this character wanders the scene
     largeBubble: false,          // ← thought bubble anchors normally
     outfits: {
         pajamas: {               // alternate render config (see below)
@@ -71,7 +72,20 @@ When more than one playable character is registered, the engine automatically of
 
 1. Stores the new active character id
 2. Rebuilds the active walker with the new character's render config
-3. Emits a `characterchange` event that NPC reactions can listen for
+3. Repositions the newly active character to where the previous active character stood
+4. Updates the inactive wandering characters (see below)
+5. Emits a `characterchange` event that NPC reactions can listen for
+
+## Wanderers (Inactive Characters)
+
+When multiple playable characters are registered, the currently unselected (inactive) characters can autonomously wander around the scene. The engine manages these characters through `engineScene.idleCharacters`.
+
+To enable wandering, you must opt-in:
+- **Registry Opt-in:** Set `wanderer: true` when registering the character. They will automatically wander whenever they are inactive.
+- **Explicit Override:** Pass a `wanderers` array to the spawn method in your scene's `create()`: `this.spawnIdleCharacters({ wanderers: ["sister"] })`.
+- **Suppressing:** Set `disableIdleCharacter: true` in your `AdventureSceneConfig` to completely disable wanderers for that scene.
+
+You can also provide a `greeting` callback to `spawnIdleCharacters` to give them click-to-speak dialogue lines.
 
 ## Outfits (ADR 0006)
 

src/characters/CharacterRegistry.js

@@ -14,6 +14,7 @@
  * @property {Record<string, number>} [animationScales]
  * @property {Record<string, { x?: number, y?: number }>} [animationOrigins]
  * @property {boolean} [playable]
+ * @property {boolean} [wanderer] - whether the character wanders the scene when inactive (opt-in).
  * @property {boolean} [largeBubble]
  * @property {Record<string, CharacterConfig>} [outfits]
  * @property {{ scale?: number, texture?: string, offsetX?: number, offsetY?: number }} [portraitSettings]

src/characters/CharacterSwitcher.js

@@ -15,6 +15,7 @@ import { characters } from "./CharacterRegistry.js";
 import { store } from "../state/Store.js";
 import { UI_DEPTH } from "../ui/UIHelper.js";
 import { resolveCharacterPortrait } from "./portraits.js";
+import { IdleCharacter } from "../movement/IdleCharacter.js";
 
 // ─── Exported class ─────────────────────────────────────────────────────────
 
@@ -96,15 +97,102 @@ export class CharacterSwitcher {
             /** @param {any} _p @param {any} _x @param {any} _y @param {PointerEvent} event */
             (_p, _x, _y, event) => {
                 event?.stopPropagation?.();
-                if (this.opts.onSwitch) this.opts.onSwitch();
-                else {
-                    const s = /** @type {any} */ (this.scene);
-                    if (typeof s.switchActiveCharacter === "function") s.switchActiveCharacter();
-                }
+                this.switchActiveCharacter();
             },
         );
     }
 
+    /** Switch the active playable character, falling back to game-agnostic logic if the scene doesn't provide it. */
+    switchActiveCharacter() {
+        if (this.opts.onSwitch) {
+            this.opts.onSwitch();
+            return;
+        }
+
+        const engineScene = /** @type {any} */ (this.scene);
+        if (typeof engineScene.switchActiveCharacter === "function") {
+            engineScene.switchActiveCharacter();
+            return;
+        }
+
+        // Game-agnostic default implementation
+        const walk = engineScene.walk;
+
+        if (!walk) return;
+        if (walk.locked) return; // don't switch mid-puzzle
+
+        const activeName = store.getActiveCharacter() ?? characters.defaultPlayer ?? "";
+        const playables = characters.playableIds();
+        if (playables.length < 2) return;
+        const nextName = playables[(playables.indexOf(activeName) + 1) % playables.length] ?? activeName;
+        if (nextName === activeName) return;
+
+        const activeX = walk.sprite.x;
+        const activeY = walk.sprite.y;
+
+        // Find the IdleCharacter instance for the character that is ABOUT TO BECOME ACTIVE
+        const nextIdleChar = engineScene.idleCharacters?.find(
+            /** @param {{ name?: string }} c */
+            (c) => c.name === nextName,
+        );
+
+        let inactiveX, inactiveY;
+        const isInactivePresent = nextIdleChar && nextIdleChar.isPresent();
+        if (isInactivePresent) {
+            const pos = nextIdleChar.getPosition();
+            inactiveX = pos ? pos.x : -150;
+            inactiveY = pos ? pos.y : activeY;
+        } else {
+            inactiveX = -150;
+            inactiveY = activeY;
+        }
+
+        const newActiveX = isInactivePresent ? inactiveX : activeX;
+        const newActiveY = isInactivePresent ? inactiveY : activeY;
+        const newInactiveX = activeX;
+        const newInactiveY = activeY;
+
+        // Preserve idle character options (like greetings) to recreate it
+        const idleOpts = engineScene.idleCharacters?.[0]?.opts ?? {};
+
+        store.setActiveCharacter(nextName);
+
+        walk.shutdown();
+        if (walk.sprite) walk.sprite.destroy();
+        engineScene.walk = null;
+
+        for (const c of engineScene.idleCharacters ?? []) c.destroy();
+        engineScene.idleCharacters = [];
+
+        if (typeof engineScene.spawnActiveCharacter === "function") {
+            engineScene.spawnActiveCharacter({ x: newActiveX, y: newActiveY });
+        }
+
+        if (typeof engineScene.spawnIdleCharacters === "function") {
+            engineScene.spawnIdleCharacters(idleOpts);
+        } else if (typeof engineScene.createIdleCharacter === "function") {
+            // Fallback for games that haven't updated yet
+            engineScene.idleCharacters = [engineScene.createIdleCharacter()];
+        } else {
+            engineScene.idleCharacters = engineScene.sceneConfig?.disableIdleCharacter
+                ? []
+                : playables.filter((id) => id !== nextName).map((id) =>
+                    new IdleCharacter(engineScene, { ...idleOpts, characterId: id })
+                );
+        }
+
+        // Make the newly inactive character stand where the active character just was
+        const newlyInactiveChar = engineScene.idleCharacters?.find(
+            /** @param {{ name?: string }} c */
+            (c) => c.name === activeName,
+        );
+        if (newlyInactiveChar) {
+            newlyInactiveChar.presentAt(newInactiveX, newInactiveY);
+        }
+
+        this.createPortrait();
+    }
+
     /** @param {boolean} visible */
     setVisible(visible) {
         this.sprite?.setVisible(visible);

src/movement/IdleCharacter.js

@@ -7,6 +7,7 @@ import { walkControllerWanderHost } from "./behaviors/walker.js";
 
 /**
  * @typedef {object} IdleCharacterOptions
+ * @property {string} [characterId] - the specific playable character id to spawn. Defaults to the first inactive.
  * @property {(activeId: string, idleId: string) => string} [greeting] - text to
  *   speak when the idle character is clicked. No bubble if omitted.
  * @property {boolean} [startPresent] - spawn already on-screen (vs. the default
@@ -44,13 +45,17 @@ export class IdleCharacter {
         if (!sceneConfig?.walkable || sceneConfig.disableIdleCharacter) return;
 
         const playables = characters.playableIds();
+        /** @type {string} */
         this.activeName = store.getActiveCharacter() ?? characters.defaultPlayer ?? "";
         // Inert unless the active character is itself playable and a different
         // playable exists to stand in as the idle one.
         if (!playables.includes(this.activeName)) return;
-        const idle = playables.find((id) => id !== this.activeName);
-        if (!idle) return;
-        this.name = idle;
+
+        /** @type {string | undefined} */
+        const targetId = opts.characterId ?? playables.find((id) => id !== this.activeName);
+        if (!targetId || targetId === this.activeName) return;
+
+        this.name = targetId;
         this.config = characters.render(this.name, store.getOutfit(this.name));
 
         this.walkable = sceneConfig.walkable;

src/scene/AdventureScene.js

@@ -13,6 +13,7 @@ import { characters } from "../characters/CharacterRegistry.js";
 import { engineAssets } from "../assets/EngineAssets.js";
 import { loadAssetKeys, registerAssetKeys } from "../assets/assetLoading.js";
 import { clearLastTransitionFrom, lastTransitionFrom } from "./transitions.js";
+import { IdleCharacter } from "../movement/IdleCharacter.js";
 
 /**
  * @typedef {object} SpawnPose
@@ -83,6 +84,8 @@ export class AdventureScene extends Phaser.Scene {
     editor;
     /** @type {CastDirector} */
     cast;
+    /** @type {IdleCharacter[]} */
+    idleCharacters = [];
     /**
      * Count of live NPCs per character id, maintained by `NPC`. Lets wanderers
      * skip a character already present in the scene.
@@ -151,14 +154,47 @@ export class AdventureScene extends Phaser.Scene {
         loadAssetKeys(this, this.collectAssetKeys());
     }
 
+    /**
+     * Spawn the idle characters (the inactive playables) to wander the scene.
+     * The engine automatically determines which characters are inactive, but only
+     * spawns those flagged `wanderer: true` in the registry, unless overridden via opts.
+     * @param {import("../movement/IdleCharacter.js").IdleCharacterOptions & { wanderers?: string[] }} [opts]
+     */
+    spawnIdleCharacters(opts) {
+        for (const char of this.idleCharacters) char.destroy();
+        this.idleCharacters = [];
+        
+        // Scene-wide suppression?
+        if (this.sceneConfig.disableIdleCharacter) return this.idleCharacters;
+
+        const playables = characters.playableIds();
+        const activeName = this.getActiveCharacterId();
+        const inactives = playables.filter((id) => id !== activeName);
+
+        // Explicit list provided? Otherwise use registry opt-in.
+        let targetIds = opts?.wanderers;
+        if (!targetIds) {
+            targetIds = inactives.filter((id) => characters.get(id)?.wanderer);
+        }
+
+        // Only spawn those that are actually inactive
+        const toSpawn = targetIds.filter(id => inactives.includes(id));
+
+        for (const id of toSpawn) {
+            this.idleCharacters.push(new IdleCharacter(this, { ...opts, characterId: id }));
+        }
+        return this.idleCharacters;
+    }
+
     /**
      * Build the active character's WalkController from the registry, applying
      * the character's current outfit and any per-scene scale override. Reused
      * by `create()` and by a subclass's switch/rebuild.
-     * @param {string} name @param {{ x: number, y: number }} startPos
+     * @param {{ x: number, y: number }} startPos
      * @param {"up" | "down" | "left" | "right"} [initialFacing]
      */
-    spawnActiveCharacter(name, startPos, initialFacing) {
+    spawnActiveCharacter(startPos, initialFacing) {
+        const name = this.getActiveCharacterId();
         const cfg = this.sceneConfig;
         const conf = characters.render(name, store.getOutfit(name));
         const baseScale = 0.55;
@@ -230,7 +266,7 @@ export class AdventureScene extends Phaser.Scene {
         }
         if (lastTransitionFrom) clearLastTransitionFrom();
 
-        this.spawnActiveCharacter(this.getActiveCharacterId(), startPos, initialFacing);
+        this.spawnActiveCharacter(startPos, initialFacing);
         if (cfg.suppressActiveCharacter) this.suppressActiveCharacter();
 
         this.inventory = new InventoryLayer(this, {