Animation.core.ts

Animation — pure core.

A locomotion blend tree that maps a character's current movement speed to weights on three animation clips (idle / walk / run), plus a scaled playback speedRatio that keeps feet from sliding.

Zero imports from @babylonjs, three, solid-js or the DOM. The core takes numbers in, returns numbers out — the System is the only place allowed to talk to the renderer. That means the same blend logic can be exercised in a pure Node test and drives both adapters with no changes.

Blend shape: speed < speedThreshold → pure idle (weight 1,0,0) threshold ≤ speed < walkSpeed → idle→walk blend (t linear) walkSpeed ≤ speed < runSpeed → walk→run blend (t linear) speed ≥ runSpeed → pure run (weight 0,0,1)

Output weights smooth toward targets via a framerate-aware lerpTowards at blendSpeed units per second. A second, slower lerp on speedRatio (rate 2) prevents jarring audible clicks when playback speed changes.

Public surface: createAnimation(params) — factory instance.update(speed, dt) — returns AnimationOutputs snapshot instance.getState() — read-only live state for HUDs instance.getParams() / setParams — live-tune from panel instance.reset() — back to pure idle + default params

Animation.core.ts

export type AnimationState = 'idle' | 'walk' | 'run';

export interface AnimationParams {
  /** Movement speed at which `walk` weight reaches 1. */
  walkSpeed: number;
  /** Movement speed at which `run` weight reaches 1. */
  runSpeed: number;
  /** Weight transition speed per second. Higher = snappier blends. */
  blendSpeed: number;
  /** Movement-speed smoothing rate (per second). Higher = follows input faster. */
  speedSmoothRate: number;
  /** Dead-zone: any speed below this reads as "standing still". */
  speedThreshold: number;
  /** Min clamp on the animation playback rate multiplier. */
  minSpeedRatio: number;
  /** Max clamp on the animation playback rate multiplier. */
  maxSpeedRatio: number;
}

export const DEFAULT_ANIMATION_PARAMS: AnimationParams = {
  walkSpeed: 3,
  runSpeed: 6,
  blendSpeed: 8,
  speedSmoothRate: 4,
  speedThreshold: 0.5,
  minSpeedRatio: 0.5,
  maxSpeedRatio: 3,
};

export interface AnimationOutputs {
  /** Weight in [0,1] on the idle clip. */
  idleWeight: number;
  /** Weight in [0,1] on the walk clip. */
  walkWeight: number;
  /** Weight in [0,1] on the run clip. */
  runWeight: number;
  /** Playback speed multiplier for locomotion clips (idle stays at 1). */
  speedRatio: number;
  /** Dominant weight, resolved as an enum for HUD/event wiring. */
  state: AnimationState;
  /** True the frame `state` differs from the previous frame's state. */
  stateChanged: boolean;
  /** Smoothed speed used internally this frame — useful for debug. */
  smoothedSpeed: number;
}

export interface AnimationState_ {
  idleWeight: number;
  walkWeight: number;
  runWeight: number;
  speedRatio: number;
  state: AnimationState;
  smoothedSpeed: number;
}

export interface AnimationInstance {
  update(speed: number, dt: number): AnimationOutputs;
  getState(): Readonly<AnimationState_>;
  getParams(): Readonly<AnimationParams>;
  setParams(partial: Partial<AnimationParams>): void;
  reset(): void;
}

Framerate-aware move-toward helper. Same signature as Babylon's Scalar.MoveTowards. Snaps to target within maxDelta so the caller never overshoots.

Animation.core.ts

function lerpTowards(current: number, target: number, maxDelta: number): number {
  const diff = target - current;
  if (Math.abs(diff) <= maxDelta) return target;
  return current + Math.sign(diff) * maxDelta;
}

export function createAnimation(
  params: Partial<AnimationParams> = {},
): AnimationInstance {
  const active: AnimationParams = { ...DEFAULT_ANIMATION_PARAMS, ...params };

  let idleWeight = 1;
  let walkWeight = 0;
  let runWeight = 0;
  let speedRatio = 1;
  let smoothedSpeed = 0;
  let state: AnimationState = 'idle';

  const snapshot = (): AnimationState_ => ({
    idleWeight,
    walkWeight,
    runWeight,
    speedRatio,
    state,
    smoothedSpeed,
  });

  return {
    update(rawSpeed, dt) {
      // Guard negative dt (e.g., a replay step backwards) — treat as 0 so we
      // never unwind the blends and we stay deterministic.
      const stepDt = Math.max(0, dt);

      // 1. Smooth the input speed so physics micro-jitter doesn't flap the blend.
      smoothedSpeed = lerpTowards(
        smoothedSpeed,
        rawSpeed,
        active.speedSmoothRate * stepDt,
      );
      const s = smoothedSpeed;

      // 2. Compute target weights across the four speed bands.
      let tIdle = 0;
      let tWalk = 0;
      let tRun = 0;

      if (s < active.speedThreshold) {
        tIdle = 1;
      } else if (active.walkSpeed <= active.speedThreshold || s < active.walkSpeed) {
        if (active.walkSpeed <= active.speedThreshold) {
          // Degenerate config: threshold >= walkSpeed. Fall straight to walk.
          tWalk = 1;
        } else {
          const t = Math.min(
            1,
            (s - active.speedThreshold) / (active.walkSpeed - active.speedThreshold),
          );
          tIdle = 1 - t;
          tWalk = t;
        }
      } else if (active.runSpeed <= active.walkSpeed || s < active.runSpeed) {
        if (active.runSpeed <= active.walkSpeed) {
          // No meaningful run band; pin walk.
          tWalk = 1;
        } else {
          const t = Math.min(1, (s - active.walkSpeed) / (active.runSpeed - active.walkSpeed));
          tWalk = 1 - t;
          tRun = t;
        }
      } else {
        tRun = 1;
      }

      // 3. Smooth current weights toward their targets.
      const blendDelta = active.blendSpeed * stepDt;
      idleWeight = lerpTowards(idleWeight, tIdle, blendDelta);
      walkWeight = lerpTowards(walkWeight, tWalk, blendDelta);
      runWeight = lerpTowards(runWeight, tRun, blendDelta);

      // 4. Scale playback rate to match movement speed (prevents foot-sliding).
      let targetSpeedRatio = 1;
      if (s > active.speedThreshold) {
        const baseSpeed =
          runWeight > walkWeight && active.runSpeed > 0
            ? active.runSpeed
            : active.walkSpeed;
        if (baseSpeed > 0) {
          targetSpeedRatio = Math.max(
            active.minSpeedRatio,
            Math.min(active.maxSpeedRatio, s / baseSpeed),
          );
        }
      }
      speedRatio = lerpTowards(speedRatio, targetSpeedRatio, 2 * stepDt);

      // 5. Resolve dominant state.
      const prev = state;
      if (idleWeight > walkWeight && idleWeight > runWeight) {
        state = 'idle';
      } else if (runWeight > walkWeight) {
        state = 'run';
      } else {
        state = 'walk';
      }

      return {
        idleWeight,
        walkWeight,
        runWeight,
        speedRatio,
        state,
        stateChanged: prev !== state,
        smoothedSpeed,
      };
    },

    getState() {
      return snapshot();
    },

    getParams() {
      return active;
    },

    setParams(partial) {
      Object.assign(active, partial);
    },

    reset() {
      Object.assign(active, DEFAULT_ANIMATION_PARAMS);
      idleWeight = 1;
      walkWeight = 0;
      runWeight = 0;
      speedRatio = 1;
      smoothedSpeed = 0;
      state = 'idle';
    },
  };
}

