@newkrok/nape-js 3.5.3 → 3.6.2

package/dist/index.d.cts

@@ -72,6 +72,36 @@ declare class Vec2 {
      * const v = Vec2.fromPolar(1, Math.PI / 4); // 45-degree unit vector
      */
     static fromPolar(length: number, angle: number, weak?: boolean): Vec2;
+    /**
+     * Create a unit Vec2 pointing in the given direction (angle in radians).
+     * Equivalent to `Vec2.fromPolar(1, radians)`.
+     *
+     * @param radians - The angle in radians, measured counter-clockwise from the +x axis.
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A unit Vec2 at the given angle.
+     */
+    static fromAngle(radians: number, weak?: boolean): Vec2;
+    /**
+     * Linearly interpolate between two Vec2s. Returns `a + t * (b - a)`.
+     * Disposes weak arguments after use.
+     *
+     * @param a - The start Vec2 (t = 0).
+     * @param b - The end Vec2 (t = 1).
+     * @param t - The interpolation factor (typically 0–1, but not clamped).
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A new Vec2 at the interpolated position.
+     */
+    static lerp(a: Vec2, b: Vec2, t: number, weak?: boolean): Vec2;
+    /**
+     * Check whether two Vec2s are component-wise equal, within an optional epsilon tolerance.
+     * Disposes weak arguments after comparison.
+     *
+     * @param a - The first Vec2.
+     * @param b - The second Vec2.
+     * @param epsilon - Maximum allowed difference per component (default 0).
+     * @returns `true` if both components differ by at most `epsilon`.
+     */
+    static eq(a: Vec2, b: Vec2, epsilon?: number): boolean;
     /**
      * Squared Euclidean distance between two Vec2s. Avoids a square root when
      * only comparison is needed.
@@ -140,6 +170,20 @@ declare class Vec2 {
      * @returns `this` for chaining.
      */
     setxy(x: number, y: number): this;
+    /**
+     * Return a new Vec2 with the same components. Alias for `copy()`.
+     *
+     * @returns A new Vec2 with the same x and y values.
+     */
+    clone(): Vec2;
+    /**
+     * Check whether this Vec2 is component-wise equal to another, within an optional epsilon tolerance.
+     *
+     * @param other - The Vec2 to compare against.
+     * @param epsilon - Maximum allowed difference per component (default 0).
+     * @returns `true` if both components differ by at most `epsilon`.
+     */
+    equals(other: Vec2, epsilon?: number): boolean;
     /**
      * Return a new Vec2 with the same components.
      *
@@ -333,6 +377,19 @@ declare class Vec3 {
      * @returns `this` for chaining.
      */
     setxyz(x: number, y: number, z: number): this;
+    /**
+     * Check whether this Vec3 is component-wise equal to another, within an optional epsilon tolerance.
+     *
+     * @param other - The Vec3 to compare against.
+     * @param epsilon - Maximum allowed difference per component (default 0).
+     * @returns `true` if all three components differ by at most `epsilon`.
+     */
+    equals(other: Vec3, epsilon?: number): boolean;
+    /**
+     * Return a new Vec3 with the same components.
+     * @returns A copy of this vector.
+     */
+    clone(): Vec3;
     /**
      * Return the x and y components as a new Vec2.
      * @param weak - If true, the returned Vec2 is a weak (pooled) reference.
@@ -416,6 +473,19 @@ declare class Mat23 {
     set ty(v: number);
     /** The determinant of the linear 2×2 part (ad − bc). */
     get determinant(): number;
+    /**
+     * Return a new Mat23 with the same components. Alias for `copy()`.
+     * @returns A new Mat23 with the same components.
+     */
+    clone(): Mat23;
+    /**
+     * Check whether this Mat23 is component-wise equal to another, within an optional epsilon tolerance.
+     *
+     * @param other - The Mat23 to compare against.
+     * @param epsilon - Maximum allowed difference per component (default 0).
+     * @returns `true` if all six components differ by at most `epsilon`.
+     */
+    equals(other: Mat23, epsilon?: number): boolean;
     /**
      * Return a new Mat23 with the same components.
      * @returns A deep copy of this matrix.
@@ -601,6 +671,14 @@ declare class AABB {
      * @param height - The height of the box (default 0). Must be ≥ 0.
      */
     constructor(x?: number, y?: number, width?: number, height?: number);
+    /**
+     * Create the smallest AABB that contains all the given points.
+     * Disposes weak Vec2 arguments after use.
+     *
+     * @param points - An array of Vec2 points to enclose. Must contain at least one point.
+     * @returns A new AABB enclosing all the points.
+     */
+    static fromPoints(points: Vec2[]): AABB;
     /** The x position of the left edge (minx). Setting shifts the box horizontally. */
     get x(): number;
     /** The x position of the left edge (minx). Setting shifts the box horizontally. */
@@ -640,6 +718,20 @@ declare class AABB {
      * @param max - A Vec2 whose components become the new (maxx, maxy).
      */
     set max(max: any);
+    /**
+     * Return a new AABB with the same bounds. Alias for `copy()`.
+     *
+     * @returns A new AABB with the same position and dimensions.
+     */
+    clone(): AABB;
+    /**
+     * Check whether this AABB is equal to another, within an optional epsilon tolerance.
+     *
+     * @param other - The AABB to compare against.
+     * @param epsilon - Maximum allowed difference per component (default 0).
+     * @returns `true` if all four bounds (minx, miny, maxx, maxy) differ by at most `epsilon`.
+     */
+    equals(other: AABB, epsilon?: number): boolean;
     /**
      * Return a new AABB with the same bounds.
      *
@@ -686,6 +778,20 @@ declare class MatMN {
      * @returns The written value.
      */
     setx(row: number, col: number, value: number): number;
+    /**
+     * Check whether this MatMN is element-wise equal to another, within an optional epsilon tolerance.
+     * Matrices must have the same dimensions.
+     *
+     * @param other - The MatMN to compare against.
+     * @param epsilon - Maximum allowed difference per element (default 0).
+     * @returns `true` if dimensions match and all elements differ by at most `epsilon`.
+     */
+    equals(other: MatMN, epsilon?: number): boolean;
+    /**
+     * Return a new MatMN with the same dimensions and element values.
+     * @returns A deep copy of this matrix.
+     */
+    clone(): MatMN;
     /**
      * String representation with rows separated by semicolons.
      * @returns A human-readable string of the matrix elements.
@@ -777,6 +883,11 @@ declare class Ray {
      * @returns The point `origin + distance * normalised_direction`.
      */
     at(distance: number, weak?: boolean): Vec2;
+    /**
+     * Return a new Ray with the same origin, direction, and maxDistance. Alias for `copy()`.
+     * @returns A new Ray with the same properties.
+     */
+    clone(): Ray;
     /**
      * Return a new Ray with the same origin, direction, and maxDistance.
      * @returns A deep copy of this Ray.
@@ -1075,13 +1186,13 @@ declare class Constraint {
      * The impulse applied to `body` by this constraint in the last simulation step,
      * expressed as a {@link Vec3} `(fx, fy, torque)`.
      *
-     * @param body - Must be one of the bodies linked to this constraint.
+     * @param _body - Must be one of the bodies linked to this constraint.
      */
     bodyImpulse(_body: Body): Vec3 | null;
     /**
      * Invokes `fn` once for each distinct body linked to this constraint.
      *
-     * @param fn - Function to call for each body.
+     * @param _fn - Function to call for each body.
      */
     visitBodies(_fn: (body: Body) => void): void;
     /**
@@ -1103,25 +1214,58 @@ declare class Constraint {
  */
 declare class InteractionFilter {
     static __name__: string[];
+    /**
+     * @param collisionGroup - Collision group bits (default 1).
+     * @param collisionMask - Collision mask bits (default -1, all bits set).
+     * @param sensorGroup - Sensor group bits (default 1).
+     * @param sensorMask - Sensor mask bits (default -1, all bits set).
+     * @param fluidGroup - Fluid group bits (default 1).
+     * @param fluidMask - Fluid mask bits (default -1, all bits set).
+     */
     constructor(collisionGroup?: number, collisionMask?: number, sensorGroup?: number, sensorMask?: number, fluidGroup?: number, fluidMask?: number);
+    /** Bit-mask identifying which collision group(s) this shape belongs to. */
     get collisionGroup(): number;
     set collisionGroup(value: number);
+    /** Bit-mask of collision groups this shape will collide with. */
     get collisionMask(): number;
     set collisionMask(value: number);
+    /** Bit-mask identifying which sensor group(s) this shape belongs to. */
     get sensorGroup(): number;
     set sensorGroup(value: number);
+    /** Bit-mask of sensor groups this shape will sense. */
     get sensorMask(): number;
     set sensorMask(value: number);
+    /** Bit-mask identifying which fluid group(s) this shape belongs to. */
     get fluidGroup(): number;
     set fluidGroup(value: number);
+    /** Bit-mask of fluid groups this shape will interact with as a fluid. */
     get fluidMask(): number;
     set fluidMask(value: number);
+    /** Arbitrary user data attached to this filter. */
     get userData(): Record<string, unknown>;
+    /** Read-only list of shapes currently using this filter. */
     get shapes(): any;
+    /**
+     * Test whether two filters allow collision interaction.
+     * @param filter - The other filter to test against.
+     * @returns `true` if the two filters' group/mask bits permit collision.
+     */
     shouldCollide(filter: InteractionFilter): boolean;
+    /**
+     * Test whether two filters allow sensor interaction.
+     * @param filter - The other filter to test against.
+     * @returns `true` if the two filters' group/mask bits permit sensing.
+     */
     shouldSense(filter: InteractionFilter): boolean;
+    /**
+     * Test whether two filters allow fluid interaction.
+     * @param filter - The other filter to test against.
+     * @returns `true` if the two filters' group/mask bits permit fluid interaction.
+     */
     shouldFlow(filter: InteractionFilter): boolean;
+    /** Create a copy of this filter with the same group/mask values. */
     copy(): InteractionFilter;
+    /** Return a hex-formatted string representation of all group/mask pairs. */
     toString(): string;
 }
 
@@ -2439,7 +2583,7 @@ declare class Arbiter {
      * Overridden by {@link CollisionArbiter} and {@link FluidArbiter}.
      *
      * @param body - One of the two interacting bodies, or `null` for the combined impulse.
-     * @param freshOnly - When `true`, only count fresh (new) contacts. Default `false`.
+     * @param _freshOnly - When `true`, only count fresh (new) contacts. Default `false`.
      */
     totalImpulse(body?: Body | null, _freshOnly?: boolean): Vec3;
     toString(): string;
@@ -3516,6 +3660,194 @@ declare class PulleyJoint extends Constraint {
     visitBodies(lambda: (body: Body) => void): void;
 }
 
+/**
+ * ZPP_Constraint — Internal base class for all constraints / joints.
+ *
+ * Manages activation/deactivation, callback types, space integration,
+ * and provides stubs for solver methods overridden by joint subclasses.
+ *
+ * Converted from nape-compiled.js lines 21424–21827.
+ */
+declare class ZPP_Constraint {
+    static __name__: string[];
+    /**
+     * Namespace references, set by the compiled module after import.
+     * _nape = the `nape` public namespace (for CbTypeIterator in copyto)
+     * _zpp = the `zpp_nape` internal namespace (for ZNPList_*, ZPP_CbSet, etc.)
+     */
+    static _nape: any;
+    static _zpp: any;
+    outer: any;
+    id: number;
+    userData: any;
+    compound: any;
+    space: any;
+    active: boolean;
+    stiff: boolean;
+    frequency: number;
+    damping: number;
+    maxForce: number;
+    maxError: number;
+    breakUnderForce: boolean;
+    breakUnderError: boolean;
+    removeOnBreak: boolean;
+    component: any;
+    ignore: boolean;
+    __velocity: boolean;
+    cbTypes: any;
+    cbSet: any;
+    wrap_cbTypes: any;
+    pre_dt: number;
+    __class__: any;
+    constructor();
+    /**
+     * Initialise base constraint fields.
+     * Extracted into a separate method because compiled joint subclasses
+     * call `ZPP_Constraint.call(this)` — ES classes can't be invoked that
+     * way, so the compiled wrapper delegates to this method instead.
+     */
+    _initBase(): void;
+    clear(): void;
+    activeBodies(): void;
+    inactiveBodies(): void;
+    clearcache(): void;
+    validate(): void;
+    wake_connected(): void;
+    forest(): void;
+    broken(): void;
+    warmStart(): void;
+    draw(_g: any): void;
+    pair_exists(_id: any, _di: any): boolean;
+    preStep(_dt: number): boolean;
+    applyImpulseVel(): boolean;
+    applyImpulsePos(): boolean;
+    copy(_dict?: any, _todo?: any): any;
+    immutable_midstep(name: string): void;
+    setupcbTypes(): void;
+    immutable_cbTypes(): void;
+    wrap_cbTypes_subber(pcb: any): void;
+    wrap_cbTypes_adder(cb: any): boolean;
+    insert_cbtype(cb: any): void;
+    alloc_cbSet(): void;
+    dealloc_cbSet(): void;
+    activate(): void;
+    deactivate(): void;
+    addedToSpace(): void;
+    removedFromSpace(): void;
+    activeInSpace(): void;
+    inactiveOrOutSpace(): void;
+    wake(): void;
+    copyto(ret: any): void;
+    static _findRoot(comp: any): any;
+    static _unionComponents(a: any, b: any): void;
+}
+
+/**
+ * ZPP_UserBody — pairs a body with a reference count for user constraints.
+ *
+ * Converted from nape-compiled.js lines 28038–28054.
+ */
+declare class ZPP_UserBody {
+    static __name__: string[];
+    cnt: number;
+    body: any;
+    constructor(cnt: number, body: any);
+}
+
+/**
+ * ZPP_UserConstraint — Internal N-DOF user-defined constraint with Cholesky decomposition.
+ *
+ * A generic constraint where the user supplies callbacks for effective mass,
+ * velocity/position errors, impulse application, and clamping.  The solver
+ * factorises the effective-mass matrix via Cholesky (solve/transform) and
+ * drives the constraint each step through warmStart / applyImpulseVel /
+ * applyImpulsePos.
+ *
+ * Converted from nape-compiled.js lines 27368–28037.
+ */
+
+declare class ZPP_UserConstraint extends ZPP_Constraint {
+    static __name__: string[];
+    static __super__: typeof ZPP_Constraint;
+    outer_zn: any;
+    bodies: ZPP_UserBody[];
+    dim: number;
+    jAcc: number[];
+    bias: number[];
+    stepped: boolean;
+    L: number[];
+    y: number[];
+    soft: number;
+    gamma: number;
+    velonly: boolean;
+    jMax: number;
+    Keff: number[];
+    vec3: any;
+    J: number[];
+    jOld: number[];
+    __class__: any;
+    constructor(dim: number, velonly: boolean);
+    bindVec2_invalidate(_: any): void;
+    addBody(b: any): void;
+    remBody(b: any): boolean;
+    bodyImpulse(b: any): any;
+    activeBodies(): void;
+    inactiveBodies(): void;
+    copy(_dict: any, _todo: any): any;
+    validate(): void;
+    wake_connected(): void;
+    forest(): void;
+    pair_exists(id: number, di: number): boolean;
+    broken(): void;
+    clearcache(): void;
+    lsq(v: number[]): number;
+    _clamp(v: number[], max: number): void;
+    solve(m: number[]): number[];
+    transform(L: number[], x: number[]): void;
+    preStep(dt: number): boolean;
+    warmStart(): void;
+    applyImpulseVel(): boolean;
+    applyImpulsePos(): boolean;
+    draw(g: any): void;
+}
+
+/**
+ * Base class for user-defined N-DOF constraints.
+ *
+ * Fully modernized — uses ZPP_UserConstraint directly (extracted to TypeScript).
+ * Subclass and override the abstract callback methods to define custom constraints.
+ */
+declare abstract class UserConstraint extends Constraint {
+    zpp_inner: ZPP_UserConstraint;
+    constructor(dimensions: number, velocityOnly?: boolean);
+    __bindVec2(): Vec2;
+    /** Create a copy of this constraint. Must be overridden. */
+    __copy(): UserConstraint;
+    /** Called when the constraint breaks. Optional override. */
+    __broken(): void;
+    /** Called to validate the constraint. Optional override. */
+    __validate(): void;
+    /** Draw debug visualization. Optional override. */
+    __draw(_debug: any): void;
+    /** Prepare the constraint for solving. Optional override. */
+    __prepare(): void;
+    /** Compute positional error. Must be overridden for non-velocity-only constraints. */
+    __position(_err: number[]): void;
+    /** Compute velocity error. Must be overridden. */
+    __velocity(_err: number[]): void;
+    /** Compute effective mass matrix (upper triangle). Must be overridden. */
+    __eff_mass(_eff: number[]): void;
+    /** Clamp accumulated impulse. Optional override. */
+    __clamp(_jAcc: number[]): void;
+    /** Apply impulse to a body. Must be overridden. */
+    __impulse(_imp: number[], _body: Body, _out: any): void;
+    impulse(): MatMN;
+    bodyImpulse(body: Body): Vec3;
+    visitBodies(lambda: (body: Body) => void): void;
+    __invalidate(): void;
+    __registerBody(oldBody: Body | null, newBody: Body | null): Body | null;
+}
+
 declare const VERSION: string;
 
-export { AABB, AngleJoint, Arbiter, ArbiterType, Body, BodyCallback, BodyListener, BodyType, Broadphase, Callback, CbEvent, CbType, Circle, CollisionArbiter, Compound, Constraint, ConstraintCallback, ConstraintListener, Contact, ConvexResult, DistanceJoint, Edge, FluidArbiter, FluidProperties, Geom, GeomPoly, GravMassMode, InertiaMode, InteractionCallback, InteractionFilter, InteractionGroup, InteractionListener, InteractionType, Interactor, LineJoint, Listener, ListenerType, MarchingSquares, MassMode, Mat23, MatMN, Material, MotorJoint, NapeList, OptionType, PivotJoint, Polygon, PreCallback, PreFlag, PreListener, PulleyJoint, Ray, RayResult, Shape, ShapeType, Space, VERSION, ValidationResult, Vec2, Vec3, WeldJoint, Winding };
+export { AABB, AngleJoint, Arbiter, ArbiterType, Body, BodyCallback, BodyListener, BodyType, Broadphase, Callback, CbEvent, CbType, type CbTypeSet, Circle, CollisionArbiter, Compound, Constraint, ConstraintCallback, ConstraintListener, Contact, ConvexResult, DistanceJoint, Edge, FluidArbiter, FluidProperties, Geom, GeomPoly, GravMassMode, InertiaMode, InteractionCallback, InteractionFilter, InteractionGroup, InteractionListener, InteractionType, Interactor, LineJoint, Listener, ListenerType, MarchingSquares, MassMode, Mat23, MatMN, Material, MotorJoint, NapeList, OptionType, PivotJoint, Polygon, PreCallback, PreFlag, PreListener, PulleyJoint, Ray, RayResult, Shape, ShapeType, Space, UserConstraint, VERSION, ValidationResult, Vec2, Vec3, WeldJoint, Winding };