@woosh/meep-engine 3.44.0 → 3.45.0

package/src/core/math/linalg/matrix_symmetric_3x3_solve_ldlt.js

@@ -0,0 +1,71 @@
+/**
+ * Solve `M·x = b` for a symmetric positive definite 3×3 `M`, by LDLᵀ factorisation.
+ *
+ * `M` is read as its six distinct entries, diagonal first: `[m00, m11, m22, m01, m02, m12]`.
+ *
+ * LDLᵀ rather than a cofactor inverse. The two agree in exact arithmetic and do not agree in Float64: an SPD
+ * matrix with a condition number in the billions has a cofactor determinant — a sum of triple products that
+ * has to cancel down by that ratio squared — that can come out *negative* although every eigenvalue is
+ * positive. The factorisation never forms those products, so its pivots stay positive where the determinant
+ * does not, and their product is the determinant to full precision.
+ *
+ * The pivots of an SPD matrix are `M` restricted to nested subspaces, so all three positive *is* positive
+ * definiteness: the function checks exactly that, and returns `false` without writing `out` when a pivot is
+ * not positive and finite — an indefinite, singular or non-finite `M`. An infinite pivot needs refusing
+ * explicitly: it is positive, and dividing by it reads as a finite solution, zero along that axis.
+ *
+ * @param {Float64Array|Float32Array|number[]} out solution `x`, 3 entries at `out_offset`
+ * @param {number} out_offset
+ * @param {Float64Array|Float32Array|number[]} m `[m00, m11, m22, m01, m02, m12]` at `m_offset`
+ * @param {number} m_offset
+ * @param {Float64Array|Float32Array|number[]} b right-hand side, 3 entries at `b_offset`
+ * @param {number} b_offset
+ * @returns {boolean} true when `M` was positive definite and `out` holds the solution
+ */
+export function matrix_symmetric_3x3_solve_ldlt(
+    out, out_offset,
+    m, m_offset,
+    b, b_offset
+) {
+    const m00 = m[m_offset];
+    const m11 = m[m_offset + 1];
+    const m22 = m[m_offset + 2];
+    const m01 = m[m_offset + 3];
+    const m02 = m[m_offset + 4];
+    const m12 = m[m_offset + 5];
+
+    const pivot_0 = m00;
+    const lower_10 = m01 / pivot_0;
+    const lower_20 = m02 / pivot_0;
+
+    const pivot_1 = m11 - lower_10 * m01;
+    const lower_21 = (m12 - lower_20 * m01) / pivot_1;
+
+    const pivot_2 = m22 - lower_20 * m02 - lower_21 * lower_21 * pivot_1;
+
+    if (!(
+        pivot_0 > 0 && pivot_0 < Infinity
+        && pivot_1 > 0 && pivot_1 < Infinity
+        && pivot_2 > 0 && pivot_2 < Infinity
+    )) {
+        return false;
+    }
+
+    const b0 = b[b_offset];
+    const b1 = b[b_offset + 1];
+    const b2 = b[b_offset + 2];
+
+    // Forward substitution through L, scale by D, back substitution through Lᵀ.
+    const forward_1 = b1 - lower_10 * b0;
+    const forward_2 = b2 - lower_20 * b0 - lower_21 * forward_1;
+
+    const x2 = forward_2 / pivot_2;
+    const x1 = forward_1 / pivot_1 - lower_21 * x2;
+    const x0 = b0 / pivot_0 - lower_10 * x1 - lower_20 * x2;
+
+    out[out_offset] = x0;
+    out[out_offset + 1] = x1;
+    out[out_offset + 2] = x2;
+
+    return true;
+}

package/src/core/math/max2_exact.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `Math.max(a, b)` without the call, as {@link min2_exact}: the larger, NaN if either is, and `+0`
+ * above `-0`.
+ *
+ * {@link max2} drops a NaN in `b` and lets the first of two zeros win; this does neither.
+ *
+ * The same as `Math.max` under `Object.is` for every pair of numbers, except that a NaN answer is the
+ * canonical NaN.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function max2_exact(a: number, b: number): number;
+//# sourceMappingURL=max2_exact.d.ts.map

package/src/core/math/max2_exact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"max2_exact.d.ts","sourceRoot":"","sources":["../../../../src/core/math/max2_exact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,8BAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAkBlB"}