Animation.defs.ts

Animation — definitions.

Holds the AnimationComponent class, its event dictionary and the shapes its data and events travel in. No System lives here, which is the point: another component can name Animation in a query, or type an event it listens for, without pulling Animation's behaviour into its own bundle. Import from here, not from Animation.ts.

Animation.defs.ts

import { Component } from '@babylonjsmarket/ecs';
import { DEFAULT_ANIMATION_PARAMS, type AnimationInstance, type AnimationParams, type AnimationState } from './Animation.core';

Events

Animation.defs.ts

export const AnimationEvents = {
  /** Fired the frame the dominant clip flips (e.g., idle → walk). */
  STATE_CHANGED: 'animation.state.changed',
  /** Fired every frame with the current blend weights. Useful for HUDs. */
  BLEND_UPDATED: 'animation.blend.updated',
  /** Fired once after the component has wired up to an animation set. */
  READY: 'animation.ready',
} as const;

export const AnimationInputEvents = {
  /** External producer (MovementSystem, StrideSystem, AI) pushes a speed. */
  SET_SPEED: 'animation.speed.set',
} as const;

export interface AnimationSetSpeedRequest {
  entityId: string;
  speed: number;
}

export interface AnimationInput extends Partial<AnimationParams> {
  /** Name of the idle clip in the imported GLB (default: `"IDLE_RIFLE"`). */
  idleClip?: string;
  /** Name of the walk clip. */
  walkClip?: string;
  /** Name of the run clip. Optional — falls back to pure walk if missing. */
  runClip?: string;
  /** Start playing with full idle weight on attach (default: true). */
  autoPlay?: boolean;
}

Component

Animation.defs.ts

export class AnimationComponent extends Component {
  params: AnimationParams;
  idleClip: string;
  walkClip: string;
  runClip: string;
  autoPlay: boolean;
  /** Populated by the System at attach time. */
  instance: AnimationInstance | null = null;
  /** Cached dominant state so tests + HUDs can observe without calling update. */
  lastState: AnimationState = 'idle';

  constructor(data: AnimationInput = {}) {
    super();
    const { idleClip, walkClip, runClip, autoPlay, ...params } = data;
    this.params = { ...DEFAULT_ANIMATION_PARAMS, ...params };
    this.idleClip = idleClip ?? 'IDLE_RIFLE';
    this.walkClip = walkClip ?? 'WALK_RIFLE';
    this.runClip = runClip ?? 'RUN_RIFLE';
    this.autoPlay = autoPlay ?? true;
  }

  serialize(): AnimationInput {
    return {
      ...this.params,
      idleClip: this.idleClip,
      walkClip: this.walkClip,
      runClip: this.runClip,
      autoPlay: this.autoPlay,
    };
  }
}

Animation.panel.tsx

Renderer-free Solid panel for the Animation core. Binds directly to the instance and can be mounted over either the Babylon or Three.js demo. Zero imports from @babylonjs or three (including type-only).

Animation.panel.tsx

import { Component as SolidComponent, createSignal, onCleanup, onMount } from 'solid-js';
import { createStore } from 'solid-js/store';
import { Slider, ResetButton, Section } from '../_shared/ui';
import {
  DEFAULT_ANIMATION_PARAMS,
  type AnimationInstance,
  type AnimationParams,
} from './Animation.core';

export interface AnimationPanelProps {
  /** The live core instance for the demo target. */
  core: AnimationInstance;
  /** Drives the demo speed. If omitted the panel writes directly into core. */
  onSpeed?: (speed: number) => void;
}

export const AnimationPanel: SolidComponent<AnimationPanelProps> = (props) => {
  const [params, setParams] = createStore<AnimationParams>({ ...props.core.getParams() });
  const [state, setState] = createSignal(props.core.getState());
  const [demoSpeed, setDemoSpeed] = createSignal(0);

  // Poll the live state so the bars tick along with the world clock without
  // needing to thread a per-frame signal in from the caller.
  let pollId: ReturnType<typeof setInterval> | undefined;
  onMount(() => {
    pollId = setInterval(() => setState(props.core.getState()), 60);
  });
  onCleanup(() => {
    if (pollId) clearInterval(pollId);
  });

  const push = <K extends keyof AnimationParams>(key: K, value: AnimationParams[K]) => {
    setParams(key, value);
    props.core.setParams({ [key]: value } as Partial<AnimationParams>);
  };

  const reset = () => {
    setParams({ ...DEFAULT_ANIMATION_PARAMS });
    props.core.setParams(DEFAULT_ANIMATION_PARAMS);
    props.core.reset();
    setDemoSpeed(0);
    if (props.onSpeed) props.onSpeed(0);
  };

  const applySpeed = (v: number) => {
    setDemoSpeed(v);
    if (props.onSpeed) props.onSpeed(v);
  };

  const bar = (label: string, weight: number, color: string) => (
    <div style={{ 'margin-bottom': '4px' }}>
      <div
        style={{
          display: 'flex',
          'justify-content': 'space-between',
          'font-size': '10px',
          color: '#aaa',
        }}
      >
        <span>{label}</span>
        <span>{weight.toFixed(2)}</span>
      </div>
      <div
        style={{
          height: '6px',
          background: '#222',
          'border-radius': '3px',
          overflow: 'hidden',
          border: '1px solid #333',
        }}
      >
        <div
          style={{
            height: '100%',
            width: `${Math.max(0, Math.min(1, weight)) * 100}%`,
            background: color,
            transition: 'width 60ms linear',
          }}
        />
      </div>
    </div>
  );

  return (
    <div style={{ 'font-family': 'system-ui, sans-serif', color: '#ddd', 'min-width': '260px' }}>
      <Section title="Blend">
        {bar('idle', state().idleWeight, '#66ccff')}
        {bar('walk', state().walkWeight, '#66cc55')}
        {bar('run', state().runWeight, '#ff9933')}
        <div style={{ color: '#888', 'font-size': '10px', 'margin-top': '4px' }}>
          state: <span style={{ color: '#fff' }}>{state().state}</span>
          <span style={{ 'margin-left': '8px' }}>
            speedRatio: {state().speedRatio.toFixed(2)}
          </span>
        </div>
      </Section>

      <Section title="Drive">
        <Slider
          label="demo speed"
          value={demoSpeed()}
          min={0}
          max={12}
          step={0.1}
          onChange={applySpeed}
        />
      </Section>

      <Section title="Tuning">
        <Slider
          label="walkSpeed"
          value={params.walkSpeed}
          min={0.1}
          max={10}
          step={0.1}
          onChange={(v) => push('walkSpeed', v)}
        />
        <Slider
          label="runSpeed"
          value={params.runSpeed}
          min={0.1}
          max={20}
          step={0.1}
          onChange={(v) => push('runSpeed', v)}
        />
        <Slider
          label="blendSpeed"
          value={params.blendSpeed}
          min={0.1}
          max={30}
          step={0.1}
          onChange={(v) => push('blendSpeed', v)}
        />
        <Slider
          label="speedSmoothRate"
          value={params.speedSmoothRate}
          min={0.1}
          max={30}
          step={0.1}
          onChange={(v) => push('speedSmoothRate', v)}
        />
        <Slider
          label="speedThreshold"
          value={params.speedThreshold}
          min={0}
          max={3}
          step={0.05}
          onChange={(v) => push('speedThreshold', v)}
        />
      </Section>

      <ResetButton onClick={reset} />
    </div>
  );
};

