@newkrok/nape-js 3.30.3 → 3.31.0

package/dist/index.d.cts

@@ -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,319 @@ 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;
+}
+
 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, 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 };