package/src/core/math/max2_exact.js

@@ -0,0 +1,30 @@
+/**
+ * `Math.max(a, b)` without the call, as {@link min2_exact}: the larger, NaN if either is, and `+0`
+ * above `-0`.
+ *
+ * {@link max2} drops a NaN in `b` and lets the first of two zeros win; this does neither.
+ *
+ * The same as `Math.max` under `Object.is` for every pair of numbers, except that a NaN answer is the
+ * canonical NaN.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function max2_exact(a, b) {
+    if (a > b) {
+        return a;
+    }
+
+    if (b > a) {
+        return b;
+    }
+
+    if (a === b) {
+        // equal, and of two zeros the positive one if either is
+        return a === 0 && 1 / a < 0 ? b : a;
+    }
+
+    // one of them is NaN
+    return NaN;
+}

package/src/core/math/min2_exact.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `Math.min(a, b)` without the call: the smaller, NaN if either is, and `-0` below `+0`.
+ *
+ * {@link min2} is `a < b ? a : b`, which answers `b` whenever the comparison is false — a NaN in `a`
+ * is dropped, and of two zeros the second one wins. That is right for a running minimum over values
+ * known to be numbers, and wrong for a bound that has to stay poisoned when its input was.
+ *
+ * Why not `Math.min` itself: in code V8 has not optimised yet (a function run a few times a step can
+ * stay unoptimised for thousands of steps), `Math.min` is a call into a builtin that hands its answer
+ * back boxed into a heap object. This is comparisons only.
+ *
+ * The same as `Math.min` under `Object.is` for every pair of numbers. A NaN answer is the canonical
+ * NaN; which NaN `Math.min` answers is the platform's (on x64, the one with the sign bit set).
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function min2_exact(a: number, b: number): number;
+//# sourceMappingURL=min2_exact.d.ts.map

package/src/core/math/min2_exact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"min2_exact.d.ts","sourceRoot":"","sources":["../../../../src/core/math/min2_exact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAkBlB"}

package/src/core/math/min2_exact.js

@@ -0,0 +1,35 @@
+/**
+ * `Math.min(a, b)` without the call: the smaller, NaN if either is, and `-0` below `+0`.
+ *
+ * {@link min2} is `a < b ? a : b`, which answers `b` whenever the comparison is false — a NaN in `a`
+ * is dropped, and of two zeros the second one wins. That is right for a running minimum over values
+ * known to be numbers, and wrong for a bound that has to stay poisoned when its input was.
+ *
+ * Why not `Math.min` itself: in code V8 has not optimised yet (a function run a few times a step can
+ * stay unoptimised for thousands of steps), `Math.min` is a call into a builtin that hands its answer
+ * back boxed into a heap object. This is comparisons only.
+ *
+ * The same as `Math.min` under `Object.is` for every pair of numbers. A NaN answer is the canonical
+ * NaN; which NaN `Math.min` answers is the platform's (on x64, the one with the sign bit set).
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function min2_exact(a, b) {
+    if (a < b) {
+        return a;
+    }
+
+    if (b < a) {
+        return b;
+    }
+
+    if (a === b) {
+        // equal, and of two zeros the negative one if either is
+        return a === 0 && 1 / a > 0 ? b : a;
+    }
+
+    // one of them is NaN
+    return NaN;
+}

package/src/engine/ecs/ik/IKGoalSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IKGoalSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/IKGoalSystem.js"],"names":[],"mappings":"AAyOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;;IAEI,6DAA6C;IAE7C,kbASE;IAEF;;;OAGG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,WAFU,MAAM,CAEC;IAkDjB;;;;OAIG;IACH,WAJW,MAAM,cACN,mBAAmB,UACnB,MAAM,QAgChB;IAED;;;;OAIG;IACH,aAJW,MAAM,cACN,mBAAmB,UACnB,MAAM,QAkBhB;IAED,sCA+BC;;CA6nBJ;uBA1hCsB,cAAc;oCAED,gDAAgD;uBAQ7D,aAAa;4BAD7B,6BAA6B;4CA1BQ,oDAAoD;yCAEvD,uDAAuD;0BAQtE,2BAA2B;kCAEnB,6BAA6B;6BAIlC,2BAA2B;sBAPlC,4BAA4B"}
+{"version":3,"file":"IKGoalSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/IKGoalSystem.js"],"names":[],"mappings":"AA0OA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;;IAEI,6DAA6C;IAE7C,kbASE;IAEF;;;OAGG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,WAFU,MAAM,CAEC;IAkDjB;;;;OAIG;IACH,WAJW,MAAM,cACN,mBAAmB,UACnB,MAAM,QAgChB;IAED;;;;OAIG;IACH,aAJW,MAAM,cACN,mBAAmB,UACnB,MAAM,QAkBhB;IAED,sCA+BC;;CA6nBJ;uBA1hCsB,cAAc;oCAED,gDAAgD;uBAQ7D,aAAa;4BAD7B,6BAA6B;4CA3BQ,oDAAoD;yCAEvD,uDAAuD;0BAQtE,2BAA2B;kCAEnB,6BAA6B;6BAIlC,2BAA2B;sBAPlC,4BAA4B"}

package/src/engine/ecs/ik/IKGoalSystem.js

@@ -19,6 +19,7 @@ import { GPUStateAuthorityFlags } from "../gpu/GPUStateAuthorityFlags.js";
 import { gpu_authority_hold } from "../gpu/gpu_authority_hold.js";
 import { gpu_authority_unhold } from "../gpu/gpu_authority_unhold.js";
 import { ParentEntity } from "../parent/ParentEntity.js";
+import { parent_entity_model_of } from "../parent/parent_entity_model_of.js";
 import { System } from "../System.js";
 import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
 import { TransformAttachment } from "../transform-attachment/TransformAttachment.js";
@@ -354,8 +355,8 @@ export class IKGoalSystem extends System {
         record.entity = entity;
         record.goal = goal;
         record.system = this;
-        record.model = model_of(dataset, entity);
-        record.target_model = dataset.entityExists(goal.target) ? model_of(dataset, goal.target) : -1;
+        record.model = parent_entity_model_of(dataset, entity);
+        record.target_model = dataset.entityExists(goal.target) ? parent_entity_model_of(dataset, goal.target) : -1;
 
         this.#records.set(entity, record);
 
@@ -1071,23 +1072,6 @@ export class IKGoalSystem extends System {
     }
 }
 
-/**
- * The entity whose clips drive `entity`: the model its lifetime belongs to, or itself.
- *
- * @param {EntityComponentDataset} dataset
- * @param {number} entity
- * @returns {number}
- */
-function model_of(dataset, entity) {
-    const owner = dataset.getComponent(entity, ParentEntity);
-
-    if (owner === undefined || owner === null) {
-        return entity;
-    }
-
-    return owner.entity;
-}
-
 /**
  * Goals grouped by connected paths: two goals whose paths share a bone are solved together.
  *

package/src/engine/ecs/parent/parent_entity_model_of.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The entity whose clips drive `entity`: the model its lifetime belongs to, or itself.
+ *
+ * A placed model's bones each carry a {@link ParentEntity} naming the model's root, and the root is
+ * where the model's clips and animation drivers live. So the model of a bone is one step up the
+ * lifetime edge, and an entity without one — a root, a prop, a hand-made rig — is its own model.
+ *
+ * One step, not a walk to the top: a model placed under another model is still its own model, with
+ * its own clips.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {number} the model entity; `entity` itself when it has no {@link ParentEntity}, or one
+ * naming no entity yet (`-1`)
+ */
+export function parent_entity_model_of(dataset: EntityComponentDataset, entity: number): number;
+//# sourceMappingURL=parent_entity_model_of.d.ts.map