Animation.ts

Animation.ts — renderer-agnostic locomotion blend System.

Pure math lives in Animation.core.ts. This System is a thin driver: 1. Listens for SET_SPEED input events keyed by entityId. 2. Each frame, calls the core's update(speed, dt) to get new clip weights + speedRatio. 3. Pushes those through world.renderer.playAnimation, setAnimationWeight, setAnimationSpeed.

It emits STATE_CHANGED when the dominant weight flips (idle→walk→run) and BLEND_UPDATED every frame for HUDs. No @babylonjs / three imports here.

Animation.ts

import { System } from '@babylonjsmarket/ecs';
import type { EventBus } from '@babylonjsmarket/ecs';
import type { Entity } from '@babylonjsmarket/ecs';
import { createAnimation } from './Animation.core';
import { AnimationComponent, AnimationEvents, AnimationInputEvents, type AnimationSetSpeedRequest } from './Animation.defs';

System

Animation.ts

export class AnimationSystem extends System {
  private entitySpeeds = new Map<string, number>();
  /** Entities we've already started playback on this session. */
  private started = new Set<string>();

  constructor(eventBus: EventBus) {
    super(eventBus);
    this.query = { required: [AnimationComponent] };
  }

  protected onInitialize(): void {
    this.eventBus.on(AnimationInputEvents.SET_SPEED, (e: AnimationSetSpeedRequest) => {
      this.entitySpeeds.set(e.entityId, e.speed);
    });

    for (const entity of this.entities) this.ensureInstance(entity);
  }

  protected onEntityAdded(entity: Entity): void {
    this.ensureInstance(entity);
  }

  protected onEntityRemoved(entity: Entity): void {
    const id = (entity as unknown as { id: string }).id;
    const comp = entity.get(AnimationComponent);
    if (comp && this.started.has(id)) {
      const r = this.world?.renderer;
      // Free the adapter's clip-state so re-adding the entity later starts
      // from a clean slate.
      r?.stopAnimation(id, comp.idleClip);
      r?.stopAnimation(id, comp.walkClip);
      r?.stopAnimation(id, comp.runClip);
    }
    this.entitySpeeds.delete(id);
    this.started.delete(id);
  }

  private ensureInstance(entity: Entity): void {
    const comp = entity.get(AnimationComponent);
    if (!comp || comp.instance) return;
    comp.instance = createAnimation(comp.params);
  }

  protected onUpdate(dt: number): void {
    const r = this.world?.renderer;

    for (const entity of this.entities) {
      const id = (entity as unknown as { id: string }).id;
      const comp = entity.get(AnimationComponent);
      if (!comp?.instance) continue;

      // Start the clips once per session so adapter `play` calls aren't
      // repeated every frame (both adapters guard against restart but this
      // keeps the per-frame work minimal).
      if (comp.autoPlay && !this.started.has(id) && r) {
        r.playAnimation(id, comp.idleClip, true);
        r.playAnimation(id, comp.walkClip, true);
        r.playAnimation(id, comp.runClip, true);
        this.started.add(id);
        this.eventBus.emit(AnimationEvents.READY, { entityId: id });
      }

      const speed = this.entitySpeeds.get(id) ?? 0;
      const out = comp.instance.update(speed, dt);

      if (r) {
        r.setAnimationWeight(id, comp.idleClip, out.idleWeight);
        r.setAnimationWeight(id, comp.walkClip, out.walkWeight);
        r.setAnimationWeight(id, comp.runClip, out.runWeight);
        // Idle stays at 1 so its rhythm doesn't tie to locomotion pace.
        r.setAnimationSpeed(id, comp.idleClip, 1);
        r.setAnimationSpeed(id, comp.walkClip, out.speedRatio);
        r.setAnimationSpeed(id, comp.runClip, out.speedRatio);
      }

      comp.lastState = out.state;

      if (out.stateChanged) {
        this.eventBus.emit(AnimationEvents.STATE_CHANGED, {
          entityId: id,
          state: out.state,
        });
      }

      this.eventBus.emit(AnimationEvents.BLEND_UPDATED, {
        entityId: id,
        idleWeight: out.idleWeight,
        walkWeight: out.walkWeight,
        runWeight: out.runWeight,
        speedRatio: out.speedRatio,
      });
    }
  }

  protected onShutdown(): void {
    this.entitySpeeds.clear();
    this.started.clear();
  }
}

The definitions live in Animation.defs.ts; re-exported so existing importers keep working. New code should import them from './Animation.defs' directly.

Animation.ts

export { AnimationComponent, AnimationEvents, type AnimationInput, AnimationInputEvents, type AnimationSetSpeedRequest } from './Animation.defs';

Animation.viz.tsx

Animation.viz.tsx — ECS wrapper that registers the renderer-free Panel with vizStore. The Panel (Animation.panel.tsx) is what Three.js / Babylon demos both mount — this wrapper only exists to wire the Panel's callbacks through the EventBus.

Animation.viz.tsx

import { Component } from '@babylonjsmarket/ecs';
import { System } from '@babylonjsmarket/ecs';
import type { EventBus } from '@babylonjsmarket/ecs';
import type { Entity } from '@babylonjsmarket/ecs';
import { vizStore } from '../_shared/viz';
import { AnimationPanel } from './Animation.panel';
import {
  AnimationComponent,
  AnimationInputEvents,
} from './Animation';
import type { AnimationInstance } from './Animation.core';

export interface AnimationDebuggerInput {
  visible?: boolean;
  activationKey?: string;
  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
  /** Entity id of the Animation target the panel controls. */
  targetEntityId?: string;
}

export class AnimationDebuggerComponent extends Component {
  visible: boolean;
  activationKey: string;
  position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
  targetEntityId: string | null;

  constructor(data: AnimationDebuggerInput = {}) {
    super();
    this.visible = data.visible ?? false;
    this.activationKey = data.activationKey ?? 'Digit1';
    this.position = data.position ?? 'top-right';
    this.targetEntityId = data.targetEntityId ?? null;
  }

  serialize(): AnimationDebuggerInput {
    return {
      visible: this.visible,
      activationKey: this.activationKey,
      position: this.position,
      targetEntityId: this.targetEntityId ?? undefined,
    };
  }
}

const PANEL_ID = 'animation-debugger';

export class AnimationDebuggerSystem extends System {
  private component: AnimationDebuggerComponent | null = null;
  private keydownHandler: ((e: KeyboardEvent) => void) | null = null;
  private panelRegistered = false;

