@woosh/meep-engine 3.40.0 → 3.41.0

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

@@ -1,120 +0,0 @@
-import { SurfacePoint3 } from "../../../core/geom/3d/SurfacePoint3.js";
-import Quaternion from "../../../core/geom/Quaternion.js";
-import Vector3 from "../../../core/geom/Vector3.js";
-import { two_joint_ik } from "../../physics/inverse_kinematics/two_joint_ik.js";
-import { IKBone, ik_bone_chain } from "./ik_bone_chain.js";
-import { ik_probe_terrain_contact } from "./ik_probe_terrain_contact.js";
-import { t64_read_rotation } from "../transform/t64_read_rotation.js";
-import { t64_read_translation } from "../transform/t64_read_translation.js";
-import { IKSolver } from "./IKSolver.js";
-import { ik_write_local_rotation } from "./ik_write_local_rotation.js";
-
-const contact = new SurfacePoint3();
-
-const targetPosition = new Vector3();
-
-const positionA = new Vector3();
-const positionB = new Vector3();
-const positionC = new Vector3();
-
-const worldRotationA = new Quaternion();
-const worldRotationB = new Quaternion();
-
-const localRotationA = new Quaternion();
-const localRotationB = new Quaternion();
-
-const targetLocalRotationA = new Quaternion();
-const targetLocalRotationB = new Quaternion();
-
-const r0 = new Quaternion();
-const r1 = new Quaternion();
-
-/**
- * effector, its parent, its grandparent
- *
- * @type {IKBone[]}
- */
-const CHAIN = [new IKBone(), new IKBone(), new IKBone()];
-
-export class TwoBoneInverseKinematicsSolver extends IKSolver {
-
-
-    solve(problem) {
-
-        const { dataset, effector, terrain, constraint, playbacks, cache } = problem;
-
-        if (!ik_bone_chain(CHAIN, dataset, effector, 3, playbacks, cache)) {
-            // the hierarchy does not hold three links yet
-            return;
-        }
-
-        const boneC = CHAIN[0];
-        const boneB = CHAIN[1];
-        const boneA = CHAIN[2];
-
-        /*
-         The world poses are read straight off the components. There is no matrix to bring up to
-         date first: `TransformAttachmentSystem` composes a world transform the moment anything it
-         depends on changes, so what is on the component is what the hierarchy currently says.
-
-         They are read OUT of the transforms rather than used in place, because `two_joint_ik` is
-         geometry math over vectors and quaternions and a Transform64 is an array with none of their
-         methods on it.
-        */
-        t64_read_translation(positionA, boneA.world);
-        t64_read_translation(positionB, boneB.world);
-        t64_read_translation(positionC, boneC.world);
-
-        //compute total length of the limb
-        const limbLength = positionA.distanceTo(positionB) + positionB.distanceTo(positionC);
-
-        //check if there is a penetration with the terrain between the two bones
-        const influence = ik_probe_terrain_contact(
-            targetPosition,
-            contact,
-            terrain,
-            positionA.x, positionA.y, positionA.z,
-            positionC.x, positionC.y, positionC.z,
-            constraint,
-            limbLength
-        );
-
-        if (influence <= 0) {
-            //no contact, or no influence
-            return;
-        }
-
-        t64_read_rotation(localRotationA, boneA.local);
-        t64_read_rotation(localRotationB, boneB.local);
-
-        t64_read_rotation(worldRotationA, boneA.world);
-        t64_read_rotation(worldRotationB, boneB.world);
-
-        targetLocalRotationA.copy(localRotationA);
-        targetLocalRotationB.copy(localRotationB);
-
-        //compute
-        two_joint_ik(
-            positionA,
-            positionB,
-            positionC,
-            targetPosition,
-            0.01,
-            worldRotationA,
-            worldRotationB,
-            targetLocalRotationA,
-            targetLocalRotationB
-        );
-
-        //lerp bone rotations based on influence
-        r0.lerpQuaternions(localRotationA, targetLocalRotationA, influence);
-        r1.lerpQuaternions(localRotationB, targetLocalRotationB, influence);
-
-        /*
-         Both lerps are taken before either write, because a write recomposes every world transform
-         below it — reading a bone's pose after moving its parent would read the corrected one.
-        */
-        ik_write_local_rotation(dataset, boneA, r0);
-        ik_write_local_rotation(dataset, boneB, r1);
-    }
-}

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