package/src/engine/ecs/parent/parent_entity_model_of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parent_entity_model_of.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/parent/parent_entity_model_of.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,gFAJW,MAAM,GACJ,MAAM,CAWlB"}

package/src/engine/ecs/parent/parent_entity_model_of.js

@@ -0,0 +1,26 @@
+import { ParentEntity } from "./ParentEntity.js";
+
+/**
+ * The entity whose clips drive `entity`: the model its lifetime belongs to, or itself.
+ *
+ * A placed model's bones each carry a {@link ParentEntity} naming the model's root, and the root is
+ * where the model's clips and animation drivers live. So the model of a bone is one step up the
+ * lifetime edge, and an entity without one — a root, a prop, a hand-made rig — is its own model.
+ *
+ * One step, not a walk to the top: a model placed under another model is still its own model, with
+ * its own clips.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {number} the model entity; `entity` itself when it has no {@link ParentEntity}, or one
+ * naming no entity yet (`-1`)
+ */
+export function parent_entity_model_of(dataset, entity) {
+    const owner = dataset.getComponent(entity, ParentEntity);
+
+    if (owner === undefined || owner === null || owner.entity < 0) {
+        return entity;
+    }
+
+    return owner.entity;
+}

package/src/engine/ecs/transform/t64_read_pose_array.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pack a transform's rigid pose, `[tx, ty, tz, qx, qy, qz, qw]`, into an array: the translation and
+ * the rotation, without the scale or the matrix.
+ *
+ * Seven floats is the shape a contact kernel, an oriented box transform or a cloth holder takes a
+ * pose in. Read off the transform's lanes (a {@link Transform64} is a `Float64Array`) rather than
+ * through `translation_x` and the rest: a hot caller that does not inline those accessor calls gets
+ * each number back boxed, and the vector getters allocate outright.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset receives 7 floats
+ * @param {Transform64|Float64Array} transform a `Transform64`, or an array in its layout
+ */
+export function t64_read_pose_array(out: number[] | Float32Array | Float64Array, out_offset: number, transform: Transform64 | Float64Array): void;
+//# sourceMappingURL=t64_read_pose_array.d.ts.map