  constructor(eventBus: EventBus) {
    super(eventBus);
    this.query = { required: [AnimationDebuggerComponent] };
    this._pauseable = false;
  }

  protected onInitialize(): void {
    for (const entity of this.entities) {
      const comp = entity.get(AnimationDebuggerComponent);
      if (comp) {
        this.component = comp;
        break;
      }
    }
    this.setupKeyboardListener();
    this.tryRegisterPanel();
  }

  protected onUpdate(_dt: number): void {
    if (!this.panelRegistered) this.tryRegisterPanel();
  }

  private tryRegisterPanel(): void {
    if (this.panelRegistered || !this.component || !this.world) return;

    const found = this.findTarget();
    if (!found) return;
    const { entityId, core } = found;

    vizStore.registerPanel({
      id: PANEL_ID,
      title: 'Animation',
      position: this.component.position,
      titleColor: '#66cc55',
      content: () => (
        <AnimationPanel
          core={core}
          onSpeed={(speed) =>
            this.eventBus.emit(AnimationInputEvents.SET_SPEED, { entityId, speed })
          }
        />
      ),
    });

    this.panelRegistered = true;
    if (this.component.visible) {
      vizStore.showPanel(PANEL_ID);
    }
  }

  private findTarget(): { entityId: string; core: AnimationInstance } | null {
    if (!this.world || !this.component) return null;

    if (this.component.targetEntityId) {
      const entity = this.world.getEntity(this.component.targetEntityId);
      const comp = entity?.get(AnimationComponent);
      if (comp?.instance) {
        return { entityId: this.component.targetEntityId, core: comp.instance };
      }
    }

    for (const entity of this.world.getEntities()) {
      const comp = entity.get(AnimationComponent);
      if (comp?.instance) {
        return {
          entityId: (entity as unknown as { id: string }).id,
          core: comp.instance,
        };
      }
    }
    return null;
  }

  private setupKeyboardListener(): void {
    if (this.keydownHandler) return;
    this.keydownHandler = (e: KeyboardEvent) => {
      if (!this.component) return;
      if (e.code === this.component.activationKey) {
        e.preventDefault();
        vizStore.togglePanel(PANEL_ID);
        this.component.visible = vizStore.isVisible(PANEL_ID);
      }
    };
    window.addEventListener('keydown', this.keydownHandler);
  }

  protected onEntityAdded(entity: Entity): void {
    const comp = entity.get(AnimationDebuggerComponent);
    if (comp && !this.component) {
      this.component = comp;
      this.tryRegisterPanel();
    }
  }

  protected onShutdown(): void {
    vizStore.unregisterPanel(PANEL_ID);
    this.panelRegistered = false;
    if (this.keydownHandler) {
      window.removeEventListener('keydown', this.keydownHandler);
      this.keydownHandler = null;
    }
  }
}

Animation.contract.test.ts

13 ✓

ArcadeECS contract: Animation

Component() with no args constructs and applies defaults
Component merges sample input on top of defaults
Component.serialize() round-trips into a constructor input
System constructor signature is exactly (eventBus)
System declares a non-empty query.required
world.addSystem + initialize + update runs clean with no entity
adding the Component attaches the entity to the System
world.update(dt) does not throw with the entity attached
Adapter handles: create/dispose balance across entity lifecycle
EventBus has no lingering listeners after world.destroy()
Declared event names follow the "{domain}.{action}" convention
Emits at least one declared output event during an update
Registers a listener for each declared input event

Last run 2026-08-22

Animation.contract.test.ts

import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import type { MechanicContractContext } from '@babylonjsmarket/ecs/testing';
import {
  AnimationComponent,
  AnimationSystem,
  AnimationEvents,
  AnimationInputEvents,
} from './Animation';

/**
 * Animation routes SET_SPEED requests by entityId and emits BLEND_UPDATED
 * every frame a matching entity exists. The contract battery creates a
 * fresh entity for its assertions — we hook `world.entity.created` so the
 * most-recently-minted id is always available when `makeInputPayload` runs.
 */
let latestEntityId = 'contract-test';

runMechanicContract({
  name: 'Animation',
  componentClass: AnimationComponent,
  systemClass: AnimationSystem,
  sampleInput: { walkSpeed: 4, runSpeed: 9 },
  events: {
    input: [AnimationInputEvents.SET_SPEED],
    output: [AnimationEvents.BLEND_UPDATED, AnimationEvents.STATE_CHANGED, AnimationEvents.READY],
  },
  setup(ctx: MechanicContractContext) {
    ctx.eventBus.on('world.entity.created', (e: { entity: { id: string } }) => {
      latestEntityId = e.entity.id;
    });
  },
  makeInputPayload(event) {
    if (event === AnimationInputEvents.SET_SPEED) {
      return { entityId: latestEntityId, speed: 5 };
    }
    return {};
  },
});

Animation.core.test.ts

14 ✓

Animation core

starts with full idle weight and zero locomotion weights
stays in idle when speed is below the speedThreshold
blends from idle toward walk as speed crosses the threshold
blends from walk toward run as speed crosses walkSpeed
pins run weight at 1 when speed exceeds runSpeed
emits stateChanged only the frame dominant weight flips
scales speedRatio with movement speed, clamped to [minSpeedRatio, maxSpeedRatio]
speedRatio holds at 1 while the character is idle
same sequence of speed/dt inputs produces the same outputs (deterministic)
setParams updates behavior on the next frame
reset returns params to defaults and collapses back to pure idle
handles a zero walkSpeed config without throwing
pins walk when runSpeed collapses to/below walkSpeed (no run band)
treats negative dt as zero (never unwinds weights)

Last run 2026-08-22

Animation.core.test.ts

import { describe, it, expect } from 'vitest';
import { createAnimation, DEFAULT_ANIMATION_PARAMS } from './Animation.core';

