@newkrok/nape-js 3.22.1 → 3.24.0

package/dist/index.d.cts

@@ -1169,6 +1169,70 @@ declare class PulleyJoint extends Constraint {
     visitBodies(lambda: (body: Body) => void): void;
 }
 
+/**
+ * A spring/damper constraint between two anchor points on two bodies.
+ *
+ * Applies a spring force that pulls or pushes the anchors toward a target
+ * `restLength`. The spring behavior is controlled by `frequency` (Hz) and
+ * `damping` (ratio), inherited from {@link Constraint}.
+ *
+ * Unlike {@link DistanceJoint}, a SpringJoint:
+ * - Is **always soft** — there is no rigid/stiff mode.
+ * - Has a single `restLength` instead of a `[jointMin, jointMax]` range.
+ * - Applies force in **both directions** (compression and extension).
+ * - Never goes slack — the spring always exerts a restorative force.
+ *
+ * Ideal for: vehicle suspension, soft-body connections, ragdoll hair/cloth,
+ * bouncy UI animations, bridge/rope segments, trampolines.
+ *
+ * @example
+ * ```ts
+ * const spring = new SpringJoint(
+ *   body1, body2,
+ *   Vec2.weak(0, 0),   // anchor on body1 (local)
+ *   Vec2.weak(0, 0),   // anchor on body2 (local)
+ *   100,               // rest length (pixels)
+ * );
+ * spring.frequency = 5;  // 5 Hz oscillation
+ * spring.damping = 0.5;  // underdamped (bouncy)
+ * spring.space = space;
+ * ```
+ */
+declare class SpringJoint extends Constraint {
+    /**
+     * @param body1 - First body, or `null` for a static world anchor.
+     * @param body2 - Second body, or `null` for a static world anchor.
+     * @param anchor1 - Anchor point in `body1`'s local space (disposed if weak).
+     * @param anchor2 - Anchor point in `body2`'s local space (disposed if weak).
+     * @param restLength - Equilibrium distance between anchors (must be `>= 0`).
+     */
+    constructor(body1: Body | null, body2: Body | null, anchor1: Vec2, anchor2: Vec2, restLength: number);
+    /** First body. `null` treats the anchor as a static world point. */
+    get body1(): Body;
+    set body1(value: Body | null);
+    /** Second body. `null` treats the anchor as a static world point. */
+    get body2(): Body;
+    set body2(value: Body | null);
+    /** Anchor point on `body1` in local coordinates. */
+    get anchor1(): Vec2;
+    set anchor1(value: Vec2);
+    /** Anchor point on `body2` in local coordinates. */
+    get anchor2(): Vec2;
+    set anchor2(value: Vec2);
+    /** Equilibrium distance between anchors (pixels, must be `>= 0`). */
+    get restLength(): number;
+    set restLength(value: number);
+    /**
+     * SpringJoint is always soft — setting `stiff` to `true` is not allowed.
+     * Use {@link DistanceJoint} if you need a rigid distance constraint.
+     */
+    get stiff(): boolean;
+    set stiff(_value: boolean);
+    impulse(): MatMN;
+    bodyImpulse(body: Body): Vec3;
+    visitBodies(lambda: (body: Body) => void): void;
+}
+
 /**
  * ZPP_Constraint — Internal base class for all constraints / joints.
  *
@@ -1656,6 +1720,146 @@ declare class TriggerZone {
     private _removeListener;
 }
 
+/**
+ * Voronoi diagram generation for 2D point sets.
+ *
+ * Uses the half-plane intersection method: for each site, start with the
+ * bounding box and clip by the perpendicular bisector against every other site.
+ * This is O(n²) but perfectly robust for the fracture use-case (typically 4–30
+ * sites). Every cell is guaranteed to be a finite, closed, convex polygon.
+ *
+ * Designed for use in fracture/destruction systems.
+ */
+/** A 2D point (plain object — avoids coupling to Vec2 pooling). */
+interface VoronoiPoint {
+    x: number;
+    y: number;
+}
+/** A single Voronoi cell: the site that generated it and its polygon vertices (CCW). */
+interface VoronoiCell {
+    /** The generating site index (into the original points array). */
+    siteIndex: number;
+    /** The generating site coordinates. */
+    site: VoronoiPoint;
+    /** Cell polygon vertices in counter-clockwise order. */
+    vertices: VoronoiPoint[];
+}
+/** Result of a Voronoi diagram computation. */
+interface VoronoiResult {
+    /** One cell per input site, in the same order as the input points. */
+    cells: VoronoiCell[];
+}
+/**
+ * Compute the Voronoi diagram for a set of 2D points, clipped to a bounding box.
+ *
+ * Uses half-plane intersection: for each site, clips the bounding rectangle by
+ * the perpendicular bisector with every other site. Produces one convex cell per
+ * site, all cells together tile the bounding box exactly.
+ *
+ * @param points - Array of site points. Must contain at least 1 point.
+ * @param bounds - Clipping rectangle `{ minX, minY, maxX, maxY }`.
+ * @returns A `VoronoiResult` containing one cell per input point.
+ *
+ * @example
+ * ```ts
+ * const result = computeVoronoi(
+ *   [{ x: 10, y: 10 }, { x: 90, y: 50 }, { x: 50, y: 90 }],
+ *   { minX: 0, minY: 0, maxX: 100, maxY: 100 },
+ * );
+ * for (const cell of result.cells) {
+ *   console.log(`Site ${cell.siteIndex}:`, cell.vertices);
+ * }
+ * ```
+ */
+declare function computeVoronoi(points: ReadonlyArray<Readonly<VoronoiPoint>>, bounds: {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}): VoronoiResult;
+/**
+ * Generate random Voronoi fracture sites within a polygon.
+ *
+ * Places `count` random points inside the given polygon using rejection
+ * sampling. Useful for generating fracture patterns.
+ *
+ * @param vertices - Polygon vertices (as VoronoiPoint[]).
+ * @param count - Number of sites to generate.
+ * @param random - Optional RNG function (default `Math.random`).
+ * @returns Array of points guaranteed to be inside the polygon.
+ */
+declare function generateFractureSites(vertices: ReadonlyArray<Readonly<VoronoiPoint>>, count: number, random?: () => number): VoronoiPoint[];
+
+/**
+ * Options for body fracture.
+ */
+interface FractureOptions {
+    /** Number of fracture fragments to generate. Default `8`. */
+    fragmentCount?: number;
+    /**
+     * Material to apply to all fragment shapes.
+     * If not specified, the first shape's material is copied from the original body.
+     */
+    material?: Material;
+    /** Interaction filter for all fragment shapes. */
+    filter?: InteractionFilter;
+    /**
+     * Explosion impulse magnitude applied radially from the impact point.
+     * Default `0` (no explosion impulse — fragments inherit body velocity).
+     */
+    explosionImpulse?: number;
+    /**
+     * Custom RNG function for reproducible fracture patterns.
+     * Default `Math.random`.
+     */
+    random?: () => number;
+    /**
+     * If true, automatically add fragments to the same space as the original body
+     * and remove the original body. Default `true`.
+     */
+    addToSpace?: boolean;
+    /**
+     * Custom Voronoi site positions (in body-local space).
+     * If provided, `fragmentCount` is ignored and these exact sites are used.
+     */
+    sites?: VoronoiPoint[];
+}
+/**
+ * Result of a fracture operation.
+ */
+interface FractureResult {
+    /** The generated fragment bodies. */
+    fragments: Body[];
+    /** The original body that was fractured (removed from space if `addToSpace` is true). */
+    originalBody: Body;
+}
+/**
+ * Fracture a body into multiple pieces using Voronoi decomposition.
+ *
+ * Takes the first polygon shape on the body, generates Voronoi cells within it,
+ * clips each cell to the original polygon, and creates a new dynamic body for
+ * each fragment. Fragments inherit the original body's linear and angular
+ * velocity, plus an optional radial explosion impulse.
+ *
+ * @param body - The body to fracture. Must have at least one polygon shape.
+ * @param impactPoint - World-space point where the fracture originates.
+ *   Used as the center bias for site generation and explosion impulse direction.
+ * @param options - Fracture configuration.
+ * @returns A `FractureResult` with the array of fragment bodies.
+ *
+ * @throws If the body has no polygon shapes.
+ *
+ * @example
+ * ```ts
+ * const result = fractureBody(box, Vec2.get(100, 50), {
+ *   fragmentCount: 12,
+ *   explosionImpulse: 200,
+ * });
+ * // result.fragments are already in the space
+ * ```
+ */
+declare function fractureBody(body: Body, impactPoint: Vec2, options?: FractureOptions): FractureResult;
+
 declare const VERSION: string;
 
