@woosh/meep-engine 3.23.0 → 3.24.0

package/src/engine/ecs/gpu/gpu_authority_declare.js

@@ -0,0 +1,39 @@
+import { assert } from "../../../core/assert.js";
+import { GPUStateAuthority } from "./GPUStateAuthority.js";
+
+/**
+ * Give an entity a {@link GPUStateAuthority} with nothing claimed, so that every later authority
+ * change is a bit write.
+ *
+ * **This is the only place the component is added, and it belongs at creation** — in the bulk build
+ * that makes the entity, or at the moment the one system that may flag it first links. Adding and
+ * removing a component is a structural dataset change that relinks systems, and the thing being
+ * described starts and stops constantly: a clip beginning and ending would otherwise churn the
+ * dataset once per transition, for a bit.
+ *
+ * Zero flags is not the same as no component. Both mean the CPU owns everything today; the
+ * difference is that this one is ready to change its mind.
+ *
+ * Idempotent: an entity that already carries the component keeps the flags it has. Two systems may
+ * both know an entity is flaggable, and neither is wrong.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {GPUStateAuthority} the entity's component, existing or newly attached
+ */
+export function gpu_authority_declare(dataset, entity) {
+    assert.defined(dataset, 'dataset');
+    assert.isNonNegativeInteger(entity, 'entity');
+
+    const existing = dataset.getComponent(entity, GPUStateAuthority);
+
+    if (existing !== undefined && existing !== null) {
+        return existing;
+    }
+
+    const authority = new GPUStateAuthority();
+
+    dataset.addComponentToEntity(entity, authority);
+
+    return authority;
+}

package/src/engine/ecs/gpu/gpu_authority_grant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * State that the GPU now owns these components for this entity.
+ *
+ * A bit write, never a component add — the entity must already have been declared flaggable by
+ * {@link gpu_authority_declare}, at creation. An entity that reaches here without one is a
+ * declaration site that was missed, and adding the component here to paper over it is exactly the
+ * structural churn the declaration exists to avoid.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}
+ * @returns {boolean} whether anything changed — `false` when the GPU already owned all of them
+ */
+export function gpu_authority_grant(dataset: EntityComponentDataset, entity: number, flags: number): boolean;
+//# sourceMappingURL=gpu_authority_grant.d.ts.map

package/src/engine/ecs/gpu/gpu_authority_grant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_authority_grant.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_grant.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,6EAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAsBnB"}

package/src/engine/ecs/gpu/gpu_authority_grant.js

@@ -0,0 +1,38 @@
+import { assert } from "../../../core/assert.js";
+import { GPUStateAuthority } from "./GPUStateAuthority.js";
+import { GPU_STATE_AUTHORITY_FLAGS_ALL, gpu_state_authority_flag_names } from "./GPUStateAuthorityFlags.js";
+
+/**
+ * State that the GPU now owns these components for this entity.
+ *
+ * A bit write, never a component add — the entity must already have been declared flaggable by
+ * {@link gpu_authority_declare}, at creation. An entity that reaches here without one is a
+ * declaration site that was missed, and adding the component here to paper over it is exactly the
+ * structural churn the declaration exists to avoid.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}
+ * @returns {boolean} whether anything changed — `false` when the GPU already owned all of them
+ */
+export function gpu_authority_grant(dataset, entity, flags) {
+    assert.defined(dataset, 'dataset');
+    assert.isNonNegativeInteger(entity, 'entity');
+    assert.isNonNegativeInteger(flags, 'flags');
+    assert.equal(flags & ~GPU_STATE_AUTHORITY_FLAGS_ALL, 0, `flags (${gpu_state_authority_flag_names(flags)}) contains bits GPUStateAuthorityFlags does not assign`);
+
+    const authority = dataset.getComponent(entity, GPUStateAuthority);
+
+    assert.ok(authority !== undefined && authority !== null, `entity ${entity} has no GPUStateAuthority — it must be declared at creation, see gpu_authority_declare`);
+
+    const before = authority.flags;
+    const after = before | flags;
+
+    if (after === before) {
+        return false;
+    }
+
+    authority.flags = after;
+
+    return true;
+}