package/src/engine/ecs/transform/t64_read_pose_array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"t64_read_pose_array.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_read_pose_array.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,yCAJW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,aACN,cAAY,YAAY,QAUlC"}

package/src/engine/ecs/transform/t64_read_pose_array.js

@@ -0,0 +1,24 @@
+import { TRANSFORM64_ROTATION_OFFSET, TRANSFORM64_TRANSLATION_OFFSET } from "./Transform64.js";
+
+/**
+ * Pack a transform's rigid pose, `[tx, ty, tz, qx, qy, qz, qw]`, into an array: the translation and
+ * the rotation, without the scale or the matrix.
+ *
+ * Seven floats is the shape a contact kernel, an oriented box transform or a cloth holder takes a
+ * pose in. Read off the transform's lanes (a {@link Transform64} is a `Float64Array`) rather than
+ * through `translation_x` and the rest: a hot caller that does not inline those accessor calls gets
+ * each number back boxed, and the vector getters allocate outright.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset receives 7 floats
+ * @param {Transform64|Float64Array} transform a `Transform64`, or an array in its layout
+ */
+export function t64_read_pose_array(out, out_offset, transform) {
+    out[out_offset] = transform[TRANSFORM64_TRANSLATION_OFFSET];
+    out[out_offset + 1] = transform[TRANSFORM64_TRANSLATION_OFFSET + 1];
+    out[out_offset + 2] = transform[TRANSFORM64_TRANSLATION_OFFSET + 2];
+    out[out_offset + 3] = transform[TRANSFORM64_ROTATION_OFFSET];
+    out[out_offset + 4] = transform[TRANSFORM64_ROTATION_OFFSET + 1];
+    out[out_offset + 5] = transform[TRANSFORM64_ROTATION_OFFSET + 2];
+    out[out_offset + 6] = transform[TRANSFORM64_ROTATION_OFFSET + 3];
+}

package/src/engine/graphics/geometry/geometry_construct_triangle_normal_area_weighted.d.ts

@@ -17,6 +17,8 @@
  * to synthesise some arbitrary unit vector and hand it over as though it were a
  * measurement.
  *
+ * An indexed form of {@link tri3_compute_normal_area_weighted_array}, which holds the arithmetic.
+ *
  * Single-face callers — a raycast normal, a plane side test — want
  * {@link geometry_construct_triangle_normal} instead.
  *

package/src/engine/graphics/geometry/geometry_construct_triangle_normal_area_weighted.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geometry_construct_triangle_normal_area_weighted.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/geometry/geometry_construct_triangle_normal_area_weighted.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,sEARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,aACN,MAAM,EAAE,GAAC,YAAY,GACnB,IAAI,CAwBhB"}
+{"version":3,"file":"geometry_construct_triangle_normal_area_weighted.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/geometry/geometry_construct_triangle_normal_area_weighted.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,sEARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,aACN,MAAM,EAAE,GAAC,YAAY,GACnB,IAAI,CAShB"}