@@ -1,64 +0,0 @@
-/**
- * Fill a chain of bones running from the effector up towards the root.
- *
- * `result[0]` is the effector itself, `result[1]` its parent, and so on. The walk stops early when
- * the hierarchy runs out, which is how a chain that is too short to solve announces itself.
- *
- * @param {IKBone[]} result must hold at least `count` bones
- * @param {EntityComponentDataset} dataset
- * @param {number} effector
- * @param {number} count how many links the solver needs
- * @returns {boolean} `false` when the hierarchy holds fewer than `count` links above and including
- * 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, 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.
- *
- * A solver reads the world pose and writes the local one — writing the world pose directly would be
- * overwritten by {@link TransformAttachmentSystem} the moment anything above moved, and the local
- * rotation is what a joint angle *is*.
- */
-export class IKBone {
-    /**
-     *
-     * @type {number}
-     */
-    entity: number;
-    /**
-     * 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.
-     *
-     * @type {Transform64|null}
-     */
-    local: Transform64 | null;
-    /**
-     * The component {@link IKBone#local} belongs to.
-     *
-     * A Transform64 announces nothing when it is written, so a solver has to say that it changed,
-     * and the announcement names the component the hierarchy is listening for - which is this one,
-     * not the transform inside it.
-     *
-     * @type {TransformAttachment|null}
-     */
-    attachment: TransformAttachment | null;
-}
-import { Transform64 } from "../transform/Transform64.js";
-import { TransformAttachment } from "../transform-attachment/TransformAttachment.js";
-//# sourceMappingURL=ik_bone_chain.d.ts.map

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

