@woosh/meep-engine 3.40.0 → 3.42.0

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

@@ -47,6 +47,26 @@ export class GPUStateAuthority {
      * @type {number}
      */
     flags: number;
+    /**
+     * Bitwise OR of the {@link GPUStateAuthorityFlags} a CPU writer holds against the GPU: a cloth
+     * simulating a cape joint's offset, while a clip may be bound to the same joint.
+     *
+     * Two writers want one component, and a hold is how the CPU one wins. A held bit is never set
+     * in {@link flags}: holding clears it, and a GPU writer's grant does not set it while the hold
+     * lasts. Whoever writes on the GPU hears of the hold (see
+     * {@link GPU_AUTHORITY_EVENT_HOLD_CHANGE}) and stops, and takes the component back when it
+     * ends. So {@link flags} stays the one statement of who writes, and what is held is why the GPU
+     * does not.
+     *
+     * One holder per component: a second CPU writer of the same component is the same race in
+     * another place, and holding twice is an error.
+     *
+     * Read it through {@link gpu_authority_held} and write it through {@link gpu_authority_hold} /
+     * {@link gpu_authority_unhold}.
+     *
+     * @type {number}
+     */
+    held: number;
 }
 export namespace GPUStateAuthority {
     let typeName: string;

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

@@ -1 +1 @@
-{"version":3,"file":"GPUStateAuthority.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/GPUStateAuthority.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAYI;;;OAGG;IACH,oBAHW,MAAM,GACJ,iBAAiB,CAQ7B;IArBD;;;;;;;;OAQG;IACH,OAFU,MAAM,CAEN;CAab;;kBAIS,MAAM;sBASN,OAAO"}
+{"version":3,"file":"GPUStateAuthority.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/GPUStateAuthority.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAiCI;;;OAGG;IACH,oBAHW,MAAM,GACJ,iBAAiB,CAQ7B;IA1CD;;;;;;;;OAQG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAFU,MAAM,CAEP;CAaZ;;kBAIS,MAAM;sBASN,OAAO"}

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

@@ -43,6 +43,27 @@ export class GPUStateAuthority {
      */
     flags = 0;
 
+    /**
+     * Bitwise OR of the {@link GPUStateAuthorityFlags} a CPU writer holds against the GPU: a cloth
+     * simulating a cape joint's offset, while a clip may be bound to the same joint.
+     *
+     * Two writers want one component, and a hold is how the CPU one wins. A held bit is never set
+     * in {@link flags}: holding clears it, and a GPU writer's grant does not set it while the hold
+     * lasts. Whoever writes on the GPU hears of the hold (see
+     * {@link GPU_AUTHORITY_EVENT_HOLD_CHANGE}) and stops, and takes the component back when it
+     * ends. So {@link flags} stays the one statement of who writes, and what is held is why the GPU
+     * does not.
+     *
+     * One holder per component: a second CPU writer of the same component is the same race in
+     * another place, and holding twice is an error.
+     *
+     * Read it through {@link gpu_authority_held} and write it through {@link gpu_authority_hold} /
+     * {@link gpu_authority_unhold}.
+     *
+     * @type {number}
+     */
+    held = 0;
+
     /**
      * @param {number} [flags]
      * @returns {GPUStateAuthority}

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

@@ -0,0 +1,13 @@
+/**
+ * Sent on an entity when a CPU writer takes or gives back a component it holds against the GPU —
+ * see {@link GPUStateAuthority#held}. The payload is the entity.
+ *
+ * What a GPU writer listens for on the entities it drives: a hold means stop writing, and the end of
+ * one means it may take the component back. Read the state off the entity rather than off the
+ * event; one event names both transitions.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const GPU_AUTHORITY_EVENT_HOLD_CHANGE: "@gpu_authority/hold_change";
+//# sourceMappingURL=GPU_AUTHORITY_EVENT_HOLD_CHANGE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPU_AUTHORITY_EVENT_HOLD_CHANGE.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/GPU_AUTHORITY_EVENT_HOLD_CHANGE.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,2EAA4E"}

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

@@ -0,0 +1,12 @@
+/**
+ * Sent on an entity when a CPU writer takes or gives back a component it holds against the GPU —
+ * see {@link GPUStateAuthority#held}. The payload is the entity.
+ *
+ * What a GPU writer listens for on the entities it drives: a hold means stop writing, and the end of
+ * one means it may take the component back. Read the state off the entity rather than off the
+ * event; one event names both transitions.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const GPU_AUTHORITY_EVENT_HOLD_CHANGE = "@gpu_authority/hold_change";

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

@@ -6,10 +6,16 @@
  * declaration site that was missed, and adding the component here to paper over it is exactly the
  * structural churn the declaration exists to avoid.
  *
+ * **A component a CPU writer holds is not granted** (see {@link GPUStateAuthority#held}). The hold
+ * is the reason, stated on the same component, and the GPU side takes the bit when the hold ends —
+ * {@link gpu_authority_unhold} says so on the entity. A clip binding a cloth's cape joint grants
+ * the joint's world and not its offset.
+ *
  * @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
+ * that are not held
  */
 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

@@ -1 +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"}
+{"version":3,"file":"gpu_authority_grant.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_grant.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AACH,6EALW,MAAM,SACN,MAAM,GACJ,OAAO,CAuBnB"}

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

@@ -10,10 +10,16 @@ import { GPU_STATE_AUTHORITY_FLAGS_ALL, gpu_state_authority_flag_names } from ".
  * declaration site that was missed, and adding the component here to paper over it is exactly the
  * structural churn the declaration exists to avoid.
  *
+ * **A component a CPU writer holds is not granted** (see {@link GPUStateAuthority#held}). The hold
+ * is the reason, stated on the same component, and the GPU side takes the bit when the hold ends —
+ * {@link gpu_authority_unhold} says so on the entity. A clip binding a cloth's cape joint grants
+ * the joint's world and not its offset.
+ *
  * @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
+ * that are not held
  */
 export function gpu_authority_grant(dataset, entity, flags) {
     assert.defined(dataset, 'dataset');
@@ -26,7 +32,7 @@ export function gpu_authority_grant(dataset, entity, flags) {
     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;
+    const after = before | (flags & ~authority.held);
 
     if (after === before) {
         return false;

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

@@ -0,0 +1,14 @@
+/**
+ * Does a CPU writer hold component X of entity E against the GPU? See
+ * {@link GPUStateAuthority#held}.
+ *
+ * Asks for **all** of `flags`, as {@link gpu_authority_has} does. No component means nothing is
+ * held.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}
+ * @returns {boolean}
+ */
+export function gpu_authority_held(dataset: EntityComponentDataset, entity: number, flags: number): boolean;
+//# sourceMappingURL=gpu_authority_held.d.ts.map

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

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

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

@@ -0,0 +1,23 @@
+import { GPUStateAuthority } from "./GPUStateAuthority.js";
+
+/**
+ * Does a CPU writer hold component X of entity E against the GPU? See
+ * {@link GPUStateAuthority#held}.
+ *
+ * Asks for **all** of `flags`, as {@link gpu_authority_has} does. No component means nothing is
+ * held.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}
+ * @returns {boolean}
+ */
+export function gpu_authority_held(dataset, entity, flags) {
+    const authority = dataset.getComponent(entity, GPUStateAuthority);
+
+    if (authority === undefined || authority === null) {
+        return false;
+    }
+
+    return (authority.held & flags) === flags;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Take these components for a CPU writer, against whatever writes them on the GPU, for as long as
+ * the hold lasts.
+ *
+ * A revoke says the GPU stopped writing. A hold says the CPU needs the component **whether or not
+ * the GPU wants it**: a cloth over a cape whose clip keys the same joints. The bits clear, the GPU
+ * side cannot grant them back until {@link gpu_authority_unhold}, and
+ * {@link GPU_AUTHORITY_EVENT_HOLD_CHANGE} tells a GPU writer already driving the entity to stop.
+ *
+ * Declares the entity if it never was. A hold is a claim and has to be visible on the entity; an
+ * entity no clip has ever been able to target carries no {@link GPUStateAuthority}, and a clip that
+ * binds it later must find the hold there. Seeding a garment is that entity's moment, as binding is
+ * for a joint attached under an animated one.
+ *
+ * **Holding does not seed a value.** The component holds what the CPU last wrote, which for a joint
+ * a clip was resolving is not this frame's pose; the holder writes its own before anything reads it.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}, none of them already held
+ */
+export function gpu_authority_hold(dataset: EntityComponentDataset, entity: number, flags: number): void;
+//# sourceMappingURL=gpu_authority_hold.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_authority_hold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_hold.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4EAHW,MAAM,SACN,MAAM,QAgBhB"}

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

@@ -0,0 +1,41 @@
+import { assert } from "../../../core/assert.js";
+import { GPU_AUTHORITY_EVENT_HOLD_CHANGE } from "./GPU_AUTHORITY_EVENT_HOLD_CHANGE.js";
+import { GPU_STATE_AUTHORITY_FLAGS_ALL, gpu_state_authority_flag_names } from "./GPUStateAuthorityFlags.js";
+import { gpu_authority_declare } from "./gpu_authority_declare.js";
+
+/**
+ * Take these components for a CPU writer, against whatever writes them on the GPU, for as long as
+ * the hold lasts.
+ *
+ * A revoke says the GPU stopped writing. A hold says the CPU needs the component **whether or not
+ * the GPU wants it**: a cloth over a cape whose clip keys the same joints. The bits clear, the GPU
+ * side cannot grant them back until {@link gpu_authority_unhold}, and
+ * {@link GPU_AUTHORITY_EVENT_HOLD_CHANGE} tells a GPU writer already driving the entity to stop.
+ *
+ * Declares the entity if it never was. A hold is a claim and has to be visible on the entity; an
+ * entity no clip has ever been able to target carries no {@link GPUStateAuthority}, and a clip that
+ * binds it later must find the hold there. Seeding a garment is that entity's moment, as binding is
+ * for a joint attached under an animated one.
+ *
+ * **Holding does not seed a value.** The component holds what the CPU last wrote, which for a joint
+ * a clip was resolving is not this frame's pose; the holder writes its own before anything reads it.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}, none of them already held
+ */
+export function gpu_authority_hold(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 = gpu_authority_declare(dataset, entity);
+
+    assert.equal(authority.held & flags, 0, `entity ${entity} is already held for ${gpu_state_authority_flag_names(authority.held & flags)}: two CPU writers of one component`);
+
+    authority.held |= flags;
+    authority.flags &= ~flags;
+
+    dataset.sendEvent(entity, GPU_AUTHORITY_EVENT_HOLD_CHANGE, entity);
+}

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

@@ -0,0 +1,14 @@
+/**
+ * End a CPU writer's hold on these components — the reverse of {@link gpu_authority_hold}.
+ *
+ * **Grants nothing.** Whether the GPU writes the component now is not the holder's to say: a clip
+ * may have bound the joint during the hold, or left it. The event tells whatever drives the entity
+ * on the GPU, and that writer takes the component back if it still wants it. With nothing driving
+ * it, it stays the CPU's, holding what the holder last wrote.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}, every one of them held
+ */
+export function gpu_authority_unhold(dataset: EntityComponentDataset, entity: number, flags: number): void;
+//# sourceMappingURL=gpu_authority_unhold.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_authority_unhold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_unhold.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,8EAHW,MAAM,SACN,MAAM,QAgBhB"}

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

@@ -0,0 +1,32 @@
+import { assert } from "../../../core/assert.js";
+import { GPU_AUTHORITY_EVENT_HOLD_CHANGE } from "./GPU_AUTHORITY_EVENT_HOLD_CHANGE.js";
+import { GPUStateAuthority } from "./GPUStateAuthority.js";
+import { GPU_STATE_AUTHORITY_FLAGS_ALL, gpu_state_authority_flag_names } from "./GPUStateAuthorityFlags.js";
+
+/**
+ * End a CPU writer's hold on these components — the reverse of {@link gpu_authority_hold}.
+ *
+ * **Grants nothing.** Whether the GPU writes the component now is not the holder's to say: a clip
+ * may have bound the joint during the hold, or left it. The event tells whatever drives the entity
+ * on the GPU, and that writer takes the component back if it still wants it. With nothing driving
+ * it, it stays the CPU's, holding what the holder last wrote.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}, every one of them held
+ */
+export function gpu_authority_unhold(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, so nothing holds it`);
+    assert.equal(authority.held & flags, flags, `entity ${entity} is not held for ${gpu_state_authority_flag_names(flags & ~authority.held)}`);
+
+    authority.held &= ~flags;
+
+    dataset.sendEvent(entity, GPU_AUTHORITY_EVENT_HOLD_CHANGE, entity);
+}

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

@@ -0,0 +1,59 @@
+/**
+ * A goal for the bone it sits on, the effector: bring it to where its target entity is, turning the
+ * bones from it up to {@link chain_root}. {@link IKGoalSystem} solves it.
+ *
+ * The tree is the {@link TransformAttachment} hierarchy, and the goal's path runs from the effector
+ * up to its chain root. A link of the path turns; the chain root turns and never moves. Joint limits
+ * are the physics `Joint` on each bone of the path.
+ *
+ * - The references are entities and are fixed while the component is attached: remove it and add it
+ *   back to change them.
+ * - The goal removes itself when its target or any bone of its path is destroyed.
+ * - Weights are 0..1. Position weight 0 gives the pose the bones would have without the goal, and the
+ *   pose is continuous in it. Rotation weight 0 leaves the effector's rotation riding its chain; 1
+ *   gives it the target's.
+ *
+ * Bones are spawned with their model and never saved, and an entity id means nothing in a save, so
+ * neither is this.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class IKGoal {
+    /**
+     * @param {{target:number, chain_root:number, position_weight:number, rotation_weight:number}} options
+     * every field required
+     * @returns {IKGoal}
+     */
+    static from({ target, chain_root, position_weight, rotation_weight }: {
+        target: number;
+        chain_root: number;
+        position_weight: number;
+        rotation_weight: number;
+    }): IKGoal;
+    /**
+     * The entity whose world pose the effector is brought to.
+     * @type {number}
+     */
+    target: number;
+    /**
+     * The highest bone the goal turns: the effector itself or one of its ancestors.
+     * @type {number}
+     */
+    chain_root: number;
+    /**
+     * How far toward the target the effector is pulled, 0..1.
+     * @type {number}
+     */
+    position_weight: number;
+    /**
+     * How far toward the target's rotation the effector is turned, 0..1.
+     * @type {number}
+     */
+    rotation_weight: number;
+}
+export namespace IKGoal {
+    let typeName: string;
+    let serializable: boolean;
+}
+//# sourceMappingURL=IKGoal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IKGoal.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/IKGoal.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAyBI;;;;OAIG;IACH,sEAJW;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,UAAU,EAAC,MAAM,CAAC;QAAC,eAAe,EAAC,MAAM,CAAC;QAAC,eAAe,EAAC,MAAM,CAAA;KAAC,GAEhF,MAAM,CAkBlB;IA7CD;;;OAGG;IACH,QAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,YAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,iBAFU,MAAM,CAEI;CAwBvB;;kBAIS,MAAM;sBAMN,OAAO"}

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

@@ -0,0 +1,83 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * A goal for the bone it sits on, the effector: bring it to where its target entity is, turning the
+ * bones from it up to {@link chain_root}. {@link IKGoalSystem} solves it.
+ *
+ * The tree is the {@link TransformAttachment} hierarchy, and the goal's path runs from the effector
+ * up to its chain root. A link of the path turns; the chain root turns and never moves. Joint limits
+ * are the physics `Joint` on each bone of the path.
+ *
+ * - The references are entities and are fixed while the component is attached: remove it and add it
+ *   back to change them.
+ * - The goal removes itself when its target or any bone of its path is destroyed.
+ * - Weights are 0..1. Position weight 0 gives the pose the bones would have without the goal, and the
+ *   pose is continuous in it. Rotation weight 0 leaves the effector's rotation riding its chain; 1
+ *   gives it the target's.
+ *
+ * Bones are spawned with their model and never saved, and an entity id means nothing in a save, so
+ * neither is this.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class IKGoal {
+    /**
+     * The entity whose world pose the effector is brought to.
+     * @type {number}
+     */
+    target = -1;
+
+    /**
+     * The highest bone the goal turns: the effector itself or one of its ancestors.
+     * @type {number}
+     */
+    chain_root = -1;
+
+    /**
+     * How far toward the target the effector is pulled, 0..1.
+     * @type {number}
+     */
+    position_weight = 0;
+
+    /**
+     * How far toward the target's rotation the effector is turned, 0..1.
+     * @type {number}
+     */
+    rotation_weight = 0;
+
+    /**
+     * @param {{target:number, chain_root:number, position_weight:number, rotation_weight:number}} options
+     * every field required
+     * @returns {IKGoal}
+     */
+    static from({ target, chain_root, position_weight, rotation_weight }) {
+        assert.isNonNegativeInteger(target, 'target');
+        assert.isNonNegativeInteger(chain_root, 'chain_root');
+        assert.isNumber(position_weight, 'position_weight');
+        assert.isNumber(rotation_weight, 'rotation_weight');
+        assert.ok(position_weight >= 0 && position_weight <= 1, 'position_weight is within 0..1');
+        assert.ok(rotation_weight >= 0 && rotation_weight <= 1, 'rotation_weight is within 0..1');
+
+        const goal = new IKGoal();
+
+        goal.target = target;
+        goal.chain_root = chain_root;
+        goal.position_weight = position_weight;
+        goal.rotation_weight = rotation_weight;
+
+        return goal;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+IKGoal.typeName = "IKGoal";
+
+/**
+ * Entity ids are transient and bones are never saved: serialization is not applicable.
+ * @type {boolean}
+ */
+IKGoal.serializable = false;

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

@@ -0,0 +1,75 @@
+/**
+ * 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<any> {
+    constructor();
+    dependencies: (typeof TransformAttachment | typeof IKGoal)[];
+    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof AnimationGraphController> | ResourceAccessSpecification<typeof Animation> | ResourceAccessSpecification<typeof IKGoal> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof GPUStateAuthority> | ResourceAccessSpecification<typeof ParentEntity> | ResourceAccessSpecification<typeof Joint>)[];
+    /**
+     * The most iterations a frame FABRIK solve runs.
+     * @type {number}
+     */
+    max_iterations: number;
+    /**
+     * A frame FABRIK solve stops once an iteration moves no bone this far, in world units.
+     * @type {number}
+     */
+    tolerance: number;
+    /**
+     * @param {IKGoal} goal
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    link(goal: IKGoal, attachment: TransformAttachment, entity: number): void;
+    /**
+     * @param {IKGoal} goal
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    unlink(goal: IKGoal, attachment: TransformAttachment, entity: number): void;
+    update(time_delta_seconds: any): void;
+    #private;
+}
+import { System } from "../System.js";
+import { TransformAttachment } from "../transform-attachment/TransformAttachment.js";
+import { IKGoal } from "./IKGoal.js";
+import { Transform64 } from "../transform/Transform64.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { AnimationGraphController } from "../../graphics3/animation/AnimationGraphController.js";
+import { Animation } from "../animation/Animation.js";
+import { GPUStateAuthority } from "../gpu/GPUStateAuthority.js";
+import { ParentEntity } from "../parent/ParentEntity.js";
+import { Joint } from "../../physics/ecs/Joint.js";
+//# sourceMappingURL=IKGoalSystem.d.ts.map

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

@@ -0,0 +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"}