package/src/engine/graphics/geometry/geometry_construct_triangle_normal_area_weighted.js

@@ -1,3 +1,5 @@
+import { tri3_compute_normal_area_weighted_array } from "../../../core/geom/3d/triangle/tri3_compute_normal_area_weighted_array.js";
+
 /**
  * The face normal of an indexed triangle, NOT normalised — the raw
  * `(c - b) × (a - b)`, whose magnitude is twice the triangle's area.
@@ -17,6 +19,8 @@
  * to synthesise some arbitrary unit vector and hand it over as though it were a
  * measurement.
  *
+ * An indexed form of {@link tri3_compute_normal_area_weighted_array}, which holds the arithmetic.
+ *
  * Single-face callers — a raycast normal, a plane side test — want
  * {@link geometry_construct_triangle_normal} instead.
  *
@@ -29,25 +33,10 @@
  * @returns {void}
  */
 export function geometry_construct_triangle_normal_area_weighted(out, out_offset, a, b, c, positions) {
-
-    const a_address = a * 3;
-    const b_address = b * 3;
-    const c_address = c * 3;
-
-    const bx = positions[b_address];
-    const by = positions[b_address + 1];
-    const bz = positions[b_address + 2];
-
-    const cb_x = positions[c_address] - bx;
-    const cb_y = positions[c_address + 1] - by;
-    const cb_z = positions[c_address + 2] - bz;
-
-    const ab_x = positions[a_address] - bx;
-    const ab_y = positions[a_address + 1] - by;
-    const ab_z = positions[a_address + 2] - bz;
-
-    // the same winding `tri3_compute_normal` uses, so the direction agrees
-    out[out_offset] = cb_y * ab_z - cb_z * ab_y;
-    out[out_offset + 1] = cb_z * ab_x - cb_x * ab_z;
-    out[out_offset + 2] = cb_x * ab_y - cb_y * ab_x;
+    tri3_compute_normal_area_weighted_array(
+        out, out_offset,
+        positions, a * 3,
+        positions, b * 3,
+        positions, c * 3
+    );
 }

package/src/engine/graphics3/AnimationGraphSystem.d.ts

@@ -6,6 +6,10 @@
  * components, whoever put them there — a model `MeshSystem` loaded, or a rig built in code. New
  * clips are a new component, which this system sees as the entity leaving and coming back.
  *
+ * **Every node the clips key holds a row here** ({@link hold_clip_targets}), from the graph being
+ * bound to the clips until they go. A clip binds only once all of them do, and a keyed node outside
+ * every skin with nothing drawn under it — a socket, say — is held by no other system.
+ *
  * **It is the CPU that plays the animation and the GPU that draws it.** Shade can advance a clip
  * itself, and this never asks it to — `AnimationClipFlags.Playing` is left clear and every audible
  * clip's time is written down each frame from the controller's own clock. That is I-4: the pose
@@ -66,6 +70,7 @@ export class AnimationGraphSystem extends System<any> {
      * @param {number} entity
      */
     unlink(controller: AnimationGraphController, clips: AnimationClips, entity: number): void;
+    startup(entityManager: any): Promise<void>;
     shutdown(entityManager: any): Promise<void>;
     #private;
 }

