@codexo/exojs-physics 0.13.0 → 0.15.0

package/dist/esm/PhysicsWorld.d.ts

@@ -2,48 +2,108 @@ import type { SceneNode } from '@codexo/exojs';
 import { Signal, Vector } from '@codexo/exojs';
 import type { Aabb } from './Aabb';
 import type { PhysicsBackend } from './backend/PhysicsBackend';
-import type { BindingOptions, PhysicsBinding } from './binding/PhysicsBinding';
-import type { Collider, ColliderOptions } from './Collider';
+import type { PhysicsBinding } from './binding/PhysicsBinding';
+import { Collider } from './Collider';
 import type { CollisionEvent, SensorEvent } from './events';
-import type { BodyOptions, BodyOwner } from './PhysicsBody';
+import type { Joint } from './joints/Joint';
+import type { BodyOwner } from './PhysicsBody';
 import { PhysicsBody } from './PhysicsBody';
 import type { QueryFilter, RayHit } from './query/QueryEngine';
-import type { Shape } from './shapes/Shape';
+import type { AnyShape } from './shapes/AnyShape';
 import { TimeStepper } from './TimeStepper';
-import type { VectorLike } from './types';
+import type { BodyType, CollisionFilter, VectorLike } from './types';
 /** Construction options for a {@link PhysicsWorld}. */
 export interface PhysicsWorldOptions {
-    /** Gravity in px/s² (+Y down). Stored; applied once the dynamics solver ships. Default `(0, 0)`. */
+    /** Gravity in px/s² (+Y down). Integrated each sub-step. Default `(0, 0)`. */
     gravity?: VectorLike;
     /** Fixed timestep in seconds. Default `1 / 60`. */
     fixedDelta?: number;
-    /** Maximum sub-steps per `step` (spiral-of-death guard). Default `8`. */
+    /** Maximum fixed steps per `step` call (spiral-of-death guard). Default `8`. */
     maxSubSteps?: number;
-    /** Solver velocity iterations (stored for forward-compat). Default `8`. */
-    velocityIterations?: number;
-    /** Solver position iterations (stored for forward-compat). Default `3`. */
-    positionIterations?: number;
-    /** Interpolate bound nodes between sub-steps (no effect until dynamics integrate). Default `true`. */
-    interpolation?: boolean;
+    /**
+     * TGS-Soft sub-steps per fixed step (the solver's stiffness scales with this,
+     * not iteration count). Default `4`. Must be ≥ 1. Values below `2` visibly
+     * degrade tall-stack stability (a 10-box tower jitters at `1`), so the default
+     * is load-bearing — do not lower it for performance.
+     */
+    subStepCount?: number;
+    /** Soft-contact stiffness in Hz (the contact behaves as a damped spring at this frequency). Default `30`. */
+    contactHertz?: number;
+    /** Soft-contact damping ratio (≥ 1 keeps contacts from oscillating). Default `10`. */
+    dampingRatio?: number;
+    /** Put resting bodies to sleep so they skip integration and solving. Default `true`. */
+    enableSleeping?: boolean;
+    /** Linear speed at or below which a body is a sleep candidate, px/s. Default `5`. */
+    sleepLinearVelocity?: number;
+    /** Angular speed at or below which a body is a sleep candidate, rad/s. Default `0.06`. */
+    sleepAngularVelocity?: number;
+    /** Seconds a body must stay below the sleep thresholds before it sleeps. Default `0.5`. */
+    timeToSleep?: number;
 }