describe('Animation core', () => {
  it('starts with full idle weight and zero locomotion weights', () => {
    const a = createAnimation();
    const s = a.getState();
    expect(s.idleWeight).toBe(1);
    expect(s.walkWeight).toBe(0);
    expect(s.runWeight).toBe(0);
    expect(s.state).toBe('idle');
  });

  it('stays in idle when speed is below the speedThreshold', () => {
    const a = createAnimation({ walkSpeed: 3, runSpeed: 6, speedThreshold: 0.5 });
    // Feed a slow enough speed for long enough that smoothing doesn't matter.
    for (let i = 0; i < 100; i++) a.update(0.2, 1 / 60);
    const out = a.update(0.2, 1 / 60);
    expect(out.state).toBe('idle');
    expect(out.idleWeight).toBeCloseTo(1, 5);
  });

  it('blends from idle toward walk as speed crosses the threshold', () => {
    const a = createAnimation({ walkSpeed: 3, blendSpeed: 8 });
    // Target: halfway between threshold (0.5) and walkSpeed (3).
    const speed = (0.5 + 3) / 2;
    // Run long enough for smoothing + blending to converge.
    for (let i = 0; i < 300; i++) a.update(speed, 1 / 60);
    const out = a.update(speed, 1 / 60);
    expect(out.idleWeight).toBeGreaterThan(0.1);
    expect(out.walkWeight).toBeGreaterThan(0.1);
    // With run not engaged, weights are approximately complementary.
    expect(out.idleWeight + out.walkWeight).toBeCloseTo(1, 3);
  });

  it('blends from walk toward run as speed crosses walkSpeed', () => {
    const a = createAnimation({ walkSpeed: 3, runSpeed: 6, blendSpeed: 8 });
    const speed = 5; // between walk and run
    for (let i = 0; i < 300; i++) a.update(speed, 1 / 60);
    const out = a.update(speed, 1 / 60);
    expect(out.walkWeight).toBeGreaterThan(0.1);
    expect(out.runWeight).toBeGreaterThan(0.1);
    expect(out.idleWeight).toBeCloseTo(0, 2);
  });

  it('pins run weight at 1 when speed exceeds runSpeed', () => {
    const a = createAnimation({ walkSpeed: 3, runSpeed: 6, blendSpeed: 8 });
    for (let i = 0; i < 400; i++) a.update(10, 1 / 60);
    const out = a.update(10, 1 / 60);
    expect(out.runWeight).toBeCloseTo(1, 3);
    expect(out.walkWeight).toBeCloseTo(0, 3);
    expect(out.state).toBe('run');
  });

  it('emits stateChanged only the frame dominant weight flips', () => {
    const a = createAnimation({ walkSpeed: 3, runSpeed: 6, blendSpeed: 50 });
    // Start at idle, then jump to run.
    let sawChange = false;
    for (let i = 0; i < 300; i++) {
      const out = a.update(10, 1 / 60);
      if (out.stateChanged) sawChange = true;
    }
    expect(sawChange).toBe(true);
    // Once we've fully settled on pure run, no further flips.
    let laterFlip = false;
    for (let i = 0; i < 60; i++) {
      const out = a.update(10, 1 / 60);
      if (out.stateChanged) laterFlip = true;
    }
    expect(laterFlip).toBe(false);
  });

  it('scales speedRatio with movement speed, clamped to [minSpeedRatio, maxSpeedRatio]', () => {
    const a = createAnimation({
      walkSpeed: 3,
      runSpeed: 6,
      minSpeedRatio: 0.5,
      maxSpeedRatio: 3,
    });
    // Absurdly high speed — ratio must still clamp.
    for (let i = 0; i < 400; i++) a.update(1000, 1 / 60);
    const out = a.update(1000, 1 / 60);
    expect(out.speedRatio).toBeLessThanOrEqual(3);
    expect(out.speedRatio).toBeGreaterThanOrEqual(0.5);
  });

  it('speedRatio holds at 1 while the character is idle', () => {
    const a = createAnimation();
    // Let smoothed speed sit below threshold.
    for (let i = 0; i < 60; i++) a.update(0, 1 / 60);
    const out = a.update(0, 1 / 60);
    expect(out.speedRatio).toBeCloseTo(1, 5);
  });

  it('same sequence of speed/dt inputs produces the same outputs (deterministic)', () => {
    const a = createAnimation({ walkSpeed: 3, runSpeed: 6 });
    const b = createAnimation({ walkSpeed: 3, runSpeed: 6 });
    const script = [0, 1, 2, 4, 8, 5, 2, 0.3, 0, 0];
    let la = a.update(0, 0);
    let lb = b.update(0, 0);
    for (const speed of script) {
      la = a.update(speed, 0.1);
      lb = b.update(speed, 0.1);
      expect(la).toEqual(lb);
    }
  });

  it('setParams updates behavior on the next frame', () => {
    const a = createAnimation({ walkSpeed: 3, runSpeed: 6, blendSpeed: 8 });
    for (let i = 0; i < 300; i++) a.update(4, 1 / 60);
    // At speed 4, we're in walk->run; walkWeight should dominate.
    const before = a.update(4, 1 / 60);
    expect(before.walkWeight).toBeGreaterThan(before.runWeight);
    // Shrink runSpeed so 4 now sits above the run cutoff.
    a.setParams({ runSpeed: 3.5 });
    for (let i = 0; i < 300; i++) a.update(4, 1 / 60);
    const after = a.update(4, 1 / 60);
    expect(after.runWeight).toBeGreaterThan(after.walkWeight);
  });

  it('reset returns params to defaults and collapses back to pure idle', () => {
    const a = createAnimation({ walkSpeed: 3, runSpeed: 6 });
    for (let i = 0; i < 100; i++) a.update(10, 1 / 60);
    a.reset();
    expect(a.getParams()).toEqual(DEFAULT_ANIMATION_PARAMS);
    const s = a.getState();
    expect(s.idleWeight).toBe(1);
    expect(s.walkWeight).toBe(0);
    expect(s.runWeight).toBe(0);
    expect(s.state).toBe('idle');
  });

  it('handles a zero walkSpeed config without throwing', () => {
    const a = createAnimation({ walkSpeed: 0, runSpeed: 0, speedThreshold: 0.5 });
    expect(() => {
      for (let i = 0; i < 10; i++) a.update(2, 1 / 60);
    }).not.toThrow();
  });

  it('pins walk when runSpeed collapses to/below walkSpeed (no run band)', () => {
    // walkSpeed (3) is a real band above the threshold, but runSpeed (2) sits
    // at-or-below it, so there is no meaningful run band: any speed past
    // walkSpeed must settle on pure walk, never run.
    const a = createAnimation({
      walkSpeed: 3,
      runSpeed: 2,
      speedThreshold: 0.5,
      blendSpeed: 50,
    });
    for (let i = 0; i < 400; i++) a.update(5, 1 / 60);
    const out = a.update(5, 1 / 60);
    expect(out.walkWeight).toBeCloseTo(1, 3);
    expect(out.runWeight).toBeCloseTo(0, 3);
    expect(out.idleWeight).toBeCloseTo(0, 3);
    expect(out.state).toBe('walk');
  });

  it('treats negative dt as zero (never unwinds weights)', () => {
    const a = createAnimation();
    const before = a.getState();
    const out = a.update(5, -0.1);
    expect(out.idleWeight).toBe(before.idleWeight);
    expect(out.walkWeight).toBe(before.walkWeight);
    expect(out.runWeight).toBe(before.runWeight);
  });
});

Animation.panel.test.tsx

6 ✓

AnimationPanel (renderer-free)

mounts against a stub core and shows the blend sections
moving a tuning slider calls core.setParams with the new value
the demo speed slider calls onSpeed when supplied
each tuning slider forwards its own param key into the core
Reset also zeroes the demo speed through onSpeed when supplied
the Reset button clears core params back to defaults

Last run 2026-08-22

Animation.panel.test.tsx

// @vitest-environment jsdom
import { describe, it, expect, vi } from 'vitest';
import { render, fireEvent } from '@solidjs/testing-library';
import { AnimationPanel } from './Animation.panel';
import { createAnimation } from './Animation.core';

