@newkrok/nape-js 3.30.4 → 3.32.0

package/dist/index.d.ts

@@ -1539,6 +1539,20 @@ interface CharacterControllerOptions {
      * @default null
      */
     filter?: InteractionFilter | null;
+    /**
+     * World-space "down" direction used for ground / wall raycasts.
+     *
+     * Default `Vec2(0, 1)` matches a standard top-down-Y platformer (gravity
+     * points along +Y). Override for radial-gravity / planet-platformer
+     * scenarios — set `cc.down` each frame to the unit vector pointing from
+     * the character toward whatever you treat as "down" (e.g. the nearest
+     * planet's centre). Walls are detected perpendicular to this direction.
+     *
+     * The vector is normalized internally; magnitude is ignored.
+     *
+     * @default Vec2(0, 1)
+     */
+    down?: Vec2;
 }
 /**
  * Velocity-based character controller for 2D platformers.
@@ -1585,6 +1599,8 @@ declare class CharacterController {
     private _maxSlopeAngle;
     private _maxSlopeCos;
     private _filter;
+    private _downX;
+    private _downY;
     private _oneWayListener;
     private _grounded;
     private _groundNormal;
@@ -1601,6 +1617,16 @@ declare class CharacterController {
     get timeSinceGrounded(): number;
     get maxSlopeAngle(): number;
     set maxSlopeAngle(v: number);
+    /**
+     * Current world-space "down" direction used for ground / wall raycasts.
+     * Returns a fresh `Vec2` each call; mutate via {@link setDown} or by
+     * assigning a new `Vec2` to this property.
+     */
+    get down(): Vec2;
+    set down(value: Vec2);
+    /** Update the down direction from raw components (normalized internally). */
+    setDown(x: number, y: number): void;
+    private _setDown;
     /**
      * Set the character body's velocity. Call this each frame **before**
      * `space.step()`.
@@ -1860,6 +1886,670 @@ interface FractureResult {
  */
 declare function fractureBody(body: Body, impactPoint: Vec2, options?: FractureOptions): FractureResult;
 