-export { AABB, AngleJoint, Arbiter, Body, BodyCallback, BodyListener, BodyType, Callback, Capsule, CbEvent, CbType, CharacterController, type CharacterControllerOptions, Circle, CollisionArbiter, type ConcaveBodyOptions, Constraint, ConstraintCallback, ConstraintListener, Contact, DebugDrawFlags, DistanceJoint, Geom, GeomPoly, InteractionCallback, InteractionFilter, InteractionListener, InteractionType, Interactor, LineJoint, Listener, MarchingSquares, MatMN, Material, MotorJoint, type MoveResult, OptionType, PivotJoint, PreCallback, PreFlag, PreListener, PulleyJoint, Shape, ShapeType, Space, type TriggerHandler, TriggerZone, type TriggerZoneOptions, UserConstraint, VERSION, ValidationResult, Vec2, Vec3, WeldJoint, Winding, createConcaveBody };
+export { AABB, AngleJoint, Arbiter, Body, BodyCallback, BodyListener, BodyType, Callback, Capsule, CbEvent, CbType, CharacterController, type CharacterControllerOptions, Circle, CollisionArbiter, type ConcaveBodyOptions, Constraint, ConstraintCallback, ConstraintListener, Contact, DebugDrawFlags, DistanceJoint, type FractureOptions, type FractureResult, Geom, GeomPoly, InteractionCallback, InteractionFilter, InteractionListener, InteractionType, Interactor, LineJoint, Listener, MarchingSquares, MatMN, Material, MotorJoint, type MoveResult, OptionType, PivotJoint, PreCallback, PreFlag, PreListener, PulleyJoint, Shape, ShapeType, Space, SpringJoint, type TriggerHandler, TriggerZone, type TriggerZoneOptions, UserConstraint, VERSION, ValidationResult, Vec2, Vec3, type VoronoiCell, type VoronoiPoint, type VoronoiResult, WeldJoint, Winding, computeVoronoi, createConcaveBody, fractureBody, generateFractureSites };