describe('AnimationPanel (renderer-free)', () => {
  it('mounts against a stub core and shows the blend sections', () => {
    const core = createAnimation();
    const { container } = render(() => <AnimationPanel core={core} />);
    expect(container.textContent).toContain('Blend');
    expect(container.textContent).toContain('idle');
    expect(container.textContent).toContain('walk');
    expect(container.textContent).toContain('run');
    expect(container.textContent).toContain('Tuning');
  });

  it('moving a tuning slider calls core.setParams with the new value', () => {
    const core = createAnimation();
    const spy = vi.spyOn(core, 'setParams');
    const { getAllByRole } = render(() => <AnimationPanel core={core} />);
    const sliders = getAllByRole('slider') as HTMLInputElement[];
    // The first slider is demo speed, the next one is walkSpeed.
    const walkSpeedSlider = sliders[1];
    fireEvent.input(walkSpeedSlider, { target: { value: '4.5' } });
    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ walkSpeed: 4.5 }));
  });

  it('the demo speed slider calls onSpeed when supplied', () => {
    const core = createAnimation();
    const onSpeed = vi.fn();
    const { getAllByRole } = render(() => <AnimationPanel core={core} onSpeed={onSpeed} />);
    const sliders = getAllByRole('slider') as HTMLInputElement[];
    const speedSlider = sliders[0];
    fireEvent.input(speedSlider, { target: { value: '5' } });
    expect(onSpeed).toHaveBeenCalledWith(5);
  });

  it('each tuning slider forwards its own param key into the core', () => {
    const core = createAnimation();
    const spy = vi.spyOn(core, 'setParams');
    const { getAllByRole } = render(() => <AnimationPanel core={core} />);
    const sliders = getAllByRole('slider') as HTMLInputElement[];
    // [0]=demo speed, [1]=walkSpeed, [2]=runSpeed, [3]=blendSpeed,
    // [4]=speedSmoothRate, [5]=speedThreshold.
    fireEvent.input(sliders[2], { target: { value: '12' } });
    fireEvent.input(sliders[3], { target: { value: '20' } });
    fireEvent.input(sliders[4], { target: { value: '15' } });
    fireEvent.input(sliders[5], { target: { value: '1.2' } });

    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ runSpeed: 12 }));
    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ blendSpeed: 20 }));
    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ speedSmoothRate: 15 }));
    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ speedThreshold: 1.2 }));
    // The live core actually picked up the new tuning, not just the spy.
    expect(core.getParams().runSpeed).toBe(12);
    expect(core.getParams().speedThreshold).toBe(1.2);
  });

  it('Reset also zeroes the demo speed through onSpeed when supplied', () => {
    const core = createAnimation({ walkSpeed: 10 });
    const onSpeed = vi.fn();
    const resetSpy = vi.spyOn(core, 'reset');
    const { getByText, getAllByRole } = render(() => (
      <AnimationPanel core={core} onSpeed={onSpeed} />
    ));
    // Drive the demo speed up first so the reset-to-zero is observable.
    fireEvent.input((getAllByRole('slider') as HTMLInputElement[])[0], {
      target: { value: '7' },
    });
    onSpeed.mockClear();

    fireEvent.click(getByText(/reset/i));
    expect(resetSpy).toHaveBeenCalled();
    expect(onSpeed).toHaveBeenCalledWith(0);
  });

  it('the Reset button clears core params back to defaults', () => {
    const core = createAnimation({ walkSpeed: 10 });
    const spy = vi.spyOn(core, 'setParams');
    const { getByText } = render(() => <AnimationPanel core={core} />);
    fireEvent.click(getByText(/reset/i));
    expect(spy).toHaveBeenCalled();
  });
});

Animation.test.ts

12 ✓

AnimationComponent

applies defaults
accepts custom clip names and params
serialize round-trips through the constructor

AnimationSystem

creates a core instance when an entity with AnimationComponent is added
on first update, plays all three clips once via the adapter
does NOT replay clips on the second frame — play is idempotent per session
pushes updated weights through setAnimationWeight every frame
ramps walk weight up when SET_SPEED pushes speed above the threshold
emits STATE_CHANGED when the dominant state flips
emits BLEND_UPDATED with live weights every frame
stops clips via the adapter when the entity is removed
does not call play when autoPlay is false

Last run 2026-08-22

Animation.test.ts

import { describe, it, expect, beforeEach, vi } from 'vitest';
import {
  AnimationComponent,
  AnimationSystem,
  AnimationEvents,
  AnimationInputEvents,
} from './Animation';
import { DEFAULT_ANIMATION_PARAMS } from './Animation.core';
import { EventBus, World } from '@babylonjsmarket/ecs';
import { MockRendererAdapter } from '@babylonjsmarket/ecs';

describe('AnimationComponent', () => {
  it('applies defaults', () => {
    const comp = new AnimationComponent();
    expect(comp.params).toEqual(DEFAULT_ANIMATION_PARAMS);
    expect(comp.idleClip).toBe('IDLE_RIFLE');
    expect(comp.walkClip).toBe('WALK_RIFLE');
    expect(comp.runClip).toBe('RUN_RIFLE');
    expect(comp.autoPlay).toBe(true);
    expect(comp.instance).toBeNull();
  });

  it('accepts custom clip names and params', () => {
    const comp = new AnimationComponent({
      idleClip: 'stand',
      walkClip: 'stroll',
      runClip: 'sprint',
      walkSpeed: 2,
      runSpeed: 5,
      autoPlay: false,
    });
    expect(comp.idleClip).toBe('stand');
    expect(comp.runClip).toBe('sprint');
    expect(comp.params.walkSpeed).toBe(2);
    expect(comp.params.runSpeed).toBe(5);
    expect(comp.autoPlay).toBe(false);
  });

  it('serialize round-trips through the constructor', () => {
    const original = new AnimationComponent({
      idleClip: 'A',
      walkClip: 'B',
      runClip: 'C',
      walkSpeed: 4,
      runSpeed: 9,
      blendSpeed: 12,
      autoPlay: false,
    });
    const copy = new AnimationComponent(original.serialize());
    expect(copy.params).toEqual(original.params);
    expect(copy.idleClip).toBe(original.idleClip);
    expect(copy.walkClip).toBe(original.walkClip);
    expect(copy.runClip).toBe(original.runClip);
    expect(copy.autoPlay).toBe(original.autoPlay);
  });
});

