@woosh/meep-engine 3.39.0 → 3.41.0

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

@@ -1,54 +0,0 @@
-/**
- * Places bones of an entity's hierarchy against the terrain — a foot onto the slope it stands on,
- * rather than through it.
- *
- * **A bone is an entity here.** The constraint names one, the name is resolved to an entity beneath
- * the constrained entity, and the chain above it is the {@link TransformAttachment} parent walk. So
- * this system knows nothing about renderers: it reads world {@link Transform64}s the hierarchy has
- * already composed and writes local ones back, which is the whole of what a joint angle is.
- */
-export class InverseKinematicsSystem extends System<any> {
-    constructor();
-    dependencies: (typeof Transform64 | typeof InverseKinematics)[];
-    components_used: ResourceAccessSpecification<typeof Transform64>[];
-    /**
-     *
-     * @type {{"2BIK": TwoBoneInverseKinematicsSolver, "1BSA": OneBoneSurfaceAlignmentSolver}}
-     */
-    solvers: {
-        "2BIK": TwoBoneInverseKinematicsSolver;
-        "1BSA": OneBoneSurfaceAlignmentSolver;
-    };
-    problems: {};
-    get componentClass(): typeof InverseKinematics;
-    /**
-     *
-     * @param {InverseKinematics} ik
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    link(ik: InverseKinematics, transform: Transform64, entity: number): void;
-    /**
-     *
-     * @param {InverseKinematics} ik
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    unlink(ik: InverseKinematics, transform: Transform64, entity: number): void;
-    /**
-     *
-     * @param {InverseKinematics} ik
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    recordEntityProblems(ik: InverseKinematics, transform: Transform64, entity: number): void;
-    update(timeDelta: any): void;
-    #private;
-}
-import { System } from "../System.js";
-import { Transform64 } from "../transform/Transform64.js";
-import { InverseKinematics } from "./InverseKinematics.js";
-import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
-import { TwoBoneInverseKinematicsSolver } from "./TwoBoneInverseKinematicsSolver.js";
-import { OneBoneSurfaceAlignmentSolver } from "./OneBoneSurfaceAlignmentSolver.js";
-//# sourceMappingURL=InverseKinematicsSystem.d.ts.map

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

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

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

@@ -1,212 +0,0 @@
-import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
-import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
-import { collect_entity_playbacks } from "../../graphics3/pose/collect_entity_playbacks.js";
-import { System } from "../System.js";
-import { obtainTerrain } from "../terrain/util/obtainTerrain.js";
-import {
-    transform_attachment_find_descendant_by_name
-} from "../transform-attachment/transform_attachment_find_descendant_by_name.js";
-import { T64WorldCache } from "../transform/T64WorldCache.js";
-import { Transform64 } from "../transform/Transform64.js";
-import { IKProblem } from "./IKProblem.js";
-import { InverseKinematics } from "./InverseKinematics.js";
-import { OneBoneSurfaceAlignmentSolver } from "./OneBoneSurfaceAlignmentSolver.js";
-import { TwoBoneInverseKinematicsSolver } from "./TwoBoneInverseKinematicsSolver.js";
-
-/**
- * Places bones of an entity's hierarchy against the terrain — a foot onto the slope it stands on,
- * rather than through it.
- *
- * **A bone is an entity here.** The constraint names one, the name is resolved to an entity beneath
- * the constrained entity, and the chain above it is the {@link TransformAttachment} parent walk. So
- * this system knows nothing about renderers: it reads world {@link Transform64}s the hierarchy has
- * already composed and writes local ones back, which is the whole of what a joint angle is.
- */
-export class InverseKinematicsSystem extends System {
-
-    dependencies = [InverseKinematics, Transform64];
-
-    components_used = [
-        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read | ResourceAccessKind.Write)
-    ];
-
-    /**
-     *
-     * @type {{"2BIK": TwoBoneInverseKinematicsSolver, "1BSA": OneBoneSurfaceAlignmentSolver}}
-     */
-    solvers = {
-        "2BIK": new TwoBoneInverseKinematicsSolver(),
-        "1BSA": new OneBoneSurfaceAlignmentSolver()
-    };
-
-    problems = {};
-
-    /**
-     * Effector entities already found, per constrained entity, indexed the same way its constraints
-     * are. A name is resolved by searching the hierarchy, which is worth doing once — a model's
-     * bones do not move between entities.
-     *
-     * An entry is absent while the search has not succeeded, and the search is retried until it
-     * does, because the hierarchy a constraint names arrives with the model rather than with the
-     * component.
-     *
-     * @type {Array<number[]>}
-     */
-    #effectors = [];
-
-    /**
-     *
-     * @type {Terrain}
-     */
-    #terrain = null;
-
-    /**
-     * Evaluated worlds of the tick, for chains the GPU composes: the constraints on one model
-     * share its spine, and a socket asked twice is evaluated once.
-     *
-     * @type {T64WorldCache}
-     */
-    #cache = new T64WorldCache();
-
-
-    get componentClass() {
-        return InverseKinematics;
-    }
-
-    /**
-     *
-     * @param {InverseKinematics} ik
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    link(ik, transform, entity) {
-        this.#effectors[entity] = [];
-    }
-
-    /**
-     *
-     * @param {InverseKinematics} ik
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    unlink(ik, transform, entity) {
-        delete this.#effectors[entity];
-    }
-
-    /**
-     *
-     * @param {InverseKinematics} ik
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    recordEntityProblems(ik, transform, entity) {
-        const ecd = this.entityManager.dataset;
-
-        const effectors = this.#effectors[entity];
-
-        const ikConstraints = ik.constraints;
-
-        const n = ikConstraints.length;
-
-        for (let i = 0; i < n; i++) {
-            /**
-             *
-             * @type {IKConstraint}
-             */
-            const c = ikConstraints[i];
-
-            let effector = effectors[i];
-
-            if (effector === undefined) {
-                effector = transform_attachment_find_descendant_by_name(ecd, entity, c.effector);
-
-                if (effector === -1) {
-                    // the hierarchy carries no such bone yet
-                    continue;
-                }
-
-                effectors[i] = effector;
-            }
-
-            const solverID = c.solver;
-
-            //define problem
-            const problem = IKProblem.pool.create();
-            problem.constraint = c;
-            problem.dataset = ecd;
-            problem.effector = effector;
-            problem.terrain = this.#terrain;
-
-            // what the chain is evaluated against if the GPU composes it; a pooled problem keeps
-            // its list, so it is emptied before it is filled
-            problem.playbacks.length = 0;
-            collect_entity_playbacks(problem.playbacks, this.entityManager, entity);
-            problem.cache = this.#cache;
-
-            const problemSet = this.problems[solverID];
-
-            if (problemSet === undefined) {
-                this.problems[solverID] = [problem];
-            } else {
-                problemSet.push(problem);
-            }
-        }
-
-    }
-
-    update(timeDelta) {
-
-
-        const em = this.entityManager;
-
-        const ecd = em.dataset;
-
-        if (ecd == null) {
-            return;
-        }
-
-        this.#terrain = obtainTerrain(ecd);
-
-        if (this.#terrain === null) {
-            return;
-        }
-
-
-        // last tick's answers are last tick's
-        this.#cache.invalidate();
-
-        ecd.traverseEntities([InverseKinematics, Transform64], this.recordEntityProblems, this);
-
-        //solve problems
-        for (const solverID in this.solvers) {
-            const problemSet = this.problems[solverID];
-
-            if (problemSet === undefined) {
-                continue;
-            }
-
-            const n = problemSet.length;
-
-            if (n === 0) {
-                continue;
-            }
-
-            const solver = this.solvers[solverID];
-
-            for (let i = 0; i < n; i++) {
-                const problem = problemSet[i];
-
-                solver.solve(problem);
-
-                IKProblem.pool.release(problem);
-            }
-        }
-
-        //clear problem set
-        for (const solverID in this.problems) {
-            const problemSet = this.problems[solverID];
-
-            problemSet.splice(0, problemSet.length);
-        }
-    }
-}

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