package/src/engine/ecs/gpu/gpu_authority_has.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Does the GPU own component X for entity E?
+ *
+ * The one question every reader of {@link GPUStateAuthority} asks, answered in one place so that
+ * "no component" and "component with the bit clear" cannot be told apart by accident — both mean the
+ * CPU owns it, and an entity that will never be flagged carries no component at all.
+ *
+ * With more than one bit in `flags` this asks for **all** of them: `gpu_authority_has(ecd, e,
+ * Transform64 | TransformAttachment)` is true only where the GPU owns both. Ask about one bit at a
+ * time unless that is really the question.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}
+ * @returns {boolean}
+ */
+export function gpu_authority_has(dataset: EntityComponentDataset, entity: number, flags: number): boolean;
+//# sourceMappingURL=gpu_authority_has.d.ts.map

package/src/engine/ecs/gpu/gpu_authority_has.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_authority_has.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_has.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,2EAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAWnB"}

package/src/engine/ecs/gpu/gpu_authority_has.js

@@ -0,0 +1,28 @@
+import { GPUStateAuthority } from "./GPUStateAuthority.js";
+
+/**
+ * Does the GPU own component X for entity E?
+ *
+ * The one question every reader of {@link GPUStateAuthority} asks, answered in one place so that
+ * "no component" and "component with the bit clear" cannot be told apart by accident — both mean the
+ * CPU owns it, and an entity that will never be flagged carries no component at all.
+ *
+ * With more than one bit in `flags` this asks for **all** of them: `gpu_authority_has(ecd, e,
+ * Transform64 | TransformAttachment)` is true only where the GPU owns both. Ask about one bit at a
+ * time unless that is really the question.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}
+ * @returns {boolean}
+ */
+export function gpu_authority_has(dataset, entity, flags) {
+    const authority = dataset.getComponent(entity, GPUStateAuthority);
+
+    if (authority === undefined || authority === null) {
+        // no statement made, so the CPU owns everything about this entity
+        return false;
+    }
+
+    return (authority.flags & flags) === flags;
+}

package/src/engine/ecs/gpu/gpu_authority_revoke.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Take these components back for the CPU.
+ *
+ * The component stays; only bits clear. An entity whose clip just ended is very likely to start
+ * another one, and the whole point of declaring authority at creation is that the transition costs a
+ * word.
+ *
+ * **Revoking does not seed a value.** The CPU's copy of a component the GPU has been writing is
+ * whatever it was when the GPU took over, and nothing here changes that. Whoever hands authority
+ * back is responsible for seeding the CPU value first — by exact evaluation, never by a readback,
+ * which is a frame late and would make the entity snap backwards.
+ *
+ * Tolerates an entity with no {@link GPUStateAuthority}: absence already means the CPU owns
+ * everything, so there is nothing to take back. That is the difference from
+ * {@link gpu_authority_grant}, which insists on the component because a grant that silently did
+ * nothing would be a claim nobody could see.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}
+ * @returns {boolean} whether anything changed
+ */
+export function gpu_authority_revoke(dataset: EntityComponentDataset, entity: number, flags: number): boolean;
+//# sourceMappingURL=gpu_authority_revoke.d.ts.map

package/src/engine/ecs/gpu/gpu_authority_revoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_authority_revoke.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_revoke.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8EAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAwBnB"}

package/src/engine/ecs/gpu/gpu_authority_revoke.js