package/dist/index.d.ts

@@ -1169,6 +1169,70 @@ declare class PulleyJoint extends Constraint {
     visitBodies(lambda: (body: Body) => void): void;
 }
 
+/**
+ * A spring/damper constraint between two anchor points on two bodies.
+ *
+ * Applies a spring force that pulls or pushes the anchors toward a target
+ * `restLength`. The spring behavior is controlled by `frequency` (Hz) and
+ * `damping` (ratio), inherited from {@link Constraint}.
+ *
+ * Unlike {@link DistanceJoint}, a SpringJoint:
+ * - Is **always soft** — there is no rigid/stiff mode.
+ * - Has a single `restLength` instead of a `[jointMin, jointMax]` range.
+ * - Applies force in **both directions** (compression and extension).
+ * - Never goes slack — the spring always exerts a restorative force.
+ *
+ * Ideal for: vehicle suspension, soft-body connections, ragdoll hair/cloth,
+ * bouncy UI animations, bridge/rope segments, trampolines.
+ *
+ * @example
+ * ```ts
+ * const spring = new SpringJoint(
+ *   body1, body2,
+ *   Vec2.weak(0, 0),   // anchor on body1 (local)
+ *   Vec2.weak(0, 0),   // anchor on body2 (local)
+ *   100,               // rest length (pixels)
+ * );
+ * spring.frequency = 5;  // 5 Hz oscillation
+ * spring.damping = 0.5;  // underdamped (bouncy)
+ * spring.space = space;
+ * ```
+ */
+declare class SpringJoint extends Constraint {
+    /**
+     * @param body1 - First body, or `null` for a static world anchor.
+     * @param body2 - Second body, or `null` for a static world anchor.
+     * @param anchor1 - Anchor point in `body1`'s local space (disposed if weak).
+     * @param anchor2 - Anchor point in `body2`'s local space (disposed if weak).
+     * @param restLength - Equilibrium distance between anchors (must be `>= 0`).
+     */
+    constructor(body1: Body | null, body2: Body | null, anchor1: Vec2, anchor2: Vec2, restLength: number);
+    /** First body. `null` treats the anchor as a static world point. */
+    get body1(): Body;
+    set body1(value: Body | null);
+    /** Second body. `null` treats the anchor as a static world point. */
+    get body2(): Body;
+    set body2(value: Body | null);
+    /** Anchor point on `body1` in local coordinates. */
+    get anchor1(): Vec2;
+    set anchor1(value: Vec2);
+    /** Anchor point on `body2` in local coordinates. */
+    get anchor2(): Vec2;
+    set anchor2(value: Vec2);
+    /** Equilibrium distance between anchors (pixels, must be `>= 0`). */
+    get restLength(): number;
+    set restLength(value: number);
+    /**
+     * SpringJoint is always soft — setting `stiff` to `true` is not allowed.
+     * Use {@link DistanceJoint} if you need a rigid distance constraint.
+     */
+    get stiff(): boolean;
+    set stiff(_value: boolean);
+    impulse(): MatMN;
+    bodyImpulse(body: Body): Vec3;
+    visitBodies(lambda: (body: Body) => void): void;
+}
+
 /**
  * ZPP_Constraint — Internal base class for all constraints / joints.
  *
@@ -1656,6 +1720,146 @@ declare class TriggerZone {
     private _removeListener;
 }
 
+/**
+ * Voronoi diagram generation for 2D point sets.
+ *
+ * Uses the half-plane intersection method: for each site, start with the
+ * bounding box and clip by the perpendicular bisector against every other site.
+ * This is O(n²) but perfectly robust for the fracture use-case (typically 4–30
+ * sites). Every cell is guaranteed to be a finite, closed, convex polygon.
+ *
+ * Designed for use in fracture/destruction systems.
+ */
+/** A 2D point (plain object — avoids coupling to Vec2 pooling). */
+interface VoronoiPoint {
+    x: number;
+    y: number;
+}
+/** A single Voronoi cell: the site that generated it and its polygon vertices (CCW). */
+interface VoronoiCell {
+    /** The generating site index (into the original points array). */
+    siteIndex: number;
+    /** The generating site coordinates. */
+    site: VoronoiPoint;
+    /** Cell polygon vertices in counter-clockwise order. */
+    vertices: VoronoiPoint[];
+}
+/** Result of a Voronoi diagram computation. */
+interface VoronoiResult {
+    /** One cell per input site, in the same order as the input points. */
+    cells: VoronoiCell[];
+}
+/**
+ * Compute the Voronoi diagram for a set of 2D points, clipped to a bounding box.
+ *
+ * Uses half-plane intersection: for each site, clips the bounding rectangle by
+ * the perpendicular bisector with every other site. Produces one convex cell per
+ * site, all cells together tile the bounding box exactly.
+ *
+ * @param points - Array of site points. Must contain at least 1 point.
+ * @param bounds - Clipping rectangle `{ minX, minY, maxX, maxY }`.
+ * @returns A `VoronoiResult` containing one cell per input point.
+ *
+ * @example
+ * ```ts
+ * const result = computeVoronoi(
+ *   [{ x: 10, y: 10 }, { x: 90, y: 50 }, { x: 50, y: 90 }],
+ *   { minX: 0, minY: 0, maxX: 100, maxY: 100 },
+ * );
+ * for (const cell of result.cells) {
+ *   console.log(`Site ${cell.siteIndex}:`, cell.vertices);
+ * }
+ * ```
+ */
+declare function computeVoronoi(points: ReadonlyArray<Readonly<VoronoiPoint>>, bounds: {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}): VoronoiResult;
+/**
+ * Generate random Voronoi fracture sites within a polygon.
+ *
+ * Places `count` random points inside the given polygon using rejection
+ * sampling. Useful for generating fracture patterns.
+ *
+ * @param vertices - Polygon vertices (as VoronoiPoint[]).
+ * @param count - Number of sites to generate.
+ * @param random - Optional RNG function (default `Math.random`).
+ * @returns Array of points guaranteed to be inside the polygon.
+ */
+declare function generateFractureSites(vertices: ReadonlyArray<Readonly<VoronoiPoint>>, count: number, random?: () => number): VoronoiPoint[];
+
+/**
+ * Options for body fracture.
+ */
+interface FractureOptions {
+    /** Number of fracture fragments to generate. Default `8`. */
+    fragmentCount?: number;
+    /**
+     * Material to apply to all fragment shapes.
+     * If not specified, the first shape's material is copied from the original body.
+     */
+    material?: Material;
+    /** Interaction filter for all fragment shapes. */
+    filter?: InteractionFilter;
+    /**
+     * Explosion impulse magnitude applied radially from the impact point.
+     * Default `0` (no explosion impulse — fragments inherit body velocity).
+     */
+    explosionImpulse?: number;
+    /**
+     * Custom RNG function for reproducible fracture patterns.
+     * Default `Math.random`.
+     */
+    random?: () => number;
+    /**
+     * If true, automatically add fragments to the same space as the original body
+     * and remove the original body. Default `true`.
+     */
+    addToSpace?: boolean;
+    /**
+     * Custom Voronoi site positions (in body-local space).
+     * If provided, `fragmentCount` is ignored and these exact sites are used.
+     */
+    sites?: VoronoiPoint[];
+}
+/**
+ * Result of a fracture operation.
+ */
+interface FractureResult {
+    /** The generated fragment bodies. */
+    fragments: Body[];
+    /** The original body that was fractured (removed from space if `addToSpace` is true). */
+    originalBody: Body;
+}
+/**
+ * Fracture a body into multiple pieces using Voronoi decomposition.
+ *
+ * Takes the first polygon shape on the body, generates Voronoi cells within it,
+ * clips each cell to the original polygon, and creates a new dynamic body for
+ * each fragment. Fragments inherit the original body's linear and angular
+ * velocity, plus an optional radial explosion impulse.
+ *
+ * @param body - The body to fracture. Must have at least one polygon shape.
+ * @param impactPoint - World-space point where the fracture originates.
+ *   Used as the center bias for site generation and explosion impulse direction.
+ * @param options - Fracture configuration.
+ * @returns A `FractureResult` with the array of fragment bodies.
+ *
+ * @throws If the body has no polygon shapes.
+ *
+ * @example
+ * ```ts
+ * const result = fractureBody(box, Vec2.get(100, 50), {
+ *   fragmentCount: 12,
+ *   explosionImpulse: 200,
+ * });
+ * // result.fragments are already in the space
+ * ```
+ */
+declare function fractureBody(body: Body, impactPoint: Vec2, options?: FractureOptions): FractureResult;
+
 declare const VERSION: string;
 
