@woosh/meep-engine 3.39.0 → 3.41.0

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"}