@newkrok/nape-js 3.31.0 → 3.32.0

package/dist/index.d.cts

@@ -2199,6 +2199,357 @@ declare class RadialGravityFieldGroup {
     apply(space: Space): void;
 }
 
+/** Shape used for each spawned particle body. */
+type ParticleShape = "circle" | "polygon";
+/** State snapshot passed to the `onSpawn` hook. */
+interface ParticleSpawnState {
+    /** World-space spawn position. */
+    position: Vec2;
+    /** Initial linear velocity. */
+    velocity: Vec2;
+    /** Initial rotation (rad). */
+    angle: number;
+    /** Initial angular velocity (rad/s). */
+    angularVelocity: number;
+    /** Lifetime in seconds. `<= 0` disables auto-death. */
+    lifetime: number;
+    /** Free-form per-particle payload (color, frame index, damage, etc.). */
+    userData: unknown;
+}
+/**
+ * Spawn-position pattern. Position is sampled once per particle, in
+ * emitter-local space (relative to {@link ParticleEmitter.origin}), then
+ * translated into world space.
+ *
+ * - `point` — always at the origin.
+ * - `rect` — uniform inside an axis-aligned rectangle centred on the origin.
+ * - `circle` — uniform inside a disk; `hollow: true` samples the rim only.
+ * - `arc` — on the rim of a circular arc, `angle*` in radians.
+ * - `custom` — user-provided sampler. Receives the emitter's RNG.
+ */
+type SpawnPattern = {
+    kind: "point";
+} | {
+    kind: "rect";
+    width: number;
+    height: number;
+} | {
+    kind: "circle";
+    radius: number;
+    hollow?: boolean;
+} | {
+    kind: "arc";
+    radius: number;
+    angleStart: number;
+    angleEnd: number;
+} | {
+    kind: "custom";
+    sample: (rng: () => number) => Vec2;
+};
+/**
+ * Initial-velocity pattern. The local spawn position is passed to the
+ * `radial` and `custom` samplers so the velocity can depend on where the
+ * particle was spawned (radial = "outward from origin").
+ *
+ * - `fixed` — every particle gets the same velocity vector.
+ * - `cone` — uniformly random direction inside a cone of half-width
+ *   `spread` rad, centred on `direction` rad. Speed uniform in
+ *   `[speedMin, speedMax]`.
+ * - `radial` — outward from the spawn point relative to the origin.
+ *   Speed uniform in `[speedMin, speedMax]`. If the spawn point is exactly
+ *   at the origin, falls back to a random direction.
+ * - `custom` — user-provided sampler. Receives RNG and the local spawn
+ *   position.
+ */
+type VelocityPattern = {
+    kind: "fixed";
+    value: Vec2;
+} | {
+    kind: "cone";
+    direction: number;
+    spread: number;
+    speedMin: number;
+    speedMax: number;
+} | {
+    kind: "radial";
+    speedMin: number;
+    speedMax: number;
+} | {
+    kind: "custom";
+    sample: (rng: () => number, localPos: Vec2) => Vec2;
+};
+/**
+ * What to do when {@link ParticleEmitterOptions.maxParticles} is full and a
+ * new spawn is requested.
+ *
+ * - `drop-oldest` (default) — kill the oldest live particle to make room for
+ *   the new one. Keeps emitter responsive (e.g. bullets always come out).
+ * - `drop-new` — silently drop the new spawn. Protects already-visible
+ *   particles from churn.
+ */
+type ParticleOverflowPolicy = "drop-oldest" | "drop-new";
+/** Reason a particle was killed, passed to `onDeath`. */
+type ParticleDeathReason = "lifetime" | "manual" | "bounds";
+/** World-space rectangle outside which particles auto-die. */
+interface ParticleBounds {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Configuration options for {@link ParticleEmitter}. */
+interface ParticleEmitterOptions {
+    /** Space the emitted particle bodies live in. Required. */
+    space: Space;
+    /**
+     * Spawn anchor. A `Vec2` is captured by reference (mutating it after
+     * construction moves the emitter); a `Body` is tracked by position each
+     * spawn (the body does not need to be in the same space). Required.
+     */
+    origin: Vec2 | Body;
+    /** Spawn-position pattern. @default `{ kind: "point" }` */
+    spawn?: SpawnPattern;
+    /** Initial velocity pattern. @default `{ kind: "fixed", value: (0, 0) }` */
+    velocity?: VelocityPattern;
+    /**
+     * Continuous spawn rate in particles/second. Accumulated across `update()`
+     * calls — fractional rates work. `0` disables continuous spawning (use
+     * {@link ParticleEmitter.emit} for manual bursts).
+     * @default `0`
+     */
+    rate?: number;
+    /**
+     * Periodic-burst count (particles per burst). Combined with
+     * `burstInterval`, fires a burst every `burstInterval` seconds.
+     * @default `0`
+     */
+    burstCount?: number;
+    /**
+     * Period of automatic bursts in seconds. Has no effect when `burstCount`
+     * is `0`.
+     * @default `0`
+     */
+    burstInterval?: number;
+    /**
+     * Maximum simultaneously alive particles. The pool size is capped at this
+     * value too. @default `512`
+     */
+    maxParticles?: number;
+    /** Lifetime range minimum (s). @default `1` */
+    lifetimeMin?: number;
+    /** Lifetime range maximum (s). @default `1` */
+    lifetimeMax?: number;
+    /** Body shape for each particle. @default `"circle"` */
+    particleShape?: ParticleShape;
+    /** Radius for circle particles. Ignored for polygon. @default `2` */
+    particleRadius?: number;
+    /**
+     * Polygon vertices in body-local space (used when
+     * `particleShape: "polygon"`). Defaults to a small square.
+     */
+    particlePolygon?: Vec2[];
+    /** Material applied to every particle shape. @default `new Material()` */
+    particleMaterial?: Material;
+    /**
+     * Filter applied to every particle shape. If omitted and `selfCollision`
+     * is `false`, the emitter generates a self-excluding filter automatically.
+     */
+    particleFilter?: InteractionFilter;
+    /**
+     * Collision-callback type tagged on every particle body. Required for
+     * `onCollide` to fire. The emitter never auto-creates one — pass your own
+     * if you need it (so multiple emitters can share a type, or a single
+     * emitter can match a user-defined cbType).
+     */
+    particleCbType?: CbType;
+    /** Whether particles can rotate. @default `true` */
+    allowRotation?: boolean;
+    /**
+     * When `false` and no explicit `particleFilter` is given, particles
+     * receive a generated filter that skips its own group — particles in the
+     * same emitter never collide with each other. Has no effect when
+     * `particleFilter` is provided. @default `false`
+     */
+    selfCollision?: boolean;
+    /** Policy when `maxParticles` is reached. @default `"drop-oldest"` */
+    overflowPolicy?: ParticleOverflowPolicy;
+    /** Optional world-space bounds — particles outside die instantly. */
+    bounds?: ParticleBounds;
+    /**
+     * Deterministic RNG. All emitter randomness (spawn jitter, velocity cone,
+     * lifetime sampling) flows through this. @default `Math.random` */
+    random?: () => number;
+    /** Whether the emitter is active. @default `true` */
+    enabled?: boolean;
+    /** Fired once per spawn, after the body is in the space. */
+    onSpawn?: (state: ParticleSpawnState, body: Body) => void;
+    /** Fired every `update()` for each live particle (ages > 0). */
+    onUpdate?: (body: Body, age: number, dt: number) => void;
+    /** Fired when a particle dies (lifetime, bounds, manual, or `killAll`). */
+    onDeath?: (body: Body, reason: ParticleDeathReason) => void;
+    /**
+     * Fired when a particle's body collides with another body. Requires
+     * `particleCbType` to be set. The handler runs from inside a Space
+     * callback — do not mutate the space synchronously; use
+     * {@link ParticleEmitter.requestKill} for deferred cleanup.
+     */
+    onCollide?: (body: Body, other: Body) => void;
+}
+/**
+ * Physics-aware particle emitter — a pooled, lifecycle-managed swarm of
+ * dynamic bodies. Each particle is a real {@link Body} with a {@link Circle}
+ * or {@link Polygon} shape, so it collides with the world, reacts to
+ * gravity / fluids / forces, and triggers callbacks like any other body.
+ *
+ * @example
+ * ```ts
+ * // Volcano: emit lava drops upward in a 40-deg cone.
+ * const volcano = new ParticleEmitter({
+ *   space,
+ *   origin: new Vec2(400, 100),
+ *   velocity: {
+ *     kind: "cone",
+ *     direction: -Math.PI / 2,
+ *     spread: Math.PI / 9,
+ *     speedMin: 350,
+ *     speedMax: 600,
+ *   },
+ *   rate: 80,
+ *   lifetimeMin: 4,
+ *   lifetimeMax: 8,
+ *   particleRadius: 3,
+ *   maxParticles: 600,
+ * });
+ *
+ * // Each frame, before space.step():
+ * volcano.update(1 / 60);
+ * space.step(1 / 60);
+ * ```
+ */
+declare class ParticleEmitter {
+    enabled: boolean;
+    origin: Vec2 | Body;
+    spawn: SpawnPattern;
+    velocity: VelocityPattern;
+    rate: number;
+    burstCount: number;
+    burstInterval: number;
+    maxParticles: number;
+    lifetimeMin: number;
+    lifetimeMax: number;
+    allowRotation: boolean;
+    overflowPolicy: ParticleOverflowPolicy;
+    bounds: ParticleBounds | null;
+    onSpawn: ((state: ParticleSpawnState, body: Body) => void) | null;
+    onUpdate: ((body: Body, age: number, dt: number) => void) | null;
+    onDeath: ((body: Body, reason: ParticleDeathReason) => void) | null;
+    onCollide: ((body: Body, other: Body) => void) | null;
+    readonly space: Space;
+    readonly particleShape: ParticleShape;
+    readonly particleRadius: number;
+    readonly particlePolygon: Vec2[] | null;
+    readonly particleMaterial: Material;
+    readonly particleFilter: InteractionFilter;
+    readonly particleCbType: CbType | null;
+    readonly random: () => number;
+    private _alive;
+    private _ages;
+    private _lifetimes;
+    private _pool;
+    private _totalSpawned;
+    private _rateAccumulator;
+    private _burstAccumulator;
+    private _killSet;
+    private _listener;
+    private _destroyed;
+    constructor(options: ParticleEmitterOptions);
+    /** Live particle bodies. Read-only — do not mutate. */
+    get active(): ReadonlyArray<Body>;
+    /**
+     * Per-particle age in seconds, indexed parallel to {@link active}.
+     * Read-only — do not mutate. Useful for renderers that fade particles
+     * by `age / lifetime`.
+     */
+    get ages(): ReadonlyArray<number>;
+    /**
+     * Per-particle lifetime in seconds, indexed parallel to {@link active}.
+     * Read-only — do not mutate.
+     */
+    get lifetimes(): ReadonlyArray<number>;
+    /** Number of bodies currently in the recycle pool. */
+    get poolSize(): number;
+    /** Total spawn count over the lifetime of this emitter. */
+    get totalSpawned(): number;
+    private _originXY;
+    /** Sample a position in emitter-local space. */
+    private _sampleSpawn;
+    /** Sample initial velocity given the local spawn position. */
+    private _sampleVelocity;
+    private _sampleLifetime;
+    private _buildBody;
+    /** Take a body out of the pool, or build a new one. */
+    private _acquire;
+    /**
+     * Reset a body's per-life mutable state and add it to the space at the
+     * given world position with the given velocity.
+     */
+    private _reviveBody;
+    /**
+     * Spawn `count` particles immediately. Returns the live bodies that were
+     * spawned (length may be < `count` when the emitter is full and
+     * `overflowPolicy` is `"drop-new"`).
+     */
+    emit(count: number): Body[];
+    /** Spawn a single particle. Returns the body or `null` if dropped. */
+    private _spawnOne;
+    /** Remove the live particle at `index` (swap-pop) and return it to the pool. */
+    private _killAt;
+    /**
+     * Mark a body for death at the start of the next `update()` call. Safe to
+     * call from inside collision callbacks. No-op if the body is not a live
+     * particle of this emitter.
+     */
+    requestKill(body: Body): void;
+    private _flushKillSet;
+    /** Kill every live particle. Bodies return to the pool. */
+    killAll(): void;
+    /**
+     * Advance lifetimes, fire `onUpdate`, kill expired / out-of-bounds
+     * particles, and run continuous / periodic spawning.
+     *
+     * Call once per frame, **before** `space.step()`. `dt` should match the
+     * step size you'll pass to `space.step()`.
+     */
+    update(dt: number): void;
+    /**
+     * Remove every body (live + pooled) from the space, drop the listener,
+     * and mark the emitter unusable. Subsequent `update` / `emit` calls
+     * throw.
+     */
+    destroy(): void;
+    private _installCollisionListener;
+}
+/**
+ * Composable collection of {@link ParticleEmitter}s — analogous to
+ * {@link RadialGravityFieldGroup}. One `update(dt)` runs every member emitter.
+ */
+declare class ParticleEmitterGroup {
+    /** Ordered list of emitters. Mutate via {@link add} / {@link remove}. */
+    readonly emitters: ParticleEmitter[];
+    /** Add an emitter to the group and return it. */
+    add(emitter: ParticleEmitter): ParticleEmitter;
+    /** Remove an emitter from the group. Returns `true` if it was present. */
+    remove(emitter: ParticleEmitter): boolean;
+    /** Remove all emitters (does NOT call `destroy` on them). */
+    clear(): void;
+    /** Number of emitters currently in the group. */
+    get length(): number;
+    /** Advance every emitter. */
+    update(dt: number): void;
+    /** Call `destroy()` on every emitter and clear the group. */
+    destroyAll(): void;
+}
+
 declare const VERSION: string;
 
-export { AABB, AngleJoint, Arbiter, Body, BodyCallback, type BodyFilter, 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, type GravityFalloff, InteractionCallback, InteractionFilter, InteractionListener, InteractionType, Interactor, type LDtkIntGridLayer, LineJoint, Listener, MarchingSquares, MatMN, Material, MotorJoint, type MoveResult, OptionType, PivotJoint, PreCallback, PreFlag, PreListener, PulleyJoint, RadialGravityField, RadialGravityFieldGroup, type RadialGravityFieldOptions, Shape, ShapeType, Space, SpringJoint, type TiledTileLayer, type TilemapGrid, type TilemapMergeMode, type TilemapOptions, type TilemapRect, type TilemapSolidPredicate, type TilemapTileSize, type TriggerHandler, TriggerZone, type TriggerZoneOptions, UserConstraint, VERSION, ValidationResult, Vec2, Vec3, type VoronoiCell, type VoronoiPoint, type VoronoiResult, WeldJoint, Winding, buildTilemapBody, computeVoronoi, createConcaveBody, fractureBody, generateFractureSites, ldtkLayerToGrid, meshTilemap, tiledLayerToGrid };
+export { AABB, AngleJoint, Arbiter, Body, BodyCallback, type BodyFilter, 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, type GravityFalloff, InteractionCallback, InteractionFilter, InteractionListener, InteractionType, Interactor, type LDtkIntGridLayer, LineJoint, Listener, MarchingSquares, MatMN, Material, MotorJoint, type MoveResult, OptionType, type ParticleBounds, type ParticleDeathReason, ParticleEmitter, ParticleEmitterGroup, type ParticleEmitterOptions, type ParticleOverflowPolicy, type ParticleShape, type ParticleSpawnState, PivotJoint, PreCallback, PreFlag, PreListener, PulleyJoint, RadialGravityField, RadialGravityFieldGroup, type RadialGravityFieldOptions, Shape, ShapeType, Space, type SpawnPattern, SpringJoint, type TiledTileLayer, type TilemapGrid, type TilemapMergeMode, type TilemapOptions, type TilemapRect, type TilemapSolidPredicate, type TilemapTileSize, type TriggerHandler, TriggerZone, type TriggerZoneOptions, UserConstraint, VERSION, ValidationResult, Vec2, Vec3, type VelocityPattern, type VoronoiCell, type VoronoiPoint, type VoronoiResult, WeldJoint, Winding, buildTilemapBody, computeVoronoi, createConcaveBody, fractureBody, generateFractureSites, ldtkLayerToGrid, meshTilemap, tiledLayerToGrid };