-/** {@link PhysicsWorld.createStaticCollider} options: a collider plus its static body placement. */
-export interface StaticColliderOptions extends ColliderOptions {
-    /** World position of the implicit static body. Default `(0, 0)`. */
+/**
+ * {@link PhysicsWorld.attach} convenience options: a body type plus a single
+ * collider, attached to a scene node in one call.
+ */
+export interface AttachOptions {
+    /** Simulation role of the created body. Default `'dynamic'`. */
+    type?: BodyType;
+    /** Initial world position of the body. Default the node's position is left untouched and `(0, 0)` is used. */
     position?: VectorLike;
-    /** Rotation (radians) of the implicit static body. Default `0`. */
+    /** Initial rotation (radians) of the body. Default `0`. */
     angle?: number;
+    /** Per-body multiplier on world gravity. Default `1`. */
+    gravityScale?: number;
+    /** When `true`, the body never rotates under contacts. Default `false`. */
+    fixedRotation?: boolean;
+    /** The collider geometry. */
+    shape: AnyShape;
+    /** Body-local offset of the collider. Default `(0, 0)`. */
+    offset?: VectorLike;
+    /** Body-local rotation of the collider (radians). Default `0`. */
+    rotation?: number;
+    /** Collider density (mass per px²). Default `1`. */
+    density?: number;
+    /** Coulomb friction coefficient. Default `0.2`. */
+    friction?: number;
+    /** Restitution / bounciness in `[0, 1]`. Default `0`. */
+    restitution?: number;
+    /** When `true`, the collider generates overlap events but no contact response. Default `false`. */
+    isSensor?: boolean;
+    /** Category/mask/group collision filter; partials merge over the defaults. */
+    filter?: Partial<CollisionFilter>;
 }
 /**
  * The collision/query world: owns bodies, colliders, the detection backend,
  * bindings, the query engine and the fixed-step accumulator. Stepped by the
- * caller (commonly from a `Scene.update`), it runs broad- and narrow-phase
- * detection, fires immutable contact/sensor events, and writes bound node
- * transforms. It holds **no module-level state**, so any number of worlds run
- * in isolation (gate I-1).
+ * caller (commonly from a `Scene.update`), each fixed sub-step it integrates
+ * body velocities, runs broad- and narrow-phase detection, solves contacts and
+ * integrates positions, then fires immutable contact/sensor events and writes
+ * bound node transforms. It holds **no module-level state**, so any number of
+ * worlds run in isolation (gate I-1).
  *
- * This release performs collision detection, sensors, events, queries and
- * binding; bodies move only via {@link PhysicsBody.setTransform}. Gravity,
- * forces and impulse integration arrive with the dynamics solver.
+ * The dynamics are a native, warm-started **TGS-Soft** solver (Box2D-v3 "soft
+ * step"): each fixed step runs detection once, then several sub-steps, each
+ * integrating gravity over the sub-step and solving contacts with a soft
+ * position bias plus a bias-free relax pass; a 2-point block normal solve
+ * propagates stack loads, and restitution is a separate final pass. Decoupling
+ * stiffness from the iteration count keeps tall towers stable. The detection
+ * backend sits behind an internal seam, so the solver is swappable without
+ * touching this public surface.
+ *
+ * **Operating envelope.** The soft solver trades a little accuracy for
+ * robustness, so it has a few documented limits — each stays finite/stable and
+ * each is pinned by a gate in `dynamics.test.ts`:
+ * - **Mass ratio** — resting stacks are slop-accurate up to ~100:1. Beyond that
+ *   the velocity-capped soft push-out (`maxBiasVelocity`) lets the lighter body
+ *   settle progressively deeper (≈6px at 500:1, fully through a thin floor by
+ *   ~5000:1) — always finite, never exploding (SG-MR3).
+ * - **No CCD** — detection runs once per fixed step with no swept test, so a
+ *   body that travels farther than an obstacle's thickness in one step tunnels
+ *   straight through it (it stays finite). Reliably stopping fast projectiles is
+ *   a future bullet-mode feature (SG-X5).
+ * - **{@link PhysicsWorldOptions.subStepCount}** — the default `4` is
+ *   load-bearing for tall-stack stability; lowering it below `2` visibly
+ *   degrades stacking, so do not reduce it for performance.
  */
 export declare class PhysicsWorld implements BodyOwner {
     /** Fires when two solid colliders begin touching. Argument is an immutable snapshot. */
@@ -54,22 +114,39 @@ export declare class PhysicsWorld implements BodyOwner {
     readonly onSensorEnter: Signal<[SensorEvent]>;
     /** Fires when a collider leaves a sensor. */
     readonly onSensorExit: Signal<[SensorEvent]>;
-    /** World gravity (px/s², +Y down). Stored until dynamics ship. */
+    /** World gravity (px/s², +Y down). Integrated each sub-step. */
     readonly gravity: Vector;
     /** The fixed-step accumulator. */
     readonly timeStepper: TimeStepper;
-    /** Whether bound nodes interpolate between sub-steps (no effect until dynamics). */
-    readonly interpolation: boolean;
-    /** Solver velocity iterations (stored for forward-compat). */
-    readonly velocityIterations: number;
-    /** Solver position iterations (stored for forward-compat). */
-    readonly positionIterations: number;
+    /** TGS-Soft sub-steps per fixed step. */
+    readonly subStepCount: number;
+    /** Soft-contact stiffness in Hz. */
+    readonly contactHertz: number;
+    /** Soft-contact damping ratio. */
+    readonly dampingRatio: number;
+    /** Whether resting bodies are put to sleep. */
+    readonly enableSleeping: boolean;
+    /** Linear sleep threshold (px/s). */
+    readonly sleepLinearVelocity: number;
+    /** Angular sleep threshold (rad/s). */
+    readonly sleepAngularVelocity: number;
+    /** Seconds below the thresholds before a body sleeps. */
+    readonly timeToSleep: number;
     private readonly _backend;
     private readonly _bodies;
     private readonly _colliders;
+    private readonly _joints;
     private readonly _bindings;
     private readonly _query;
     private readonly _commands;
+    /** Pooled union-find parent array for the per-step island pass (reused; sized to the body count). */
+    private readonly _islandParent;
+    /** Pooled per-island minimum sleep time, indexed by union-find root. */
+    private readonly _islandMinSleep;
+    /** Pooled ray-hit buffer + origin/direction for the CCD swept test. */
+    private readonly _ccdHits;
+    private readonly _ccdOrigin;
+    private readonly _ccdDir;
     private _nextBodyId;
     private _nextColliderId;
     private _dispatching;
@@ -79,21 +156,46 @@ export declare class PhysicsWorld implements BodyOwner {
     get bodies(): readonly PhysicsBody[];
     /** Live colliders (read-only view). */
     get colliders(): readonly Collider[];
-    /** Create a body. Safe to call inside an event callback (deferred to end of step). */
-    createBody(options?: BodyOptions): PhysicsBody;
-    /** Sugar: an explicit static body carrying a single collider. The body is addressable via `collider.body`. */
-    createStaticCollider(options: StaticColliderOptions): Collider;
+    /**
+     * Add a body to the world: allocates the body and its collider ids, registers
+     * the colliders, computes the mass model and tracks the body for stepping.
+     * Construct the body freely first (`new PhysicsBody({ … })`), then add it.
+     * Safe to call inside an event callback — the body push is deferred to the end
+     * of the step, exactly like collider registration. Returns the body.
+     *
+     * @throws if the body has already been added to a world.
+     */
+    add(body: PhysicsBody): PhysicsBody;
+    /**
+     * Convenience: create a body carrying a single collider, add it to the world
+     * and bind it to `node` in one call. The node tracks `body.position` after each
+     * step. Returns the body. Equivalent to `new PhysicsBody(...)` + `add` + `bind`.
+     */
+    attach(node: SceneNode, options: AttachOptions): PhysicsBody;
     /** Destroy a body and its colliders. Deferred when called inside a callback. */
     destroyBody(body: PhysicsBody): void;
     /** Destroy a single collider, recomputing its body's mass. Deferred when called inside a callback. */
     destroyCollider(collider: Collider): void;
+    /** Live joints (read-only view). */
+    get joints(): readonly Joint[];
+    /**
+     * Add a constraint joint. Construct it first (`new DistanceJoint({ … })`),
+     * then add it. Wakes both bodies; safe inside a callback (registration is
+     * deferred). Returns the joint.
+     */
+    addJoint<T extends Joint>(joint: T): T;
+    /** Remove a joint, waking both bodies so they respond to the lost constraint. Deferred when called inside a callback. */
+    removeJoint(joint: Joint): void;
     /**
-     * Advance the world by `frameDeltaSeconds`. Accumulates into fixed sub-steps,
-     * runs detection, dispatches events, then writes bound node transforms.
+     * Advance the world by `frameDeltaSeconds`. Accumulates into fixed steps; each
+     * fixed step runs detection once, then a TGS-Soft sub-step loop (integrate
+     * gravity, solve contacts with a soft bias, integrate positions, relax) and a
+     * restitution pass, then writes the accumulated motion into each body. Finally
+     * dispatches events and writes bound node transforms.
      */
     step(frameDeltaSeconds: number): void;
     /** Link a body to a scene node; the node tracks the body after each step. */
-    bind(body: PhysicsBody, node: SceneNode, options?: BindingOptions): PhysicsBinding;
+    bind(body: PhysicsBody, node: SceneNode): PhysicsBinding;
     /** Remove a body↔node link. */
     unbind(body: PhysicsBody): void;
     /** Colliders containing `point`. Fresh array. */
@@ -107,7 +209,7 @@ export declare class PhysicsWorld implements BodyOwner {
     /** All collider hits along the ray, sorted by distance. Writes into `out` (cleared) if given. */
     rayCastAll(origin: VectorLike, direction: VectorLike, filter?: QueryFilter, out?: RayHit[], maxDistance?: number): RayHit[];
     /** Colliders overlapping `shape` placed at `position`/`angle`. Fresh array. */
-    overlapShape(shape: Shape, position: VectorLike, filter?: QueryFilter, angle?: number): Collider[];
+    overlapShape(shape: AnyShape, position: VectorLike, filter?: QueryFilter, angle?: number): Collider[];
     /** Release every body, collider, binding and backend resource. */
     destroy(): void;
     _allocateColliderId(): number;
@@ -115,6 +217,42 @@ export declare class PhysicsWorld implements BodyOwner {
     /** The detection backend (internal; consumed by the debug draw layer). */
     get backend(): PhysicsBackend;
     private _dispatchEvents;
+    /**
+     * Accumulate per-body sleep timers and put/keep islands of resting bodies
+     * asleep so a stack sleeps and wakes as one unit. An island is a connected
+     * component of dynamic bodies joined by touching solid contacts (static and
+     * kinematic bodies are boundaries, not nodes); it sleeps once every member has
+     * stayed below the sleep thresholds for `timeToSleep`, and wakes the instant
+     * any member does (e.g. an awake body merges into it via a new contact).
+     * Deterministic: union-find roots break ties by lower index and the contact
+     * set is id-sorted.
+     */
+    private _updateSleeping;
+    /** Union-find union by lower index (deterministic roots). */
+    private _union;
+    /** Union-find find with path halving. */
+    private _find;
+    /** Build each joint's per-frame constraint data (once per fixed step). */
+    private _prepareJoints;
+    /** Re-apply each joint's accumulated impulse (each sub-step). */
+    private _warmStartJoints;
+    /** One joint velocity pass (each sub-step, after the contacts). */
+    private _solveJoints;
+    /** Whether any dynamic body is flagged for continuous collision (bullet mode). */
+    private _hasBullets;
+    /** Snapshot each bullet's centre of mass at the start of the fixed step (the swept-test origin). */
+    private _recordBulletPositions;
+    /**
+     * Sweep each bullet's centre of mass along this fixed step's motion against every
+     * other body's colliders; if it would cross one, clamp the body just short of the
+     * surface and resolve the impact about the surface normal (a slide for a non-bouncy
+     * body, an elastic reflection as restitution → 1) so it cannot tunnel. Sweeps the
+     * centre point — good for small/point-like projectiles; a full swept-shape TOI for
+     * large fast bodies is backlog (raise sub-steps or thicken geometry meanwhile).
+     */
+    private _advanceBullets;
+    /** The highest restitution among a body's colliders (its CCD bounce factor). */
+    private _bulletRestitution;
     /** Run `command` now, or queue it when inside an event dispatch (deferred to end of step). */
     private _defer;
     private _drainCommands;