@@ -0,0 +1,49 @@
+import { assert } from "../../../core/assert.js";
+import { GPUStateAuthority } from "./GPUStateAuthority.js";
+import { GPU_STATE_AUTHORITY_FLAGS_ALL, gpu_state_authority_flag_names } from "./GPUStateAuthorityFlags.js";
+
+/**
+ * Take these components back for the CPU.
+ *
+ * The component stays; only bits clear. An entity whose clip just ended is very likely to start
+ * another one, and the whole point of declaring authority at creation is that the transition costs a
+ * word.
+ *
+ * **Revoking does not seed a value.** The CPU's copy of a component the GPU has been writing is
+ * whatever it was when the GPU took over, and nothing here changes that. Whoever hands authority
+ * back is responsible for seeding the CPU value first — by exact evaluation, never by a readback,
+ * which is a frame late and would make the entity snap backwards.
+ *
+ * Tolerates an entity with no {@link GPUStateAuthority}: absence already means the CPU owns
+ * everything, so there is nothing to take back. That is the difference from
+ * {@link gpu_authority_grant}, which insists on the component because a grant that silently did
+ * nothing would be a claim nobody could see.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}
+ * @returns {boolean} whether anything changed
+ */
+export function gpu_authority_revoke(dataset, entity, flags) {
+    assert.defined(dataset, 'dataset');
+    assert.isNonNegativeInteger(entity, 'entity');
+    assert.isNonNegativeInteger(flags, 'flags');
+    assert.equal(flags & ~GPU_STATE_AUTHORITY_FLAGS_ALL, 0, `flags (${gpu_state_authority_flag_names(flags)}) contains bits GPUStateAuthorityFlags does not assign`);
+
+    const authority = dataset.getComponent(entity, GPUStateAuthority);
+
+    if (authority === undefined || authority === null) {
+        return false;
+    }
+
+    const before = authority.flags;
+    const after = before & ~flags;
+
+    if (after === before) {
+        return false;
+    }
+
+    authority.flags = after;
+
+    return true;
+}

package/src/engine/ecs/ik/IKProblem.d.ts

@@ -23,6 +23,20 @@ export class IKProblem {
      * @type {Terrain}
      */
     terrain: Terrain;
+    /**
+     * The clips playing on the constrained entity's model, with their times and weights: what a
+     * chain under a GPU-composed ancestor is evaluated against. Empty for a model nothing plays.
+     *
+     * @type {PosePlayback[]}
+     */
+    playbacks: PosePlayback[];
+    /**
+     * The system's per-tick evaluation cache, shared by every problem of the tick; null where a
+     * chain is evaluated on its own.
+     *
+     * @type {T64WorldCache|null}
+     */
+    cache: T64WorldCache | null;
 }
 export namespace IKProblem {
     let pool: ObjectPoolFactory<IKProblem>;

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

@@ -1 +1 @@
-{"version":3,"file":"IKProblem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/IKProblem.js"],"names":[],"mappings":"AAGA;IAEI;;;OAGG;IACH,yBAAkB;IAElB;;;;;OAKG;IACH,gCAAe;IAEf;;;;;OAKG;IACH,UAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,iBAAe;CAElB;;cAIS,kBAAkB,SAAS,CAAC;;kCApCJ,iDAAiD"}
+{"version":3,"file":"IKProblem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/IKProblem.js"],"names":[],"mappings":"AAGA;IAEI;;;OAGG;IACH,yBAAkB;IAElB;;;;;OAKG;IACH,gCAAe;IAEf;;;;;OAKG;IACH,UAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,iBAAe;IAEf;;;;;OAKG;IACH,WAFU,cAAc,CAET;IAEf;;;;;OAKG;IACH,OAFU,gBAAc,IAAI,CAEf;CAEhB;;cAIS,kBAAkB,SAAS,CAAC;;kCApDJ,iDAAiD"}

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