+/** A 2D row-major grid of tile values. `grid[y][x]` is the cell at row `y`, column `x`. */
+type TilemapGrid = ArrayLike<ArrayLike<number>>;
+/** Predicate deciding whether a tile value at `(x, y)` represents a solid (collidable) cell. */
+type TilemapSolidPredicate = (value: number, x: number, y: number) => boolean;
+/**
+ * Strategy for combining adjacent solid tiles into fewer rectangles.
+ *
+ * - `"none"`   — every solid tile becomes its own 1x1 rectangle
+ * - `"rows"`   — horizontally-adjacent solid tiles within a row are merged
+ * - `"greedy"` — runs are extended both horizontally and vertically using a
+ *   greedy meshing pass (default — produces the fewest rectangles)
+ */
+type TilemapMergeMode = "none" | "rows" | "greedy";
+/** Tile width and height in pixels. */
+interface TilemapTileSize {
+    /** Tile width in pixels. */
+    w: number;
+    /** Tile height in pixels. */
+    h: number;
+}
+/** Configuration options for {@link buildTilemapBody} / {@link meshTilemap}. */
+interface TilemapOptions {
+    /** Tile size in pixels — either a square size or `{ w, h }` for non-square tiles. */
+    tileSize: number | TilemapTileSize;
+    /** Body position (top-left corner of the map in world space). Default `(0, 0)`. */
+    position?: Vec2;
+    /**
+     * Predicate deciding which cells are solid. Default treats any non-zero
+     * value as solid.
+     */
+    solid?: TilemapSolidPredicate;
+    /** Merge strategy — defaults to `"greedy"`. */
+    merge?: TilemapMergeMode;
+    /** Material applied to every generated shape. */
+    material?: Material;
+    /** InteractionFilter applied to every generated shape. */
+    filter?: InteractionFilter;
+    /** CbTypes added to every generated shape. */
+    cbTypes?: CbType[];
+    /** Body type — defaults to `BodyType.STATIC`. Ignored when `body` is provided. */
+    bodyType?: BodyType;
+    /**
+     * Append shapes to this existing body instead of creating a new one. Useful
+     * for chunked maps where many tilemap layers share one body, or when adding
+     * a collision mesh to a body that already exists.
+     */
+    body?: Body;
+}
+/** A rectangle in tile coordinates produced by {@link meshTilemap}. */
+interface TilemapRect {
+    /** Tile column of the rectangle's left edge. */
+    x: number;
+    /** Tile row of the rectangle's top edge. */
+    y: number;
+    /** Width in tiles (>= 1). */
+    w: number;
+    /** Height in tiles (>= 1). */
+    h: number;
+}
+/** Subset of a Tiled JSON tile layer needed for grid extraction. */
+interface TiledTileLayer {
+    /** Flat row-major array of tile GIDs. */
+    data: ArrayLike<number>;
+    /** Width of the layer in tiles. */
+    width: number;
+    /** Height of the layer in tiles. */
+    height: number;
+}
+/** Subset of an LDtk IntGrid layer instance needed for grid extraction. */
+interface LDtkIntGridLayer {
+    /** Row-major flat array of int values (0 = empty). */
+    intGridCsv: ArrayLike<number>;
+    /** Cell-grid width (LDtk's `__cWid`, falls back to `cWid`). */
+    __cWid?: number;
+    /** Cell-grid height (LDtk's `__cHei`, falls back to `cHei`). */
+    __cHei?: number;
+    /** Alternate width key. */
+    cWid?: number;
+    /** Alternate height key. */
+    cHei?: number;
+}
+/**
+ * Convert a 2D grid of tile values into the minimal set of axis-aligned
+ * rectangles that cover the solid cells, using the requested merge strategy.
+ *
+ * The result is geometry-only — no `Body` or `Shape` is created — which makes
+ * this function reusable for debug overlays, rendering, or custom body
+ * construction. {@link buildTilemapBody} is a thin wrapper that converts the
+ * rectangles to `Polygon` shapes.
+ *
+ * Greedy meshing reduces shape count dramatically for typical platformer
+ * maps. A 50-tile floor strip becomes one rectangle; a solid 10x10 block
+ * becomes one rectangle instead of 100. Fewer shapes = smaller broadphase
+ * footprint, faster narrowphase, less debug-draw work.
+ *
+ * @param grid - 2D row-major tile grid (`grid[y][x]`).
+ * @param options - Optional `solid` predicate and `merge` strategy.
+ * @returns The list of merged rectangles in tile coordinates.
+ *
+ * @example
+ * ```ts
+ * const rects = meshTilemap([
+ *   [1, 1, 1, 0, 1],
+ *   [1, 1, 1, 0, 1],
+ *   [0, 0, 0, 0, 1],
+ * ]);
+ * // -> [{x:0,y:0,w:3,h:2}, {x:4,y:0,w:1,h:3}]
+ * ```
+ */
+declare function meshTilemap(grid: TilemapGrid, options?: {
+    solid?: TilemapSolidPredicate;
+    merge?: TilemapMergeMode;
+}): TilemapRect[];
+/**
+ * Build a single physics `Body` from a 2D tile grid.
+ *
+ * Each merged rectangle becomes a `Polygon` shape on the body. Tiles are laid
+ * out with `(0, 0)` at the top-left of tile `(0, 0)`, so the body's
+ * `position` (defaults to origin) is the world-space location of that
+ * top-left corner.
+ *
+ * Defaults to `BodyType.STATIC` and `merge: "greedy"`, matching the most
+ * common gamedev use case (level collision geometry from a Tiled / LDtk map).
+ *
+ * @param grid - 2D row-major tile grid.
+ * @param options - Tile size + body / shape options.
+ * @returns A `Body` containing one `Polygon` shape per merged rectangle.
+ *   The returned body is not yet attached to a `Space` — set `body.space`
+ *   to insert it.
+ *
+ * @example
+ * ```ts
+ * const grid = [
+ *   [1, 1, 1, 0, 1, 1, 1],
+ *   [0, 0, 0, 0, 0, 0, 0],
+ *   [1, 1, 1, 1, 1, 1, 1],
+ * ];
+ * const body = buildTilemapBody(grid, { tileSize: 32, position: Vec2.get(0, 100) });
+ * body.space = space;
+ * ```
+ */
+declare function buildTilemapBody(grid: TilemapGrid, options: TilemapOptions): Body;
+/**
+ * Convert a Tiled JSON tile layer into a 2D row-major grid suitable for
+ * {@link meshTilemap} / {@link buildTilemapBody}.
+ *
+ * Only the `data`, `width`, and `height` fields of the layer are read — the
+ * helper has no runtime dependency on a Tiled SDK and accepts any object with
+ * that shape.
+ *
+ * @param layer - A Tiled tile layer (e.g. `map.layers[i]` from a Tiled JSON export).
+ * @returns A 2D number array, with `0` representing empty tiles.
+ */
+declare function tiledLayerToGrid(layer: TiledTileLayer): number[][];
+/**
+ * Convert an LDtk IntGrid layer instance into a 2D row-major grid.
+ *
+ * Reads `intGridCsv` plus the cell-dimension fields (`__cWid` / `__cHei`,
+ * with `cWid` / `cHei` accepted as fallbacks). LDtk uses `0` for empty
+ * IntGrid cells, which the default `solid` predicate already treats as
+ * non-solid.
+ *
+ * @param layer - An LDtk IntGrid layer instance.
+ * @returns A 2D number array, with `0` representing empty cells.
+ */
+declare function ldtkLayerToGrid(layer: LDtkIntGridLayer): number[][];
+
+/**
+ * Falloff law for {@link RadialGravityField}.
+ *
+ * - `"inverse-square"` — `F = strength / d²` (Newtonian gravity, default)
+ * - `"inverse"` — `F = strength / d` (line-source gravity)
+ * - `"constant"` — `F = strength` (constant pull regardless of distance)
+ * - `(distance) => number` — custom multiplier, applied as `F = strength * fn(d)`
+ */
+type GravityFalloff = "inverse-square" | "inverse" | "constant" | ((distance: number) => number);
+/** Per-body filter — `false` skips the body. */
+type BodyFilter = (body: Body) => boolean;
+/** Configuration options for {@link RadialGravityField}. */
+interface RadialGravityFieldOptions {
+    /**
+     * The field's anchor point. May be a `Vec2` (fixed world position — captured
+     * by reference, so mutating it after construction moves the field), or a
+     * `Body` (the field tracks `body.position` automatically each step).
+     */
+    source: Vec2 | Body;
+    /** Field strength scaling — units depend on `falloff` (see {@link GravityFalloff}). */
+    strength: number;
+    /** Falloff law. @default `"inverse-square"` */
+    falloff?: GravityFalloff;
+    /** Multiply the resulting force by `body.mass` (Newtonian gravity). @default `true` */
+    scaleByMass?: boolean;
+    /**
+     * Bodies farther than this from the source receive zero force — useful for
+     * bounded gravity wells with hard edges.
+     * @default `Infinity`
+     */
+    maxRadius?: number;
+    /**
+     * Distance values used in the falloff calculation are clamped to be at
+     * least this — prevents singularities at the source center.
+     * @default `1`
+     */
+    minRadius?: number;
+    /**
+     * Softening epsilon added to `d²` for the inverse-square falloff (smooths
+     * out near-source spikes without disabling the pull). Has no effect on
+     * other falloff laws.
+     * @default `0`
+     */
+    softening?: number;
+    /**
+     * Predicate deciding which bodies the field affects. `null` (default)
+     * means "all dynamic bodies". Static and kinematic bodies are always
+     * skipped (forces have no effect on them anyway).
+     * @default `null`
+     */
+    bodyFilter?: BodyFilter | null;
+    /** When `false`, calls to {@link RadialGravityField.apply} are no-ops. @default `true` */
+    enabled?: boolean;
+}
+/**
+ * A point-source gravity field — pulls bodies toward an anchor with a chosen
+ * falloff law.
+ *
+ * Replaces the manual `for (body of space.bodies) body.force = ...` loops
+ * commonly written for orbital / planet / multi-body gravity scenarios.
+ * Multiple fields compose naturally via {@link RadialGravityFieldGroup} or
+ * by calling `apply()` on each one in sequence — each call **adds** to the
+ * existing accumulated force, so userland `body.force` writes are preserved.
+ *
+ * @example
+ * ```ts
+ * // Mario-Galaxy-style planet pulling everything toward its center
+ * const planet = new Body(BodyType.STATIC, new Vec2(400, 300));
+ * planet.shapes.add(new Circle(40));
+ * planet.space = space;
+ *
+ * const field = new RadialGravityField({
+ *   source: planet,
+ *   strength: 800000,
+ *   maxRadius: 250,
+ *   softening: 100,
+ * });
+ *
+ * // Each frame, BEFORE space.step():
+ * field.apply(space);
+ * space.step(1 / 60);
+ * ```
+ */
+declare class RadialGravityField {
+    source: Vec2 | Body;
+    strength: number;
+    falloff: GravityFalloff;
+    scaleByMass: boolean;
+    maxRadius: number;
+    minRadius: number;
+    softening: number;
+    bodyFilter: BodyFilter | null;
+    enabled: boolean;
+    constructor(options: RadialGravityFieldOptions);
+    /**
+     * Current world-space center of the field.
+     *
+     * Returns the anchor's `(x, y)` — for a `Body` source this reflects the
+     * body's current position each call, so the field automatically tracks
+     * a moving anchor.
+     */
+    getPosition(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Compute (but do not apply) the force this field would exert on `body`
+     * given its current position. Returns `(0, 0)` when the field is disabled,
+     * the body is static, the body is filtered out, or the body is outside
+     * `maxRadius`.
+     *
+     * The returned `Vec2` is fresh and owned by the caller.
+     */
+    forceOn(body: Body): Vec2;
+    /**
+     * Add this field's force contribution to every eligible body in `space`.
+     *
+     * Adds to (does not replace) each body's existing accumulated force, so
+     * multiple fields and userland force writes all stack naturally. Call
+     * once per frame, before `space.step()`.
+     */
+    apply(space: Space): void;
+}
+/**
+ * A composable collection of {@link RadialGravityField} instances. Calling
+ * `apply()` runs every member field once — convenient for multi-source
+ * scenarios (binary stars, three-body, planet platformers).
+ */
+declare class RadialGravityFieldGroup {
+    /** Ordered list of fields. Mutate via {@link add} / {@link remove}. */
+    readonly fields: RadialGravityField[];
+    /** Add a field to the group and return it. */
+    add(field: RadialGravityField): RadialGravityField;
+    /** Remove a field from the group. Returns `true` if it was present. */
+    remove(field: RadialGravityField): boolean;
+    /** Remove all fields. */
+    clear(): void;
+    /** Number of fields currently in the group. */
+    get length(): number;
+    /**
+     * Apply every field's force contribution to all eligible bodies in `space`.
+     * Forces stack additively, preserving any userland `body.force` writes.
+     */
+    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, 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 };
+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 };