@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/animation/ClipListPlayer.d.ts

@@ -49,7 +49,7 @@ export class ClipListPlayer {
      * What each of the model's clips weighs, by the instance's own clip order — which is the order
      * the animation manager's registration uses, so it is the lookup for both.
      *
-     * A clip the list does not name weighs zero: `MeshSystem3` registers every clip a model carries,
+     * A clip the list does not name weighs zero: `MeshSystem` registers every clip a model carries,
      * and an unclaimed one would otherwise lay itself over the pose at full strength.
      *
      * @type {Float32Array}

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

@@ -1,263 +1,263 @@
-import { assert } from "../../../core/assert.js";
-import { AnimationEventTypes } from "../../graphics/ecs/animation/animator/AnimationEventTypes.js";
-import { ClipPlayback } from "./ClipPlayback.js";
-import { wrap_clip_time } from "./wrap_clip_time.js";
-
-/**
- * Plays one {@link Animation} component's list of clips against one model.
- *
- * **The component is reused as it stands**, unlike the graph's, which had to be restated because it
- * *was* an `AnimationMixer`: `Animation` holds a name, a repeat count, a weight and a time scale per
- * clip and no renderer handle of any kind. What the legacy system added to it — the mixer, its
- * actions and their clocks — is what this replaces, and the clocks are here because the pose
- * gameplay asks about has to come off the same clock the picture is drawn from (I-4).
- *
- * **Weights are shares of one pose.** Shade's accumulator adds up what every bound clip contributes
- * and has no rest-pose term, so what reaches it is each clip's weight over the list's total —
- * which is what three's mixer did too, by cumulative weight, and is why the game can author a walk
- * clip at weight 1000 against an idle at 1 and mean "the walk".
- *
- * **A clip that has run out holds its last frame.** Three disabled a finished one-shot and let the
- * rig fall back to its bind pose; there is no pose to fall back to here, and a list whose every clip
- * has stopped contributing resolves each joint it drives to *zero* rather than to rest. So
- * `AnimationClipFlag.ClampWhenFinished` decides nothing — holding is the only case — and it keeps
- * deserializing (I-13) like `AnimationFlags.MeshSizeCulling`, whose 32 px² cull does not come across
- * either: a clock camera framing can stop is a simulation camera framing can change (§2.6-2).
- */
-export class ClipListPlayer {
-    /**
-     * The list being played. Every entry's `weight`, `timeScale` and `repeatCount` is read each
-     * tick, so changing one takes effect without removing and re-adding the clip.
-     *
-     * @type {Animation}
-     */
-    component = null;
-
-    /**
-     * The entity's private copy of the model — where the clips named in the list are found, and
-     * where their durations come from.
-     *
-     * @type {SceneBundleInstance}
-     */
-    instance = null;
-
-    /**
-     * One per entry of {@link component}'s list, in the list's own order.
-     *
-     * @type {ClipPlayback[]}
-     */
-    playbacks = [];
-
-    /**
-     * What each of the model's clips weighs, by the instance's own clip order — which is the order
-     * the animation manager's registration uses, so it is the lookup for both.
-     *
-     * A clip the list does not name weighs zero: `MeshSystem3` registers every clip a model carries,
-     * and an unclaimed one would otherwise lay itself over the pose at full strength.
-     *
-     * @type {Float32Array}
-     */
-    weights = new Float32Array(0);
-
-    /**
-     * @type {number}
-     */
-    #entity = -1;
-
-    /**
-     * @type {EntityComponentDataset}
-     */
-    #dataset = null;
-
-    /**
-     * Names already reported as absent from this model, so the report is one line rather than one a
-     * frame. Cleared with the model, because the next one may well carry the name.
-     *
-     * @type {Set<string>}
-     */
-    #reported_missing = new Set();
-
-    /**
-     * @param {Animation} component
-     * @returns {ClipListPlayer}
-     */
-    static from(component) {
-        assert.defined(component, 'component');
-
-        const r = new ClipListPlayer();
-
-        r.component = component;
-
-        return r;
-    }
-
-    /**
-     * Take up a model, and the entity whose events its clips fire as.
-     *
-     * Every playback is dropped, because the clips a playback was pointing at are not this model's.
-     *
-     * @param {number} entity
-     * @param {EntityComponentDataset} ecd
-     * @param {SceneBundleInstance} instance
-     */
-    bind(entity, ecd, instance) {
-        assert.isNonNegativeInteger(entity, 'entity');
-        assert.defined(ecd, 'ecd');
-        assert.defined(instance, 'instance');
-
-        this.#entity = entity;
-        this.#dataset = ecd;
-
-        this.instance = instance;
-        this.playbacks = [];
-        this.weights = new Float32Array(instance.clips.length);
-        this.#reported_missing.clear();
-    }
-
-    /**
-     * Advance every clock, say so when one runs out, and work out what the list therefore weighs.
-     *
-     * 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 clip's end is ever reached.
-     *
-     * @param {number} time_delta_seconds
-     */
-    tick(time_delta_seconds) {
-        this.#reconcile();
-        this.#advance(time_delta_seconds);
-        this.#blend();
-    }
-
-    /**
-     * Match the playbacks against the list, which the game edits while it runs —
-     * `StartAnimationBehavior` adds an entry, `StopAnimationBehavior` and `AnimationController`'s
-     * rules remove one. Identity is the match, so a clip stopped and started again is a new entry
-     * and plays from its own beginning.
-     *
-     * **A name the model has not got does not play, and says so once (D43).** Clip names are
-     * authored against models the game does not own and they do miss — the strategy map's buildings
-     * ask for `Take01` of a model whose clip is `Take 001`, and one that has no clips at all. This
-     * threw until D43, out of `AnimationSystem3.update`, which cost *every* entity its animation on
-     * every frame for as long as one such entity existed. Reporting it per frame buries the console
-     * and reporting it not at all is how the mismatch survived the three path unnoticed, so it is
-     * said once per name, with the model's real clip list beside it.
-     */
-    #reconcile() {
-        const clips = this.component.clips;
-        const playbacks = this.playbacks;
-
-        for (let i = playbacks.length - 1; i >= 0; i--) {
-            if (clips.indexOf(playbacks[i].clip) === -1) {
-                playbacks.splice(i, 1);
-            }
-        }
-
-        const available = this.instance.clips;
-
-        for (let i = 0; i < clips.length; i++) {
-            const clip = clips.get(i);
-
-            if (find_playback(playbacks, clip) !== null) {
-                continue;
-            }
-
-            const name = clip.name.getValue();
-            const slot = available.findIndex(c => c.name === name);
-
-            if (slot === -1) {
-                this.#report_missing(name, available);
-
-                continue;
-            }
-
-            playbacks.push(ClipPlayback.from(clip, slot, available[slot].duration));
-        }
-    }
-
-    /**
-     * Say once, per name, that this model has no such clip — and say what it does have, because the
-     * mismatch is nearly always spelling and the answer is in the list beside it.
-     *
-     * @param {string} name
-     * @param {ShadeAnimationClip[]} available
-     */
-    #report_missing(name, available) {
-        if (this.#reported_missing.has(name)) {
-            return;
-        }
-
-        this.#reported_missing.add(name);
-
-        console.warn(
-            `Animation clip '${name}' is not in the model of entity ${this.#entity}, so it does not `
-            + `play. The model carries: ${available.map(c => `'${c.name}'`).join(', ')}`
-        );
-    }
-
-    /**
-     * @param {number} time_delta_seconds
-     */
-    #advance(time_delta_seconds) {
-        const playing = this.component.isPlaying;
-        const playbacks = this.playbacks;
-
-        for (let i = 0; i < playbacks.length; i++) {
-            const playback = playbacks[i];
-
-            if (playing && !playback.finished) {
-                playback.elapsed += time_delta_seconds * playback.clip.timeScale.getValue();
-            }
-
-            const repeats = playback.clip.repeatCount.getValue();
-
-            // `Infinity * duration` is `Infinity`, which no elapsed time reaches — so a looping
-            // clip takes the wrapping branch forever without a case of its own
-            const finished = playback.elapsed >= repeats * playback.duration;
-
-            playback.time = wrap_clip_time(playback.elapsed, playback.duration, !finished);
-
-            if (finished && !playback.finished) {
-                playback.finished = true;
-
-                this.#dataset.sendEvent(this.#entity, AnimationEventTypes.ClipEnded, playback.clip);
-            }
-        }
-    }
-
-    #blend() {
-        const playbacks = this.playbacks;
-        const weights = this.weights;
-
-        weights.fill(0);
-
-        let total = 0;
-
-        for (let i = 0; i < playbacks.length; i++) {
-            total += playbacks[i].clip.weight.getValue();
-        }
-
-        for (let i = 0; i < playbacks.length; i++) {
-            const playback = playbacks[i];
-
-            // an author who weighted every clip at zero asked for silence, and gets it
-            playback.weight = total > 0 ? playback.clip.weight.getValue() / total : 0;
-
-            weights[playback.slot] += playback.weight;
-        }
-    }
-}
-
-/**
- * @param {ClipPlayback[]} playbacks
- * @param {AnimationClip} clip
- * @returns {ClipPlayback|null}
- */
-function find_playback(playbacks, clip) {
-    for (let i = 0; i < playbacks.length; i++) {
-        if (playbacks[i].clip === clip) {
-            return playbacks[i];
-        }
-    }
-
-    return null;
-}
+import { assert } from "../../../core/assert.js";
+import { AnimationEventTypes } from "../../graphics/ecs/animation/animator/AnimationEventTypes.js";
+import { ClipPlayback } from "./ClipPlayback.js";
+import { wrap_clip_time } from "./wrap_clip_time.js";
+
+/**
+ * Plays one {@link Animation} component's list of clips against one model.
+ *
+ * **The component is reused as it stands**, unlike the graph's, which had to be restated because it
+ * *was* an `AnimationMixer`: `Animation` holds a name, a repeat count, a weight and a time scale per
+ * clip and no renderer handle of any kind. What the legacy system added to it — the mixer, its
+ * actions and their clocks — is what this replaces, and the clocks are here because the pose
+ * gameplay asks about has to come off the same clock the picture is drawn from (I-4).
+ *
+ * **Weights are shares of one pose.** Shade's accumulator adds up what every bound clip contributes
+ * and has no rest-pose term, so what reaches it is each clip's weight over the list's total —
+ * which is what three's mixer did too, by cumulative weight, and is why the game can author a walk
+ * clip at weight 1000 against an idle at 1 and mean "the walk".
+ *
+ * **A clip that has run out holds its last frame.** Three disabled a finished one-shot and let the
+ * rig fall back to its bind pose; there is no pose to fall back to here, and a list whose every clip
+ * has stopped contributing resolves each joint it drives to *zero* rather than to rest. So
+ * `AnimationClipFlag.ClampWhenFinished` decides nothing — holding is the only case — and it keeps
+ * deserializing (I-13) like `AnimationFlags.MeshSizeCulling`, whose 32 px² cull does not come across
+ * either: a clock camera framing can stop is a simulation camera framing can change (§2.6-2).
+ */
+export class ClipListPlayer {
+    /**
+     * The list being played. Every entry's `weight`, `timeScale` and `repeatCount` is read each
+     * tick, so changing one takes effect without removing and re-adding the clip.
+     *
+     * @type {Animation}
+     */
+    component = null;
+
+    /**
+     * The entity's private copy of the model — where the clips named in the list are found, and
+     * where their durations come from.
+     *
+     * @type {SceneBundleInstance}
+     */
+    instance = null;
+
+    /**
+     * One per entry of {@link component}'s list, in the list's own order.
+     *
+     * @type {ClipPlayback[]}
+     */
+    playbacks = [];
+
+    /**
+     * What each of the model's clips weighs, by the instance's own clip order — which is the order
+     * the animation manager's registration uses, so it is the lookup for both.
+     *
+     * A clip the list does not name weighs zero: `MeshSystem` registers every clip a model carries,
+     * and an unclaimed one would otherwise lay itself over the pose at full strength.
+     *
+     * @type {Float32Array}
+     */
+    weights = new Float32Array(0);
+
+    /**
+     * @type {number}
+     */
+    #entity = -1;
+
+    /**
+     * @type {EntityComponentDataset}
+     */
+    #dataset = null;
+
+    /**
+     * Names already reported as absent from this model, so the report is one line rather than one a
+     * frame. Cleared with the model, because the next one may well carry the name.
+     *
+     * @type {Set<string>}
+     */
+    #reported_missing = new Set();
+
+    /**
+     * @param {Animation} component
+     * @returns {ClipListPlayer}
+     */
+    static from(component) {
+        assert.defined(component, 'component');
+
+        const r = new ClipListPlayer();
+
+        r.component = component;
+
+        return r;
+    }
+
+    /**
+     * Take up a model, and the entity whose events its clips fire as.
+     *
+     * Every playback is dropped, because the clips a playback was pointing at are not this model's.
+     *
+     * @param {number} entity
+     * @param {EntityComponentDataset} ecd
+     * @param {SceneBundleInstance} instance
+     */
+    bind(entity, ecd, instance) {
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.defined(ecd, 'ecd');
+        assert.defined(instance, 'instance');
+
+        this.#entity = entity;
+        this.#dataset = ecd;
+
+        this.instance = instance;
+        this.playbacks = [];
+        this.weights = new Float32Array(instance.clips.length);
+        this.#reported_missing.clear();
+    }
+
+    /**
+     * Advance every clock, say so when one runs out, and work out what the list therefore weighs.
+     *
+     * 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 clip's end is ever reached.
+     *
+     * @param {number} time_delta_seconds
+     */
+    tick(time_delta_seconds) {
+        this.#reconcile();
+        this.#advance(time_delta_seconds);
+        this.#blend();
+    }
+
+    /**
+     * Match the playbacks against the list, which the game edits while it runs —
+     * `StartAnimationBehavior` adds an entry, `StopAnimationBehavior` and `AnimationController`'s
+     * rules remove one. Identity is the match, so a clip stopped and started again is a new entry
+     * and plays from its own beginning.
+     *
+     * **A name the model has not got does not play, and says so once (D43).** Clip names are
+     * authored against models the game does not own and they do miss — the strategy map's buildings
+     * ask for `Take01` of a model whose clip is `Take 001`, and one that has no clips at all. This
+     * threw until D43, out of `AnimationSystem.update`, which cost *every* entity its animation on
+     * every frame for as long as one such entity existed. Reporting it per frame buries the console
+     * and reporting it not at all is how the mismatch survived the three path unnoticed, so it is
+     * said once per name, with the model's real clip list beside it.
+     */
+    #reconcile() {
+        const clips = this.component.clips;
+        const playbacks = this.playbacks;
+
+        for (let i = playbacks.length - 1; i >= 0; i--) {
+            if (clips.indexOf(playbacks[i].clip) === -1) {
+                playbacks.splice(i, 1);
+            }
+        }
+
+        const available = this.instance.clips;
+
+        for (let i = 0; i < clips.length; i++) {
+            const clip = clips.get(i);
+
+            if (find_playback(playbacks, clip) !== null) {
+                continue;
+            }
+
+            const name = clip.name.getValue();
+            const slot = available.findIndex(c => c.name === name);
+
+            if (slot === -1) {
+                this.#report_missing(name, available);
+
+                continue;
+            }
+
+            playbacks.push(ClipPlayback.from(clip, slot, available[slot].duration));
+        }
+    }
+
+    /**
+     * Say once, per name, that this model has no such clip — and say what it does have, because the
+     * mismatch is nearly always spelling and the answer is in the list beside it.
+     *
+     * @param {string} name
+     * @param {ShadeAnimationClip[]} available
+     */
+    #report_missing(name, available) {
+        if (this.#reported_missing.has(name)) {
+            return;
+        }
+
+        this.#reported_missing.add(name);
+
+        console.warn(
+            `Animation clip '${name}' is not in the model of entity ${this.#entity}, so it does not `
+            + `play. The model carries: ${available.map(c => `'${c.name}'`).join(', ')}`
+        );
+    }
+
+    /**
+     * @param {number} time_delta_seconds
+     */
+    #advance(time_delta_seconds) {
+        const playing = this.component.isPlaying;
+        const playbacks = this.playbacks;
+
+        for (let i = 0; i < playbacks.length; i++) {
+            const playback = playbacks[i];
+
+            if (playing && !playback.finished) {
+                playback.elapsed += time_delta_seconds * playback.clip.timeScale.getValue();
+            }
+
+            const repeats = playback.clip.repeatCount.getValue();
+
+            // `Infinity * duration` is `Infinity`, which no elapsed time reaches — so a looping
+            // clip takes the wrapping branch forever without a case of its own
+            const finished = playback.elapsed >= repeats * playback.duration;
+
+            playback.time = wrap_clip_time(playback.elapsed, playback.duration, !finished);
+
+            if (finished && !playback.finished) {
+                playback.finished = true;
+
+                this.#dataset.sendEvent(this.#entity, AnimationEventTypes.ClipEnded, playback.clip);
+            }
+        }
+    }
+
+    #blend() {
+        const playbacks = this.playbacks;
+        const weights = this.weights;
+
+        weights.fill(0);
+
+        let total = 0;
+
+        for (let i = 0; i < playbacks.length; i++) {
+            total += playbacks[i].clip.weight.getValue();
+        }
+
+        for (let i = 0; i < playbacks.length; i++) {
+            const playback = playbacks[i];
+
+            // an author who weighted every clip at zero asked for silence, and gets it
+            playback.weight = total > 0 ? playback.clip.weight.getValue() / total : 0;
+
+            weights[playback.slot] += playback.weight;
+        }
+    }
+}
+
+/**
+ * @param {ClipPlayback[]} playbacks
+ * @param {AnimationClip} clip
+ * @returns {ClipPlayback|null}
+ */
+function find_playback(playbacks, clip) {
+    for (let i = 0; i < playbacks.length; i++) {
+        if (playbacks[i].clip === clip) {
+            return playbacks[i];
+        }
+    }
+
+    return null;
+}

package/src/engine/graphics3/animation/ClipPlayback.d.ts

@@ -4,7 +4,7 @@
  * The `Animation` component says *what* to play — a name, a repeat count, a weight, a time scale —
  * and holds no clock of its own, because it is data that a level authors and a save round-trips.
  * This is the running half: where that clip is, how strongly it is contributing, and whether it has
- * run out. {@link AnimationSystem3} owns one per clip in the list and hands them out, because the
+ * run out. {@link AnimationSystem} owns one per clip in the list and hands them out, because the
  * pose a gameplay query has to answer from is exactly this (I-4) — never a readback.
  */
 export class ClipPlayback {
@@ -52,7 +52,7 @@ export class ClipPlayback {
     time: number;
     /**
      * The share of the pose this clip is contributing, normalized across every clip in the list —
-     * see {@link AnimationSystem3}.
+     * see {@link AnimationSystem}.
      *
      * @type {number}
      */