@newkrok/nape-js 3.18.0 → 3.20.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { V as Vec2, A as AABB, B as Body, S as Shape, M as Material, I as InteractionFilter, C as CollisionArbiter, a as Vec3, b as CbEvent, L as Listener, c as Interactor, d as InteractionType, e as Constraint, f as Arbiter, P as PreFlag, g as MatMN, h as BodyType } from './ConvexResult-DafossGq.cjs';
-export { i as ArbiterList, j as ArbiterType, k as BodyList, l as Broadphase, m as CbTypeSet, n as Compound, o as CompoundList, p as ConstraintList, q as ConvexResult, r as ConvexResultList, D as DebugDraw, s as DebugVec2, E as Edge, F as FluidArbiter, t as FluidProperties, G as GravMassMode, u as InertiaMode, v as InteractionGroup, w as ListenerList, x as ListenerType, y as MassMode, z as Mat23, N as NapeList, H as Polygon, R as Ray, J as RayResult, K as RayResultList, O as ShapeList, Q as ShapeType, T as Space, U as TypedListLike } from './ConvexResult-DafossGq.cjs';
+import { V as Vec2, A as AABB, B as Body, S as Shape, M as Material, I as InteractionFilter, a as ShapeType, C as CollisionArbiter, b as Vec3, c as CbEvent, L as Listener, d as Interactor, e as InteractionType, f as Constraint, g as Arbiter, P as PreFlag, h as MatMN, i as BodyType, j as Space } from './ConvexResult-w4mY_6fr.cjs';
+export { k as ArbiterList, l as ArbiterType, m as BodyList, n as Broadphase, o as CbTypeSet, p as Compound, q as CompoundList, r as ConstraintList, s as ConvexResult, t as ConvexResultList, D as DebugDraw, u as DebugVec2, E as Edge, F as FluidArbiter, v as FluidProperties, G as GravMassMode, w as InertiaMode, x as InteractionGroup, y as ListenerList, z as ListenerType, H as MassMode, J as Mat23, N as NapeList, K as Polygon, R as Ray, O as RayResult, Q as RayResultList, T as ShapeList, U as TypedListLike } from './ConvexResult-w4mY_6fr.cjs';
 
 /**
  * ZNPList<T> — Generic singly-linked list backed by ZNPNode<T>.
@@ -167,8 +167,8 @@ declare class Circle extends Shape {
 /**
  * A capsule physics shape — a line segment with a radius (stadium geometry).
  *
- * Geometrically equivalent to a rectangle with two semicircular end-caps.
- * The spine runs along the **local X-axis** through localCOM.
+ * Internally backed by a convex polygon approximation for robust collision
+ * detection. The polygon uses the engine's well-tested SAT narrowphase.
  *
  * - Total width  = 2 * (halfLength + radius)
  * - Total height = 2 * radius
@@ -190,7 +190,13 @@ declare class Capsule extends Shape {
      * @param filter - InteractionFilter to assign (uses default if omitted).
      */
     constructor(width?: number, height?: number, localCOM?: Vec2, material?: Material, filter?: InteractionFilter);
-    /** The capsule's end-cap radius (half the height). Must be > 0. */
+    /** Override type to return CAPSULE (internally backed by polygon). */
+    get type(): ShapeType;
+    /** A capsule is not a plain polygon from the user's perspective. */
+    isPolygon(): boolean;
+    /** A capsule identifies as capsule. */
+    isCapsule(): boolean;
+    /** The capsule's end-cap radius (half the height). */
     get radius(): number;
     set radius(value: number);
     /** Half the spine length. Total width = 2 * (halfLength + radius). */