describe('AnimationSystem', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  let system: AnimationSystem;

  beforeEach(() => {
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer, detectRaces: false });
    system = new AnimationSystem(eventBus);
    world.addSystem(system);
    world.initialize();
  });

  it('creates a core instance when an entity with AnimationComponent is added', () => {
    const entity = world.createEntity();
    entity.add(new AnimationComponent({ walkSpeed: 2, runSpeed: 5 }));
    const comp = entity.get(AnimationComponent);
    expect(comp?.instance).not.toBeNull();
    expect(comp?.instance?.getParams().walkSpeed).toBe(2);
  });

  it('on first update, plays all three clips once via the adapter', () => {
    const entity = world.createEntity();
    entity.add(new AnimationComponent());
    world.update(1 / 60);
    const playCalls = renderer.calls.filter((c) => c.method === 'playAnimation');
    expect(playCalls).toHaveLength(3);
    const clipNames = playCalls.map((c) => c.args[1]);
    expect(clipNames).toEqual(
      expect.arrayContaining(['IDLE_RIFLE', 'WALK_RIFLE', 'RUN_RIFLE']),
    );
  });

  it('does NOT replay clips on the second frame — play is idempotent per session', () => {
    const entity = world.createEntity();
    entity.add(new AnimationComponent());
    world.update(1 / 60);
    const initialPlayCount = renderer.calls.filter(
      (c) => c.method === 'playAnimation',
    ).length;
    world.update(1 / 60);
    const laterPlayCount = renderer.calls.filter(
      (c) => c.method === 'playAnimation',
    ).length;
    expect(laterPlayCount).toBe(initialPlayCount);
  });

  it('pushes updated weights through setAnimationWeight every frame', () => {
    const entity = world.createEntity();
    entity.add(new AnimationComponent());
    world.update(1 / 60);
    const weightCalls = renderer.calls.filter(
      (c) => c.method === 'setAnimationWeight',
    );
    // One per clip (3) per frame, 1 frame → 3 calls.
    expect(weightCalls).toHaveLength(3);
  });

  it('ramps walk weight up when SET_SPEED pushes speed above the threshold', () => {
    const entity = world.createEntity();
    entity.add(new AnimationComponent({ walkSpeed: 3, blendSpeed: 50 }));
    // Tell the system we're walking.
    eventBus.emit(AnimationInputEvents.SET_SPEED, { entityId: entity.id, speed: 3 });
    // Run enough frames for smoothing + blending to converge.
    for (let i = 0; i < 300; i++) world.update(1 / 60);
    const comp = entity.get(AnimationComponent)!;
    const s = comp.instance!.getState();
    expect(s.walkWeight).toBeGreaterThan(0.5);
    expect(s.idleWeight).toBeLessThan(0.5);
  });

  it('emits STATE_CHANGED when the dominant state flips', () => {
    const entity = world.createEntity();
    entity.add(new AnimationComponent({ walkSpeed: 3, blendSpeed: 50 }));
    const spy = vi.fn();
    eventBus.on(AnimationEvents.STATE_CHANGED, spy);
    eventBus.emit(AnimationInputEvents.SET_SPEED, { entityId: entity.id, speed: 10 });
    for (let i = 0; i < 120; i++) world.update(1 / 60);
    expect(spy).toHaveBeenCalled();
    const lastCall = spy.mock.calls[spy.mock.calls.length - 1]![0];
    expect(lastCall).toMatchObject({ entityId: entity.id });
    expect(['walk', 'run']).toContain(lastCall.state);
  });

  it('emits BLEND_UPDATED with live weights every frame', () => {
    const entity = world.createEntity();
    entity.add(new AnimationComponent());
    const spy = vi.fn();
    eventBus.on(AnimationEvents.BLEND_UPDATED, spy);
    world.update(1 / 60);
    world.update(1 / 60);
    expect(spy).toHaveBeenCalledTimes(2);
    const payload = spy.mock.calls[0][0];
    expect(payload).toMatchObject({ entityId: entity.id });
    expect(typeof payload.idleWeight).toBe('number');
  });

  it('stops clips via the adapter when the entity is removed', () => {
    const entity = world.createEntity();
    entity.add(new AnimationComponent());
    world.update(1 / 60); // play
    renderer.calls.length = 0;
    world.removeEntity(entity.id);
    const stopCalls = renderer.calls.filter((c) => c.method === 'stopAnimation');
    expect(stopCalls).toHaveLength(3);
  });

  it('does not call play when autoPlay is false', () => {
    const entity = world.createEntity();
    entity.add(new AnimationComponent({ autoPlay: false }));
    world.update(1 / 60);
    const playCalls = renderer.calls.filter((c) => c.method === 'playAnimation');
    expect(playCalls).toHaveLength(0);
  });
});

Animation.viz.test.tsx

16 ✓

AnimationDebuggerComponent

applies defaults
honors supplied input
serialize round-trips through the constructor
serialize maps a null target back to undefined

AnimationDebuggerSystem

registers the panel once a live Animation target exists
shows the panel immediately when the component starts visible
defers registration until a target appears, then registers on update
adopts a debugger component added after initialize
ignores a second debugger component once one is adopted
prefers the explicit targetEntityId when resolving the core
falls back to scanning for any Animation core when the named target is missing
does not register when a target entity has no live core
toggles the panel on the activation key and mirrors visibility back
ignores key presses that are not the activation key
a key press before any debugger is adopted is a no-op
cleans up the panel and keyboard listener on shutdown

Last run 2026-08-22

Animation.viz.test.tsx

// @vitest-environment jsdom
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { render, fireEvent } from '@solidjs/testing-library';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import { vizStore } from '../_shared/viz';
import {
  AnimationDebuggerComponent,
  AnimationDebuggerSystem,
} from './Animation.viz';
import { AnimationComponent, AnimationInputEvents } from './Animation';
import { createAnimation } from './Animation.core';

const PANEL_ID = 'animation-debugger';

// Track every world so afterEach can shut it down — the DebuggerSystem adds a
// window keydown listener in onInitialize that only onShutdown removes, and a
// leaked listener from a prior test would fire on a later dispatch.
const liveWorlds: World[] = [];

function makeWorld() {
  const eventBus = new EventBus();
  const renderer = new MockRendererAdapter();
  const world = new World({ eventBus, renderer, detectRaces: false });
  liveWorlds.push(world);
  return { eventBus, world };
}

/** Mint an entity that actually carries a live AnimationComponent core. */
function addAnimationTarget(world: World, id?: string) {
  const entity = world.createEntity(id);
  const comp = new AnimationComponent();
  comp.instance = createAnimation();
  entity.add(comp);
  return entity;
}

describe('AnimationDebuggerComponent', () => {
  it('applies defaults', () => {
    const c = new AnimationDebuggerComponent();
    expect(c.visible).toBe(false);
    expect(c.activationKey).toBe('Digit1');
    expect(c.position).toBe('top-right');
    expect(c.targetEntityId).toBeNull();
  });

  it('honors supplied input', () => {
    const c = new AnimationDebuggerComponent({
      visible: true,
      activationKey: 'Digit5',
      position: 'bottom-left',
      targetEntityId: 'hero',
    });
    expect(c.visible).toBe(true);
    expect(c.activationKey).toBe('Digit5');
    expect(c.position).toBe('bottom-left');
    expect(c.targetEntityId).toBe('hero');
  });

  it('serialize round-trips through the constructor', () => {
    const original = new AnimationDebuggerComponent({
      visible: true,
      activationKey: 'Digit3',
      position: 'bottom-right',
      targetEntityId: 'npc',
    });
    const copy = new AnimationDebuggerComponent(original.serialize());
    expect(copy.serialize()).toEqual(original.serialize());
  });

  it('serialize maps a null target back to undefined', () => {
    const c = new AnimationDebuggerComponent();
    expect(c.serialize().targetEntityId).toBeUndefined();
  });
});