-export { AABB, AngleJoint, Arbiter, Body, BodyCallback, BodyListener, BodyType, Callback, Capsule, CbEvent, CbType, CharacterController, type CharacterControllerOptions, Circle, CollisionArbiter, type ConcaveBodyOptions, Constraint, ConstraintCallback, ConstraintListener, Contact, DebugDrawFlags, DistanceJoint, Geom, GeomPoly, InteractionCallback, InteractionFilter, InteractionListener, InteractionType, Interactor, LineJoint, Listener, MarchingSquares, MatMN, Material, MotorJoint, type MoveResult, OptionType, PivotJoint, PreCallback, PreFlag, PreListener, PulleyJoint, Shape, ShapeType, Space, type TriggerHandler, TriggerZone, type TriggerZoneOptions, UserConstraint, VERSION, ValidationResult, Vec2, Vec3, WeldJoint, Winding, createConcaveBody };
+export { AABB, AngleJoint, Arbiter, Body, BodyCallback, BodyListener, BodyType, Callback, Capsule, CbEvent, CbType, CharacterController, type CharacterControllerOptions, Circle, CollisionArbiter, type ConcaveBodyOptions, Constraint, ConstraintCallback, ConstraintListener, Contact, DebugDrawFlags, DistanceJoint, type FractureOptions, type FractureResult, Geom, GeomPoly, InteractionCallback, InteractionFilter, InteractionListener, InteractionType, Interactor, LineJoint, Listener, MarchingSquares, MatMN, Material, MotorJoint, type MoveResult, OptionType, PivotJoint, PreCallback, PreFlag, PreListener, PulleyJoint, Shape, ShapeType, Space, SpringJoint, type TriggerHandler, TriggerZone, type TriggerZoneOptions, UserConstraint, VERSION, ValidationResult, Vec2, Vec3, type VoronoiCell, type VoronoiPoint, type VoronoiResult, WeldJoint, Winding, computeVoronoi, createConcaveBody, fractureBody, generateFractureSites };