@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/animation/AnimationGraphController.js

@@ -1,518 +1,518 @@
-import { assert } from "../../../core/assert.js";
-import { AnimationClipFlag } from "../../graphics/ecs/animation/animator/AnimationClipFlag.js";
-import { AnimationState } from "../../graphics/ecs/animation/animator/graph/AnimationState.js";
-import { AnimationStateType } from "../../graphics/ecs/animation/animator/graph/AnimationStateType.js";
-import { AnimationTransition } from "../../graphics/ecs/animation/animator/graph/AnimationTransition.js";
-import { wrap_clip_time } from "./wrap_clip_time.js";
-
-/**
- * One entity's animation state machine: which state it is in, which transitions are running, what
- * each clip therefore weighs, and — the part the GPU cannot own — what time each of those clips is
- * playing at.
- *
- * **The clock is here and not on the GPU**, and I-4 is what forces it. Shade advances clip time
- * itself in its tick shader, but the time gameplay reads has to be the time the picture is drawn
- * from: notifications fire at authored moments off this clock, and the CPU pose evaluator answers
- * socket queries from it. Two clocks drift, so there is one, and {@link AnimationGraphSystem3}
- * writes it down to the renderer with `set_time` rather than letting the GPU advance anything.
- *
- * The state machine itself is not new — `AnimationState`, `AnimationTransition`, `BlendStateMatrix`
- * and the graph definitions are reused as they stand. What is not reused is the three-only half of
- * the legacy `AnimationGraph`: an `AnimationMixer`, the per-clip `AnimationAction`s it owns, and
- * writing weights onto them.
- */
-export class AnimationGraphController {
-    /**
-     * @type {AnimationGraphDefinition}
-     */
-    def = null;
-
-    /**
-     * @type {AnimationState[]}
-     */
-    states = [];
-
-    /**
-     * @type {AnimationTransition[]}
-     */
-    transitions = [];
-
-    /**
-     * The state the graph is in. During a transition this is already the target — the source stays
-     * in {@link simulatedStates} until the transition finishes.
-     *
-     * @type {AnimationState}
-     */
-    state = null;
-
-    /**
-     * @type {AnimationTransition[]}
-     */
-    activeTransitions = [];
-
-    /**
-     * Every state whose clock is running: the current one, plus the sources of transitions that
-     * have not finished.
-     *
-     * @type {AnimationState[]}
-     */
-    simulatedStates = [];
-
-    /**
-     * Per-clip weights and time scales, in `def.clipIndex` order. The weights are what reaches the
-     * GPU; the time scales are consumed here, by {@link AnimationState#tick}, and have no GPU
-     * counterpart because the time they scale is already integrated into the state's clock.
-     *
-     * @type {BlendStateMatrix}
-     */
-    blendState = null;
-
-    /**
-     * Where in its starting clip the graph begins, as a fraction of that clip's duration.
-     *
-     * A fraction rather than a time because a clip's duration comes from the model and the model
-     * loads long after the entity does. Its purpose is to keep identical units from moving in
-     * lockstep, and it is applied once, at {@link link}, without dispatching the notifications it
-     * skips over — a unit that spawns mid-stride should not also spawn the footstep it missed.
-     *
-     * @type {number}
-     */
-    start_phase = 0;
-
-    /**
-     * The dataset this graph fires its notifications into.
-     *
-     * **Public, and named with the leading underscores, because `AnimationState.tick` reads it off
-     * the graph by exactly that name.** The state classes are reused as they stand, so this is
-     * their interface rather than an accident of style.
-     *
-     * @type {EntityComponentDataset}
-     */
-    __dataset = null;
-
-    /**
-     * The entity those notifications are addressed to. Read by `AnimationState.tick` — see
-     * {@link __dataset}.
-     *
-     * @type {number}
-     */
-    __entity = -1;
-
-    /**
-     * @type {boolean}
-     */
-    #linked = false;
-
-    /**
-     * Playback time of each clip, in `def.clipIndex` order, already wrapped or clamped into the
-     * clip's own duration — which is what the renderer's clip record wants, and what a pose query
-     * has to agree with.
-     *
-     * @type {Float64Array}
-     */
-    #clip_times = new Float64Array(0);
-
-    /**
-     * @returns {boolean}
-     */
-    get linked() {
-        return this.#linked;
-    }
-
-    /**
-     * Build the runtime graph — one {@link AnimationState} per state definition, one
-     * {@link AnimationTransition} per transition definition, wired to each other.
-     *
-     * @param {AnimationGraphDefinition} def
-     */
-    initialize(def) {
-        assert.defined(def, 'def');
-        assert.equal(this.#linked, false, 'graph is linked');
-
-        this.def = def;
-
-        this.blendState = def.createBlendState();
-        this.#clip_times = new Float64Array(def.clipIndex.length);
-
-        const state_definitions = def.states;
-        const state_count = state_definitions.length;
-
-        this.states = [];
-
-        for (let i = 0; i < state_count; i++) {
-            const state = new AnimationState();
-
-            state.def = state_definitions[i];
-            state.graph = this;
-
-            this.states[i] = state;
-        }
-
-        const transition_definitions = def.transitions;
-        const transition_count = transition_definitions.length;
-
-        this.transitions = [];
-
-        for (let i = 0; i < transition_count; i++) {
-            const transition = new AnimationTransition();
-
-            transition.def = transition_definitions[i];
-            transition.graph = this;
-
-            this.transitions[i] = transition;
-        }
-
-        this.state = this.state_by_definition(def.startingSate);
-
-        for (let i = 0; i < transition_count; i++) {
-            const transition = this.transitions[i];
-
-            transition.source = this.state_by_definition(transition.def.source);
-            transition.target = this.state_by_definition(transition.def.target);
-
-            transition.initialize();
-        }
-
-        for (let i = 0; i < state_count; i++) {
-            const state = this.states[i];
-
-            state.inEdges = state.def.inEdges.map(this.transition_by_definition, this);
-            state.outEdges = state.def.outEdges.map(this.transition_by_definition, this);
-
-            state.initialize();
-        }
-    }
-
-    /**
-     * @param {AnimationStateDefinition} definition
-     * @returns {AnimationState|undefined}
-     */
-    state_by_definition(definition) {
-        assert.defined(definition, 'definition');
-
-        const states = this.states;
-
-        for (let i = 0; i < states.length; i++) {
-            if (states[i].def === definition) {
-                return states[i];
-            }
-        }
-
-        return undefined;
-    }
-
-    /**
-     * @param {string} name
-     * @returns {AnimationState|undefined}
-     */
-    state_by_name(name) {
-        const states = this.states;
-
-        for (let i = 0; i < states.length; i++) {
-            if (states[i].def.name === name) {
-                return states[i];
-            }
-        }
-
-        return undefined;
-    }
-
-    /**
-     * @param {string} name name of the clip the state plays
-     * @returns {AnimationState|undefined}
-     */
-    state_by_clip_name(name) {
-        const states = this.states;
-
-        for (let i = 0; i < states.length; i++) {
-            const definition = states[i].def;
-
-            if (definition.type !== AnimationStateType.Clip) {
-                continue;
-            }
-
-            if (definition.motion.def.name === name) {
-                return states[i];
-            }
-        }
-
-        return undefined;
-    }
-
-    /**
-     * @param {AnimationTransitionDefinition} definition
-     * @returns {AnimationTransition|undefined}
-     */
-    transition_by_definition(definition) {
-        const transitions = this.transitions;
-
-        for (let i = 0; i < transitions.length; i++) {
-            if (transitions[i].def === definition) {
-                return transitions[i];
-            }
-        }
-
-        return undefined;
-    }
-
-    /**
-     * Start the graph: take the clip durations the model turned out to have, enter the starting
-     * state, and begin listening for the events its transitions fire on.
-     *
-     * **Durations arrive here rather than at construction** because they are the model's and not
-     * the graph's — `animation-graph.json` names clips, the `.glb` says how long they are — and the
-     * notification path needs them to be right before a single frame is ticked. They are written
-     * onto the shared clip definitions, which is where {@link AnimationClip} reads them.
-     *
-     * @param {number} entity
-     * @param {EntityComponentDataset} ecd
-     * @param {ArrayLike<number>} durations seconds, one per `def.clipIndex` entry, in that order
-     */
-    link(entity, ecd, durations) {
-        assert.isNonNegativeInteger(entity, 'entity');
-        assert.defined(ecd, 'ecd');
-        assert.equal(this.#linked, false, 'graph is already linked, call unlink first');
-
-        const clip_index = this.def.clipIndex;
-
-        assert.equal(durations.length, clip_index.length, 'durations.length');
-
-        for (let i = 0; i < clip_index.length; i++) {
-            clip_index[i].duration = durations[i];
-        }
-
-        this.__entity = entity;
-        this.__dataset = ecd;
-
-        this.#linked = true;
-
-        this.enter_state(this.state);
-
-        this.state.time = this.start_phase * this.#state_clip_duration(this.state);
-
-        this.update_blend_state();
-    }
-
-    /**
-     * Stop listening. The graph keeps the state it was in, so a re-link resumes rather than
-     * restarts.
-     */
-    unlink() {
-        if (!this.#linked) {
-            return;
-        }
-
-        this.exit_state(this.state);
-
-        this.#linked = false;
-    }
-
-    /**
-     * Advance every running clock by `time_delta`, fire whatever notifications were crossed, and
-     * recompute the blend.
-     *
-     * Unconditional by design: §2.6-2's split puts pose evaluation and its events on the CPU
-     * precisely so that camera framing cannot decide whether a projectile spawns. The screen-area
-     * cull the legacy system applied has no counterpart here.
-     *
-     * @param {number} time_delta in seconds
-     */
-    tick(time_delta) {
-        assert.equal(this.#linked, true, 'graph is not linked');
-
-        const active_transitions = this.activeTransitions;
-
-        let transition_count = active_transitions.length;
-
-        transitions: for (let i = 0; i < transition_count; i++) {
-            const active = active_transitions[i];
-
-            active.tick(time_delta);
-
-            if (!active.isFinished()) {
-                continue;
-            }
-
-            active_transitions.splice(i, 1);
-
-            transition_count--;
-            i--;
-
-            for (let j = 0; j < transition_count; j++) {
-                const other = active_transitions[j];
-
-                if (other.source === active.source || other.target === active.source) {
-                    // the state it came from is still in use by another transition
-                    continue transitions;
-                }
-            }
-
-            this.stop_state_simulation(active.source);
-        }
-
-        const simulated = this.simulatedStates;
-
-        for (let i = 0; i < simulated.length; i++) {
-            simulated[i].tick(time_delta);
-        }
-
-        this.update_blend_state();
-    }
-
-    /**
-     * @param {AnimationState} state
-     * @returns {boolean} `false` when the state was not being simulated
-     */
-    stop_state_simulation(state) {
-        const i = this.simulatedStates.indexOf(state);
-
-        if (i === -1) {
-            return false;
-        }
-
-        this.simulatedStates.splice(i, 1);
-
-        return true;
-    }
-
-    /**
-     * Recompute per-clip weights from the states and transitions that are running, and the time
-     * each of those clips is at.
-     */
-    update_blend_state() {
-        const simulated = this.simulatedStates;
-
-        for (let i = 0; i < simulated.length; i++) {
-            simulated[i].updateBlendState();
-        }
-
-        const active_transitions = this.activeTransitions;
-        const transition_count = active_transitions.length;
-
-        const blend = this.blendState;
-
-        if (transition_count === 1) {
-            const first = active_transitions[0];
-
-            first.updateBlendsState();
-
-            blend.copy(first.blendState);
-        } else if (transition_count > 1) {
-            blend.zero();
-
-            for (let i = 0; i < transition_count; i++) {
-                const active = active_transitions[i];
-
-                active.updateBlendsState();
-
-                blend.add(active.blendState);
-            }
-
-            blend.weightsMultiplyScalar(1 / transition_count);
-        } else {
-            blend.copy(this.state.blendState);
-        }
-
-        const times = this.#clip_times;
-
-        for (let i = 0; i < simulated.length; i++) {
-            const state = simulated[i];
-
-            if (state.def.type !== AnimationStateType.Clip) {
-                continue;
-            }
-
-            const clip = state.def.motion;
-
-            times[this.def.getClipIndex(clip.def)] = wrap_clip_time(
-                state.time,
-                clip.def.duration,
-                clip.getFlag(AnimationClipFlag.Repeat)
-            );
-        }
-    }
-
-    /**
-     * Where clip `clip_index` is playing, in seconds from its own start — wrapped for a looping
-     * clip and clamped for a one-shot, so it is directly what the renderer's clip record holds and
-     * what a pose query has to be asked at.
-     *
-     * Only meaningful for a clip the blend gives weight to; a clip nothing is playing keeps
-     * whatever time it last stopped at.
-     *
-     * @param {number} clip_index
-     * @returns {number}
-     */
-    clip_time(clip_index) {
-        return this.#clip_times[clip_index];
-    }
-
-    /**
-     * @param {AnimationState} state
-     * @returns {number}
-     */
-    #state_clip_duration(state) {
-        if (state.def.type !== AnimationStateType.Clip) {
-            return 0;
-        }
-
-        return state.def.motion.def.duration;
-    }
-
-    /**
-     * @param {AnimationState} state
-     */
-    enter_state(state) {
-        this.state = state;
-
-        if (this.simulatedStates.indexOf(state) === -1) {
-            this.simulatedStates.push(state);
-        }
-
-        state.activate(this.__entity, this.__dataset);
-    }
-
-    /**
-     * @param {AnimationState} state
-     */
-    exit_state(state) {
-        state.deactivate(this.__entity, this.__dataset);
-    }
-
-    /**
-     * @param {AnimationState} state
-     */
-    activate_state(state) {
-        this.exit_state(this.state);
-
-        this.enter_state(state);
-    }
-
-    /**
-     * Begin a transition that has just fired.
-     *
-     * **Named for `AnimationTransition.transition`, which calls it** — the transitions listen to
-     * ECS events themselves and push the result back here.
-     *
-     * @param {AnimationTransition} transition
-     */
-    transition(transition) {
-        this.activeTransitions.push(transition);
-
-        this.activate_state(transition.target);
-    }
-}
-
-/**
- * What the binary serialization registry knows this component by.
- *
- * The controller is built transiently — `CombatUnitEntityDecorator` constructs one from the
- * creature's `animation-graph.json` every time it decorates a unit — so nothing writes one to disk
- * and there is no adapter behind this name. It is here because the registry warns on any component
- * class that reaches it unnamed, once per boot, printing the whole class source; and because a
- * component with no name cannot be told apart from another one later, which is I-13's business
- * whether or not it round-trips today.
- *
- * @type {string}
- */
-AnimationGraphController.typeName = "AnimationGraphController";
+import { assert } from "../../../core/assert.js";
+import { AnimationClipFlag } from "../../graphics/ecs/animation/animator/AnimationClipFlag.js";
+import { AnimationState } from "../../graphics/ecs/animation/animator/graph/AnimationState.js";
+import { AnimationStateType } from "../../graphics/ecs/animation/animator/graph/AnimationStateType.js";
+import { AnimationTransition } from "../../graphics/ecs/animation/animator/graph/AnimationTransition.js";
+import { wrap_clip_time } from "./wrap_clip_time.js";
+
+/**
+ * One entity's animation state machine: which state it is in, which transitions are running, what
+ * each clip therefore weighs, and — the part the GPU cannot own — what time each of those clips is
+ * playing at.
+ *
+ * **The clock is here and not on the GPU**, and I-4 is what forces it. Shade advances clip time
+ * itself in its tick shader, but the time gameplay reads has to be the time the picture is drawn
+ * from: notifications fire at authored moments off this clock, and the CPU pose evaluator answers
+ * socket queries from it. Two clocks drift, so there is one, and {@link AnimationGraphSystem}
+ * writes it down to the renderer with `set_time` rather than letting the GPU advance anything.
+ *
+ * The state machine itself is not new — `AnimationState`, `AnimationTransition`, `BlendStateMatrix`
+ * and the graph definitions are reused as they stand. What is not reused is the three-only half of
+ * the legacy `AnimationGraph`: an `AnimationMixer`, the per-clip `AnimationAction`s it owns, and
+ * writing weights onto them.
+ */
+export class AnimationGraphController {
+    /**
+     * @type {AnimationGraphDefinition}
+     */
+    def = null;
+
+    /**
+     * @type {AnimationState[]}
+     */
+    states = [];
+
+    /**
+     * @type {AnimationTransition[]}
+     */
+    transitions = [];
+
+    /**
+     * The state the graph is in. During a transition this is already the target — the source stays
+     * in {@link simulatedStates} until the transition finishes.
+     *
+     * @type {AnimationState}
+     */
+    state = null;
+
+    /**
+     * @type {AnimationTransition[]}
+     */
+    activeTransitions = [];
+
+    /**
+     * Every state whose clock is running: the current one, plus the sources of transitions that
+     * have not finished.
+     *
+     * @type {AnimationState[]}
+     */
+    simulatedStates = [];
+
+    /**
+     * Per-clip weights and time scales, in `def.clipIndex` order. The weights are what reaches the
+     * GPU; the time scales are consumed here, by {@link AnimationState#tick}, and have no GPU
+     * counterpart because the time they scale is already integrated into the state's clock.
+     *
+     * @type {BlendStateMatrix}
+     */
+    blendState = null;
+
+    /**
+     * Where in its starting clip the graph begins, as a fraction of that clip's duration.
+     *
+     * A fraction rather than a time because a clip's duration comes from the model and the model
+     * loads long after the entity does. Its purpose is to keep identical units from moving in
+     * lockstep, and it is applied once, at {@link link}, without dispatching the notifications it
+     * skips over — a unit that spawns mid-stride should not also spawn the footstep it missed.
+     *
+     * @type {number}
+     */
+    start_phase = 0;
+
+    /**
+     * The dataset this graph fires its notifications into.
+     *
+     * **Public, and named with the leading underscores, because `AnimationState.tick` reads it off
+     * the graph by exactly that name.** The state classes are reused as they stand, so this is
+     * their interface rather than an accident of style.
+     *
+     * @type {EntityComponentDataset}
+     */
+    __dataset = null;
+
+    /**
+     * The entity those notifications are addressed to. Read by `AnimationState.tick` — see
+     * {@link __dataset}.
+     *
+     * @type {number}
+     */
+    __entity = -1;
+
+    /**
+     * @type {boolean}
+     */
+    #linked = false;
+
+    /**
+     * Playback time of each clip, in `def.clipIndex` order, already wrapped or clamped into the
+     * clip's own duration — which is what the renderer's clip record wants, and what a pose query
+     * has to agree with.
+     *
+     * @type {Float64Array}
+     */
+    #clip_times = new Float64Array(0);
+
+    /**
+     * @returns {boolean}
+     */
+    get linked() {
+        return this.#linked;
+    }
+
+    /**
+     * Build the runtime graph — one {@link AnimationState} per state definition, one
+     * {@link AnimationTransition} per transition definition, wired to each other.
+     *
+     * @param {AnimationGraphDefinition} def
+     */
+    initialize(def) {
+        assert.defined(def, 'def');
+        assert.equal(this.#linked, false, 'graph is linked');
+
+        this.def = def;
+
+        this.blendState = def.createBlendState();
+        this.#clip_times = new Float64Array(def.clipIndex.length);
+
+        const state_definitions = def.states;
+        const state_count = state_definitions.length;
+
+        this.states = [];
+
+        for (let i = 0; i < state_count; i++) {
+            const state = new AnimationState();
+
+            state.def = state_definitions[i];
+            state.graph = this;
+
+            this.states[i] = state;
+        }
+
+        const transition_definitions = def.transitions;
+        const transition_count = transition_definitions.length;
+
+        this.transitions = [];
+
+        for (let i = 0; i < transition_count; i++) {
+            const transition = new AnimationTransition();
+
+            transition.def = transition_definitions[i];
+            transition.graph = this;
+
+            this.transitions[i] = transition;
+        }
+
+        this.state = this.state_by_definition(def.startingSate);
+
+        for (let i = 0; i < transition_count; i++) {
+            const transition = this.transitions[i];
+
+            transition.source = this.state_by_definition(transition.def.source);
+            transition.target = this.state_by_definition(transition.def.target);
+
+            transition.initialize();
+        }
+
+        for (let i = 0; i < state_count; i++) {
+            const state = this.states[i];
+
+            state.inEdges = state.def.inEdges.map(this.transition_by_definition, this);
+            state.outEdges = state.def.outEdges.map(this.transition_by_definition, this);
+
+            state.initialize();
+        }
+    }
+
+    /**
+     * @param {AnimationStateDefinition} definition
+     * @returns {AnimationState|undefined}
+     */
+    state_by_definition(definition) {
+        assert.defined(definition, 'definition');
+
+        const states = this.states;
+
+        for (let i = 0; i < states.length; i++) {
+            if (states[i].def === definition) {
+                return states[i];
+            }
+        }
+
+        return undefined;
+    }
+
+    /**
+     * @param {string} name
+     * @returns {AnimationState|undefined}
+     */
+    state_by_name(name) {
+        const states = this.states;
+
+        for (let i = 0; i < states.length; i++) {
+            if (states[i].def.name === name) {
+                return states[i];
+            }
+        }
+
+        return undefined;
+    }
+
+    /**
+     * @param {string} name name of the clip the state plays
+     * @returns {AnimationState|undefined}
+     */
+    state_by_clip_name(name) {
+        const states = this.states;
+
+        for (let i = 0; i < states.length; i++) {
+            const definition = states[i].def;
+
+            if (definition.type !== AnimationStateType.Clip) {
+                continue;
+            }
+
+            if (definition.motion.def.name === name) {
+                return states[i];
+            }
+        }
+
+        return undefined;
+    }
+
+    /**
+     * @param {AnimationTransitionDefinition} definition
+     * @returns {AnimationTransition|undefined}
+     */
+    transition_by_definition(definition) {
+        const transitions = this.transitions;
+
+        for (let i = 0; i < transitions.length; i++) {
+            if (transitions[i].def === definition) {
+                return transitions[i];
+            }
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Start the graph: take the clip durations the model turned out to have, enter the starting
+     * state, and begin listening for the events its transitions fire on.
+     *
+     * **Durations arrive here rather than at construction** because they are the model's and not
+     * the graph's — `animation-graph.json` names clips, the `.glb` says how long they are — and the
+     * notification path needs them to be right before a single frame is ticked. They are written
+     * onto the shared clip definitions, which is where {@link AnimationClip} reads them.
+     *
+     * @param {number} entity
+     * @param {EntityComponentDataset} ecd
+     * @param {ArrayLike<number>} durations seconds, one per `def.clipIndex` entry, in that order
+     */
+    link(entity, ecd, durations) {
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.defined(ecd, 'ecd');
+        assert.equal(this.#linked, false, 'graph is already linked, call unlink first');
+
+        const clip_index = this.def.clipIndex;
+
+        assert.equal(durations.length, clip_index.length, 'durations.length');
+
+        for (let i = 0; i < clip_index.length; i++) {
+            clip_index[i].duration = durations[i];
+        }
+
+        this.__entity = entity;
+        this.__dataset = ecd;
+
+        this.#linked = true;
+
+        this.enter_state(this.state);
+
+        this.state.time = this.start_phase * this.#state_clip_duration(this.state);
+
+        this.update_blend_state();
+    }
+
+    /**
+     * Stop listening. The graph keeps the state it was in, so a re-link resumes rather than
+     * restarts.
+     */
+    unlink() {
+        if (!this.#linked) {
+            return;
+        }
+
+        this.exit_state(this.state);
+
+        this.#linked = false;
+    }
+
+    /**
+     * Advance every running clock by `time_delta`, fire whatever notifications were crossed, and
+     * recompute the blend.
+     *
+     * Unconditional by design: §2.6-2's split puts pose evaluation and its events on the CPU
+     * precisely so that camera framing cannot decide whether a projectile spawns. The screen-area
+     * cull the legacy system applied has no counterpart here.
+     *
+     * @param {number} time_delta in seconds
+     */
+    tick(time_delta) {
+        assert.equal(this.#linked, true, 'graph is not linked');
+
+        const active_transitions = this.activeTransitions;
+
+        let transition_count = active_transitions.length;
+
+        transitions: for (let i = 0; i < transition_count; i++) {
+            const active = active_transitions[i];
+
+            active.tick(time_delta);
+
+            if (!active.isFinished()) {
+                continue;
+            }
+
+            active_transitions.splice(i, 1);
+
+            transition_count--;
+            i--;
+
+            for (let j = 0; j < transition_count; j++) {
+                const other = active_transitions[j];
+
+                if (other.source === active.source || other.target === active.source) {
+                    // the state it came from is still in use by another transition
+                    continue transitions;
+                }
+            }
+
+            this.stop_state_simulation(active.source);
+        }
+
+        const simulated = this.simulatedStates;
+
+        for (let i = 0; i < simulated.length; i++) {
+            simulated[i].tick(time_delta);
+        }
+
+        this.update_blend_state();
+    }
+
+    /**
+     * @param {AnimationState} state
+     * @returns {boolean} `false` when the state was not being simulated
+     */
+    stop_state_simulation(state) {
+        const i = this.simulatedStates.indexOf(state);
+
+        if (i === -1) {
+            return false;
+        }
+
+        this.simulatedStates.splice(i, 1);
+
+        return true;
+    }
+
+    /**
+     * Recompute per-clip weights from the states and transitions that are running, and the time
+     * each of those clips is at.
+     */
+    update_blend_state() {
+        const simulated = this.simulatedStates;
+
+        for (let i = 0; i < simulated.length; i++) {
+            simulated[i].updateBlendState();
+        }
+
+        const active_transitions = this.activeTransitions;
+        const transition_count = active_transitions.length;
+
+        const blend = this.blendState;
+
+        if (transition_count === 1) {
+            const first = active_transitions[0];
+
+            first.updateBlendsState();
+
+            blend.copy(first.blendState);
+        } else if (transition_count > 1) {
+            blend.zero();
+
+            for (let i = 0; i < transition_count; i++) {
+                const active = active_transitions[i];
+
+                active.updateBlendsState();
+
+                blend.add(active.blendState);
+            }
+
+            blend.weightsMultiplyScalar(1 / transition_count);
+        } else {
+            blend.copy(this.state.blendState);
+        }
+
+        const times = this.#clip_times;
+
+        for (let i = 0; i < simulated.length; i++) {
+            const state = simulated[i];
+
+            if (state.def.type !== AnimationStateType.Clip) {
+                continue;
+            }
+
+            const clip = state.def.motion;
+
+            times[this.def.getClipIndex(clip.def)] = wrap_clip_time(
+                state.time,
+                clip.def.duration,
+                clip.getFlag(AnimationClipFlag.Repeat)
+            );
+        }
+    }
+
+    /**
+     * Where clip `clip_index` is playing, in seconds from its own start — wrapped for a looping
+     * clip and clamped for a one-shot, so it is directly what the renderer's clip record holds and
+     * what a pose query has to be asked at.
+     *
+     * Only meaningful for a clip the blend gives weight to; a clip nothing is playing keeps
+     * whatever time it last stopped at.
+     *
+     * @param {number} clip_index
+     * @returns {number}
+     */
+    clip_time(clip_index) {
+        return this.#clip_times[clip_index];
+    }
+
+    /**
+     * @param {AnimationState} state
+     * @returns {number}
+     */
+    #state_clip_duration(state) {
+        if (state.def.type !== AnimationStateType.Clip) {
+            return 0;
+        }
+
+        return state.def.motion.def.duration;
+    }
+
+    /**
+     * @param {AnimationState} state
+     */
+    enter_state(state) {
+        this.state = state;
+
+        if (this.simulatedStates.indexOf(state) === -1) {
+            this.simulatedStates.push(state);
+        }
+
+        state.activate(this.__entity, this.__dataset);
+    }
+
+    /**
+     * @param {AnimationState} state
+     */
+    exit_state(state) {
+        state.deactivate(this.__entity, this.__dataset);
+    }
+
+    /**
+     * @param {AnimationState} state
+     */
+    activate_state(state) {
+        this.exit_state(this.state);
+
+        this.enter_state(state);
+    }
+
+    /**
+     * Begin a transition that has just fired.
+     *
+     * **Named for `AnimationTransition.transition`, which calls it** — the transitions listen to
+     * ECS events themselves and push the result back here.
+     *
+     * @param {AnimationTransition} transition
+     */
+    transition(transition) {
+        this.activeTransitions.push(transition);
+
+        this.activate_state(transition.target);
+    }
+}
+
+/**
+ * What the binary serialization registry knows this component by.
+ *
+ * The controller is built transiently — `CombatUnitEntityDecorator` constructs one from the
+ * creature's `animation-graph.json` every time it decorates a unit — so nothing writes one to disk
+ * and there is no adapter behind this name. It is here because the registry warns on any component
+ * class that reaches it unnamed, once per boot, printing the whole class source; and because a
+ * component with no name cannot be told apart from another one later, which is I-13's business
+ * whether or not it round-trips today.
+ *
+ * @type {string}
+ */
+AnimationGraphController.typeName = "AnimationGraphController";