math 0.0.0 → 0.1.0

package/dist/src/ik/fabrik2.d.ts

@@ -0,0 +1,314 @@
+import { type Vec2 } from '../core/index.js';
+/** What a joint's clockwise and anticlockwise limits are measured from. */
+export declare enum ConstraintCoordinateSystem {
+    /** The direction of the previous bone, so the limits bound how far this bone may bend. */
+    LOCAL = 0,
+    /** A fixed world direction, so the limits bound this bone's absolute heading. */
+    GLOBAL = 1
+}
+/**
+ * How the first bone in a chain is constrained.
+ *
+ * The first bone has no bone before it, so it is constrained against a direction held on the chain.
+ * The `LOCAL_` types only mean anything for a chain in a {@link Structure2}, where
+ * {@link solveStructure} resolves them against the bone the chain hangs off.
+ */
+export declare enum BaseboneConstraintType {
+    /** The first bone may point anywhere. */
+    NONE = 0,
+    /** Constrained against a fixed world direction. */
+    GLOBAL_ABSOLUTE = 1,
+    /** Constrained against the host bone's direction, so the chain bends relative to what it hangs off. */
+    LOCAL_RELATIVE = 2,
+    /**
+     * Constrained against a direction expressed in the host bone's frame, where **+Y** is the host
+     * bone's own direction. (`fabrik3`'s equivalent uses +Z, so a rig ported between the two needs
+     * its axes rotated.)
+     */
+    LOCAL_ABSOLUTE = 3
+}
+/** Which end of a host bone a connected chain hangs off. */
+export declare enum BoneConnectionPoint {
+    /** The host bone's start - the joint it shares with the bone before it. */
+    START = 0,
+    /** The host bone's end. */
+    END = 1
+}
+/**
+ * A joint's rotational limits: a wedge about a baseline.
+ *
+ * Angles are in radians, and a limit of PI means unconstrained in that direction. Anticlockwise is
+ * positive, matching {@link vec2.signedAngle}.
+ */
+export type Joint2 = {
+    /** How far the bone may swing clockwise of the baseline, in [0, PI]. */
+    clockwise: number;
+    /** How far the bone may swing anticlockwise of the baseline, in [0, PI]. */
+    anticlockwise: number;
+    /** What `clockwise` and `anticlockwise` are measured from. */
+    coordinateSystem: ConstraintCoordinateSystem;
+    /** The baseline for a `GLOBAL` joint - a world direction. Unit length. Unused when `LOCAL`. */
+    globalAxis: Vec2;
+};
+/** A single bone: two points, the fixed distance between them, and how it may rotate. */
+export type Bone2 = {
+    /** The joint shared with the previous bone; on the first bone, the base. */
+    start: Vec2;
+    /** The joint shared with the next bone; on the last bone, the end effector. */
+    end: Vec2;
+    /** The rest distance between `start` and `end`, preserved by every solve. */
+    length: number;
+    /** How far this bone may rotate away from the bone before it. */
+    joint: Joint2;
+};
+/**
+ * A chain of bones, from the base (index 0) to the end effector (the last bone's `end`).
+ *
+ * Allocate one with {@link createChain2}, fill it with {@link addBone} or
+ * {@link addConsecutiveBone}, then solve it every frame.
+ *
+ * `bones[0].joint` is unused - the first bone is governed by the chain's basebone fields instead,
+ * so a joint's fields never change meaning with its index.
+ */
+export type Chain2 = {
+    /**
+     * The bones, base first and end effector last.
+     *
+     * Neighbours share a point - bone `i`'s end is bone `i + 1`'s start - and the solver keeps it
+     * that way, so moving one moves the other.
+     */
+    bones: Bone2[];
+    /** The sum of every bone length - the chain's reach. Maintained by {@link addBone}. */
+    length: number;
+    /** Where the base of the chain is pinned when `fixedBase` is set. */
+    base: Vec2;
+    /** Whether `backward` pins the base to `base`. Clear it to let the whole chain drift. Forced on for a chain connected in a structure. */
+    fixedBase: boolean;
+    /** How the first bone is held; see {@link BaseboneConstraintType}. */
+    baseboneConstraintType: BaseboneConstraintType;
+    /** The baseline direction, in the space named by `baseboneConstraintType`. Unit length. */
+    baseboneAxis: Vec2;
+    /** `baseboneAxis` in world space. Equal to it for `GLOBAL_ABSOLUTE`; resolved by {@link solveStructure} otherwise. */
+    baseboneWorldAxis: Vec2;
+    /** How far the first bone may swing clockwise of the baseline, in [0, PI]. */
+    baseboneClockwise: number;
+    /** How far the first bone may swing anticlockwise of the baseline, in [0, PI]. */
+    baseboneAnticlockwise: number;
+    /** The target this chain solves for inside a {@link Structure2} when `useEmbeddedTarget` is set. */
+    embeddedTarget: Vec2;
+    /**
+     * Whether this chain solves for its own `embeddedTarget` instead of the target passed to
+     * {@link solveStructure}. Ignored outside a {@link Structure2}.
+     */
+    useEmbeddedTarget: boolean;
+    /** The most iterations {@link solve} will run. */
+    maxIterations: number;
+    /** {@link solve} stops as soon as the effector is this close to the target. */
+    solveDistanceThreshold: number;
+    /**
+     * How still an iteration must be before {@link solve} treats the chain as stuck.
+     *
+     * Only consulted on an iteration that fails to beat the best distance so far, and compared
+     * against the previous iteration rather than the best - so a solve that is slowly getting worse
+     * runs its full budget. That is deliberate: FABRIK often worsens before it improves, and every
+     * stricter rule tried here bought fewer iterations at a disproportionate cost in final pose.
+     */
+    minIterationChange: number;
+    /** The distance from the effector to the target after the last {@link solve}. */
+    solveDistance: number;
+    /** Scratch holding the best pose {@link solve} has seen, four numbers per bone. Grown by {@link addBone}. */
+    bestSolution: number[];
+};
+/** A chain's attachment to a bone in another chain of the same structure. */
+export type Connection = {
+    /** The index of the host chain in `structure.chains`, or -1 for a chain that hangs off nothing. */
+    hostChain: number;
+    /** The index of the host bone within that chain. */
+    hostBone: number;
+    /** Which end of the host bone this chain's base is pinned to. */
+    point: BoneConnectionPoint;
+};
+/** A set of chains, each optionally hanging off a bone of another. */
+export type Structure2 = {
+    /** Solved in insertion order, so a connected chain always sees its host already posed. */
+    chains: Chain2[];
+    /** Parallel to `chains`. */
+    connections: Connection[];
+};
+/** Creates an unconstrained joint. */
+export declare function createJoint2(): Joint2;
+/** Creates an empty chain with a fixed base at the origin and no basebone constraint. */
+export declare function createChain2(): Chain2;
+/**
+ * Appends a bone spanning `start` to `end`, copying both.
+ *
+ * The bone's length is taken from the distance between them. When this is the first bone the
+ * chain's base is moved to `start`.
+ *
+ * @param chain the chain to append to
+ * @param start the bone's start point
+ * @param end the bone's end point
+ * @param joint the bone's joint, or a fresh unconstrained one if omitted
+ * @returns the appended bone
+ */
+export declare function addBone(chain: Chain2, start: Vec2, end: Vec2, joint?: Joint2): Bone2;
+/**
+ * Appends a bone starting where the chain currently ends, running `length` along `direction`.
+ *
+ * @param chain the chain to append to, which must already have at least one bone
+ * @param direction the direction to extend in, assumed to be unit length
+ * @param length the length of the new bone
+ * @param joint the bone's joint, or a fresh unconstrained one if omitted
+ * @returns the appended bone
+ */
+export declare function addConsecutiveBone(chain: Chain2, direction: Vec2, length: number, joint?: Joint2): Bone2;
+/**
+ * Prepends a bone at the base end, extending the chain backward.
+ *
+ * This is what a follower grows with: driven by {@link forward} alone the base end is the tail.
+ *
+ * `joint` becomes the joint of the bone that was previously first, because that is the junction the
+ * new bone creates. The new first bone's own joint is unused, as always.
+ *
+ * @param chain the chain to prepend to, which must already have at least one bone
+ * @param direction the direction the new bone points, from its own start toward the existing chain. Assumed to be unit length
+ * @param length the length of the new bone
+ * @param joint the joint for the junction this creates, or a fresh unconstrained one if omitted
+ * @returns the prepended bone
+ */
+export declare function addBoneAtBase(chain: Chain2, direction: Vec2, length: number, joint?: Joint2): Bone2;
+/**
+ * Sets a joint's limits relative to the previous bone's direction, which is the usual case.
+ *
+ * @param joint the joint to configure
+ * @param clockwise how far the bone may swing clockwise of the previous bone, in radians, clamped to [0, PI]
+ * @param anticlockwise how far it may swing anticlockwise, in radians, clamped to [0, PI]
+ * @returns the joint
+ */
+export declare function setLocalJoint(joint: Joint2, clockwise: number, anticlockwise: number): Joint2;
+/**
+ * Sets a joint's limits relative to a fixed world direction, pinning the bone's absolute heading
+ * however the bones before it move.
+ *
+ * @param joint the joint to configure
+ * @param axis the world direction the limits are measured from, assumed to be unit length
+ * @param clockwise how far the bone may swing clockwise of `axis`, in radians, clamped to [0, PI]
+ * @param anticlockwise how far it may swing anticlockwise, in radians, clamped to [0, PI]
+ * @returns the joint
+ */
+export declare function setGlobalJoint(joint: Joint2, axis: Vec2, clockwise: number, anticlockwise: number): Joint2;
+/**
+ * Constrains the first bone to a wedge about `axis`.
+ *
+ * @param chain the chain to configure
+ * @param type which space `axis` is expressed in
+ * @param axis the baseline direction, assumed to be unit length. Ignored for {@link BaseboneConstraintType.LOCAL_RELATIVE}, which uses the host bone's direction
+ * @param clockwise how far the first bone may swing clockwise of the baseline, in radians, clamped to [0, PI]
+ * @param anticlockwise how far it may swing anticlockwise, in radians, clamped to [0, PI]
+ * @returns the chain
+ */
+export declare function setBaseboneConstraint(chain: Chain2, type: BaseboneConstraintType, axis: Vec2, clockwise: number, anticlockwise: number): Chain2;
+/**
+ * Moves the chain's pinned base, without moving the bones.
+ *
+ * The next {@link backward} or {@link solve} pulls the chain to it.
+ */
+export declare function setBaseLocation(chain: Chain2, base: Vec2): Chain2;
+/**
+ * Lays the chain out straight from its base along `direction`, discarding the current pose.
+ *
+ * A dead-straight chain is the worst starting pose for {@link solve} - see the note there. Bend
+ * `direction` slightly between bones instead if the chain will be solved cold.
+ */
+export declare function straighten(chain: Chain2, direction: Vec2): Chain2;
+/**
+ * Writes the end effector's position - the last bone's end - into `out`.
+ *
+ * A chain with no bones has its base as its effector, matching {@link solve}, which treats an empty
+ * chain as a supported state rather than an error.
+ */
+export declare function getEffector(out: Vec2, chain: Chain2): Vec2;
+/** Writes the unit direction of bone `index`, from its start toward its end, into `out`. */
+export declare function getBoneDirection(out: Vec2, chain: Chain2, index: number): Vec2;
+/** The angle of bone `index`, in radians, measured counter-clockwise from the +X axis. */
+export declare function getBoneAngle(chain: Chain2, index: number): number;
+/** Whether `target` is within reach of the chain's base, so a solve can place the effector exactly on it. */
+export declare function isReachable(chain: Chain2, target: Vec2): boolean;
+/**
+ * The forward pass: snaps the end effector onto `target` and drags the rest of the chain after it.
+ *
+ * A non-finite target leaves the chain untouched rather than poisoning it.
+ *
+ * The base is not pinned, so the whole chain moves. Run alone once per frame this is a follower
+ * rather than a solver - a rope or tentacle whose head leads. Pair it with {@link backward}, or use
+ * {@link solve}, to keep the base put.
+ *
+ * @param chain the chain to move, mutated in place
+ * @param target where the end effector should go
+ * @returns the chain
+ */
+export declare function forward(chain: Chain2, target: Vec2): Chain2;
+/**
+ * The backward pass: pins the base and pushes each bone outward from it. The basebone constraint
+ * is applied here.
+ *
+ * @param chain the chain to move, mutated in place
+ * @param base where the base should go, used only when `chain.fixedBase` is set
+ * @returns the chain
+ */
+export declare function backward(chain: Chain2, base: Vec2): Chain2;
+/**
+ * One full FABRIK iteration - {@link forward} then {@link backward}.
+ *
+ * @param chain the chain to move, mutated in place
+ * @param target where the end effector should go
+ * @returns the distance from the effector to `target` afterwards
+ */
+export declare function iterate(chain: Chain2, target: Vec2): number;
+/**
+ * Solves the chain for `target`, iterating until it is close enough, stops improving, or runs out
+ * of attempts.
+ *
+ * A constrained chain does not converge monotonically, so the best pose seen is kept and restored.
+ *
+ * A dead-straight chain is the worst case to solve cold: every direction lies on one line, leaving
+ * nothing sideways to bend it with. Give it a slight bend if the first solve matters.
+ *
+ * @param chain the chain to solve, mutated in place
+ * @param target where the end effector should go
+ * @returns the distance from the effector to `target`, also stored as `chain.solveDistance`
+ */
+export declare function solve(chain: Chain2, target: Vec2): number;
+/** Creates an empty structure. */
+export declare function createStructure2(): Structure2;
+/**
+ * Adds a chain that hangs off nothing, solving directly for the structure's target.
+ *
+ * @returns the index of the added chain
+ */
+export declare function addChain(structure: Structure2, chain: Chain2): number;
+/**
+ * Adds a chain whose base is pinned to one end of a bone in a chain already in the structure.
+ *
+ * Add the host first: {@link solveStructure} walks chains in insertion order, so a chain always
+ * sees its host already posed.
+ *
+ * @param structure the structure to add to
+ * @param chain the chain to add
+ * @param hostChain the index of the chain to hang off
+ * @param hostBone the index of the bone within that chain
+ * @param point which end of the host bone to attach to
+ * @returns the index of the added chain
+ */
+export declare function connectChain(structure: Structure2, chain: Chain2, hostChain: number, hostBone: number, point: BoneConnectionPoint): number;
+/**
+ * Solves every chain in the structure.
+ *
+ * A connected chain has its base moved onto its host bone's connection point and any `LOCAL_`
+ * basebone constraint resolved against the host bone's direction first. A chain with
+ * `useEmbeddedTarget` set solves for its own `embeddedTarget` instead.
+ *
+ * @param structure the structure to solve, mutated in place
+ * @param target the target for every chain that does not use an embedded target
+ */
+export declare function solveStructure(structure: Structure2, target: Vec2): void;

