feat: refine exploration presentation and audio flow

src/game/data/explorationCharacterAssets.ts

@@ -200,6 +200,55 @@ export function explorationCharacterAnimationKey(
   return `${textureKey}-${motion}-${direction}`;
 }
 
+export function explorationCharacterFrameFor(
+  motion: ExplorationCharacterMotion,
+  direction: ExplorationCharacterDirection,
+  frameIndex = 0
+) {
+  const rowStart =
+    explorationCharacterSheetRows[direction] * explorationCharacterFramesPerDirection;
+  const motionStart = motion === 'walk' ? explorationCharacterIdleFrameCount : 0;
+  const motionFrameCount = motion === 'walk'
+    ? explorationCharacterWalkFrameCount
+    : explorationCharacterIdleFrameCount;
+  const normalizedFrameIndex = Math.max(
+    0,
+    Math.min(motionFrameCount - 1, Math.trunc(frameIndex))
+  );
+  return rowStart + motionStart + normalizedFrameIndex;
+}
+
+export function applyExplorationCharacterMotion(
+  sprite: Phaser.GameObjects.Sprite,
+  textureKey: ExplorationCharacterTextureKey,
+  motion: ExplorationCharacterMotion,
+  direction: ExplorationCharacterDirection,
+  reducedMotion = false
+) {
+  if (!sprite.scene.textures.exists(textureKey)) {
+    return false;
+  }
+
+  if (reducedMotion && motion === 'idle') {
+    sprite.anims.stop();
+    sprite.setFrame(explorationCharacterFrameFor('idle', direction));
+    return true;
+  }
+
+  const animationKey = explorationCharacterAnimationKey(
+    textureKey,
+    motion,
+    direction
+  );
+  if (
+    sprite.anims.currentAnim?.key !== animationKey ||
+    !sprite.anims.isPlaying
+  ) {
+    sprite.play(animationKey);
+  }
+  return true;
+}
+
 export function ensureExplorationCharacterAnimations(
   scene: Phaser.Scene,
   textureKeysOrUnitTextureKeys: Iterable<string>
@@ -210,20 +259,18 @@ export function ensureExplorationCharacterAnimations(
     }
 
     explorationCharacterDirections.forEach((direction) => {
-      const rowStart =
-        explorationCharacterSheetRows[direction] * explorationCharacterFramesPerDirection;
       const idleFrames = Array.from(
         { length: explorationCharacterIdleFrameCount },
         (_, frameIndex) => ({
           key,
-          frame: rowStart + frameIndex
+          frame: explorationCharacterFrameFor('idle', direction, frameIndex)
         })
       );
       const walkFrames = Array.from(
         { length: explorationCharacterWalkFrameCount },
         (_, frameIndex) => ({
           key,
-          frame: rowStart + explorationCharacterIdleFrameCount + frameIndex
+          frame: explorationCharacterFrameFor('walk', direction, frameIndex)
         })
       );
       const idleAnimationKey = explorationCharacterAnimationKey(key, 'idle', direction);