@woosh/meep-engine 3.43.0 → 3.45.0

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

@@ -1,263 +1,262 @@
-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 {PrefabInstance}
-     */
-    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 {PrefabInstance} 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;
-}
+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 the clips its entity carries — its
+ * `AnimationClips`.
+ *
+ * **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 clips — where the clips named in the list are found, and where their durations
+     * come from.
+     *
+     * @type {ShadeAnimationClip[]}
+     */
+    clips = null;
+
+    /**
+     * One per entry of {@link component}'s list, in the list's own order.
+     *
+     * @type {ClipPlayback[]}
+     */
+    playbacks = [];
+
+    /**
+     * What each of the entity's clips weighs, in {@link clips}' 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.
+     *
+     * @type {Float32Array}
+     */
+    weights = new Float32Array(0);
+
+    /**
+     * @type {number}
+     */
+    #entity = -1;
+
+    /**
+     * @type {EntityComponentDataset}
+     */
+    #dataset = null;
+
+    /**
+     * Names already reported as absent from these clips, so the report is one line rather than one a
+     * frame. Cleared with the clips, because the next set 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 set of clips, and the entity whose events they fire as.
+     *
+     * Every playback is dropped, because the clips a playback was pointing at are not these.
+     *
+     * @param {number} entity
+     * @param {EntityComponentDataset} ecd
+     * @param {ShadeAnimationClip[]} clips the entity's `AnimationClips`
+     */
+    bind(entity, ecd, clips) {
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.defined(ecd, 'ecd');
+        assert.isArray(clips, 'clips');
+
+        this.#entity = entity;
+        this.#dataset = ecd;
+
+        this.clips = clips;
+        this.playbacks = [];
+        this.weights = new Float32Array(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 entity's clips have 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 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.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 the entity 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 among the clips of entity ${this.#entity}, so it does not `
+            + `play. Its AnimationClips 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/write_clip_playback.d.ts

@@ -1,5 +1,5 @@
 /**
- * Hand one clip list's blend down to the renderer: what each of the model's clips weighs, and where
+ * Hand one clip list's blend down to the renderer: what each of the entity's clips weighs, and where
  * each of the audible ones is playing.
  *
  * **Time is written every frame and weight only when it moves.** The clock is the reason this
@@ -14,8 +14,8 @@
  *
  * @param {GPUAnimationManager} manager
  * @param {ClipListPlayer} player
- * @param {ArrayLike<number>} clip_ids the manager's id for each of the model's clips, in the
- * instance's order, or {@link CLIP_NOT_REGISTERED} for one this driver does not play. Those are
+ * @param {ArrayLike<number>} clip_ids the manager's id for each of the entity's clips, in its
+ * `AnimationClips`' order, or {@link CLIP_NOT_REGISTERED} for one this driver does not play. Those are
  * skipped rather than written at weight zero: an unregistered clip has no row, and it is unregistered
  * precisely so that it marks no joints (D37)
  * @param {Float32Array} written the weight each of those clips was last given; updated in place.

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

@@ -1,8 +1,8 @@
 import { assert } from "../../../core/assert.js";
-import { CLIP_NOT_REGISTERED } from "../register_instance_animation.js";
+import { CLIP_NOT_REGISTERED } from "../register_clips.js";
 
 /**
- * Hand one clip list's blend down to the renderer: what each of the model's clips weighs, and where
+ * Hand one clip list's blend down to the renderer: what each of the entity's clips weighs, and where
  * each of the audible ones is playing.
  *
  * **Time is written every frame and weight only when it moves.** The clock is the reason this
@@ -17,8 +17,8 @@ import { CLIP_NOT_REGISTERED } from "../register_instance_animation.js";
  *
  * @param {GPUAnimationManager} manager
  * @param {ClipListPlayer} player
- * @param {ArrayLike<number>} clip_ids the manager's id for each of the model's clips, in the
- * instance's order, or {@link CLIP_NOT_REGISTERED} for one this driver does not play. Those are
+ * @param {ArrayLike<number>} clip_ids the manager's id for each of the entity's clips, in its
+ * `AnimationClips`' order, or {@link CLIP_NOT_REGISTERED} for one this driver does not play. Those are
  * skipped rather than written at weight zero: an unregistered clip has no row, and it is unregistered
  * precisely so that it marks no joints (D37)
  * @param {Float32Array} written the weight each of those clips was last given; updated in place.

package/src/engine/graphics3/pose/query_entity_node_world_pose.d.ts

@@ -12,6 +12,11 @@
  * (hierarchy, clip set, time, weights), off the same clock the renderer is written from, which is
  * what keeps a socket on the mesh that is drawn — whether or not the GPU owns the joint's row.
  *
+ * **A name is only how a loaded model is asked.** For a joint the caller already holds — one of a
+ * rig built in code — there is nothing to look up: {@link collect_entity_playbacks} for the entity
+ * playing its clips, then {@link t64_evaluate_world} for the joint, which is all this does once the
+ * name is resolved.
+ *
  * The result carries both its matrix and its components.
  *
  * @param {Transform64} result

package/src/engine/graphics3/pose/query_entity_node_world_pose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query_entity_node_world_pose.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/pose/query_entity_node_world_pose.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,yGANW,MAAM,aACN,MAAM,GACJ,OAAO,CAwCnB"}
+{"version":3,"file":"query_entity_node_world_pose.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/pose/query_entity_node_world_pose.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,yGANW,MAAM,aACN,MAAM,GACJ,OAAO,CAwCnB"}