@woosh/meep-engine 3.40.0 → 3.42.0

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

@@ -0,0 +1,1456 @@
+import { assert } from "../../../core/assert.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { pose_evaluate_local } from "../../../shade/renderer/animation/pose/pose_evaluate_local.js";
+import { AnimationGraphController } from "../../graphics3/animation/AnimationGraphController.js";
+import { collect_entity_playbacks } from "../../graphics3/pose/collect_entity_playbacks.js";
+import { FrameFabrikProblem } from "../../physics/inverse_kinematics/frame_fabrik/FrameFabrikProblem.js";
+import { frame_fabrik_limit_from_joint } from "../../physics/inverse_kinematics/frame_fabrik/frame_fabrik_limit_from_joint.js";
+import { frame_fabrik_solve } from "../../physics/inverse_kinematics/frame_fabrik/frame_fabrik_solve.js";
+import { joint_hinge_mid_axis } from "../../physics/inverse_kinematics/joint_hinge_mid_axis.js";
+import { two_bone_path_solve } from "../../physics/inverse_kinematics/two_bone_path_solve.js";
+import { Joint } from "../../physics/ecs/Joint.js";
+import { Animation } from "../animation/Animation.js";
+import { EventType } from "../EventType.js";
+import { GPUStateAuthority } from "../gpu/GPUStateAuthority.js";
+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 { System } from "../System.js";
+import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
+import { TransformAttachment } from "../transform-attachment/TransformAttachment.js";
+import { T64WorldCache } from "../transform/T64WorldCache.js";
+import {
+    Transform64,
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_SCALE_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET
+} from "../transform/Transform64.js";
+import { IKGoal } from "./IKGoal.js";
+
+/**
+ * A bone IK holds: what it was before the hold, which goals need it.
+ */
+class IKHeldBone {
+    /**
+     * @type {number}
+     */
+    entity = -1;
+
+    /**
+     * The bone's offset when IK took it: its authored local pose, the rest every clip evaluates
+     * from, and what IK writes back when it lets go.
+     * @type {Transform64}
+     */
+    captured = new Transform64();
+
+    /**
+     * @type {TransformAttachment|null}
+     */
+    attachment = null;
+
+    /**
+     * How many goals' paths hold it.
+     * @type {number}
+     */
+    count = 0;
+}
+
+/**
+ * One linked goal.
+ */
+class IKGoalRecord {
+    /**
+     * The effector.
+     * @type {number}
+     */
+    entity = -1;
+
+    /**
+     * @type {IKGoal|null}
+     */
+    goal = null;
+
+    /**
+     * Effector first, up to and including the chain root.
+     * @type {number[]}
+     */
+    path = [];
+
+    /**
+     * Whose clips drive the path: the model the effector belongs to.
+     * @type {number}
+     */
+    model = -1;
+
+    /**
+     * Its target's model, likewise.
+     * @type {number}
+     */
+    target_model = -1;
+
+    /**
+     * The knee's hinge, for a two-bone path.
+     * @type {Vector3}
+     */
+    mid_axis = new Vector3();
+
+    /**
+     * A rejected goal holds nothing and pulls on nothing.
+     * @type {boolean}
+     */
+    rejected = false;
+
+    /**
+     * Its removal listeners are on.
+     * @type {boolean}
+     */
+    listening = false;
+
+    /**
+     * @type {IKGoalSystem|null}
+     */
+    system = null;
+
+    /**
+     * The target or a bone of the path is gone, so the goal goes too.
+     */
+    handle_removal() {
+        if (!this.listening) {
+            // a stale dispatch: the listener list is copied before it is walked
+            return;
+        }
+
+        const dataset = this.system.entityManager.dataset;
+
+        if (dataset.entityExists(this.entity)) {
+            dataset.removeComponentFromEntity(this.entity, IKGoal);
+        }
+    }
+}
+
+/**
+ * Connected paths, solved together: goals whose paths share a bone.
+ */
+class IKGroup {
+    /**
+     * @type {IKGoalRecord[]}
+     */
+    goals = [];
+
+    /**
+     * Every bone of the paths, parents before children; the first is the group's top.
+     * @type {number[]}
+     */
+    joints = [];
+
+    /**
+     * @type {Map<number, number>}
+     */
+    index = new Map();
+
+    /**
+     * Each bone's parent within the group, or -1 for the top.
+     * @type {Int32Array|null}
+     */
+    parent = null;
+
+    /**
+     * The top's parent, which the group does not pose.
+     * @type {number}
+     */
+    top_parent = -1;
+
+    /**
+     * Whose clips drive the bones.
+     * @type {number}
+     */
+    model = -1;
+
+    /**
+     * One goal on a path of three bones: solved analytically.
+     * @type {boolean}
+     */
+    two_bone = false;
+
+    /**
+     * @type {FrameFabrikProblem|null}
+     */
+    problem = null;
+
+    /**
+     * The animated pose of each bone, local and composed.
+     * @type {Transform64[]}
+     */
+    base_local = [];
+
+    /**
+     * @type {Transform64[]}
+     */
+    base_world = [];
+
+    /**
+     * The world pose of {@link top_parent}.
+     * @type {Transform64}
+     */
+    above = new Transform64();
+
+    /**
+     * Groups that solve first: this one's bones, or its targets, hang below theirs.
+     * @type {IKGroup[]}
+     */
+    after = [];
+
+    /**
+     * @type {boolean}
+     */
+    rejected = false;
+}
+
+const scratch_world = new Transform64();
+const scratch_target = new Transform64();
+
+const v_relative = new Vector3();
+
+const v_a = new Vector3();
+const v_b = new Vector3();
+const v_c = new Vector3();
+const v_t = new Vector3();
+
+const q_a_world = new Quaternion();
+const q_b_world = new Quaternion();
+const q_a_local = new Quaternion();
+const q_b_local = new Quaternion();
+const q_c_local = new Quaternion();
+const q_target = new Quaternion();
+
+const q_0 = new Quaternion();
+const q_1 = new Quaternion();
+const q_2 = new Quaternion();
+
+/**
+ * Brings bones to their goals ({@link IKGoal}): frame FABRIK over the connected paths of a model, or,
+ * for a lone path of three bones, the analytic two-bone solve.
+ *
+ * **IK holds the bones it poses** (`gpu_authority_hold` on their {@link TransformAttachment}), as
+ * cloth holds a cape's. The animation manager mutes every clip binding that names a held bone, and
+ * everything downstream — the GPU hierarchy, `t64_evaluate_world`, sockets, cloth anchors — reads the
+ * held offset, which IK writes every tick. Nothing downstream knows IK exists.
+ *
+ * - **Link:** a goal's path is held bone by bone, each offset captured, and the animated pose
+ *   written at once, so no frame shows the bind pose.
+ * - **Every tick:** each bone's animated local pose is evaluated from its clips with the captured
+ *   offset as its rest (`pose_evaluate_local`, never a held offset, which is IK's own answer), the
+ *   paths are solved, and each held bone's whole local pose is written: translation, rotation and
+ *   scale, since a hold mutes every channel.
+ * - **Unlink:** the captured offset is written back and the hold ended, for every bone no other goal
+ *   still needs.
+ *
+ * A goal is rejected, holding nothing, for a chain root that is not the effector or an ancestor of
+ * it, a chain root that is no bone, a target that is gone or hangs below the goal's own path, a
+ * two-bone path whose knee has no bend side, and a cycle of groups each waiting on another. Each is a
+ * real branch and an assert, because asserts are stripped in production.
+ *
+ * A target hanging below another goal's bones in the same group is read from the solver's frames on
+ * every iteration. One hanging below another group's bones waits for that group to solve and write.
+ *
+ * Declared access: IK reads {@link Animation} and {@link AnimationGraphController}, which their
+ * drivers write, so it runs after the drivers have set this tick's clip times. A system that places a
+ * target through its own `TransformAttachment` (a physics contact probe) reads and writes that
+ * component as IK does: declared access leaves the two a cycle, and the scheduler keeps their
+ * registration order, so register it first.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class IKGoalSystem extends System {
+
+    dependencies = [IKGoal, TransformAttachment];
+
+    components_used = [
+        ResourceAccessSpecification.from(IKGoal, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(TransformAttachment, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(GPUStateAuthority, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(ParentEntity, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Joint, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Animation, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(AnimationGraphController, ResourceAccessKind.Read),
+    ];
+
+    /**
+     * The most iterations a frame FABRIK solve runs.
+     * @type {number}
+     */
+    max_iterations = 16;
+
+    /**
+     * A frame FABRIK solve stops once an iteration moves no bone this far, in world units.
+     * @type {number}
+     */
+    tolerance = 1e-6;
+
+    /**
+     * By effector.
+     * @type {Map<number, IKGoalRecord>}
+     */
+    #records = new Map();
+
+    /**
+     * By bone.
+     * @type {Map<number, IKHeldBone>}
+     */
+    #held = new Map();
+
+    /**
+     * Groups in the order they solve.
+     * @type {IKGroup[]}
+     */
+    #groups = [];
+
+    /**
+     * Goals came or went since the groups were built.
+     * @type {boolean}
+     */
+    #dirty = false;
+
+    /**
+     * What each model plays this tick.
+     * @type {Map<number, PosePlayback[]>}
+     */
+    #playbacks = new Map();
+
+    /**
+     * Exact worlds of this tick per model, forgotten whenever a group writes.
+     * @type {Map<number, T64WorldCache>}
+     */
+    #caches = new Map();
+
+    /**
+     * The same caches, to walk without an iterator.
+     * @type {T64WorldCache[]}
+     */
+    #cache_list = [];
+
+    /**
+     * Which models' playbacks were collected this tick.
+     * @type {Set<number>}
+     */
+    #collected = new Set();
+
+    /**
+     * @param {IKGoal} goal
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    link(goal, attachment, entity) {
+        const dataset = this.entityManager.dataset;
+
+        const record = new IKGoalRecord();
+
+        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;
+
+        this.#records.set(entity, record);
+
+        const problem = this.#validate(record);
+
+        if (problem === "") {
+            for (let i = 0; i < record.path.length; i++) {
+                this.#hold(record.path[i], record.model);
+            }
+        } else {
+            record.rejected = true;
+        }
+
+        this.#listen(record);
+
+        this.#dirty = true;
+
+        assert.equal(problem, "", `IKGoal on entity ${entity} is rejected`);
+
+        this.#assert_limits(record);
+    }
+
+    /**
+     * @param {IKGoal} goal
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    unlink(goal, attachment, entity) {
+        const record = this.#records.get(entity);
+
+        if (record === undefined) {
+            return;
+        }
+
+        this.#records.delete(entity);
+
+        this.#unlisten(record);
+
+        if (!record.rejected) {
+            this.#release_path(record);
+        }
+
+        this.#dirty = true;
+    }
+
+    update(time_delta_seconds) {
+        const dataset = this.entityManager.dataset;
+
+        if (dataset === null || dataset === undefined) {
+            return;
+        }
+
+        if (this.#dirty) {
+            this.#regroup();
+        }
+
+        this.#collected.clear();
+
+        const groups = this.#groups;
+
+        for (let i = 0; i < groups.length; i++) {
+            const group = groups[i];
+
+            if (group.rejected) {
+                continue;
+            }
+
+            // everything evaluated so far may sit below what the last group wrote
+            this.#forget_worlds();
+
+            if (group.two_bone) {
+                this.#solve_two_bone(group);
+            } else {
+                this.#solve_fabrik(group);
+            }
+        }
+    }
+
+    // --- link ---
+
+    /**
+     * Walk the goal's path and check it, filling `record.path`.
+     *
+     * @param {IKGoalRecord} record
+     * @returns {string} why the goal is rejected, or empty
+     */
+    #validate(record) {
+        const dataset = this.entityManager.dataset;
+        const goal = record.goal;
+
+        const path = record.path;
+
+        path.length = 0;
+
+        let bone = record.entity;
+
+        while (true) {
+            const attachment = dataset.getComponent(bone, TransformAttachment);
+
+            if (attachment === undefined || attachment === null) {
+                return `bone ${bone} on the way up to chain_root ${goal.chain_root} has no TransformAttachment: the chain root is no bone, or no ancestor of the effector`;
+            }
+
+            path.push(bone);
+
+            if (bone === goal.chain_root) {
+                break;
+            }
+
+            bone = attachment.parent;
+
+            if (bone < 0 || !dataset.entityExists(bone)) {
+                return `chain_root ${goal.chain_root} is not the effector or one of its ancestors`;
+            }
+        }
+
+        if (!dataset.entityExists(goal.target)) {
+            return `target ${goal.target} does not exist`;
+        }
+
+        // a target the effector carries moves with every answer; one below another bone of the path
+        // is found when the groups are known, since another goal's bones may carry it in between
+        for (let e = goal.target; e >= 0 && dataset.entityExists(e);) {
+            if (e === record.entity) {
+                return `target ${goal.target} hangs below its own effector: it would chase the answer`;
+            }
+
+            const attachment = dataset.getComponent(e, TransformAttachment);
+
+            if (attachment === undefined || attachment === null) {
+                break;
+            }
+
+            e = attachment.parent;
+        }
+
+        if (path.length === 3) {
+            const knee = path[1];
+
+            const joint = dataset.getComponent(knee, Joint);
+
+            if (joint === undefined || joint === null || !joint_hinge_mid_axis(record.mid_axis, joint)) {
+                return `the knee ${knee} of a two-bone path has no bend side: it needs a physics Joint hinged with limits that reach further one way`;
+            }
+        }
+
+        return "";
+    }
+
+    /**
+     * The physics Joint on each bone of the path is that bone's limit, read as physics reads it:
+     * `entityA` the parent bone, frames that agree at the bone's rest, angles by swing and twist.
+     *
+     * @param {IKGoalRecord} record
+     */
+    #assert_limits(record) {
+        const dataset = this.entityManager.dataset;
+        const path = record.path;
+
+        for (let i = 0; i < path.length; i++) {
+            const joint = dataset.getComponent(path[i], Joint);
+
+            if (joint === undefined || joint === null) {
+                continue;
+            }
+
+            const held = this.#held.get(path[i]);
+
+            const attachment = dataset.getComponent(path[i], TransformAttachment);
+
+            assert.equal(joint.entityA, attachment.parent, `the Joint on bone ${path[i]} has entityA ${joint.entityA}, not its parent bone ${attachment.parent}`);
+            assert.ok(joint.swingTwist === true, `the Joint on bone ${path[i]} measures its angles by swing and twist (swingTwist), as IK clamps them`);
+            assert.ok(basis_a_is_rest_times_b(joint, held === undefined ? attachment.transform : held.captured), `the Joint on bone ${path[i]} has localBasisA = rest_local * localBasisB`);
+        }
+    }
+
+    /**
+     * Remove the goal when its target or a bone of its path is destroyed, as `TransformAttachment`
+     * goes when its parent does.
+     *
+     * @param {IKGoalRecord} record
+     */
+    #listen(record) {
+        const dataset = this.entityManager.dataset;
+
+        if (dataset.entityExists(record.goal.target)) {
+            dataset.addEntityEventListener(record.goal.target, EventType.EntityRemoved, record.handle_removal, record);
+        }
+
+        // the effector's own removal takes the component with it
+        for (let i = 1; i < record.path.length; i++) {
+            dataset.addEntityEventListener(record.path[i], EventType.EntityRemoved, record.handle_removal, record);
+        }
+
+        record.listening = true;
+    }
+
+    /**
+     * @param {IKGoalRecord} record
+     */
+    #unlisten(record) {
+        if (!record.listening) {
+            return;
+        }
+
+        record.listening = false;
+
+        const dataset = this.entityManager.dataset;
+
+        if (dataset.entityExists(record.goal.target)) {
+            dataset.removeEntityEventListener(record.goal.target, EventType.EntityRemoved, record.handle_removal, record);
+        }
+
+        for (let i = 1; i < record.path.length; i++) {
+            if (dataset.entityExists(record.path[i])) {
+                dataset.removeEntityEventListener(record.path[i], EventType.EntityRemoved, record.handle_removal, record);
+            }
+        }
+    }
+
+    /**
+     * Hold a bone for one more goal; the first takes it, captures its offset and writes its animated
+     * pose at once.
+     *
+     * @param {number} entity
+     * @param {number} model
+     */
+    #hold(entity, model) {
+        const existing = this.#held.get(entity);
+
+        if (existing !== undefined) {
+            existing.count++;
+            return;
+        }
+
+        const dataset = this.entityManager.dataset;
+
+        const attachment = dataset.getComponent(entity, TransformAttachment);
+
+        const held = new IKHeldBone();
+
+        held.entity = entity;
+        held.attachment = attachment;
+        held.captured.copy(attachment.transform);
+        held.count = 1;
+
+        this.#held.set(entity, held);
+
+        // trips the existing assert if another CPU writer (cloth) holds it already
+        gpu_authority_hold(dataset, entity, GPUStateAuthorityFlags.TransformAttachment);
+
+        // the clip's pose, not the bind pose the offset holds, from the first frame of the hold
+        pose_evaluate_local(attachment.transform, entity, held.captured, this.#playbacks_of(model));
+
+        attachment.transform.updateMatrix();
+
+        dataset.sendEvent(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE);
+    }
+
+    /**
+     * Release one goal's hold on each bone of its path; a bone no goal holds any more gets its captured
+     * offset back and its hold ended.
+     *
+     * @param {IKGoalRecord} record
+     */
+    #release_path(record) {
+        const dataset = this.entityManager.dataset;
+
+        for (let i = 0; i < record.path.length; i++) {
+            const entity = record.path[i];
+
+            const held = this.#held.get(entity);
+
+            if (held === undefined) {
+                continue;
+            }
+
+            held.count--;
+
+            if (held.count > 0) {
+                continue;
+            }
+
+            this.#held.delete(entity);
+
+            if (!dataset.entityExists(entity)) {
+                continue;
+            }
+
+            held.attachment.transform.copy(held.captured);
+
+            dataset.sendEvent(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE);
+
+            const authority = dataset.getComponent(entity, GPUStateAuthority);
+
+            if (authority !== undefined && authority !== null && (authority.held & GPUStateAuthorityFlags.TransformAttachment) !== 0) {
+                gpu_authority_unhold(dataset, entity, GPUStateAuthorityFlags.TransformAttachment);
+            }
+        }
+    }
+
+    // --- groups ---
+
+    /**
+     * Group the goals by connected paths, order the groups by what hangs below what, and reject
+     * the groups of a cycle.
+     */
+    #regroup() {
+        this.#dirty = false;
+
+        const dataset = this.entityManager.dataset;
+
+        let groups;
+        let group_of_bone;
+        let rejected_by_carrier = false;
+
+        // a goal rejected for its target leaves the groups, which are then formed again without it
+        while (true) {
+            group_of_bone = new Map();
+            groups = form_groups(this.#records, group_of_bone);
+
+            let rejected = false;
+
+            for (let i = 0; i < groups.length; i++) {
+                const group = groups[i];
+
+                for (let g = 0; g < group.goals.length; g++) {
+                    const record = group.goals[g];
+
+                    if (carrier_on_own_path(record, group_of_bone, dataset)) {
+                        record.rejected = true;
+                        this.#release_path(record);
+                        rejected = true;
+                    }
+                }
+            }
+
+            if (!rejected) {
+                break;
+            }
+
+            rejected_by_carrier = true;
+        }
+
+        for (let i = 0; i < groups.length; i++) {
+            build_group(groups[i], dataset);
+        }
+
+        // what each group waits on: groups whose bones its top or its targets hang below
+        for (let i = 0; i < groups.length; i++) {
+            const group = groups[i];
+
+            add_waits(group, group.top_parent, group_of_bone, dataset);
+
+            for (let g = 0; g < group.goals.length; g++) {
+                add_waits(group, group.goals[g].goal.target, group_of_bone, dataset);
+            }
+        }
+
+        // order: Tarjan's components come out with every component a group waits on before it; a
+        // component of more than one group is a cycle, and every group on it is rejected
+        const ordered = order_groups(groups);
+
+        for (let i = 0; i < groups.length; i++) {
+            const group = groups[i];
+
+            if (!group.rejected) {
+                continue;
+            }
+
+            for (let g = 0; g < group.goals.length; g++) {
+                const record = group.goals[g];
+
+                if (record.rejected) {
+                    continue;
+                }
+
+                record.rejected = true;
+
+                this.#release_path(record);
+            }
+        }
+
+        this.#groups = ordered;
+
+        let cycle = false;
+
+        for (let i = 0; i < groups.length; i++) {
+            cycle = cycle || groups[i].rejected;
+        }
+
+        assert.notOk(rejected_by_carrier, 'an IK goal\'s target hangs below a bone of its own path, with no other goal\'s bone in between: it would chase the answer');
+        assert.notOk(cycle, 'IK groups wait on each other in a cycle: each one\'s bones or targets hang below the other\'s');
+    }
+
+    // --- solve ---
+
+    /**
+     * @param {number} model
+     * @returns {PosePlayback[]}
+     */
+    #playbacks_of(model) {
+        let list = this.#playbacks.get(model);
+
+        if (list === undefined) {
+            list = [];
+            this.#playbacks.set(model, list);
+        }
+
+        if (!this.#collected.has(model)) {
+            this.#collected.add(model);
+
+            list.length = 0;
+
+            if (model >= 0) {
+                collect_entity_playbacks(list, this.entityManager, model);
+            }
+        }
+
+        return list;
+    }
+
+    /**
+     * @param {number} model
+     * @returns {T64WorldCache}
+     */
+    #cache_of(model) {
+        let cache = this.#caches.get(model);
+
+        if (cache === undefined) {
+            cache = new T64WorldCache();
+            this.#caches.set(model, cache);
+            this.#cache_list.push(cache);
+        }
+
+        return cache;
+    }
+
+    #forget_worlds() {
+        const caches = this.#cache_list;
+
+        for (let i = 0; i < caches.length; i++) {
+            caches[i].invalidate();
+        }
+    }
+
+    /**
+     * The world pose of `entity` this tick, exactly.
+     *
+     * @param {Transform64} result
+     * @param {number} entity
+     * @param {number} model
+     */
+    #world_of(result, entity, model) {
+        this.#cache_of(model).evaluate(result, this.entityManager.dataset, entity, this.#playbacks_of(model));
+    }
+
+    /**
+     * The group's bones as animated, local and composed under the frame above the group.
+     *
+     * @param {IKGroup} group
+     */
+    #evaluate_base(group) {
+        const playbacks = this.#playbacks_of(group.model);
+
+        if (group.top_parent >= 0) {
+            this.#world_of(group.above, group.top_parent, group.model);
+        } else {
+            group.above.makeIdentity();
+        }
+
+        const joints = group.joints;
+
+        for (let j = 0; j < joints.length; j++) {
+            const held = this.#held.get(joints[j]);
+
+            const local = group.base_local[j];
+
+            pose_evaluate_local(local, joints[j], held.captured, playbacks);
+
+            local.updateMatrix();
+
+            const p = group.parent[j];
+
+            group.base_world[j].multiplyTransforms(p < 0 ? group.above : group.base_world[p], local);
+        }
+    }
+
+    /**
+     * Where a goal's target is, as animated, into `result`, and which bone of the group carries it:
+     * the deepest one it hangs below, or -1 for a target the group does not move.
+     *
+     * @param {Transform64} result
+     * @param {IKGroup} group
+     * @param {IKGoalRecord} record
+     * @returns {number} index of the carrying bone in the group, or -1
+     */
+    #target_of(result, group, record) {
+        const dataset = this.entityManager.dataset;
+        const target = record.goal.target;
+
+        this.#world_of(result, target, record.target_model);
+
+        let carrier = -1;
+
+        for (let e = target; e >= 0;) {
+            const index = group.index.get(e);
+
+            if (index !== undefined) {
+                carrier = index;
+                break;
+            }
+
+            const attachment = dataset.getComponent(e, TransformAttachment);
+
+            if (attachment === undefined || attachment === null) {
+                break;
+            }
+
+            e = attachment.parent;
+        }
+
+        if (carrier < 0) {
+            return -1;
+        }
+
+        // the target relative to its carrier is the same whichever pose the carrier is in: put it
+        // under the carrier as animated
+        const carrier_world = scratch_world;
+        const carrier_base = group.base_world[carrier];
+
+        this.#world_of(carrier_world, group.joints[carrier], record.target_model);
+
+        // relative = conj(R_c) (P_t - P_c) / s_c, and conj(R_c) R_t
+        read_rotation(q_2, carrier_world);
+        q_2.conjugate();
+
+        v_relative.set(
+            result[TRANSFORM64_TRANSLATION_OFFSET] - carrier_world[TRANSFORM64_TRANSLATION_OFFSET],
+            result[TRANSFORM64_TRANSLATION_OFFSET + 1] - carrier_world[TRANSFORM64_TRANSLATION_OFFSET + 1],
+            result[TRANSFORM64_TRANSLATION_OFFSET + 2] - carrier_world[TRANSFORM64_TRANSLATION_OFFSET + 2]
+        );
+
+        v_relative.applyQuaternion(q_2);
+
+        // uniform scale: the same bone, animated and held, differs by nothing else
+        v_relative.multiplyScalar(carrier_base[TRANSFORM64_SCALE_OFFSET] / carrier_world[TRANSFORM64_SCALE_OFFSET]);
+
+        read_rotation(q_1, result);
+        q_2.multiply(q_1);
+
+        // under the carrier as animated
+        read_rotation(q_1, carrier_base);
+
+        v_relative.applyQuaternion(q_1);
+
+        q_1.multiply(q_2);
+
+        result.setTranslation(
+            carrier_base[TRANSFORM64_TRANSLATION_OFFSET] + v_relative.x,
+            carrier_base[TRANSFORM64_TRANSLATION_OFFSET + 1] + v_relative.y,
+            carrier_base[TRANSFORM64_TRANSLATION_OFFSET + 2] + v_relative.z
+        );
+
+        result.setRotation(q_1.x, q_1.y, q_1.z, q_1.w);
+
+        return carrier;
+    }
+
+    /**
+     * @param {IKGroup} group
+     */
+    #solve_fabrik(group) {
+        this.#evaluate_base(group);
+
+        const problem = group.problem;
+        const joints = group.joints;
+        const n = joints.length;
+
+        problem.joint_count = n;
+        problem.goal_count = group.goals.length;
+
+        for (let j = 0; j < n; j++) {
+            const world = group.base_world[j];
+            const local = group.base_local[j];
+
+            problem.joint_parent[j] = group.parent[j];
+
+            copy3(problem.base_position, j * 3, world, TRANSFORM64_TRANSLATION_OFFSET);
+            copy4(problem.base_rotation, j * 4, world, TRANSFORM64_ROTATION_OFFSET);
+            copy4(problem.base_local_rotation, j * 4, local, TRANSFORM64_ROTATION_OFFSET);
+        }
+
+        for (let g = 0; g < group.goals.length; g++) {
+            const record = group.goals[g];
+            const goal = record.goal;
+
+            problem.goal_effector[g] = group.index.get(record.entity);
+            problem.goal_root[g] = group.index.get(goal.chain_root);
+            problem.goal_weight[g] = goal.position_weight;
+
+            problem.goal_target_joint[g] = this.#target_of(scratch_target, group, record);
+
+            copy3(problem.goal_target, g * 3, scratch_target, TRANSFORM64_TRANSLATION_OFFSET);
+        }
+
+        frame_fabrik_solve(problem, this.max_iterations, this.tolerance);
+
+        const rotation = problem.solved_rotation;
+
+        // each effector turned toward its target's rotation
+        for (let g = 0; g < group.goals.length; g++) {
+            const record = group.goals[g];
+            const weight = record.goal.rotation_weight;
+
+            if (weight === 0) {
+                continue;
+            }
+
+            const carrier = this.#target_of(scratch_target, group, record);
+
+            read_rotation(q_target, scratch_target);
+
+            if (carrier >= 0) {
+                // carried from the carrier's animated frame into its solved one
+                read_array_rotation(q_0, rotation, carrier * 4);
+                read_rotation(q_1, group.base_world[carrier]);
+                q_1.conjugate();
+                q_0.multiply(q_1);
+                q_target.multiplyQuaternions(q_0, q_target);
+            }
+
+            const e4 = group.index.get(record.entity) * 4;
+
+            read_array_rotation(q_0, rotation, e4);
+
+            if (weight === 1) {
+                q_0.copy(q_target);
+            } else {
+                q_0.slerpQuaternions(q_0, q_target, weight);
+            }
+
+            write_array_rotation(rotation, e4, q_0);
+        }
+
+        // and written, whole, as each bone's local pose
+        const dataset = this.entityManager.dataset;
+
+        for (let j = 0; j < n; j++) {
+            const p = group.parent[j];
+
+            if (p < 0) {
+                read_rotation(q_0, group.above);
+            } else {
+                read_array_rotation(q_0, rotation, p * 4);
+            }
+
+            q_0.conjugate();
+
+            read_array_rotation(q_1, rotation, j * 4);
+
+            q_0.multiply(q_1);
+
+            write_local(dataset, this.#held.get(joints[j]), group.base_local[j], q_0);
+        }
+    }
+
+    /**
+     * @param {IKGroup} group
+     */
+    #solve_two_bone(group) {
+        this.#evaluate_base(group);
+
+        const record = group.goals[0];
+        const goal = record.goal;
+
+        // joints are [hip, knee, ankle], parents first
+        read_translation(v_a, group.base_world[0]);
+        read_translation(v_b, group.base_world[1]);
+        read_translation(v_c, group.base_world[2]);
+
+        read_rotation(q_a_world, group.base_world[0]);
+        read_rotation(q_b_world, group.base_world[1]);
+
+        read_rotation(q_a_local, group.base_local[0]);
+        read_rotation(q_b_local, group.base_local[1]);
+        read_rotation(q_c_local, group.base_local[2]);
+
+        this.#target_of(scratch_target, group, record);
+
+        read_translation(v_t, scratch_target);
+        read_rotation(q_target, scratch_target);
+
+        // the hip's world is the frame above times its local: keep the pair consistent
+        q_2.multiplyQuaternions(read_rotation(q_0, group.above), q_a_local);
+        q_a_world.copy(q_2);
+
+        two_bone_path_solve(
+            v_a, v_b, v_c, v_t,
+            record.mid_axis,
+            q_a_world, q_b_world,
+            q_a_local, q_b_local, q_c_local,
+            goal.position_weight,
+            q_target, goal.rotation_weight
+        );
+
+        const dataset = this.entityManager.dataset;
+        const joints = group.joints;
+
+        write_local(dataset, this.#held.get(joints[0]), group.base_local[0], q_a_local);
+        write_local(dataset, this.#held.get(joints[1]), group.base_local[1], q_b_local);
+        write_local(dataset, this.#held.get(joints[2]), group.base_local[2], q_c_local);
+    }
+}
+
+/**
+ * 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.
+ *
+ * @param {Map<number, IKGoalRecord>} records
+ * @param {Map<number, IKGroup>} group_of_bone filled
+ * @returns {IKGroup[]}
+ */
+function form_groups(records, group_of_bone) {
+    const groups = [];
+
+    for (const record of records.values()) {
+        if (record.rejected) {
+            continue;
+        }
+
+        // every group this goal's path touches merges into one
+        let group = null;
+
+        for (let i = 0; i < record.path.length; i++) {
+            const other = group_of_bone.get(record.path[i]);
+
+            if (other === undefined || other === group) {
+                continue;
+            }
+
+            if (group === null) {
+                group = other;
+                continue;
+            }
+
+            for (let g = 0; g < other.goals.length; g++) {
+                group.goals.push(other.goals[g]);
+            }
+
+            for (const [bone, owner] of group_of_bone) {
+                if (owner === other) {
+                    group_of_bone.set(bone, group);
+                }
+            }
+
+            groups.splice(groups.indexOf(other), 1);
+        }
+
+        if (group === null) {
+            group = new IKGroup();
+            groups.push(group);
+        }
+
+        group.goals.push(record);
+
+        for (let i = 0; i < record.path.length; i++) {
+            group_of_bone.set(record.path[i], group);
+        }
+    }
+
+    return groups;
+}
+
+/**
+ * Whether the deepest posed bone a goal's target hangs below is a bone of the goal's own path: the
+ * target then moves rigidly with the bones the goal turns to reach it. A grip on a weapon the other
+ * hand holds is not that, though both hands share a chest: the other arm's bones carry it.
+ *
+ * @param {IKGoalRecord} record
+ * @param {Map<number, IKGroup>} group_of_bone
+ * @param {EntityComponentDataset} dataset
+ * @returns {boolean}
+ */
+function carrier_on_own_path(record, group_of_bone, dataset) {
+    for (let e = record.goal.target; e >= 0 && dataset.entityExists(e);) {
+        if (group_of_bone.has(e)) {
+            return record.path.indexOf(e) !== -1;
+        }
+
+        const attachment = dataset.getComponent(e, TransformAttachment);
+
+        if (attachment === undefined || attachment === null) {
+            return false;
+        }
+
+        e = attachment.parent;
+    }
+
+    return false;
+}
+
+/**
+ * Whether `localBasisA = rest_local * localBasisB`, the Joint's frames agreeing at the bone's rest.
+ *
+ * @param {Joint} joint
+ * @param {Transform64} rest
+ * @returns {boolean}
+ */
+function basis_a_is_rest_times_b(joint, rest) {
+    read_rotation(q_0, rest);
+    q_1.set(joint.localBasisB[0], joint.localBasisB[1], joint.localBasisB[2], joint.localBasisB[3]);
+    q_0.multiply(q_1);
+
+    const a = joint.localBasisA;
+
+    const dot = q_0.x * a[0] + q_0.y * a[1] + q_0.z * a[2] + q_0.w * a[3];
+
+    return Math.abs(dot) > 1 - 1e-6;
+}
+
+/**
+ * Lay out a group: its bones parents first, its top's parent, its model, its solver.
+ *
+ * @param {IKGroup} group
+ * @param {EntityComponentDataset} dataset
+ */
+function build_group(group, dataset) {
+    const bones = new Set();
+
+    for (let g = 0; g < group.goals.length; g++) {
+        const path = group.goals[g].path;
+
+        for (let i = 0; i < path.length; i++) {
+            bones.add(path[i]);
+        }
+    }
+
+    // depth below the group's top, by walking up within the group
+    const depth = new Map();
+
+    for (const bone of bones) {
+        let d = 0;
+
+        for (let e = dataset.getComponent(bone, TransformAttachment).parent; bones.has(e); e = dataset.getComponent(e, TransformAttachment).parent) {
+            d++;
+        }
+
+        depth.set(bone, d);
+    }
+
+    const joints = Array.from(bones);
+
+    joints.sort((a, b) => depth.get(a) - depth.get(b) || a - b);
+
+    group.joints = joints;
+
+    group.index = new Map();
+
+    for (let j = 0; j < joints.length; j++) {
+        group.index.set(joints[j], j);
+    }
+
+    group.parent = new Int32Array(joints.length);
+
+    for (let j = 0; j < joints.length; j++) {
+        const parent = dataset.getComponent(joints[j], TransformAttachment).parent;
+
+        const index = group.index.get(parent);
+
+        group.parent[j] = index === undefined ? -1 : index;
+    }
+
+    assert.equal(group.parent[0], -1, 'a group has one top');
+
+    group.top_parent = dataset.getComponent(joints[0], TransformAttachment).parent;
+
+    group.model = group.goals[0].model;
+
+    group.two_bone = group.goals.length === 1 && group.goals[0].path.length === 3;
+
+    group.base_local = joints.map(() => new Transform64());
+    group.base_world = joints.map(() => new Transform64());
+
+    if (group.two_bone) {
+        group.problem = null;
+        return;
+    }
+
+    const problem = new FrameFabrikProblem(joints.length, group.goals.length);
+
+    for (let j = 0; j < joints.length; j++) {
+        const joint = dataset.getComponent(joints[j], Joint);
+
+        if (joint !== undefined && joint !== null) {
+            frame_fabrik_limit_from_joint(problem, j, joint);
+        }
+    }
+
+    group.problem = problem;
+}
+
+/**
+ * Note every group that `entity`, or anything it hangs below, is a bone of, as one `group` waits
+ * on. Its own bones are no wait: a target among them is read from the solver's frames.
+ *
+ * @param {IKGroup} group
+ * @param {number} entity
+ * @param {Map<number, IKGroup>} group_of_bone
+ * @param {EntityComponentDataset} dataset
+ */
+function add_waits(group, entity, group_of_bone, dataset) {
+    for (let e = entity; e >= 0 && dataset.entityExists(e);) {
+        const owner = group_of_bone.get(e);
+
+        if (owner !== undefined && owner !== group && group.after.indexOf(owner) === -1) {
+            group.after.push(owner);
+        }
+
+        const attachment = dataset.getComponent(e, TransformAttachment);
+
+        if (attachment === undefined || attachment === null) {
+            break;
+        }
+
+        e = attachment.parent;
+    }
+}
+
+/**
+ * Order groups so each comes after every group it waits on, by Tarjan's strongly connected
+ * components: they are emitted with everything a component waits on already out. A component of
+ * more than one group is a cycle, and each of its groups is rejected; a group that only waits on a
+ * cycle keeps its place, after it.
+ *
+ * @param {IKGroup[]} groups
+ * @returns {IKGroup[]}
+ */
+function order_groups(groups) {
+    const ordered = [];
+    const stack = [];
+
+    let counter = 0;
+
+    const index = new Map();
+    const low = new Map();
+    const on_stack = new Set();
+
+    function connect(group) {
+        index.set(group, counter);
+        low.set(group, counter);
+        counter++;
+
+        stack.push(group);
+        on_stack.add(group);
+
+        for (let i = 0; i < group.after.length; i++) {
+            const other = group.after[i];
+
+            if (!index.has(other)) {
+                connect(other);
+                low.set(group, Math.min(low.get(group), low.get(other)));
+            } else if (on_stack.has(other)) {
+                low.set(group, Math.min(low.get(group), index.get(other)));
+            }
+        }
+
+        if (low.get(group) !== index.get(group)) {
+            return;
+        }
+
+        const component = [];
+
+        let member;
+
+        do {
+            member = stack.pop();
+            on_stack.delete(member);
+            component.push(member);
+        } while (member !== group);
+
+        for (let i = 0; i < component.length; i++) {
+            component[i].rejected = component.length > 1;
+            ordered.push(component[i]);
+        }
+    }
+
+    for (let i = 0; i < groups.length; i++) {
+        if (!index.has(groups[i])) {
+            connect(groups[i]);
+        }
+    }
+
+    return ordered;
+}
+
+function copy3(out, offset, transform, at) {
+    out[offset] = transform[at];
+    out[offset + 1] = transform[at + 1];
+    out[offset + 2] = transform[at + 2];
+}
+
+function copy4(out, offset, transform, at) {
+    out[offset] = transform[at];
+    out[offset + 1] = transform[at + 1];
+    out[offset + 2] = transform[at + 2];
+    out[offset + 3] = transform[at + 3];
+}
+
+/**
+ * @param {Vector3} out
+ * @param {Transform64} transform
+ * @returns {Vector3}
+ */
+function read_translation(out, transform) {
+    out.set(
+        transform[TRANSFORM64_TRANSLATION_OFFSET],
+        transform[TRANSFORM64_TRANSLATION_OFFSET + 1],
+        transform[TRANSFORM64_TRANSLATION_OFFSET + 2]
+    );
+
+    return out;
+}
+
+/**
+ * @param {Quaternion} out
+ * @param {Transform64} transform
+ * @returns {Quaternion}
+ */
+function read_rotation(out, transform) {
+    out.set(
+        transform[TRANSFORM64_ROTATION_OFFSET],
+        transform[TRANSFORM64_ROTATION_OFFSET + 1],
+        transform[TRANSFORM64_ROTATION_OFFSET + 2],
+        transform[TRANSFORM64_ROTATION_OFFSET + 3]
+    );
+
+    return out;
+}
+
+function read_array_rotation(out, array, offset) {
+    out.set(array[offset], array[offset + 1], array[offset + 2], array[offset + 3]);
+
+    return out;
+}
+
+function write_array_rotation(array, offset, q) {
+    array[offset] = q.x;
+    array[offset + 1] = q.y;
+    array[offset + 2] = q.z;
+    array[offset + 3] = q.w;
+}
+
+/**
+ * A held bone's whole local pose: the animated translation and scale, the solved rotation.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {IKHeldBone} held
+ * @param {Transform64} base
+ * @param {Quaternion} rotation
+ */
+function write_local(dataset, held, base, rotation) {
+    const local = held.attachment.transform;
+
+    local.setTranslation(
+        base[TRANSFORM64_TRANSLATION_OFFSET],
+        base[TRANSFORM64_TRANSLATION_OFFSET + 1],
+        base[TRANSFORM64_TRANSLATION_OFFSET + 2]
+    );
+
+    local.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
+
+    local.setScale(
+        base[TRANSFORM64_SCALE_OFFSET],
+        base[TRANSFORM64_SCALE_OFFSET + 1],
+        base[TRANSFORM64_SCALE_OFFSET + 2]
+    );
+
+    local.updateMatrix();
+
+    dataset.sendEvent(held.entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE);
+}