@@ -1,8 +0,0 @@
-/**
- * Align a single bone onto terrain surface
- */
-export class OneBoneSurfaceAlignmentSolver extends IKSolver {
-    solve(problem: any): void;
-}
-import { IKSolver } from "./IKSolver.js";
-//# sourceMappingURL=OneBoneSurfaceAlignmentSolver.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"OneBoneSurfaceAlignmentSolver.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/OneBoneSurfaceAlignmentSolver.js"],"names":[],"mappings":"AA4CA;;GAEG;AACH;IACI,0BAuGC;CACJ;yBA/IwB,eAAe"}

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

@@ -1,153 +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 { clamp } from "../../../core/math/clamp.js";
-import { inverseLerp } from "../../../core/math/inverseLerp.js";
-import { t64_read_rotation } from "../transform/t64_read_rotation.js";
-import { t64_read_translation } from "../transform/t64_read_translation.js";
-import { IKBone, ik_bone_chain } from "./ik_bone_chain.js";
-import { ik_probe_terrain_contact } from "./ik_probe_terrain_contact.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 bonePosition = new Vector3();
-const parentPosition = new Vector3();
-
-const boneWorldRotation = new Quaternion();
-const parentLocalRotation = new Quaternion();
-
-const v3 = new Vector3();
-
-const ONE_OVER_SQRT_3 = 0.57735026919;
-
-const r = new Quaternion();
-const up = new Vector3();
-
-const r_i = new Quaternion();
-
-const axis = new Vector3();
-
-const x = new Quaternion();
-
-const target = new Quaternion();
-
-/**
- * the bone, and its parent — needed for the "down" direction the probe casts along
- *
- * @type {IKBone[]}
- */
-const CHAIN = [new IKBone(), new IKBone()];
-
-/**
- * Align a single bone onto terrain surface
- */
-export class OneBoneSurfaceAlignmentSolver extends IKSolver {
-    solve(problem) {
-        const { dataset, effector, constraint, terrain, playbacks, cache } = problem;
-
-        if (!ik_bone_chain(CHAIN, dataset, effector, 2, playbacks, cache)) {
-            // the hierarchy does not hold the bone and a parent to cast from
-            return;
-        }
-
-        const bone = CHAIN[0];
-        const boneParent = CHAIN[1];
-
-        /*
-         Read straight off the components: `TransformAttachmentSystem` composes a world transform as
-         soon as anything it depends on moves, so nothing has to be brought up to date first.
-
-         They are read OUT of the transforms rather than used in place, the same way the two-bone
-         solver reads its chain: what follows is vector and quaternion math, and a Transform64 is an
-         array carrying none of those methods.
-        */
-        const world = bone.world;
-
-        t64_read_translation(bonePosition, world);
-        t64_read_translation(parentPosition, boneParent.world);
-
-        // the magnitude of a uniform scale, which is what the limb's lengths are expressed in
-        const bone_scale = Math.hypot(world.scale_x, world.scale_y, world.scale_z) * ONE_OVER_SQRT_3;
-
-        //cast from the parent towards the bone to find the surface underneath it
-        let influence = ik_probe_terrain_contact(
-            targetPosition,
-            contact,
-            terrain,
-            parentPosition.x, parentPosition.y, parentPosition.z,
-            bonePosition.x, bonePosition.y, bonePosition.z,
-            constraint,
-            bone_scale
-        );
-
-        if (influence <= 0) {
-            //no contact, or no influence
-            return;
-        }
-
-        const contactNormal = contact.normal;
-
-        t64_read_rotation(r, bone.local);
-        t64_read_rotation(boneWorldRotation, world);
-
-        //we want to make bone align orthogonally to surface contact normal
-
-
-        //convert bone UP vector to world space
-        up.copy(Vector3.forward);
-        up.applyQuaternion(boneWorldRotation);
-        up.normalize();
-
-        r_i.copyInverse(boneWorldRotation);
-
-        v3.copy(contactNormal);
-        v3.applyQuaternion(r_i);
-
-
-        //
-        axis.crossVectors(v3, Vector3.forward);
-
-        const betaSine = axis.length();
-
-        //compute angle between normal and up vector of the bone
-        const beta = Math.asin(clamp(betaSine, -1, 1));
-
-        //
-        axis.normalize();
-
-        x.fromAxisAngle(axis, beta);
-
-        target.copy(r);
-        target.multiply(x);
-
-        //compute angle between quaternions
-        t64_read_rotation(parentLocalRotation, boneParent.local);
-
-        const a = target.angleTo(parentLocalRotation);
-
-        const a_abs = Math.abs(a);
-        if (a_abs >= constraint.limit) {
-            const b = target.angleTo(r);
-
-            const b_abs = Math.abs(b);
-            if (b_abs < constraint.limit) {
-
-                const l = inverseLerp(a_abs, b_abs, constraint.limit);
-
-                influence *= l;
-            } else {
-                return;
-            }
-        }
-
-        //slerp, not lerp: see ClingToTerrainSystem.alignToVector. A componentwise blend is not a
-        //unit quaternion, and `ik_write_local_rotation` writes it straight into the Transform64.
-        r.slerp(target, constraint.strength * influence);
-
-        ik_write_local_rotation(dataset, bone, r);
-    }
-}

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

@@ -1,5 +0,0 @@
-export class TwoBoneInverseKinematicsSolver extends IKSolver {
-    solve(problem: any): void;
-}
-import { IKSolver } from "./IKSolver.js";
-//# sourceMappingURL=TwoBoneInverseKinematicsSolver.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"TwoBoneInverseKinematicsSolver.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/TwoBoneInverseKinematicsSolver.js"],"names":[],"mappings":"AAsCA;IAGI,0BA6EC;CACJ;yBA/GwB,eAAe"}

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