package/src/engine/graphics3/AnimationGraphSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimationGraphSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/AnimationGraphSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAkBI;;;OAGG;IACH,oDAgBC;IAPG,0EAA8D;IAI9D,gFAEC;IAGL;;;;;;;;;OASG;IACH,iBAJW,wBAAwB,SACxB,cAAc,UACd,MAAM,QAchB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,6BANW,YAAY,EAAE,UACd,MAAM,GACJ,OAAO,CAgDnB;IAED;;;;OAIG;IACH,mBAJW,wBAAwB,SACxB,cAAc,UACd,MAAM,QAYhB;IAED,4CAQC;;CAkJJ;uBAzUsB,kBAAkB;yCAEA,yCAAyC;+BADnD,+BAA+B;4CAHlB,iDAAiD;6BAChE,qDAAqD"}
+{"version":3,"file":"AnimationGraphSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/AnimationGraphSystem.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAyBI;;;OAGG;IACH,oDAgBC;IAPG,0EAA8D;IAI9D,gFAEC;IAGL;;;;;;;;;OASG;IACH,iBAJW,wBAAwB,SACxB,cAAc,UACd,MAAM,QAehB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,6BANW,YAAY,EAAE,UACd,MAAM,GACJ,OAAO,CAgDnB;IAED;;;;OAIG;IACH,mBAJW,wBAAwB,SACxB,cAAc,UACd,MAAM,QAkBhB;IAED,2CAaC;IAED,4CAWC;;CA2JJ;uBAvXsB,kBAAkB;yCAEA,yCAAyC;+BADnD,+BAA+B;4CAHlB,iDAAiD;6BAChE,qDAAqD"}

package/src/engine/graphics3/AnimationGraphSystem.js

@@ -6,7 +6,8 @@ import { System } from "../ecs/System.js";
 import { AnimationClips } from "./animation/AnimationClips.js";
 import { AnimationGraphController } from "./animation/AnimationGraphController.js";
 import { write_graph_playback } from "./animation/write_graph_playback.js";
-import { register_clips, unregister_clips } from "./register_clips.js";
+import { hold_clip_targets, register_clips, release_clip_targets, unregister_clips } from "./register_clips.js";
+import { RowChains } from "./RowChains.js";
 
 /**
  * Drives every entity's {@link AnimationGraphController}: runs its clock, and tells the renderer
@@ -16,6 +17,10 @@ import { register_clips, unregister_clips } from "./register_clips.js";
  * components, whoever put them there — a model `MeshSystem` loaded, or a rig built in code. New
  * clips are a new component, which this system sees as the entity leaving and coming back.
  *
+ * **Every node the clips key holds a row here** ({@link hold_clip_targets}), from the graph being
+ * bound to the clips until they go. A clip binds only once all of them do, and a keyed node outside
+ * every skin with nothing drawn under it — a socket, say — is held by no other system.
+ *
  * **It is the CPU that plays the animation and the GPU that draws it.** Shade can advance a clip
  * itself, and this never asks it to — `AnimationClipFlags.Playing` is left clear and every audible
  * clip's time is written down each frame from the controller's own clock. That is I-4: the pose
@@ -41,10 +46,17 @@ export class AnimationGraphSystem extends System {
     #scene;
 
     /**
-     * @type {Map<number, {controller: AnimationGraphController, clips: ShadeAnimationClip[], bound: boolean, clip_registration: ClipRegistration|null, slots: Int32Array, played_slots: Int32Array, clip_ids: Int32Array, weights: Float32Array, poses: PosePlayback[]}>}
+     * @type {Map<number, {controller: AnimationGraphController, clips: ShadeAnimationClip[], bound: boolean, held: boolean, clip_registration: ClipRegistration|null, slots: Int32Array, played_slots: Int32Array, clip_ids: Int32Array, weights: Float32Array, poses: PosePlayback[]}>}
      */
     #entries = new Map();
 