package/dist/src/ik/fabrik3.d.ts

@@ -0,0 +1,371 @@
+import { type Quat, type Vec3 } from '../core/index.js';
+/**
+ * How a joint may rotate relative to the bone before it.
+ *
+ * A {@link JointType.BALL} joint with a `rotor` of PI is unconstrained, which is the default, so
+ * there is no separate "no constraint" type.
+ */
+export declare enum JointType {
+    /** Rotates freely within a cone of `rotor` radians about the previous bone's direction. */
+    BALL = 0,
+    /** Rotates only in the plane perpendicular to `rotationAxis`, which is in world space. */
+    GLOBAL_HINGE = 1,
+    /**
+     * Rotates only in the plane perpendicular to `rotationAxis`, which is fixed in the previous
+     * bone's frame.
+     *
+     * That frame comes from {@link mat3.fromDirection}, so local **+Z** is the previous bone's own
+     * direction and local +X and +Y are perpendicular to it. (`fabrik2` uses +Y for the same idea,
+     * so a rig ported from 2D needs its axes rotated.) The frame's roll about the bone is arbitrary
+     * and flips near world -Z, so a hinge whose parent swings through there will pop - hinge about a
+     * `GLOBAL_HINGE` axis you rebuild from your own frame if the parent turns freely.
+     */
+    LOCAL_HINGE = 2
+}
+/**
+ * How the first bone in a chain is constrained.
+ *
+ * The first bone has no bone before it to be constrained against, so it is constrained against a
+ * direction held on the chain instead. `GLOBAL_` types read that direction as world space, while
+ * `LOCAL_` types read it relative to the bone this chain is connected to, and so only mean
+ * anything for a chain in a {@link Structure3}, where {@link solveStructure} resolves them.
+ *
+ * A `LOCAL_` direction is read in the host bone's frame from {@link mat3.fromDirection}, where
+ * **+Z** is the host bone's own direction. (`fabrik2`'s equivalent uses +Y.) That frame's roll is
+ * arbitrary and flips near world -Z, so a host bone that swings through there makes the constraint
+ * pop.
+ */
+export declare enum BaseboneConstraintType {
+    /** The first bone may point anywhere. */
+    NONE = 0,
+    /** Confined to a cone of `baseboneRotor` radians about a world-space direction. */
+    GLOBAL_ROTOR = 1,
+    /** Confined to a cone of `baseboneRotor` radians about a direction relative to the host bone. */
+    LOCAL_ROTOR = 2,
+    /** Confined to the plane perpendicular to a world-space hinge axis. */
+    GLOBAL_HINGE = 3,
+    /** Confined to the plane perpendicular to a hinge axis relative to the host bone. */
+    LOCAL_HINGE = 4
+}
+/** Which end of a host bone a connected chain hangs off. */
+export declare enum BoneConnectionPoint {
+    /** The host bone's start - the joint it shares with the bone before it. */
+    START = 0,
+    /** The host bone's end. */
+    END = 1
+}
+/**
+ * A joint's rotational limits.
+ *
+ * Which fields apply depends on `type`: `rotor` for {@link JointType.BALL}, and `rotationAxis`,
+ * `referenceAxis`, `clockwise` and `anticlockwise` for the two hinge types. All angles are in
+ * radians, and a limit of PI means unconstrained.
+ */
+export type Joint3 = {
+    /** Which of the fields below apply. */
+    type: JointType;
+    /** Ball: the half-angle of the cone about the previous bone's direction, in [0, PI]. */
+    rotor: number;
+    /** Hinge: how far the bone may swing clockwise of `referenceAxis`, in [0, PI]. */
+    clockwise: number;
+    /** Hinge: how far the bone may swing anticlockwise of `referenceAxis`, in [0, PI]. */
+    anticlockwise: number;
+    /** Hinge: the axis the bone rotates about. Unit length. */
+    rotationAxis: Vec3;
+    /** Hinge: the zero direction the clockwise and anticlockwise limits are measured from. Unit length, perpendicular to `rotationAxis`. */
+    referenceAxis: Vec3;
+};
+/** A single bone: two points, the fixed distance between them, and how it may rotate. */
+export type Bone3 = {
+    /** The joint shared with the previous bone; on the first bone, the base. */
+    start: Vec3;
+    /** The joint shared with the next bone; on the last bone, the end effector. */
+    end: Vec3;
+    /** The rest distance between `start` and `end`, preserved by every solve. */
+    length: number;
+    /** How far this bone may rotate away from the bone before it. */
+    joint: Joint3;
+};
+/**
+ * A chain of bones, from the base (index 0) to the end effector (the last bone's `end`).
+ *
+ * Allocate one with {@link createChain3}, fill it with {@link addBone} or
+ * {@link addConsecutiveBone}, then solve it every frame.
+ *
+ * `bones[0].joint` is unused - the first bone is governed by the chain's basebone fields instead,
+ * so a joint's fields never change meaning with its index.
+ */
+export type Chain3 = {
+    /**
+     * The bones, base first and end effector last.
+     *
+     * Neighbours share a point - bone `i`'s end is bone `i + 1`'s start - and the solver keeps it
+     * that way, so moving one moves the other.
+     */
+    bones: Bone3[];
+    /** The sum of every bone length - the chain's reach. Maintained by {@link addBone}. */
+    length: number;
+    /** Where the base of the chain is pinned when `fixedBase` is set. */
+    base: Vec3;
+    /** Whether `backward` pins the base to `base`. Clear it to let the whole chain drift. Forced on for a chain connected in a structure. */
+    fixedBase: boolean;
+    /** How the first bone is held; see {@link BaseboneConstraintType}. */
+    baseboneConstraintType: BaseboneConstraintType;
+    /** The cone axis or hinge axis, in the space named by `baseboneConstraintType`. Unit length. */
+    baseboneAxis: Vec3;
+    /** The hinge reference axis, in the space named by `baseboneConstraintType`. Unit length. */
+    baseboneReferenceAxis: Vec3;
+    /** `baseboneAxis` in world space. Equal to it for `GLOBAL_` types; resolved by {@link solveStructure} for `LOCAL_` ones. */
+    baseboneWorldAxis: Vec3;
+    /** `baseboneReferenceAxis` in world space. */
+    baseboneWorldReferenceAxis: Vec3;
+    /** The half-angle of the basebone cone, in [0, PI]. */
+    baseboneRotor: number;
+    /** The basebone hinge's clockwise limit, in [0, PI]. */
+    baseboneClockwise: number;
+    /** The basebone hinge's anticlockwise limit, in [0, PI]. */
+    baseboneAnticlockwise: number;
+    /** The target this chain solves for inside a {@link Structure3} when `useEmbeddedTarget` is set. */
+    embeddedTarget: Vec3;
+    /**
+     * Whether this chain solves for its own `embeddedTarget` instead of the target passed to
+     * {@link solveStructure}. Ignored outside a {@link Structure3}.
+     */
+    useEmbeddedTarget: boolean;
+    /** The most iterations {@link solve} will run. */
+    maxIterations: number;
+    /** {@link solve} stops as soon as the effector is this close to the target. */
+    solveDistanceThreshold: number;
+    /**
+     * How still an iteration must be before {@link solve} treats the chain as stuck.
+     *
+     * Only consulted on an iteration that fails to beat the best distance so far, and compared
+     * against the previous iteration rather than the best - so a solve that is slowly getting worse
+     * runs its full budget. That is deliberate: FABRIK often worsens before it improves, and every
+     * stricter rule tried here bought fewer iterations at a disproportionate cost in final pose.
+     */
+    minIterationChange: number;
+    /** The distance from the effector to the target after the last {@link solve}. */
+    solveDistance: number;
+    /** Scratch holding the best pose {@link solve} has seen, six numbers per bone. Grown by {@link addBone}. */
+    bestSolution: number[];
+};
+/** A chain's attachment to a bone in another chain of the same structure. */
+export type Connection = {
+    /** The index of the host chain in `structure.chains`, or -1 for a chain that hangs off nothing. */
+    hostChain: number;
+    /** The index of the host bone within that chain. */
+    hostBone: number;
+    /** Which end of the host bone this chain's base is pinned to. */
+    point: BoneConnectionPoint;
+};
+/** A set of chains, each optionally hanging off a bone of another. */
+export type Structure3 = {
+    /** Solved in insertion order, so a connected chain always sees its host already posed. */
+    chains: Chain3[];
+    /** Parallel to `chains`. */
+    connections: Connection[];
+};
+/** Creates an unconstrained joint. */
+export declare function createJoint3(): Joint3;
+/** Creates an empty chain with a fixed base at the origin and no basebone constraint. */
+export declare function createChain3(): Chain3;
+/**
+ * Appends a bone spanning `start` to `end`, copying both.
+ *
+ * The bone's length is taken from the distance between them. When this is the first bone the
+ * chain's base is moved to `start`.
+ *
+ * @param chain the chain to append to
+ * @param start the bone's start point
+ * @param end the bone's end point
+ * @param joint the bone's joint, or a fresh unconstrained one if omitted
+ * @returns the appended bone
+ */
+export declare function addBone(chain: Chain3, start: Vec3, end: Vec3, joint?: Joint3): Bone3;
+/**
+ * Appends a bone starting where the chain currently ends, running `length` along `direction`.
+ *
+ * @param chain the chain to append to, which must already have at least one bone
+ * @param direction the direction to extend in, assumed to be unit length
+ * @param length the length of the new bone
+ * @param joint the bone's joint, or a fresh unconstrained one if omitted
+ * @returns the appended bone
+ */
+export declare function addConsecutiveBone(chain: Chain3, direction: Vec3, length: number, joint?: Joint3): Bone3;
+/**
+ * Prepends a bone at the base end, extending the chain backward.
+ *
+ * This is what a follower grows with: driven by {@link forward} alone the base end is the tail.
+ *
+ * `joint` becomes the joint of the bone that was previously first, because that is the junction the
+ * new bone creates. The new first bone's own joint is unused, as always.
+ *
+ * @param chain the chain to prepend to, which must already have at least one bone
+ * @param direction the direction the new bone points, from its own start toward the existing chain. Assumed to be unit length
+ * @param length the length of the new bone
+ * @param joint the joint for the junction this creates, or a fresh unconstrained one if omitted
+ * @returns the prepended bone
+ */
+export declare function addBoneAtBase(chain: Chain3, direction: Vec3, length: number, joint?: Joint3): Bone3;
+/**
+ * Sets a ball-joint constraint: the bone may rotate within a cone of `rotor` radians about the
+ * direction of the bone before it.
+ *
+ * @param joint the joint to configure
+ * @param rotor the half-angle of the cone in radians, clamped to [0, PI]
+ * @returns the joint
+ */
+export declare function setBallJoint(joint: Joint3, rotor: number): Joint3;
+/**
+ * Sets a hinge constraint: the bone may only rotate in the plane perpendicular to `rotationAxis`,
+ * and within `clockwise` / `anticlockwise` radians of `referenceAxis` in that plane.
+ *
+ * `referenceAxis` is projected onto the hinge plane and normalized, so it need only be roughly
+ * perpendicular. Pass PI for both limits for a hinge that spins freely.
+ *
+ * @param joint the joint to configure
+ * @param type either {@link JointType.GLOBAL_HINGE} (axes in world space) or {@link JointType.LOCAL_HINGE} (axes relative to the previous bone)
+ * @param rotationAxis the hinge axis, assumed to be unit length
+ * @param clockwise the clockwise limit in radians, clamped to [0, PI]
+ * @param anticlockwise the anticlockwise limit in radians, clamped to [0, PI]
+ * @param referenceAxis the zero direction the limits are measured from
+ * @returns the joint
+ */
+export declare function setHingeJoint(joint: Joint3, type: JointType.GLOBAL_HINGE | JointType.LOCAL_HINGE, rotationAxis: Vec3, clockwise: number, anticlockwise: number, referenceAxis: Vec3): Joint3;
+/**
+ * Confines the first bone to a cone of `rotor` radians about `axis`.
+ *
+ * @param chain the chain to configure
+ * @param type either {@link BaseboneConstraintType.GLOBAL_ROTOR} or {@link BaseboneConstraintType.LOCAL_ROTOR}
+ * @param axis the cone axis, assumed to be unit length
+ * @param rotor the half-angle of the cone in radians, clamped to [0, PI]
+ * @returns the chain
+ */
+export declare function setBaseboneRotorConstraint(chain: Chain3, type: BaseboneConstraintType.GLOBAL_ROTOR | BaseboneConstraintType.LOCAL_ROTOR, axis: Vec3, rotor: number): Chain3;
+/**
+ * Confines the first bone to the plane perpendicular to `rotationAxis`, within `clockwise` /
+ * `anticlockwise` radians of `referenceAxis`.
+ *
+ * @param chain the chain to configure
+ * @param type either {@link BaseboneConstraintType.GLOBAL_HINGE} or {@link BaseboneConstraintType.LOCAL_HINGE}
+ * @param rotationAxis the hinge axis, assumed to be unit length
+ * @param clockwise the clockwise limit in radians, clamped to [0, PI]
+ * @param anticlockwise the anticlockwise limit in radians, clamped to [0, PI]
+ * @param referenceAxis the zero direction the limits are measured from
+ * @returns the chain
+ */
+export declare function setBaseboneHingeConstraint(chain: Chain3, type: BaseboneConstraintType.GLOBAL_HINGE | BaseboneConstraintType.LOCAL_HINGE, rotationAxis: Vec3, clockwise: number, anticlockwise: number, referenceAxis: Vec3): Chain3;
+/**
+ * Moves the chain's pinned base, without moving the bones.
+ *
+ * The next {@link backward} or {@link solve} pulls the chain to it.
+ */
+export declare function setBaseLocation(chain: Chain3, base: Vec3): Chain3;
+/**
+ * Lays the chain out straight from its base along `direction`, discarding the current pose.
+ *
+ * A dead-straight chain is the worst starting pose for {@link solve} - see the note there. Bend
+ * `direction` slightly between bones instead if the chain will be solved cold.
+ */
+export declare function straighten(chain: Chain3, direction: Vec3): Chain3;
+/**
+ * Writes the end effector's position - the last bone's end - into `out`.
+ *
+ * A chain with no bones has its base as its effector, matching {@link solve}, which treats an empty
+ * chain as a supported state rather than an error.
+ */
+export declare function getEffector(out: Vec3, chain: Chain3): Vec3;
+/** Writes the unit direction of bone `index`, from its start toward its end, into `out`. */
+export declare function getBoneDirection(out: Vec3, chain: Chain3, index: number): Vec3;
+/**
+ * Writes the rotation taking `up` onto the direction of bone `index` into `out`.
+ *
+ * Use it to orient a mesh along a bone, passing whichever axis the mesh is modelled along - `up`
+ * is `[0, 1, 0]` for a cylinder or capsule built along Y. The roll about the bone is arbitrary.
+ */
+export declare function getBoneRotation(out: Quat, chain: Chain3, index: number, up: Vec3): Quat;
+/** Whether `target` is within reach of the chain's base, so a solve can place the effector exactly on it. */
+export declare function isReachable(chain: Chain3, target: Vec3): boolean;
+/**
+ * The forward pass: snaps the end effector onto `target` and drags the rest of the chain after it.
+ *
+ * A non-finite target leaves the chain untouched rather than poisoning it.
+ *
+ * The base is not pinned, so the whole chain moves. Run alone once per frame this is a follower
+ * rather than a solver - a rope or tentacle whose head leads. Pair it with {@link backward}, or use
+ * {@link solve}, to keep the base put.
+ *
+ * @param chain the chain to move, mutated in place
+ * @param target where the end effector should go
+ * @returns the chain
+ */
+export declare function forward(chain: Chain3, target: Vec3): Chain3;
+/**
+ * The backward pass: pins the base and pushes each bone outward from it.
+ *
+ * Basebone constraints and hinge reference-axis limits are applied here only - the forward pass
+ * skips the latter, because clamping on both degrades the solution.
+ *
+ * @param chain the chain to move, mutated in place
+ * @param base where the base should go, used only when `chain.fixedBase` is set
+ * @returns the chain
+ */
+export declare function backward(chain: Chain3, base: Vec3): Chain3;
+/**
+ * One full FABRIK iteration - {@link forward} then {@link backward}. Often enough on its own for an
+ * unconstrained chain reaching a nearby target. use {@link solve} to iterate to a tolerance.
+ *
+ * @param chain the chain to move, mutated in place
+ * @param target where the end effector should go
+ * @returns the distance from the effector to `target` afterwards
+ */
+export declare function iterate(chain: Chain3, target: Vec3): number;
+/**
+ * Solves the chain for `target`, iterating until it is close enough, stops improving, or runs out
+ * of attempts.
+ *
+ * A constrained chain does not converge monotonically, so the best pose seen is kept and restored.
+ *
+ * A dead-straight chain is the worst case to solve cold: every direction lies on one line, leaving
+ * nothing sideways to bend it with. Give it a slight bend if the first solve matters.
+ *
+ * @param chain the chain to solve, mutated in place
+ * @param target where the end effector should go
+ * @returns the distance from the effector to `target`, also stored as `chain.solveDistance`
+ */
+export declare function solve(chain: Chain3, target: Vec3): number;
+/** Creates an empty structure. */
+export declare function createStructure3(): Structure3;
+/**
+ * Adds a chain that hangs off nothing, solving directly for the structure's target.
+ *
+ * @returns the index of the added chain
+ */
+export declare function addChain(structure: Structure3, chain: Chain3): number;
+/**
+ * Adds a chain whose base is pinned to one end of a bone in a chain already in the structure.
+ *
+ * Add the host first: {@link solveStructure} walks chains in insertion order, so a chain always
+ * sees its host already posed.
+ *
+ * @param structure the structure to add to
+ * @param chain the chain to add
+ * @param hostChain the index of the chain to hang off
+ * @param hostBone the index of the bone within that chain
+ * @param point which end of the host bone to attach to
+ * @returns the index of the added chain
+ */
+export declare function connectChain(structure: Structure3, chain: Chain3, hostChain: number, hostBone: number, point: BoneConnectionPoint): number;
+/**
+ * Solves every chain in the structure.
+ *
+ * A connected chain has its base moved onto its host bone's connection point and any `LOCAL_`
+ * basebone constraint resolved through the host bone's frame first. A chain with
+ * `useEmbeddedTarget` set solves for its own `embeddedTarget` instead - how a walker's legs each
+ * reach their own foothold.
+ *
+ * @param structure the structure to solve, mutated in place
+ * @param target the target for every chain that does not use an embedded target
+ */
+export declare function solveStructure(structure: Structure3, target: Vec3): void;