@@ -1425,6 +1431,136 @@ interface ConcaveBodyOptions {
  */
 declare function createConcaveBody(vertices: Vec2[] | GeomPoly, options?: ConcaveBodyOptions): Body;
 
+/** Result returned by {@link CharacterController.update}. */
+interface MoveResult {
+    /** True if the character is standing on a surface within slope limits. */
+    grounded: boolean;
+    /** Ground surface normal, or null if not grounded. */
+    groundNormal: Vec2 | null;
+    /** The body the character is standing on, or null. */
+    groundBody: Body | null;
+    /** True if standing on a kinematic (moving) platform. */
+    onMovingPlatform: boolean;
+    /** Angle of the ground slope in radians (0 = flat). */
+    slopeAngle: number;
+    /** True if touching a wall on the left side. */
+    wallLeft: boolean;
+    /** True if touching a wall on the right side. */
+    wallRight: boolean;
+    /** Seconds since the character was last grounded (for coyote-time). */
+    timeSinceGrounded: number;
+}
+/** Configuration options for {@link CharacterController}. */
+interface CharacterControllerOptions {
+    /**
+     * Maximum climbable slope angle in radians.
+     * @default Math.PI / 4 (45 degrees)
+     */
+    maxSlopeAngle?: number;
+    /**
+     * CbType for one-way platforms. When set, the controller automatically
+     * creates a PreListener that ignores collisions when the character
+     * approaches from below — matching the original nape Haxe engine pattern.
+     */
+    oneWayPlatformTag?: CbType;
+    /**
+     * CbType assigned to the character body (required if oneWayPlatformTag is set).
+     */
+    characterTag?: CbType;
+    /**
+     * InteractionFilter used for ground/wall detection raycasts.
+     * When null, an auto-generated filter excluding the character's own
+     * shapes is used.
+     * @default null
+     */
+    filter?: InteractionFilter | null;
+}
+/**
+ * Velocity-based character controller for 2D platformers.
+ *
+ * The character uses a **dynamic body** whose velocity is set each frame.
+ * Collision response (including one-way platforms) is handled entirely by
+ * the physics engine via `space.step()` and `PreListener` callbacks —
+ * matching the original nape Haxe engine pattern.
+ *
+ * The controller provides:
+ * - Velocity application (`setVelocity`)
+ * - Ground/slope detection (raycast queries)
+ * - Wall detection (raycast queries)
+ * - One-way platform support (auto-configured PreListener)
+ * - Moving platform tracking
+ * - Coyote time helper (`timeSinceGrounded`)
+ *
+ * @example
+ * ```ts
+ * const body = new Body(BodyType.DYNAMIC, new Vec2(100, 100));
+ * body.shapes.add(new Circle(14));
+ * body.allowRotation = false;
+ * body.isBullet = true;
+ * body.space = space;
+ *
+ * const cc = new CharacterController(space, body, {
+ *   maxSlopeAngle: Math.PI / 4,
+ *   oneWayPlatformTag: platformCbType,
+ *   characterTag: playerCbType,
+ * });
+ *
+ * // Each frame (before space.step):
+ * cc.setVelocity(moveX, velY);
+ * space.step(1/60);
+ * const result = cc.update();
+ * if (result.grounded) velY = 0;
+ * ```
+ */
+declare class CharacterController {
+    /** The physics space. */
+    readonly space: Space;
+    /** The character body being controlled. */
+    readonly body: Body;
+    private _maxSlopeAngle;
+    private _maxSlopeCos;
+    private _filter;
+    private _oneWayListener;
+    private _grounded;
+    private _groundNormal;
+    private _groundBody;
+    private _onMovingPlatform;
+    private _slopeAngle;
+    private _wallLeft;
+    private _wallRight;
+    private _timeSinceGrounded;
+    constructor(space: Space, body: Body, options?: CharacterControllerOptions);
+    get grounded(): boolean;
+    get groundNormal(): Vec2 | null;
+    get groundBody(): Body | null;
+    get timeSinceGrounded(): number;
+    get maxSlopeAngle(): number;
+    set maxSlopeAngle(v: number);
+    /**
+     * Set the character body's velocity. Call this each frame **before**
+     * `space.step()`.
+     *
+     * @param vx - Horizontal velocity (px/s). Set to 0 for no horizontal input.
+     * @param vy - Vertical velocity (px/s). Typically includes gravity accumulation.
+     */
+    setVelocity(vx: number, vy: number): void;
+    /**
+     * Query the character's state after `space.step()` has run.
+     * Detects ground, walls, slope angle, moving platforms, etc.
+     *
+     * Call this each frame **after** `space.step()`.
+     */
+    update(): MoveResult;
+    /**
+     * Remove the one-way platform PreListener and detach from space.
+     */
+    destroy(): void;
+    private _detectGround;
+    private _detectWalls;
+    private _setupOneWayPlatforms;
+    private _getCharacterRadius;
+}
+
 declare const VERSION: string;
 
-export { AABB, AngleJoint, Arbiter, Body, BodyCallback, BodyListener, BodyType, Callback, Capsule, CbEvent, CbType, Circle, CollisionArbiter, type ConcaveBodyOptions, Constraint, ConstraintCallback, ConstraintListener, Contact, DebugDrawFlags, DistanceJoint, Geom, GeomPoly, InteractionCallback, InteractionFilter, InteractionListener, InteractionType, Interactor, LineJoint, Listener, MarchingSquares, MatMN, Material, MotorJoint, OptionType, PivotJoint, PreCallback, PreFlag, PreListener, PulleyJoint, Shape, 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, Geom, GeomPoly, InteractionCallback, InteractionFilter, InteractionListener, InteractionType, Interactor, LineJoint, Listener, MarchingSquares, MatMN, Material, MotorJoint, type MoveResult, OptionType, PivotJoint, PreCallback, PreFlag, PreListener, PulleyJoint, Shape, ShapeType, Space, UserConstraint, VERSION, ValidationResult, Vec2, Vec3, WeldJoint, Winding, createConcaveBody };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { V as Vec2, A as AABB, B as Body, S as Shape, M as Material, I as InteractionFilter, C as CollisionArbiter, a as Vec3, b as CbEvent, L as Listener, c as Interactor, d as InteractionType, e as Constraint, f as Arbiter, P as PreFlag, g as MatMN, h as BodyType } from './ConvexResult-DafossGq.js';
-export { i as ArbiterList, j as ArbiterType, k as BodyList, l as Broadphase, m as CbTypeSet, n as Compound, o as CompoundList, p as ConstraintList, q as ConvexResult, r as ConvexResultList, D as DebugDraw, s as DebugVec2, E as Edge, F as FluidArbiter, t as FluidProperties, G as GravMassMode, u as InertiaMode, v as InteractionGroup, w as ListenerList, x as ListenerType, y as MassMode, z as Mat23, N as NapeList, H as Polygon, R as Ray, J as RayResult, K as RayResultList, O as ShapeList, Q as ShapeType, T as Space, U as TypedListLike } from './ConvexResult-DafossGq.js';
+import { V as Vec2, A as AABB, B as Body, S as Shape, M as Material, I as InteractionFilter, a as ShapeType, C as CollisionArbiter, b as Vec3, c as CbEvent, L as Listener, d as Interactor, e as InteractionType, f as Constraint, g as Arbiter, P as PreFlag, h as MatMN, i as BodyType, j as Space } from './ConvexResult-w4mY_6fr.js';
+export { k as ArbiterList, l as ArbiterType, m as BodyList, n as Broadphase, o as CbTypeSet, p as Compound, q as CompoundList, r as ConstraintList, s as ConvexResult, t as ConvexResultList, D as DebugDraw, u as DebugVec2, E as Edge, F as FluidArbiter, v as FluidProperties, G as GravMassMode, w as InertiaMode, x as InteractionGroup, y as ListenerList, z as ListenerType, H as MassMode, J as Mat23, N as NapeList, K as Polygon, R as Ray, O as RayResult, Q as RayResultList, T as ShapeList, U as TypedListLike } from './ConvexResult-w4mY_6fr.js';
 
 /**
  * ZNPList<T> — Generic singly-linked list backed by ZNPNode<T>.
@@ -167,8 +167,8 @@ declare class Circle extends Shape {
 /**
  * A capsule physics shape — a line segment with a radius (stadium geometry).
  *
- * Geometrically equivalent to a rectangle with two semicircular end-caps.
- * The spine runs along the **local X-axis** through localCOM.
+ * Internally backed by a convex polygon approximation for robust collision
+ * detection. The polygon uses the engine's well-tested SAT narrowphase.
  *
  * - Total width  = 2 * (halfLength + radius)
  * - Total height = 2 * radius
@@ -190,7 +190,13 @@ declare class Capsule extends Shape {
      * @param filter - InteractionFilter to assign (uses default if omitted).
      */
     constructor(width?: number, height?: number, localCOM?: Vec2, material?: Material, filter?: InteractionFilter);
-    /** The capsule's end-cap radius (half the height). Must be > 0. */
+    /** Override type to return CAPSULE (internally backed by polygon). */
+    get type(): ShapeType;
+    /** A capsule is not a plain polygon from the user's perspective. */
+    isPolygon(): boolean;
+    /** A capsule identifies as capsule. */
+    isCapsule(): boolean;
+    /** The capsule's end-cap radius (half the height). */
     get radius(): number;
     set radius(value: number);
     /** Half the spine length. Total width = 2 * (halfLength + radius). */
@@ -1425,6 +1431,136 @@ interface ConcaveBodyOptions {
  */
 declare function createConcaveBody(vertices: Vec2[] | GeomPoly, options?: ConcaveBodyOptions): Body;
 
+/** Result returned by {@link CharacterController.update}. */
+interface MoveResult {
+    /** True if the character is standing on a surface within slope limits. */
+    grounded: boolean;
+    /** Ground surface normal, or null if not grounded. */
+    groundNormal: Vec2 | null;
+    /** The body the character is standing on, or null. */
+    groundBody: Body | null;
+    /** True if standing on a kinematic (moving) platform. */
+    onMovingPlatform: boolean;
+    /** Angle of the ground slope in radians (0 = flat). */
+    slopeAngle: number;
+    /** True if touching a wall on the left side. */
+    wallLeft: boolean;
+    /** True if touching a wall on the right side. */
+    wallRight: boolean;
+    /** Seconds since the character was last grounded (for coyote-time). */
+    timeSinceGrounded: number;
+}
+/** Configuration options for {@link CharacterController}. */
+interface CharacterControllerOptions {
+    /**
+     * Maximum climbable slope angle in radians.
+     * @default Math.PI / 4 (45 degrees)
+     */
+    maxSlopeAngle?: number;
+    /**
+     * CbType for one-way platforms. When set, the controller automatically
+     * creates a PreListener that ignores collisions when the character
+     * approaches from below — matching the original nape Haxe engine pattern.
+     */
+    oneWayPlatformTag?: CbType;
+    /**
+     * CbType assigned to the character body (required if oneWayPlatformTag is set).
+     */
+    characterTag?: CbType;
+    /**
+     * InteractionFilter used for ground/wall detection raycasts.
+     * When null, an auto-generated filter excluding the character's own
+     * shapes is used.
+     * @default null
+     */
+    filter?: InteractionFilter | null;
+}
+/**
+ * Velocity-based character controller for 2D platformers.
+ *
+ * The character uses a **dynamic body** whose velocity is set each frame.
+ * Collision response (including one-way platforms) is handled entirely by
+ * the physics engine via `space.step()` and `PreListener` callbacks —
+ * matching the original nape Haxe engine pattern.
+ *
+ * The controller provides:
+ * - Velocity application (`setVelocity`)
+ * - Ground/slope detection (raycast queries)
+ * - Wall detection (raycast queries)
+ * - One-way platform support (auto-configured PreListener)
+ * - Moving platform tracking
+ * - Coyote time helper (`timeSinceGrounded`)
+ *
+ * @example
+ * ```ts
+ * const body = new Body(BodyType.DYNAMIC, new Vec2(100, 100));
+ * body.shapes.add(new Circle(14));
+ * body.allowRotation = false;
+ * body.isBullet = true;
+ * body.space = space;
+ *
+ * const cc = new CharacterController(space, body, {
+ *   maxSlopeAngle: Math.PI / 4,
+ *   oneWayPlatformTag: platformCbType,
+ *   characterTag: playerCbType,
+ * });
+ *
+ * // Each frame (before space.step):
+ * cc.setVelocity(moveX, velY);
+ * space.step(1/60);
+ * const result = cc.update();
+ * if (result.grounded) velY = 0;
+ * ```
+ */
+declare class CharacterController {
+    /** The physics space. */
+    readonly space: Space;
+    /** The character body being controlled. */
+    readonly body: Body;
+    private _maxSlopeAngle;
+    private _maxSlopeCos;
+    private _filter;
+    private _oneWayListener;
+    private _grounded;
+    private _groundNormal;
+    private _groundBody;
+    private _onMovingPlatform;
+    private _slopeAngle;
+    private _wallLeft;
+    private _wallRight;
+    private _timeSinceGrounded;
+    constructor(space: Space, body: Body, options?: CharacterControllerOptions);
+    get grounded(): boolean;
+    get groundNormal(): Vec2 | null;
+    get groundBody(): Body | null;
+    get timeSinceGrounded(): number;
+    get maxSlopeAngle(): number;
+    set maxSlopeAngle(v: number);
+    /**
+     * Set the character body's velocity. Call this each frame **before**
+     * `space.step()`.
+     *
+     * @param vx - Horizontal velocity (px/s). Set to 0 for no horizontal input.
+     * @param vy - Vertical velocity (px/s). Typically includes gravity accumulation.
+     */
+    setVelocity(vx: number, vy: number): void;
+    /**
+     * Query the character's state after `space.step()` has run.
+     * Detects ground, walls, slope angle, moving platforms, etc.
+     *
+     * Call this each frame **after** `space.step()`.
+     */
+    update(): MoveResult;
+    /**
+     * Remove the one-way platform PreListener and detach from space.
+     */
+    destroy(): void;
+    private _detectGround;
+    private _detectWalls;
+    private _setupOneWayPlatforms;
+    private _getCharacterRadius;
+}
+
 declare const VERSION: string;
 
-export { AABB, AngleJoint, Arbiter, Body, BodyCallback, BodyListener, BodyType, Callback, Capsule, CbEvent, CbType, Circle, CollisionArbiter, type ConcaveBodyOptions, Constraint, ConstraintCallback, ConstraintListener, Contact, DebugDrawFlags, DistanceJoint, Geom, GeomPoly, InteractionCallback, InteractionFilter, InteractionListener, InteractionType, Interactor, LineJoint, Listener, MarchingSquares, MatMN, Material, MotorJoint, OptionType, PivotJoint, PreCallback, PreFlag, PreListener, PulleyJoint, Shape, 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, Geom, GeomPoly, InteractionCallback, InteractionFilter, InteractionListener, InteractionType, Interactor, LineJoint, Listener, MarchingSquares, MatMN, Material, MotorJoint, type MoveResult, OptionType, PivotJoint, PreCallback, PreFlag, PreListener, PulleyJoint, Shape, ShapeType, Space, UserConstraint, VERSION, ValidationResult, Vec2, Vec3, WeldJoint, Winding, createConcaveBody };