bireactive 0.2.0

package/dist/constraints/rigid.d.ts

@@ -0,0 +1,210 @@
+import { Num, type Pose, Vec, type Writable } from "../core/index.js";
+import type { Constraints, Relation } from "./cluster.js";
+import type { Solver } from "./solver.js";
+import { Term } from "./term.js";
+export interface BodyOpts {
+    /** Box width (x extent) and height (y extent). */
+    size: {
+        w: number;
+        h: number;
+    };
+    /** Mass per unit area. `0` makes the body static (pinned, infinite
+     *  mass). Default `1`. */
+    density?: number;
+    /** Friction coefficient. Two bodies' coefficients combine as the
+     *  geometric mean. Default `0.5`. */
+    friction?: number;
+}
+export interface BodyInit {
+    x: number;
+    y: number;
+    theta?: number;
+}
+/** A 2D rigid body (a `Relation`; add via `world.add(body)`).
+ *
+ *  Pose is one `Pose` signal; `position` (Vec) and `angle` (Num) are
+ *  lenses on it for consumers wanting a narrower view. `cellId` is the
+ *  solver cell after `bind` (-1 before). */
+export declare class Body implements Relation {
+    readonly w: number;
+    readonly h: number;
+    readonly mass: number;
+    readonly moment: number;
+    readonly friction: number;
+    /** Bounding radius for the broadphase. */
+    readonly radius: number;
+    /** Reactive pose — single source of truth, updated each tick. */
+    readonly pose: Writable<Pose>;
+    /** Vec lens on `pose` (xy); writes propagate back through `pose`. */
+    readonly position: Writable<Vec>;
+    /** Num lens on `pose` (theta). */
+    readonly angle: Writable<Num>;
+    /** Solver cell id; -1 until `bind` runs. */
+    cellId: number;
+    /** @internal — set on bind so force code can read solver state. */
+    _solver?: Solver;
+    constructor(opts: BodyOpts, init: BodyInit);
+    bind(c: Constraints): () => void;
+    /** Relation that pins this body (mass → 0, kinematic) while
+     *  attached; restores `(m, m, I)` on detach. Composes with
+     *  `addWhile` for drag. The pose still updates from
+     *  `body.position` / `body.angle` writes. */
+    pin(): Relation;
+}
+/** Create a rigid body (add via `world.add`). `density: 0` is static
+ *  (mass 0, kinematic cell). */
+export declare function body(opts: BodyOpts, init: BodyInit): Body;
+interface Contact {
+    /** Penetration anchor on body A in A's local frame. */
+    rAx: number;
+    rAy: number;
+    /** Penetration anchor on body B in B's local frame. */
+    rBx: number;
+    rBy: number;
+    /** World-frame contact normal pointing A → B. */
+    nx: number;
+    ny: number;
+    /** Feature-pair (edge IDs) for warm-starting across frames. */
+    fp: number;
+    /** Whether the contact was sticking (static friction) last frame. */
+    stick: boolean;
+}
+/** Up to 2 contacts × (normal + tangent) = 4 rows. Coulomb friction
+ *  via clamping tangential `λ` to the cone `±μ·|λ_normal|` (updated
+ *  per iteration). Truncated Taylor at `x⁻` (paper §4), so `J` is
+ *  precomputed in `initialize` and copied out by `computeDerivatives`. */
+export declare class BoxContact extends Term {
+    bodyA: Body;
+    bodyB: Body;
+    numContacts: number;
+    contacts: Contact[];
+    private JAn;
+    private JBn;
+    private JAt;
+    private JBt;
+    private C0n;
+    private C0t;
+    private friction;
+    private _poseA;
+    private _poseB;
+    constructor(solver: Solver, bodyA: Body, bodyB: Body);
+    initialize(): boolean;
+    computeConstraint(alpha: number): void;
+    computeDerivatives(cellIdx: number): void;
+}
+export interface JointStiffness {
+    /** Stiffness for the X position row. `Infinity` = hard. Default `Infinity`. */
+    x?: number;
+    /** Stiffness for the Y position row. `Infinity` = hard. Default `Infinity`. */
+    y?: number;
+    /** Stiffness for the angle row. `0` = free (revolute joint, the
+     *  rope/chain default). `Infinity` = rigid weld. Default `0`. */
+    angle?: number;
+}
+/** Internal term for a revolute joint (anchors `rA` on `bodyA`, `rB`
+ *  on `bodyB`). Default: hard position rows, free angle (hinge);
+ *  override via `JointStiffness`. Port of the AVBD 2D `Joint`. User
+ *  code uses the `Joint` Relation via `world.add(joint(...))`. */
+export declare class JointTerm extends Term {
+    readonly bodyA: Body;
+    readonly bodyB: Body;
+    rAx: number;
+    rAy: number;
+    rBx: number;
+    rBy: number;
+    readonly torqueArm: number;
+    readonly restAngle: number;
+    private _Cn;
+    private _C0Cache;
+    private _poseA;
+    private _poseB;
+    constructor(solver: Solver, bodyA: Body, bodyB: Body, rA: {
+        x: number;
+        y: number;
+    }, rB: {
+        x: number;
+        y: number;
+    }, opts?: JointStiffness);
+    initialize(): boolean;
+    computeConstraint(alpha: number): void;
+    computeDerivatives(cellIdx: number): void;
+}
+/** @internal — soft 2-row term pulling a body's translation toward
+ *  `target` with finite `stiffness` (angle DOF left free). Backs the
+ *  `BodyAnchor` relation; see `bodyAnchor`. */
+export declare class BodyAnchorTerm extends Term {
+    readonly body: Body;
+    /** World-space target signal (mutable). */
+    readonly target: Writable<Vec>;
+    /** Mutable stiffness signal — refreshed each `initialize()`. */
+    readonly stiffnessSig: Writable<Num>;
+    constructor(solver: Solver, body: Body, target: Writable<Vec>, stiffness: Writable<Num>);
+    initialize(): boolean;
+    computeConstraint(_alpha: number): void;
+    computeDerivatives(_cellIdx: number): void;
+}
+/** Revolute or weld joint between two bodies (add via `world.add`).
+ *  Default: hard position rows, free angle (hinge). `{ angle: Infinity }`
+ *  welds; finite `{ x, y }` softens. `world` skips broadphase contacts
+ *  between jointed pairs. */
+export declare class Joint implements Relation {
+    readonly bodyA: Body;
+    readonly bodyB: Body;
+    readonly rA: {
+        x: number;
+        y: number;
+    };
+    readonly rB: {
+        x: number;
+        y: number;
+    };
+    readonly opts?: JointStiffness | undefined;
+    constructor(bodyA: Body, bodyB: Body, rA: {
+        x: number;
+        y: number;
+    }, rB: {
+        x: number;
+        y: number;
+    }, opts?: JointStiffness | undefined);
+    bind(c: Constraints): () => void;
+}
+export declare function joint(a: Body, b: Body, rA: {
+    x: number;
+    y: number;
+}, rB: {
+    x: number;
+    y: number;
+}, opts?: JointStiffness): Joint;
+/** Rigid weld — a joint with all rows hard; fuses two bodies while
+ *  keeping their independent inertias. */
+export declare function weld(a: Body, b: Body, rA: {
+    x: number;
+    y: number;
+}, rB: {
+    x: number;
+    y: number;
+}): Joint;
+/** Soft "drag" handle: pulls a body's translation toward `target`
+ *  with finite stiffness. The body keeps its mass and reacts to
+ *  contacts, so it lags behind the cursor when blocked rather than
+ *  punching through. `target` and `stiffness` are mutable signals.
+ *
+ *    const a = bodyAnchor(body, body.position.value, 5e4);
+ *    world.addWhile(dragging, a);
+ *    onPointerMove(p => a.target.value = p);
+ */
+export declare class BodyAnchor implements Relation {
+    readonly body: Body;
+    readonly target: Writable<Vec>;
+    readonly stiffness: Writable<Num>;
+    constructor(body: Body, target: Writable<Vec> | {
+        x: number;
+        y: number;
+    }, stiffness: Writable<Num> | number);
+    bind(c: Constraints): () => void;
+}
+export declare function bodyAnchor(body: Body, target: Writable<Vec> | {
+    x: number;
+    y: number;
+}, stiffness?: Writable<Num> | number): BodyAnchor;
+export {};