@@ -31,6 +31,22 @@ export class IKProblem {
      */
     terrain = null;
 
+    /**
+     * The clips playing on the constrained entity's model, with their times and weights: what a
+     * chain under a GPU-composed ancestor is evaluated against. Empty for a model nothing plays.
+     *
+     * @type {PosePlayback[]}
+     */
+    playbacks = [];
+
+    /**
+     * The system's per-tick evaluation cache, shared by every problem of the tick; null where a
+     * chain is evaluated on its own.
+     *
+     * @type {T64WorldCache|null}
+     */
+    cache = null;
+
 }
 
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"InverseKinematicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/InverseKinematicsSystem.js"],"names":[],"mappings":"AAaA;;;;;;;;GAQG;AACH;;IAEI,gEAAgD;IAEhD,mEAEE;IAEF;;;OAGG;IACH,SAFU;QAAC,MAAM,EAAE,8BAA8B,CAAC;QAAC,MAAM,EAAE,6BAA6B,CAAA;KAAC,CAKvF;IAEF,aAAc;IAsBd,+CAEC;IAED;;;;;OAKG;IACH,SAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAIhB;IAED;;;;;OAKG;IACH,WAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAIhB;IAED;;;;;OAKG;IACH,yBAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAiDhB;IAED,6BAmDC;;CACJ;uBA9LsB,cAAc;4BAKT,6BAA6B;kCAEvB,wBAAwB;4CARd,oDAAoD;+CAUjD,qCAAqC;8CADtC,oCAAoC"}
+{"version":3,"file":"InverseKinematicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/InverseKinematicsSystem.js"],"names":[],"mappings":"AAeA;;;;;;;;GAQG;AACH;;IAEI,gEAAgD;IAEhD,mEAEE;IAEF;;;OAGG;IACH,SAFU;QAAC,MAAM,EAAE,8BAA8B,CAAC;QAAC,MAAM,EAAE,6BAA6B,CAAA;KAAC,CAKvF;IAEF,aAAc;IA8Bd,+CAEC;IAED;;;;;OAKG;IACH,SAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAIhB;IAED;;;;;OAKG;IACH,WAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAIhB;IAED;;;;;OAKG;IACH,yBAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAuDhB;IAED,6BAsDC;;CACJ;uBAhNsB,cAAc;4BAMT,6BAA6B;kCAEvB,wBAAwB;4CAVd,oDAAoD;+CAYjD,qCAAqC;8CADtC,oCAAoC"}

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

@@ -1,10 +1,12 @@
 import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { collect_entity_playbacks } from "../../graphics3/pose/collect_entity_playbacks.js";
 import { System } from "../System.js";
 import { obtainTerrain } from "../terrain/util/obtainTerrain.js";
 import {
     transform_attachment_find_descendant_by_name
 } from "../transform-attachment/transform_attachment_find_descendant_by_name.js";
+import { T64WorldCache } from "../transform/T64WorldCache.js";
 import { Transform64 } from "../transform/Transform64.js";
 import { IKProblem } from "./IKProblem.js";
 import { InverseKinematics } from "./InverseKinematics.js";
