@jgengine/core 0.7.0 → 0.9.0

package/dist/physics/physicsWorld.d.ts

@@ -49,9 +49,8 @@ export interface PhysicsStats {
     substeps: number;
     stepMs: number;
 }
-export interface AddBodyOptions {
+export interface BodyCommonOptions {
     position: readonly [number, number, number];
-    halfExtents: readonly [number, number, number];
     velocity?: readonly [number, number, number];
     /** ≤ 0 or omitted with `static` → infinite mass (immovable collider). Default 1. */
     mass?: number;
@@ -60,12 +59,28 @@ export interface AddBodyOptions {
     /** Seed the body asleep (a settled bed pays no integration cost until woken). */
     asleep?: boolean;
 }
+export interface BoxBodyOptions extends BodyCommonOptions {
+    shape?: "box";
+    halfExtents: readonly [number, number, number];
+}
+/** The radius fills all three half-extent columns, so broadphase and bounds see the sphere's enclosing AABB. */
+export interface SphereBodyOptions extends BodyCommonOptions {
+    shape: "sphere";
+    radius: number;
+}
+export type AddBodyOptions = BoxBodyOptions | SphereBodyOptions;
+export declare const SHAPE_BOX = 0;
+export declare const SHAPE_SPHERE = 1;
 /**
- * `hinge`/`fixed`/`distance` are hard bilateral constraints; `spring` is a soft PD constraint.
- * No angular state → `hinge`/`fixed` both pin the shared anchor (`axis` is metadata), `distance`
- * holds a fixed separation, `spring` drives toward `restLength` (suspension, follow-point carry).
+ * Hard bilateral: `fixed` pins the shared anchor (3-DOF), `hinge` pins only the plane
+ * perpendicular to `axis` (free along the axis — translational cylindrical), `distance`
+ * holds a fixed separation. `spring` is a soft PD drive toward `restLength`.
  */
 export type JointKind = "hinge" | "distance" | "spring" | "fixed";
+export declare const JOINT_FIXED = 0;
+export declare const JOINT_HINGE = 1;
+export declare const JOINT_DISTANCE = 2;
+export declare const JOINT_SPRING = 3;
 export interface JointOptions {
     /** First body index. */
     bodyA: number;
@@ -83,7 +98,7 @@ export interface JointOptions {
     damping?: number;
     /** Clamp on the per-substep spring impulse (a follow-point that never yanks). Default unbounded. */
     maxImpulse?: number;
-    /** Hinge axis, retained as metadata (this sim has no angular DOF). */
+    /** Unit hinge axis (world). Required semantics for `hingeJoint`; free motion along this axis. Default [0,1,0]. */
     axis?: readonly [number, number, number];
 }
 /** A contact reported to `onCollision`. The object is reused each call — read/copy, never retain. */
@@ -96,6 +111,8 @@ export interface CollisionEvent {
     approachSpeed: number;
     impulse: number;
 }
+/** Cap on `nx*ny*nz` broadphase cells — guards a huge-bounds/tiny-cellSize config from hanging `step()`. */
+export declare const MAX_BROADPHASE_CELLS = 1000000;
 /** Grid cell containing a point, clamped into the grid. Pure — exported for tests. */
 export declare function cellCoord(value: number, min: number, cellSize: number, cells: number): number;
 /** Linear cell index from clamped 3D coords. Pure — exported for tests. */
@@ -130,6 +147,8 @@ export declare class PhysicsWorld {
     readonly halfZ: Float32Array;
     readonly invMass: Float32Array;
     readonly flags: Uint8Array;
+    /** `SHAPE_BOX` (0) or `SHAPE_SPHERE` (1) per body; spheres keep their radius in halfX/halfY/halfZ. */
+    readonly shape: Uint8Array;
     /** 1 for a body that took part in a contact this frame; reset each `step()`. Render tint reads this. */
     readonly contact: Uint8Array;
     private readonly sleepTimer;
@@ -142,12 +161,12 @@ export declare class PhysicsWorld {
     private readonly numCells;
     private readonly cellStart;
     private readonly cursor;
-    private readonly sorted;
+    private sorted;
     private readonly bodyCell;
     private readonly awakeList;
     private readonly awakeSlot;
     private awakeCount;
-    private readonly jSpring;
+    private readonly jKind;
     private readonly jActive;
     private readonly jBodyA;
     private readonly jBodyB;
@@ -157,6 +176,9 @@ export declare class PhysicsWorld {
     private readonly jAnchorBX;
     private readonly jAnchorBY;
     private readonly jAnchorBZ;
+    private readonly jAxisX;
+    private readonly jAxisY;
+    private readonly jAxisZ;
     private readonly jRest;
     private readonly jStiffness;
     private readonly jDamping;
@@ -165,6 +187,9 @@ export declare class PhysicsWorld {
     private jFreeCount;
     private jointHigh;
     private jointActiveCount;
+    private readonly bodyFree;
+    private bodyFreeCount;
+    private bodyHigh;
     private collisionListener;
     private collisionMinSpeed;
     private readonly collisionEvent;
@@ -175,6 +200,8 @@ export declare class PhysicsWorld {
     private addAwake;
     private removeAwake;
     get count(): number;
+    /** One past the highest slot `addBody` has ever handed out — the range `removeBody` leaves holes in. */
+    get highWater(): number;
     get cells(): {
         nx: number;
         ny: number;
@@ -196,13 +223,32 @@ export declare class PhysicsWorld {
     removeJoint(id: number): void;
     /** Move a joint's world anchor point (only meaningful when `bodyB` is a world anchor). */
     setJointAnchor(id: number, x: number, y: number, z: number): void;
+    /** Move a joint's local anchor offset on A (world axes, no rotation applied by the solver). */
+    setJointAnchorA(id: number, x: number, y: number, z: number): void;
     setJointRest(id: number, restLength: number): void;
     private jointDistance;
     /** Write [ax,ay,az,bx,by,bz] world endpoints per active joint into `out`; returns the joint count. */
     readJointSegments(out: Float32Array): number;
     addBody(options: AddBodyOptions): number;
+    /**
+     * Remove a body: it drops out of integration, the solver, and the broadphase, and its slot is
+     * queued for the next `addBody` to reuse. `id` and every other body's `id` stay valid — a dead
+     * slot is tombstoned (`FLAG_DEAD`), never swapped, since ids are handed out raw and stored as-is
+     * in joints and game state. There is no persistent contact set to consult, so — conservatively —
+     * any sleeping body whose AABB touches the removed body's (padded by `slop`) is woken; a body
+     * that was resting on it always qualifies.
+     */
+    removeBody(id: number): void;
+    private wakeTouching;
     isSleeping(i: number): boolean;
+    isAlive(i: number): boolean;
     wake(i: number): void;
+    /** Overwrite a body's velocity directly, waking it if asleep. */
+    setVelocity(id: number, x: number, y: number, z: number): void;
+    /** Move a body, keeping its current velocity, and wake it if asleep. */
+    setPosition(id: number, x: number, y: number, z: number): void;
+    /** Move a body and zero its velocity — a hard reset (respawn, teleporter) instead of a slide. */
+    teleport(id: number, x: number, y: number, z: number): void;
     wakeAll(): void;
     clear(): void;
     /** Advance by a real frame delta; runs whole fixed substeps and carries the remainder. */