@newkrok/nape-js 3.22.0 → 3.23.0

package/dist/index.d.cts

@@ -1656,6 +1656,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, 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

@@ -1656,6 +1656,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, type TriggerHandler, TriggerZone, type TriggerZoneOptions, UserConstraint, VERSION, ValidationResult, Vec2, Vec3, type VoronoiCell, type VoronoiPoint, type VoronoiResult, WeldJoint, Winding, computeVoronoi, createConcaveBody, fractureBody, generateFractureSites };