@@ -58,6 +60,14 @@ export class InverseKinematicsSystem extends System {
      */
     #terrain = null;
 
+    /**
+     * Evaluated worlds of the tick, for chains the GPU composes: the constraints on one model
+     * share its spine, and a socket asked twice is evaluated once.
+     *
+     * @type {T64WorldCache}
+     */
+    #cache = new T64WorldCache();
+
 
     get componentClass() {
         return InverseKinematics;
@@ -127,6 +137,12 @@ export class InverseKinematicsSystem extends System {
             problem.effector = effector;
             problem.terrain = this.#terrain;
 
+            // what the chain is evaluated against if the GPU composes it; a pooled problem keeps
+            // its list, so it is emptied before it is filled
+            problem.playbacks.length = 0;
+            collect_entity_playbacks(problem.playbacks, this.entityManager, entity);
+            problem.cache = this.#cache;
+
             const problemSet = this.problems[solverID];
 
             if (problemSet === undefined) {
@@ -156,6 +172,9 @@ export class InverseKinematicsSystem extends System {
         }
 
 
+        // last tick's answers are last tick's
+        this.#cache.invalidate();
+
         ecd.traverseEntities([InverseKinematics, Transform64], this.recordEntityProblems, this);
 
         //solve problems

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

@@ -47,9 +47,9 @@ const CHAIN = [new IKBone(), new IKBone()];
  */
 export class OneBoneSurfaceAlignmentSolver extends IKSolver {
     solve(problem) {
-        const { dataset, effector, constraint, terrain } = problem;
+        const { dataset, effector, constraint, terrain, playbacks, cache } = problem;
 
-        if (!ik_bone_chain(CHAIN, dataset, effector, 2)) {
+        if (!ik_bone_chain(CHAIN, dataset, effector, 2, playbacks, cache)) {
             // the hierarchy does not hold the bone and a parent to cast from
             return;
         }

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

@@ -41,9 +41,9 @@ export class TwoBoneInverseKinematicsSolver extends IKSolver {
 
     solve(problem) {
 
-        const { dataset, effector, terrain, constraint } = problem;
+        const { dataset, effector, terrain, constraint, playbacks, cache } = problem;
 
-        if (!ik_bone_chain(CHAIN, dataset, effector, 3)) {
+        if (!ik_bone_chain(CHAIN, dataset, effector, 3, playbacks, cache)) {
             // the hierarchy does not hold three links yet
             return;
         }

package/src/engine/ecs/ik/ik_bone_chain.d.ts

@@ -12,7 +12,7 @@
  * the effector, or when one of them is not a full transform pair. Neither is an error — a model
  * that has not finished arriving looks exactly like this
  */
-export function ik_bone_chain(result: IKBone[], dataset: EntityComponentDataset, effector: number, count: number): boolean;
+export function ik_bone_chain(result: IKBone[], dataset: EntityComponentDataset, effector: number, count: number, playbacks?: any, cache?: any): boolean;
 /**
  * One link of a chain the solvers work on: the entity, the world pose the hierarchy composed for
  * it, and the local pose that composition came from.
@@ -28,11 +28,20 @@ export class IKBone {
      */
     entity: number;
     /**
-     * Composed by {@link TransformAttachmentSystem}. Read only.
+     * The bone's world pose this frame. Read only.
+     *
+     * The component itself when the CPU composes the chain; {@link evaluated} when the GPU does,
+     * in which case the component holds whatever the CPU last composed and is not read.
      *
      * @type {Transform64|null}
      */
     world: Transform64 | null;
+    /**
+     * Where an evaluated world pose is written — see {@link ik_bone_chain}.
+     *
+     * @type {Transform64}
+     */
+    evaluated: Transform64;
     /**
      * Relative to the parent bone. This is what a solver writes.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"ik_bone_chain.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/ik_bone_chain.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;GAaG;AACH,sCARW,MAAM,EAAE,6CAER,MAAM,SACN,MAAM,GACJ,OAAO,CAwCnB;AA3FD;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,QAFU,MAAM,CAEJ;IAEZ;;;;OAIG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb;;;;OAIG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb;;;;;;;;OAQG;IACH,YAFU,mBAAmB,GAAC,IAAI,CAEhB;CACrB;4BAzC2B,6BAA6B;oCADrB,gDAAgD"}
+{"version":3,"file":"ik_bone_chain.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/ik_bone_chain.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;GAaG;AACH,sCARW,MAAM,EAAE,6CAER,MAAM,SACN,MAAM,iCACJ,OAAO,CAwEnB;AArID;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,QAFU,MAAM,CAEJ;IAEZ;;;;;;;OAOG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb;;;;OAIG;IACH,WAFU,WAAW,CAES;IAE9B;;;;OAIG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb;;;;;;;;OAQG;IACH,YAFU,mBAAmB,GAAC,IAAI,CAEhB;CACrB;4BApD2B,6BAA6B;oCADrB,gDAAgD"}

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

@@ -1,7 +1,10 @@
 import { assert } from "../../../core/assert.js";
+import { GPUStateAuthorityFlags } from "../gpu/GPUStateAuthorityFlags.js";
+import { gpu_authority_has } from "../gpu/gpu_authority_has.js";
 import { transform_attachment_parent_of } from "../transform-attachment/transform_attachment_parent_of.js";
 import { TransformAttachment } from "../transform-attachment/TransformAttachment.js";
 import { Transform64 } from "../transform/Transform64.js";
+import { t64_evaluate_world } from "../transform/t64_evaluate_world.js";
 
 /**
  * One link of a chain the solvers work on: the entity, the world pose the hierarchy composed for
@@ -19,12 +22,22 @@ export class IKBone {
     entity = -1;
 
     /**
-     * Composed by {@link TransformAttachmentSystem}. Read only.
+     * The bone's world pose this frame. Read only.
+     *
+     * The component itself when the CPU composes the chain; {@link evaluated} when the GPU does,
+     * in which case the component holds whatever the CPU last composed and is not read.
      *
      * @type {Transform64|null}
      */
     world = null;
 
+    /**
+     * Where an evaluated world pose is written — see {@link ik_bone_chain}.
+     *
+     * @type {Transform64}
+     */
+    evaluated = new Transform64();
+
     /**
      * Relative to the parent bone. This is what a solver writes.
      *
@@ -58,7 +71,7 @@ export class IKBone {
  * the effector, or when one of them is not a full transform pair. Neither is an error — a model
  * that has not finished arriving looks exactly like this
  */
-export function ik_bone_chain(result, dataset, effector, count) {
+export function ik_bone_chain(result, dataset, effector, count, playbacks = null, cache = null) {
     assert.isNonNegativeInteger(effector, 'effector');
     assert.isNonNegativeInteger(count, 'count');
     assert.ok(result.length >= count, 'result is too short for the requested chain');
@@ -93,5 +106,37 @@ export function ik_bone_chain(result, dataset, effector, count) {
         entity = transform_attachment_parent_of(dataset, entity);
     }
 
+    /*
+     A bone under a GPU-composed ancestor holds the world the CPU last composed, not this frame's:
+     the chain is then evaluated exactly from the clips, which is what the GPU is drawing. The
+     flag sits on the whole subtree below a driven joint, so the effector carries it whenever any
+     bone above does; every bone is checked all the same, because that is cheap and the invariant
+     is the animation manager's, not this walk's.
+    */
+    let gpu_composed = false;
+
+    for (let i = 0; i < count; i++) {
+        if (gpu_authority_has(dataset, result[i].entity, GPUStateAuthorityFlags.Transform64)) {
+            gpu_composed = true;
+            break;
+        }
+    }
+
+    if (gpu_composed) {
+        assert.defined(playbacks, 'playbacks: the chain is GPU-composed, so its world poses have to be evaluated');
+
+        for (let i = 0; i < count; i++) {
+            const bone = result[i];
+
+            if (cache !== null) {
+                cache.evaluate(bone.evaluated, dataset, bone.entity, playbacks);
+            } else {
+                t64_evaluate_world(bone.evaluated, dataset, bone.entity, playbacks);
+            }
+
+            bone.world = bone.evaluated;
+        }
+    }
+
     return true;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"ik_write_local_rotation.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/ik_write_local_rotation.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,mHAOC"}
+{"version":3,"file":"ik_write_local_rotation.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/ik_write_local_rotation.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,mHAWC"}

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

@@ -1,3 +1,5 @@
+import { GPUStateAuthorityFlags } from "../gpu/GPUStateAuthorityFlags.js";
+import { gpu_authority_assert_cpu } from "../gpu/gpu_authority_assert_cpu.js";
 import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
 
 /**
@@ -17,6 +19,10 @@ import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../transform-attachment/TRANS
  * @param {Quaternion} rotation
  */
 export function ik_write_local_rotation(dataset, bone, rotation) {
+    // A clip-driven bone's offset is the GPU's: the pose accumulator writes its row every frame
+    // and the flush would not carry this write over it. IK moves bones no clip drives.
+    gpu_authority_assert_cpu(dataset, bone.entity, GPUStateAuthorityFlags.TransformAttachment);
+
     const local = bone.local;
 
     local.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);

package/src/engine/ecs/speaker/VoiceSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VoiceSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/speaker/VoiceSystem.js"],"names":[],"mappings":"AA+JA;IA2CI;;;;OAIG;IACH;;;OA8CC;IA7FD,+BAAuB;IACvB,gZAQE;IAEF;;;OAGG;IACH,0BAAmB;IAEnB;;;OAGG;IACH,eAAW;IAEX;;;OAGG;IACH,4BAAa;IAEb;;;OAGG;IACH,8BAAY;IAEZ;;;;OAIG;IACH,iCAAqC;IAajC;;;OAGG;IACH,eAAoB;IAEpB;;;;OAIG;IACH,kBAAkC;IAGlC;;;;OAIG;IACH,eAAkB;IAElB;;;;OAIG;IACH,oBAAgC;IAEhC;;;OAGG;IACH,oBAAqC;IAErC;;;;OAIG;IACH,gBAAoB;IAGxB;;;OAGG;IACH,kBAFY,MAAM,CAIjB;IAEF,2CAqBE;IAED;;;;;OAKG;IACH,uBAJW,MAAM,UACN,MAAM,SACN,KAAK,QAsBf;IAED;;;;;;OAMG;IACH,wBAoBC;IAED;;;;;OAKG;IACH,gBAJW,MAAM,WACN,MAAM,SACN,KAAK,QA6Hf;CACJ;sCA/bqC,oCAAoC;sBAKpD,YAAY;4BAFN,6BAA6B;4CAxBb,oDAAoD;uBAkBzE,sBAAsB;6BAEhB,qCAAqC;2BADvC,8BAA8B;oCAIrB,gDAAgD;sCAR9C,wCAAwC;kCAP5C,sDAAsD"}
+{"version":3,"file":"VoiceSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/speaker/VoiceSystem.js"],"names":[],"mappings":"AAiKA;IA2CI;;;;OAIG;IACH;;;OA8CC;IA7FD,+BAAuB;IACvB,gZAQE;IAEF;;;OAGG;IACH,0BAAmB;IAEnB;;;OAGG;IACH,eAAW;IAEX;;;OAGG;IACH,4BAAa;IAEb;;;OAGG;IACH,8BAAY;IAEZ;;;;OAIG;IACH,iCAAqC;IAajC;;;OAGG;IACH,eAAoB;IAEpB;;;;OAIG;IACH,kBAAkC;IAGlC;;;;OAIG;IACH,eAAkB;IAElB;;;;OAIG;IACH,oBAAgC;IAEhC;;;OAGG;IACH,oBAAqC;IAErC;;;;OAIG;IACH,gBAAoB;IAGxB;;;OAGG;IACH,kBAFY,MAAM,CAIjB;IAEF,2CAqBE;IAED;;;;;OAKG;IACH,uBAJW,MAAM,UACN,MAAM,SACN,KAAK,QAsBf;IAED;;;;;;OAMG;IACH,wBAoBC;IAED;;;;;OAKG;IACH,gBAJW,MAAM,WACN,MAAM,SACN,KAAK,QAiIf;CACJ;sCAncqC,oCAAoC;sBAKpD,YAAY;4BAFN,6BAA6B;4CAxBb,oDAAoD;uBAkBzE,sBAAsB;6BAEhB,qCAAqC;2BADvC,8BAA8B;oCAIrB,gDAAgD;sCAR9C,wCAAwC;kCAP5C,sDAAsD"}

package/src/engine/ecs/speaker/VoiceSystem.js

@@ -1,4 +1,6 @@
 import { assert } from "../../../core/assert.js";
+import { GPUStateAuthorityFlags } from "../gpu/GPUStateAuthorityFlags.js";
+import { gpu_authority_assert_cpu } from "../gpu/gpu_authority_assert_cpu.js";
 import { weightedRandomFromArray } from "../../../core/collection/array/weightedRandomFromArray.js";
 import Vector2 from "../../../core/geom/Vector2.js";
 import { max2 } from "../../../core/math/max2.js";
@@ -407,6 +409,10 @@ export class VoiceSystem extends AbstractContextSystem {
         const source_transform = ecd.getComponent(entity, Transform64);
 
         if (source_transform !== undefined) {
+            // a speaker is placed by its own entity; one under a GPU-composed joint would have
+            // to be read back, which nothing here does yet
+            gpu_authority_assert_cpu(ecd, entity, GPUStateAuthorityFlags.Transform64);
+
             transform.copy(source_transform);
         }
 

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

@@ -0,0 +1,50 @@
+/**
+ * @typedef {import("../EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ * @typedef {import("../../../shade/renderer/animation/pose/PosePlayback.js").PosePlayback} PosePlayback
+ */
+/**
+ * {@link t64_evaluate_world}, memoised per entity for the length of a tick.
+ *
+ * An exact evaluation walks the chain to the root and evaluates every level's clips; a socket on a
+ * hand is fourteen levels deep on a character, and the sockets a game asks about share most of
+ * that chain. Within a tick the inputs — the hierarchy, the clip set, the times, the weights — do
+ * not move, so each entity's world is evaluated once and every query below it composes onto the
+ * stored answer. Measured on a 70-joint skeleton with two clips: 764 µs to evaluate every joint
+ * one query at a time, 160 µs through the cache.
+ *
+ * **One cache per tick, per model.** The answer for an entity depends on the playbacks it was
+ * evaluated under, and the cache does not check them: a caller that changes what a model plays
+ * between queries calls {@link invalidate} in between, and calls it once per tick regardless.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class T64WorldCache {
+    /**
+     * How many entities hold an evaluated world right now.
+     *
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Forget every evaluated world. Once per tick, and again whenever a model's playbacks change
+     * within one.
+     */
+    invalidate(): void;
+    /**
+     * The entity's world pose under the playbacks, exactly — the same answer as
+     * {@link t64_evaluate_world}, from the cache where it has it.
+     *
+     * @param {Transform64} result
+     * @param {EntityComponentDataset} dataset
+     * @param {number} entity
+     * @param {PosePlayback[]} playbacks
+     * @returns {Transform64} `result`
+     */
+    evaluate(result: Transform64, dataset: EntityComponentDataset, entity: number, playbacks: PosePlayback[]): Transform64;
+    #private;
+}
+export type EntityComponentDataset = import("../EntityComponentDataset.js").EntityComponentDataset;
+export type PosePlayback = import("../../../shade/renderer/animation/pose/PosePlayback.js").PosePlayback;
+import { Transform64 } from "./Transform64.js";
+//# sourceMappingURL=T64WorldCache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"T64WorldCache.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/T64WorldCache.js"],"names":[],"mappings":"AAKA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IAsBI;;;;OAIG;IACH,mBAEC;IAED;;;OAGG;IACH,mBAQC;IAED;;;;;;;;;OASG;IACH,iBANW,WAAW,WACX,sBAAsB,UACtB,MAAM,aACN,YAAY,EAAE,GACZ,WAAW,CAWvB;;CA+CJ;qCApIY,OAAO,8BAA8B,EAAE,sBAAsB;2BAC7D,OAAO,wDAAwD,EAAE,YAAY;4BAJ9D,kBAAkB"}