describe('AnimationDebuggerSystem', () => {
  beforeEach(() => {
    vizStore.clear();
    localStorage.clear();
  });

  afterEach(() => {
    // Drain every world built this test so its keydown listener is removed.
    while (liveWorlds.length) {
      const w = liveWorlds.pop();
      try {
        w?.shutdown();
      } catch {
        // already torn down
      }
    }
    vizStore.clear();
  });

  it('registers the panel once a live Animation target exists', () => {
    const { eventBus, world } = makeWorld();
    const target = addAnimationTarget(world);
    world.addSystem(new AnimationDebuggerSystem(eventBus));
    world.createEntity().add(new AnimationDebuggerComponent());
    world.initialize();

    expect(vizStore.panels[PANEL_ID]).toBeDefined();
    expect(vizStore.panels[PANEL_ID].title).toBe('Animation');
    expect(vizStore.isVisible(PANEL_ID)).toBe(false);
    expect(target.id).toBeTruthy();
  });

  it('shows the panel immediately when the component starts visible', () => {
    const { eventBus, world } = makeWorld();
    addAnimationTarget(world);
    world.addSystem(new AnimationDebuggerSystem(eventBus));
    world.createEntity().add(new AnimationDebuggerComponent({ visible: true }));
    world.initialize();

    expect(vizStore.isVisible(PANEL_ID)).toBe(true);
  });

  it('defers registration until a target appears, then registers on update', () => {
    const { eventBus, world } = makeWorld();
    world.addSystem(new AnimationDebuggerSystem(eventBus));
    world.createEntity().add(new AnimationDebuggerComponent());
    world.initialize();
    // No Animation target yet — nothing to register.
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();

    addAnimationTarget(world);
    world.update(1 / 60);
    expect(vizStore.panels[PANEL_ID]).toBeDefined();

    // A second update must not re-register (panelRegistered guards it).
    const first = vizStore.panels[PANEL_ID];
    world.update(1 / 60);
    expect(vizStore.panels[PANEL_ID]).toBe(first);
  });

  it('adopts a debugger component added after initialize', () => {
    const { eventBus, world } = makeWorld();
    addAnimationTarget(world);
    world.addSystem(new AnimationDebuggerSystem(eventBus));
    world.initialize();
    // onInitialize found no debugger component, so nothing registered.
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();

    world.createEntity().add(new AnimationDebuggerComponent());
    // onEntityAdded should adopt it and register immediately.
    expect(vizStore.panels[PANEL_ID]).toBeDefined();
  });

  it('ignores a second debugger component once one is adopted', () => {
    const { eventBus, world } = makeWorld();
    addAnimationTarget(world);
    world.addSystem(new AnimationDebuggerSystem(eventBus));
    world.createEntity().add(new AnimationDebuggerComponent({ position: 'top-left' }));
    world.initialize();

    const registered = vizStore.panels[PANEL_ID];
    expect(registered.position).toBe('top-left');

    // Adding a second debugger must not steal the slot or re-register.
    world.createEntity().add(new AnimationDebuggerComponent({ position: 'bottom-right' }));
    expect(vizStore.panels[PANEL_ID]).toBe(registered);
    expect(vizStore.panels[PANEL_ID].position).toBe('top-left');
  });

  it('prefers the explicit targetEntityId when resolving the core', () => {
    const { eventBus, world } = makeWorld();
    // Two candidates; the panel must bind to the named one.
    addAnimationTarget(world, 'other');
    const hero = addAnimationTarget(world, 'hero');
    world.addSystem(new AnimationDebuggerSystem(eventBus));
    world.createEntity().add(new AnimationDebuggerComponent({ targetEntityId: 'hero' }));
    world.initialize();

    expect(vizStore.panels[PANEL_ID]).toBeDefined();

    // Render the panel content and drive its onSpeed to confirm it's wired to hero.
    const speedSpy = vi.fn();
    eventBus.on(AnimationInputEvents.SET_SPEED, speedSpy);
    const { getAllByRole } = render(() => vizStore.panels[PANEL_ID].content());
    const slider = getAllByRole('slider')[0] as HTMLInputElement;
    fireEvent.input(slider, { target: { value: '4' } });

    expect(speedSpy).toHaveBeenCalledWith(
      expect.objectContaining({ entityId: 'hero', speed: 4 }),
    );
  });

  it('falls back to scanning for any Animation core when the named target is missing', () => {
    const { eventBus, world } = makeWorld();
    addAnimationTarget(world, 'present');
    world.addSystem(new AnimationDebuggerSystem(eventBus));
    // targetEntityId points at an entity that does not exist.
    world.createEntity().add(new AnimationDebuggerComponent({ targetEntityId: 'ghost' }));
    world.initialize();

    // Scan fallback should still find 'present' and register.
    expect(vizStore.panels[PANEL_ID]).toBeDefined();
  });

  it('does not register when a target entity has no live core', () => {
    const { eventBus, world } = makeWorld();
    // AnimationComponent present but instance never populated → no core.
    world.createEntity().add(new AnimationComponent());
    world.addSystem(new AnimationDebuggerSystem(eventBus));
    world.createEntity().add(new AnimationDebuggerComponent());
    world.initialize();

    expect(vizStore.panels[PANEL_ID]).toBeUndefined();
  });

  it('toggles the panel on the activation key and mirrors visibility back', () => {
    const { eventBus, world } = makeWorld();
    addAnimationTarget(world);
    world.addSystem(new AnimationDebuggerSystem(eventBus));
    const dbg = new AnimationDebuggerComponent({ activationKey: 'Digit2' });
    world.createEntity().add(dbg);
    world.initialize();

    expect(vizStore.isVisible(PANEL_ID)).toBe(false);

    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'Digit2' }));
    expect(vizStore.isVisible(PANEL_ID)).toBe(true);
    expect(dbg.visible).toBe(true);

    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'Digit2' }));
    expect(vizStore.isVisible(PANEL_ID)).toBe(false);
    expect(dbg.visible).toBe(false);
  });

  it('ignores key presses that are not the activation key', () => {
    const { eventBus, world } = makeWorld();
    addAnimationTarget(world);
    world.addSystem(new AnimationDebuggerSystem(eventBus));
    world.createEntity().add(new AnimationDebuggerComponent({ activationKey: 'Digit2' }));
    world.initialize();

    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'Digit9' }));
    expect(vizStore.isVisible(PANEL_ID)).toBe(false);
  });

  it('a key press before any debugger is adopted is a no-op', () => {
    const { eventBus, world } = makeWorld();
    // System present, keyboard listener installed, but no component adopted yet.
    const system = new AnimationDebuggerSystem(eventBus);
    world.addSystem(system);
    world.initialize();

    expect(() =>
      window.dispatchEvent(new KeyboardEvent('keydown', { code: 'Digit1' })),
    ).not.toThrow();
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();
  });

  it('cleans up the panel and keyboard listener on shutdown', () => {
    const { eventBus, world } = makeWorld();
    addAnimationTarget(world);
    const system = new AnimationDebuggerSystem(eventBus);
    world.addSystem(system);
    const dbg = new AnimationDebuggerComponent({ activationKey: 'Digit4' });
    world.createEntity().add(dbg);
    world.initialize();
    expect(vizStore.panels[PANEL_ID]).toBeDefined();

    world.shutdown();
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();

    // The keydown listener was removed, so toggling no longer re-registers.
    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'Digit4' }));
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();
  });
});