@@ -1 +0,0 @@
-{"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,142 +0,0 @@
-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
- * it, and the local pose that composition came from.
- *
- * A solver reads the world pose and writes the local one — writing the world pose directly would be
- * overwritten by {@link TransformAttachmentSystem} the moment anything above moved, and the local
- * rotation is what a joint angle *is*.
- */
-export class IKBone {
-    /**
-     *
-     * @type {number}
-     */
-    entity = -1;
-
-    /**
-     * 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.
-     *
-     * @type {Transform64|null}
-     */
-    local = null;
-
-    /**
-     * The component {@link IKBone#local} belongs to.
-     *
-     * A Transform64 announces nothing when it is written, so a solver has to say that it changed,
-     * and the announcement names the component the hierarchy is listening for - which is this one,
-     * not the transform inside it.
-     *
-     * @type {TransformAttachment|null}
-     */
-    attachment = null;
-}
-
-/**
- * Fill a chain of bones running from the effector up towards the root.
- *
- * `result[0]` is the effector itself, `result[1]` its parent, and so on. The walk stops early when
- * the hierarchy runs out, which is how a chain that is too short to solve announces itself.
- *
- * @param {IKBone[]} result must hold at least `count` bones
- * @param {EntityComponentDataset} dataset
- * @param {number} effector
- * @param {number} count how many links the solver needs
- * @returns {boolean} `false` when the hierarchy holds fewer than `count` links above and including
- * 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, 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');
-
-    let entity = effector;
-
-    for (let i = 0; i < count; i++) {
-        if (entity === -1) {
-            return false;
-        }
-
-        const world = dataset.getComponent(entity, Transform64);
-
-        if (world === undefined) {
-            return false;
-        }
-
-        const attachment = dataset.getComponent(entity, TransformAttachment);
-
-        if (attachment === undefined) {
-            // a root, so it has no joint angle to move and cannot be part of a chain
-            return false;
-        }
-
-        const bone = result[i];
-
-        bone.entity = entity;
-        bone.world = world;
-        bone.local = attachment.transform;
-        bone.attachment = attachment;
-
-        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_probe_terrain_contact.d.ts

@@ -1,42 +0,0 @@
-/**
- * Find where an IK chain meets the terrain and how strongly the solver should pull towards it.
- *
- * Two casts are made. The first travels from `origin` towards `effector` and establishes which
- * surface the limb is over at all. The second starts just outside that surface, directly above the
- * effector along the surface normal, and comes back down — that is what actually locates the point
- * under the effector rather than the point under the limb's root, and it is what `out_contact` and
- * `out_target` describe on return.
- *
- * The returned influence answers "how much of this correction should apply":
- * - the effector is BELOW the surface (penetrating) → `1`, correct it fully;
- * - the effector HOVERS above the surface → falls off from `1` to `0` across
- *   `constraint.distance`, measured as a fraction of `length_scale`, so the same constraint reads
- *   the same way for a long limb and a short one;
- * - no surface was found at all → `0`.
- *
- * This exists because {@link TwoBoneInverseKinematicsSolver} and
- * {@link OneBoneSurfaceAlignmentSolver} carried the identical ~70-line probe, comments and variable
- * names included, differing only in which lengths they scaled by. The solvers now hold nothing but
- * their rotation math.
- *
- * @param {Vector3} out_target receives the world position the effector should be moved to; only
- * written when a non-zero influence is returned
- * @param {SurfacePoint3} out_contact receives the surface contact from the SECOND cast; only
- * written when a non-zero influence is returned. Solvers that need the contact normal (surface
- * alignment) read it from here
- * @param {Terrain} terrain
- * @param {number} origin_x start of the limb, the root bone's world position
- * @param {number} origin_y
- * @param {number} origin_z
- * @param {number} effector_x world position of the bone being placed. The probe direction is
- * `effector - origin`, so these must not coincide
- * @param {number} effector_y
- * @param {number} effector_z
- * @param {IKConstraint} constraint supplies `offset` (how far off the surface the effector rests)
- * and `distance` (the hover band over which influence falls off)
- * @param {number} length_scale limb length in world units; `constraint.offset` and the hover
- * distance are both expressed relative to it. Must be greater than 0
- * @returns {number} influence in `[0,1]`; `0` means "do nothing"
- */
-export function ik_probe_terrain_contact(out_target: Vector3, out_contact: SurfacePoint3, terrain: Terrain, origin_x: number, origin_y: number, origin_z: number, effector_x: number, effector_y: number, effector_z: number, constraint: IKConstraint, length_scale: number): number;
-//# sourceMappingURL=ik_probe_terrain_contact.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"ik_probe_terrain_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/ik_probe_terrain_contact.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,sHAbW,MAAM,YACN,MAAM,YACN,MAAM,cACN,MAAM,cAEN,MAAM,cACN,MAAM,0CAGN,MAAM,GAEJ,MAAM,CA8ElB"}

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

@@ -1,123 +0,0 @@
-import { v3_displace_in_direction } from "../../../core/geom/vec3/v3_displace_in_direction.js";
-import { v3_dot } from "../../../core/geom/vec3/v3_dot.js";
-import { v3_length } from "../../../core/geom/vec3/v3_length.js";
-import { clamp01 } from "../../../core/math/clamp01.js";
-import { inverseLerp } from "../../../core/math/inverseLerp.js";
-
-/**
- * Find where an IK chain meets the terrain and how strongly the solver should pull towards it.
- *
- * Two casts are made. The first travels from `origin` towards `effector` and establishes which
- * surface the limb is over at all. The second starts just outside that surface, directly above the
- * effector along the surface normal, and comes back down — that is what actually locates the point
- * under the effector rather than the point under the limb's root, and it is what `out_contact` and
- * `out_target` describe on return.
- *
- * The returned influence answers "how much of this correction should apply":
- * - the effector is BELOW the surface (penetrating) → `1`, correct it fully;
- * - the effector HOVERS above the surface → falls off from `1` to `0` across
- *   `constraint.distance`, measured as a fraction of `length_scale`, so the same constraint reads
- *   the same way for a long limb and a short one;
- * - no surface was found at all → `0`.
- *
- * This exists because {@link TwoBoneInverseKinematicsSolver} and
- * {@link OneBoneSurfaceAlignmentSolver} carried the identical ~70-line probe, comments and variable
- * names included, differing only in which lengths they scaled by. The solvers now hold nothing but
- * their rotation math.
- *
- * @param {Vector3} out_target receives the world position the effector should be moved to; only
- * written when a non-zero influence is returned
- * @param {SurfacePoint3} out_contact receives the surface contact from the SECOND cast; only
- * written when a non-zero influence is returned. Solvers that need the contact normal (surface
- * alignment) read it from here
- * @param {Terrain} terrain
- * @param {number} origin_x start of the limb, the root bone's world position
- * @param {number} origin_y
- * @param {number} origin_z
- * @param {number} effector_x world position of the bone being placed. The probe direction is
- * `effector - origin`, so these must not coincide
- * @param {number} effector_y
- * @param {number} effector_z
- * @param {IKConstraint} constraint supplies `offset` (how far off the surface the effector rests)
- * and `distance` (the hover band over which influence falls off)
- * @param {number} length_scale limb length in world units; `constraint.offset` and the hover
- * distance are both expressed relative to it. Must be greater than 0
- * @returns {number} influence in `[0,1]`; `0` means "do nothing"
- */
-export function ik_probe_terrain_contact(
-    out_target,
-    out_contact,
-    terrain,
-    origin_x, origin_y, origin_z,
-    effector_x, effector_y, effector_z,
-    constraint,
-    length_scale
-) {
-
-    //check if the there is a penetration with the terrain between the two bones
-    const directionX = effector_x - origin_x;
-    const directionY = effector_y - origin_y;
-    const directionZ = effector_z - origin_z;
-
-    let contactExists = terrain.raycastFirstSync(
-        out_contact,
-        origin_x,
-        origin_y,
-        origin_z,
-        directionX,
-        directionY,
-        directionZ
-    );
-
-    if (!contactExists) {
-        //no contact
-        return 0;
-    }
-
-    const contactPosition = out_contact.position;
-    const contactNormal = out_contact.normal;
-
-    //perform secondary cast from the bone, back along the surface normal
-    contactExists = terrain.raycastFirstSync(
-        out_contact,
-        effector_x + contactNormal.x,
-        effector_y + contactNormal.y,
-        effector_z + contactNormal.z,
-        -contactNormal.x,
-        -contactNormal.y,
-        -contactNormal.z
-    );
-
-    if (!contactExists) {
-        //no contact
-        return 0;
-    }
-
-    const targetOffsetDistance = constraint.offset * length_scale;
-
-    v3_displace_in_direction(
-        out_target,
-        targetOffsetDistance,
-        contactPosition.x, contactPosition.y, contactPosition.z,
-        contactNormal.x, contactNormal.y, contactNormal.z
-    );
-
-    const delta_contact_c_x = out_target.x - effector_x;
-    const delta_contact_c_y = out_target.y - effector_y;
-    const delta_contact_c_z = out_target.z - effector_z;
-
-    //check if current effector position is above the contact point
-    const dot_contact_side = v3_dot(directionX, directionY, directionZ, delta_contact_c_x, delta_contact_c_y, delta_contact_c_z);
-
-    if (dot_contact_side < 0) {
-        //penetration detected
-        return 1;
-    }
-
-    //no penetration, hovering case, use hover distance for influence
-    const delta_contact_c_length = v3_length(delta_contact_c_x, delta_contact_c_y, delta_contact_c_z);
-
-    const normalized_effector_distance = inverseLerp(0, length_scale, delta_contact_c_length);
-
-    return 1 - clamp01(constraint.distance.normalizeValue(normalized_effector_distance));
-}

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

@@ -1,18 +0,0 @@
-/**
- * Write a solved joint angle back onto a bone.
- *
- * Three separate things have to happen, where a signalling transform did them as one. The rotation
- * is written as four numbers. The local matrix is recomposed, because only a translation write
- * lands in the matrix on its own. And the change is announced, because a {@link Transform64}
- * carries no signals and {@link TransformAttachmentSystem} is waiting to hear that this bone moved
- * before it recomposes every world pose below it.
- *
- * The announcement goes on the attachment's channel and not the transform's, because a bone's local
- * pose is not a component in its own right - it lives inside the attachment.
- *
- * @param {EntityComponentDataset} dataset
- * @param {IKBone} bone
- * @param {Quaternion} rotation
- */
-export function ik_write_local_rotation(dataset: EntityComponentDataset, bone: IKBone, rotation: Quaternion): void;
-//# sourceMappingURL=ik_write_local_rotation.d.ts.map

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

@@ -1 +0,0 @@
-{"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,32 +0,0 @@
-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";
-
-/**
- * Write a solved joint angle back onto a bone.
- *
- * Three separate things have to happen, where a signalling transform did them as one. The rotation
- * is written as four numbers. The local matrix is recomposed, because only a translation write
- * lands in the matrix on its own. And the change is announced, because a {@link Transform64}
- * carries no signals and {@link TransformAttachmentSystem} is waiting to hear that this bone moved
- * before it recomposes every world pose below it.
- *
- * The announcement goes on the attachment's channel and not the transform's, because a bone's local
- * pose is not a component in its own right - it lives inside the attachment.
- *
- * @param {EntityComponentDataset} dataset
- * @param {IKBone} bone
- * @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);
-    local.updateMatrix();
-
-    dataset.sendEvent(bone.entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE);
-}