@woosh/meep-engine 3.43.0 → 3.44.0

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

@@ -0,0 +1,56 @@
+/**
+ * @typedef {import("../../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ */
+/**
+ * The clips this entity can play: each a {@link ShadeAnimationClip} whose channels key entities —
+ * the joints of a rig, the nodes of a loaded model.
+ *
+ * **It lives on the entity that plays them**, beside its `Animation` or `AnimationGraphController`.
+ * A clip is one clock over many targets and describes no single one of them, so it is not a
+ * component on a joint. `AnimationSystem` and `AnimationGraphSystem` resolve the names their lists
+ * and graphs ask for against this set. The CPU pose consumers (IK, ContactProbe, cloth) ask those
+ * drivers about a joint's `ParentEntity`, so a joint they should see names this entity there.
+ *
+ * **Not `Animation.clips`.** That list says what to play — a name, a weight, a repeat count each;
+ * this says what there is to play and what each of those does to which entity. A name in the one is
+ * looked up by name in the other.
+ *
+ * A model loaded by `MeshSystem` carries one on its root, re-addressed to the entities of that
+ * placement; code that builds a rig puts one there the same way. A model with no clips carries an
+ * empty one, so that an `Animation` on it is still driven and says which name it could not find.
+ *
+ * **Replaced, never edited.** A clip's channels are settled once it plays; to add, drop or change a
+ * clip, take the component off and put another on, which the drivers see as their entity leaving
+ * and coming back.
+ *
+ * **Not saved**, for the reason `MeshSkin` is not: the channels key entities that whatever builds
+ * the rig creates, and the curves are asset data. A load rebuilds them the way it rebuilds the rig.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class AnimationClips {
+    /**
+     * @param {ShadeAnimationClip[]} clips may be empty
+     * @returns {AnimationClips}
+     */
+    static from(clips: ShadeAnimationClip[]): AnimationClips;
+    /**
+     * Read-only once the component is on an entity. A clip's name is the key the drivers look it up
+     * by.
+     *
+     * @type {ShadeAnimationClip[]}
+     */
+    clips: ShadeAnimationClip[];
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isAnimationClips: boolean;
+}
+export namespace AnimationClips {
+    let typeName: string;
+    let serializable: boolean;
+}
+export type ShadeAnimationClip = import("../../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip;
+//# sourceMappingURL=AnimationClips.d.ts.map

package/src/engine/graphics3/animation/AnimationClips.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimationClips.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/animation/AnimationClips.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IASI;;;OAGG;IACH,mBAHW,kBAAkB,EAAE,GAClB,cAAc,CAc1B;IAxBD;;;;;OAKG;IACH,OAFU,kBAAkB,EAAE,CAEnB;IAqBf;;;OAGG;IACH,2BAFU,OAAO,CAEwB;CANxC;;kBAUS,MAAM;sBAMN,OAAO;;iCAzEJ,OAAO,yDAAyD,EAAE,kBAAkB"}

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

@@ -0,0 +1,79 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * @typedef {import("../../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ */
+
+/**
+ * The clips this entity can play: each a {@link ShadeAnimationClip} whose channels key entities —
+ * the joints of a rig, the nodes of a loaded model.
+ *
+ * **It lives on the entity that plays them**, beside its `Animation` or `AnimationGraphController`.
+ * A clip is one clock over many targets and describes no single one of them, so it is not a
+ * component on a joint. `AnimationSystem` and `AnimationGraphSystem` resolve the names their lists
+ * and graphs ask for against this set. The CPU pose consumers (IK, ContactProbe, cloth) ask those
+ * drivers about a joint's `ParentEntity`, so a joint they should see names this entity there.
+ *
+ * **Not `Animation.clips`.** That list says what to play — a name, a weight, a repeat count each;
+ * this says what there is to play and what each of those does to which entity. A name in the one is
+ * looked up by name in the other.
+ *
+ * A model loaded by `MeshSystem` carries one on its root, re-addressed to the entities of that
+ * placement; code that builds a rig puts one there the same way. A model with no clips carries an
+ * empty one, so that an `Animation` on it is still driven and says which name it could not find.
+ *
+ * **Replaced, never edited.** A clip's channels are settled once it plays; to add, drop or change a
+ * clip, take the component off and put another on, which the drivers see as their entity leaving
+ * and coming back.
+ *
+ * **Not saved**, for the reason `MeshSkin` is not: the channels key entities that whatever builds
+ * the rig creates, and the curves are asset data. A load rebuilds them the way it rebuilds the rig.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class AnimationClips {
+    /**
+     * Read-only once the component is on an entity. A clip's name is the key the drivers look it up
+     * by.
+     *
+     * @type {ShadeAnimationClip[]}
+     */
+    clips = [];
+
+    /**
+     * @param {ShadeAnimationClip[]} clips may be empty
+     * @returns {AnimationClips}
+     */
+    static from(clips) {
+        assert.isArray(clips, 'clips');
+
+        for (let i = 0; i < clips.length; i++) {
+            assert.equal(clips[i]?.isShadeAnimationClip, true, `clips[${i}] is not a ShadeAnimationClip`);
+        }
+
+        const r = new AnimationClips();
+
+        r.clips = clips;
+
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+AnimationClips.prototype.isAnimationClips = true;
+
+/**
+ * @readonly
+ * @type {string}
+ */
+AnimationClips.typeName = "AnimationClips";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+AnimationClips.serializable = false;

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

@@ -1,5 +1,6 @@
 /**
- * Plays one {@link Animation} component's list of clips against one model.
+ * 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
@@ -33,12 +34,12 @@ export class ClipListPlayer {
      */
     component: Animation;
     /**
-     * The entity's private copy of the model — where the clips named in the list are found, and
-     * where their durations come from.
+     * The entity's clips — where the clips named in the list are found, and where their durations
+     * come from.
      *
-     * @type {PrefabInstance}
+     * @type {ShadeAnimationClip[]}
      */
-    instance: PrefabInstance;
+    clips: ShadeAnimationClip[];
     /**
      * One per entry of {@link component}'s list, in the list's own order.
      *
@@ -46,25 +47,23 @@ export class ClipListPlayer {
      */
     playbacks: ClipPlayback[];
     /**
-     * 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.
+     * 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: Float32Array;
     /**
-     * Take up a model, and the entity whose events its clips fire as.
+     * 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 this model's.
+     * Every playback is dropped, because the clips a playback was pointing at are not these.
      *
      * @param {number} entity
      * @param {EntityComponentDataset} ecd
-     * @param {PrefabInstance} instance
+     * @param {ShadeAnimationClip[]} clips the entity's `AnimationClips`
      */
-    bind(entity: number, ecd: EntityComponentDataset, instance: PrefabInstance): void;
+    bind(entity: number, ecd: EntityComponentDataset, clips: ShadeAnimationClip[]): void;
     /**
      * Advance every clock, say so when one runs out, and work out what the list therefore weighs.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"ClipListPlayer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/animation/ClipListPlayer.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAqDI;;;OAGG;IACH,uBAHW,SAAS,GACP,cAAc,CAU1B;IAhED;;;;;OAKG;IACH,WAFU,SAAS,CAEF;IAEjB;;;;;OAKG;IACH,yBAAgB;IAEhB;;;;OAIG;IACH,WAFU,YAAY,EAAE,CAET;IAEf;;;;;;;;OAQG;IACH,SAFU,YAAY,CAEQ;IAkC9B;;;;;;;;OAQG;IACH,aAJW,MAAM,+DAgBhB;IAED;;;;;;;OAOG;IACH,yBAFW,MAAM,QAMhB;;CAuHJ;6BArP4B,mBAAmB"}
+{"version":3,"file":"ClipListPlayer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/animation/ClipListPlayer.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAmDI;;;OAGG;IACH,uBAHW,SAAS,GACP,cAAc,CAU1B;IA9DD;;;;;OAKG;IACH,WAFU,SAAS,CAEF;IAEjB;;;;;OAKG;IACH,OAFU,oBAAoB,CAEjB;IAEb;;;;OAIG;IACH,WAFU,YAAY,EAAE,CAET;IAEf;;;;;;OAMG;IACH,SAFU,YAAY,CAEQ;IAkC9B;;;;;;;;OAQG;IACH,aAJW,MAAM,sCAEN,oBAAoB,QAc9B;IAED;;;;;;;OAOG;IACH,yBAFW,MAAM,QAMhB;;CAuHJ;6BApP4B,mBAAmB"}