+    /**
+     * The chains of the nodes the clips key. Null until the system has a dataset.
+     *
+     * @type {RowChains|null}
+     */
+    #chains = null;
+
     /**
      * @param {GraphicsEngine} graphics
      * @param {Scene} scene
@@ -82,6 +94,7 @@ export class AnimationGraphSystem extends System {
             controller,
             clips: clips.clips,
             bound: false,
+            held: false,
             clip_registration: null,
             slots: new Int32Array(0),
             played_slots: new Int32Array(0),
@@ -172,11 +185,32 @@ export class AnimationGraphSystem extends System {
 
         if (entry !== undefined) {
             this.#release_clips(entry);
+
+            if (entry.held) {
+                release_clip_targets(this.#chains, entry.clips);
+
+                entry.held = false;
+            }
         }
 
         this.#entries.delete(entity);
     }
 
+    async startup(entityManager) {
+        // the scene's rows are this dataset's entities; the first system to place one says so
+        const dataset = entityManager.dataset;
+        const scene = this.#scene;
+
+        assert.ok(
+            scene.dataset === null || scene.dataset === undefined || scene.dataset === dataset,
+            'the scene is bound to another dataset'
+        );
+
+        scene.dataset = dataset;
+
+        this.#chains = new RowChains(dataset);
+    }
+
     async shutdown(entityManager) {
         for (const entry of this.#entries.values()) {
             entry.controller.unlink();
@@ -185,6 +219,9 @@ export class AnimationGraphSystem extends System {
         }
 
         this.#entries.clear();
+
+        this.#chains.destroy();
+        this.#chains = null;
     }
 
     /**
@@ -223,6 +260,9 @@ export class AnimationGraphSystem extends System {
         // that fires an ability while the renderer is being replaced still fires it.
         const manager = context === null ? null : context.animation_manager;
 
+        // a new context after a restart is acquired in whole; until there is one, holds are recorded
+        this.#chains.bind(context === null ? null : context.rows);
+
         for (const [entity, entry] of this.#entries) {
             if (!entry.bound) {
                 this.#bind_clips(entry, entity, ecd);
@@ -302,6 +342,12 @@ export class AnimationGraphSystem extends System {
         entry.poses = clips.map(() => new PosePlayback());
 
         entry.bound = true;
+
+        // past the throw above, so a graph that cannot be bound holds nothing; and before anything
+        // registers, so the clips bind in the update that registers them
+        hold_clip_targets(this.#chains, clips);
+
+        entry.held = true;
     }
 
     /**

package/src/engine/graphics3/AnimationSystem.d.ts

@@ -11,6 +11,10 @@
  * components, whoever put them there — a model `MeshSystem` loaded, or a rig built in code. New
  * clips are a new component, which this system sees as the entity leaving and coming back.
  *
+ * **Every node the clips key holds a row here** ({@link hold_clip_targets}), from the clips being
+ * taken up until they go. A clip binds only once all of them do, and a keyed node outside every skin
+ * with nothing drawn under it is held by no other system.
+ *
  * **It is the CPU that plays the animation and the GPU that draws it.** Shade can advance a clip
  * itself, and this never asks it to — `AnimationClipFlags.Playing` is left clear and every audible
  * clip's time is written down each frame from the player's own clock. That is I-4: the pose
@@ -76,6 +80,7 @@ export class AnimationSystem extends System<any> {
      * @param {number} entity
      */
     unlink(component: Animation, clips: AnimationClips, entity: number): void;
+    startup(entityManager: any): Promise<void>;
     shutdown(entityManager: any): Promise<void>;
     #private;
 }

package/src/engine/graphics3/AnimationSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimationSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/AnimationSystem.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAkBI;;;OAGG;IACH,oDAgBC;IAPG,2DAA+C;IAI/C,iEAEC;IAGL;;;;;;;;OAQG;IACH,qBAHW,MAAM,GACJ,cAAc,CAU1B;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,6BANW,YAAY,EAAE,UACd,MAAM,GACJ,OAAO,CAyCnB;IAED;;;;;;;;OAQG;IACH,gBAJW,SAAS,SACT,cAAc,UACd,MAAM,QAYhB;IAED;;;;OAIG;IACH,kBAJW,SAAS,SACT,cAAc,UACd,MAAM,QAUhB;IAED,4CAMC;;CAsKJ;uBAxWsB,kBAAkB;0BADf,+BAA+B;+BAE1B,+BAA+B;4CAJlB,iDAAiD;6BAChE,qDAAqD"}
+{"version":3,"file":"AnimationSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/AnimationSystem.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAyBI;;;OAGG;IACH,oDAgBC;IAPG,2DAA+C;IAI/C,iEAEC;IAGL;;;;;;;;OAQG;IACH,qBAHW,MAAM,GACJ,cAAc,CAU1B;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,6BANW,YAAY,EAAE,UACd,MAAM,GACJ,OAAO,CAyCnB;IAED;;;;;;;;OAQG;IACH,gBAJW,SAAS,SACT,cAAc,UACd,MAAM,QAahB;IAED;;;;OAIG;IACH,kBAJW,SAAS,SACT,cAAc,UACd,MAAM,QAgBhB;IAED,2CAaC;IAED,4CASC;;CA8KJ;uBArZsB,kBAAkB;0BADf,+BAA+B;+BAE1B,+BAA+B;4CAJlB,iDAAiD;6BAChE,qDAAqD"}