@jgengine/core 0.18.0 → 0.19.0

package/dist/physics/kinematicVehicle.js

@@ -1,5 +1,10 @@
 import { steerYaw } from "../movement/steering.js";
 import { DEFAULT_GRIP_CURVE, sampleGripCurve } from "./vehicleBody.js";
+/**
+ * Arcade ground-vehicle sim (car, kart, bike) with throttle, brake, steer, drift and retunable handling.
+ *
+ * @capability kinematic-vehicle arcade car/kart driving physics with throttle, brake, steer and retunable handling
+ */
 export function createKinematicVehicle(initialTuning, options = {}) {
     // Mutable so `retune` can swap the whole block without disturbing the integrator's state; every
     // read below is per-tick rather than captured at construction for the same reason.
@@ -309,6 +314,16 @@ export function createKinematicVehicle(initialTuning, options = {}) {
         retune(next) {
             tuning = next;
         },
+        snapshot: () => ({
+            x, y, z, heading, vx, vz, gearIndex, rpm, shiftRemaining, steerAngle, yawRate,
+            previousForwardSpeed, bodyPitch, bodyRoll, airOffset, verticalVelocity,
+        }),
+        restore(state) {
+            ({
+                x, y, z, heading, vx, vz, gearIndex, rpm, shiftRemaining, steerAngle, yawRate,
+                previousForwardSpeed, bodyPitch, bodyRoll, airOffset, verticalVelocity,
+            } = state);
+        },
         resetTo(position, nextHeading) {
             x = position[0];
             y = position[1];

package/dist/physics/physicsBackend.d.ts

@@ -0,0 +1,203 @@
+/** `[x, y, z]`. */
+export type PhysicsVec3 = readonly [number, number, number];
+/** Unit quaternion `[x, y, z, w]`; `[0, 0, 0, 1]` is identity. */
+export type PhysicsQuat = readonly [number, number, number, number];
+/** The identity rotation. */
+export declare const IDENTITY_QUAT: PhysicsQuat;
+/** Collision shape of a body or a cast. Capsules stand along +Y; a trimesh or heightfield is static-only on every backend. */
+export type BodyShape = {
+    kind: "box";
+    halfExtents: PhysicsVec3;
+} | {
+    kind: "sphere";
+    radius: number;
+} | {
+    kind: "capsule";
+    radius: number;
+    halfHeight: number;
+} | {
+    kind: "convex";
+    points: readonly PhysicsVec3[];
+} | {
+    kind: "trimesh";
+    vertices: ArrayLike<number>;
+    indices: ArrayLike<number>;
+} | {
+    kind: "heightfield";
+    rows: number;
+    columns: number;
+    heights: ArrayLike<number>;
+    scale: PhysicsVec3;
+};
+/** Shape discriminator, as listed in {@link PhysicsCapabilities.shapes}. */
+export type BodyShapeKind = BodyShape["kind"];
+/** `dynamic` integrates under forces, `kinematic` moves only through {@link PhysicsBackend.setKinematicTarget}, `static` never moves. */
+export type BodyKind = "dynamic" | "kinematic" | "static";
+/** Everything a backend needs to create a body. Rotation-free backends ignore `rotation` and `angularVelocity` and say so in {@link PhysicsCapabilities}. */
+export interface BodyDesc {
+    shape: BodyShape;
+    /** Default `dynamic`. */
+    kind?: BodyKind;
+    position: PhysicsVec3;
+    rotation?: PhysicsQuat;
+    velocity?: PhysicsVec3;
+    angularVelocity?: PhysicsVec3;
+    /** Default 1; ignored for kinematic and static bodies. */
+    mass?: number;
+    friction?: number;
+    restitution?: number;
+    /** Collision layer bitmask this body belongs to. Default `1`. */
+    layers?: number;
+    /** Collision layer bitmask this body collides with. Default all bits. */
+    mask?: number;
+    /** Continuous collision detection for fast small bodies (bullets, thrown props). */
+    ccd?: boolean;
+    /** Per-second linear velocity damping on this body (air drag, water); default `0`. */
+    linearDamping?: number;
+    /** Per-second angular velocity damping on this body; default `0`. Ignored by rotation-free backends. */
+    angularDamping?: number;
+    asleep?: boolean;
+    userData?: unknown;
+}
+/** Backend-issued body id; stable for the body's lifetime and across snapshot/restore. */
+export type BodyHandle = number;
+/** Backend-issued joint id. */
+export type JointHandle = number;
+/** A body's live pose and motion. Rotation-free backends report identity rotation and zero angular velocity. */
+export interface BodyState {
+    position: PhysicsVec3;
+    rotation: PhysicsQuat;
+    velocity: PhysicsVec3;
+    angularVelocity: PhysicsVec3;
+    sleeping: boolean;
+}
+/** Joint between two bodies, or between `bodyA` and a world anchor when `bodyB` is omitted. */
+export interface JointDesc {
+    kind: "fixed" | "hinge" | "ball" | "distance" | "spring";
+    bodyA: BodyHandle;
+    bodyB?: BodyHandle;
+    /** Anchor in A's local frame. Default origin. */
+    anchorA?: PhysicsVec3;
+    /** Anchor in B's local frame, or the world point when B is omitted. Default origin. */
+    anchorB?: PhysicsVec3;
+    /** Hinge axis in world space. */
+    axis?: PhysicsVec3;
+    /** Hinge angle limits in radians. */
+    limits?: readonly [min: number, max: number];
+    restLength?: number;
+    stiffness?: number;
+    damping?: number;
+}
+/** A ray query. */
+export interface RayDesc {
+    origin: PhysicsVec3;
+    /** Need not be normalized. */
+    direction: PhysicsVec3;
+    maxDistance: number;
+    /** Only bodies whose `layers` intersect this mask are hit. Default all. */
+    mask?: number;
+    exclude?: BodyHandle;
+}
+/** Nearest surface a ray reached. */
+export interface RayHit {
+    body: BodyHandle;
+    point: PhysicsVec3;
+    normal: PhysicsVec3;
+    distance: number;
+}
+/** Sweep `shape` from `position` along `motion` and report the first body it touches. */
+export interface ShapeCastDesc {
+    shape: BodyShape;
+    position: PhysicsVec3;
+    rotation?: PhysicsQuat;
+    motion: PhysicsVec3;
+    mask?: number;
+    exclude?: BodyHandle;
+}
+/** First contact of a shape sweep. */
+export interface ShapeCastHit {
+    body: BodyHandle;
+    /** Fraction of `motion` travelled at first contact, 0..1. */
+    toi: number;
+    point: PhysicsVec3;
+    normal: PhysicsVec3;
+    distance: number;
+}
+/** Which bodies a shape placed at `position` intersects. */
+export interface OverlapDesc {
+    shape: BodyShape;
+    position: PhysicsVec3;
+    rotation?: PhysicsQuat;
+    mask?: number;
+    exclude?: BodyHandle;
+}
+/** A contact reported during {@link PhysicsBackend.step}; the object is reused between calls, so copy what you keep. */
+export interface ContactEvent {
+    a: BodyHandle;
+    b: BodyHandle;
+    normal: PhysicsVec3;
+    approachSpeed: number;
+    impulse: number;
+}
+/** What a backend can actually simulate, so a game or the conformance suite can adapt instead of guessing. */
+export interface PhysicsCapabilities {
+    rotation: boolean;
+    shapes: readonly BodyShapeKind[];
+    ccd: boolean;
+    joints: readonly JointDesc["kind"][];
+}
+/** Solver-wide knobs a backend accepts at creation and through `retune`. */
+export interface PhysicsBackendConfig {
+    gravity?: PhysicsVec3;
+    /** Fixed substep length the backend integrates with; the caller's `step(dt)` is accumulated into it. */
+    fixedDt?: number;
+    maxSubsteps?: number;
+}
+/**
+ * The seam every physics consumer talks to: the in-tree `PhysicsWorld` behind `createPhysicsWorldBackend`, or a
+ * native solver such as Rapier behind its own adapter. Handles are backend-issued and survive snapshot/restore,
+ * so gameplay state can store them.
+ *
+ * @capability physics-backend one interface over interchangeable rigid-body solvers — bodies, joints, raycast, shapecast, snapshot
+ */
+export interface PhysicsBackend {
+    readonly name: string;
+    readonly capabilities: PhysicsCapabilities;
+    addBody(desc: BodyDesc): BodyHandle;
+    removeBody(handle: BodyHandle): void;
+    hasBody(handle: BodyHandle): boolean;
+    /** Read a body's state into `out` (or a fresh object); `null` for an unknown handle. */
+    body(handle: BodyHandle, out?: BodyState): BodyState | null;
+    userDataOf(handle: BodyHandle): unknown;
+    setPosition(handle: BodyHandle, position: PhysicsVec3): void;
+    setRotation(handle: BodyHandle, rotation: PhysicsQuat): void;
+    setVelocity(handle: BodyHandle, velocity: PhysicsVec3): void;
+    setAngularVelocity(handle: BodyHandle, angularVelocity: PhysicsVec3): void;
+    applyImpulse(handle: BodyHandle, impulse: PhysicsVec3, point?: PhysicsVec3): void;
+    /**
+     * Apply a world-space force, N, over the next {@link step} only (thrust, wind, buoyancy, a tow rope). Call it
+     * every tick the force should act. A `point` off the centre of mass also applies torque on rotation backends.
+     * Pending forces are not part of a snapshot.
+     */
+    applyForce(handle: BodyHandle, force: PhysicsVec3, point?: PhysicsVec3): void;
+    /** Apply a world-space torque, N·m, over the next {@link step} only; a no-op on rotation-free backends. */
+    applyTorque(handle: BodyHandle, torque: PhysicsVec3): void;
+    /** Move a kinematic body so the solver sees its velocity over the next step (platforms, doors, hands). */
+    setKinematicTarget(handle: BodyHandle, position: PhysicsVec3, rotation?: PhysicsQuat): void;
+    wake(handle: BodyHandle): void;
+    addJoint(desc: JointDesc): JointHandle;
+    removeJoint(handle: JointHandle): void;
+    step(dt: number): void;
+    raycast(desc: RayDesc): RayHit | null;
+    shapecast(desc: ShapeCastDesc): ShapeCastHit | null;
+    overlap(desc: OverlapDesc): BodyHandle[];
+    onContact(listener: ((event: ContactEvent) => void) | null): void;
+    retune(config: PhysicsBackendConfig): void;
+    snapshot(): unknown;
+    restore(state: unknown): void;
+    dispose(): void;
+}
+/** Axis-aligned bounds of a shape at identity rotation, as half extents. */
+export declare function shapeHalfExtents(shape: BodyShape): [number, number, number];
+/** True for an absent or identity rotation. */
+export declare function isIdentityQuat(q: PhysicsQuat | undefined): boolean;

package/dist/physics/physicsBackend.js

@@ -0,0 +1,49 @@
+/** The identity rotation. */
+export const IDENTITY_QUAT = [0, 0, 0, 1];
+/** Axis-aligned bounds of a shape at identity rotation, as half extents. */
+export function shapeHalfExtents(shape) {
+    switch (shape.kind) {
+        case "box":
+            return [shape.halfExtents[0], shape.halfExtents[1], shape.halfExtents[2]];
+        case "sphere":
+            return [shape.radius, shape.radius, shape.radius];
+        case "capsule":
+            return [shape.radius, shape.halfHeight + shape.radius, shape.radius];
+        case "convex": {
+            let x = 0;
+            let y = 0;
+            let z = 0;
+            for (const p of shape.points) {
+                x = Math.max(x, Math.abs(p[0]));
+                y = Math.max(y, Math.abs(p[1]));
+                z = Math.max(z, Math.abs(p[2]));
+            }
+            return [x, y, z];
+        }
+        case "trimesh": {
+            let x = 0;
+            let y = 0;
+            let z = 0;
+            for (let i = 0; i + 2 < shape.vertices.length; i += 3) {
+                x = Math.max(x, Math.abs(shape.vertices[i]));
+                y = Math.max(y, Math.abs(shape.vertices[i + 1]));
+                z = Math.max(z, Math.abs(shape.vertices[i + 2]));
+            }
+            return [x, y, z];
+        }
+        case "heightfield": {
+            let maxH = 0;
+            for (let i = 0; i < shape.heights.length; i += 1)
+                maxH = Math.max(maxH, Math.abs(shape.heights[i]));
+            return [
+                (shape.scale[0] * (shape.columns - 1)) / 2,
+                Math.max(maxH * shape.scale[1], 1e-3),
+                (shape.scale[2] * (shape.rows - 1)) / 2,
+            ];
+        }
+    }
+}
+/** True for an absent or identity rotation. */
+export function isIdentityQuat(q) {
+    return q === undefined || (q[0] === 0 && q[1] === 0 && q[2] === 0 && Math.abs(q[3] - 1) < 1e-9);
+}

package/dist/physics/physicsBackendConformance.d.ts

@@ -0,0 +1,27 @@
+import type { PhysicsBackend } from "./physicsBackend.js";
+/** The slice of a test runner the conformance suite needs; `bun:test` satisfies it directly. */
+export interface ConformanceHarness {
+    test(name: string, run: () => void): void;
+    expect(value: unknown): {
+        toBe(expected: unknown): void;
+        toBeNull(): void;
+        not: {
+            toBeNull(): void;
+            toBe(expected: unknown): void;
+        };
+        toBeGreaterThan(expected: number): void;
+        toBeLessThan(expected: number): void;
+        toBeCloseTo(expected: number, digits?: number): void;
+        toEqual(expected: unknown): void;
+        toContain(expected: unknown): void;
+    };
+}
+/**
+ * Behavioral contract every {@link PhysicsBackend} must pass: bodies rest on floors, casts and rays report the
+ * first surface with an outward normal, kinematic targets produce velocity, masks filter, and snapshot/restore
+ * round-trips with stable handles. Backends declare what they cannot do through `capabilities`; the suite reads it.
+ * Expects `create()` to return a fresh backend whose world spans at least ±50 on every axis with a floor at y=0.
+ *
+ * @capability physics-backend-conformance the shared test contract a physics adapter runs to prove it matches the seam
+ */
+export declare function runPhysicsBackendConformance(create: () => PhysicsBackend, harness: ConformanceHarness): void;

package/dist/physics/physicsBackendConformance.js

@@ -0,0 +1,151 @@
+/**
+ * Behavioral contract every {@link PhysicsBackend} must pass: bodies rest on floors, casts and rays report the
+ * first surface with an outward normal, kinematic targets produce velocity, masks filter, and snapshot/restore
+ * round-trips with stable handles. Backends declare what they cannot do through `capabilities`; the suite reads it.
+ * Expects `create()` to return a fresh backend whose world spans at least ±50 on every axis with a floor at y=0.
+ *
+ * @capability physics-backend-conformance the shared test contract a physics adapter runs to prove it matches the seam
+ */
+export function runPhysicsBackendConformance(create, harness) {
+    const { test, expect } = harness;
+    function settle(backend, seconds) {
+        const steps = Math.ceil(seconds * 60);
+        for (let i = 0; i < steps; i += 1)
+            backend.step(1 / 60);
+    }
+    function floor(backend) {
+        return backend.addBody({ shape: { kind: "box", halfExtents: [50, 0.5, 50] }, position: [0, -0.5, 0], kind: "static" });
+    }
+    test("handles are unique, readable, and removable", () => {
+        const backend = create();
+        const a = backend.addBody({ shape: { kind: "sphere", radius: 0.5 }, position: [1, 2, 3], userData: "a" });
+        const b = backend.addBody({ shape: { kind: "box", halfExtents: [1, 1, 1] }, position: [4, 5, 6] });
+        expect(a).not.toBe(b);
+        expect(backend.body(a)?.position).toEqual([1, 2, 3]);
+        expect(backend.userDataOf(a)).toBe("a");
+        backend.removeBody(a);
+        expect(backend.hasBody(a)).toBe(false);
+        expect(backend.body(a)).toBeNull();
+        expect(backend.hasBody(b)).toBe(true);
+    });
+    test("a dynamic box falls onto a static floor and rests", () => {
+        const backend = create();
+        floor(backend);
+        const crate = backend.addBody({ shape: { kind: "box", halfExtents: [0.5, 0.5, 0.5] }, position: [0, 4, 0] });
+        settle(backend, 3);
+        const state = backend.body(crate);
+        expect(state.position[1]).toBeGreaterThan(0.4);
+        expect(state.position[1]).toBeLessThan(0.7);
+        expect(Math.abs(state.velocity[1])).toBeLessThan(0.5);
+    });
+    test("raycast reports the floor with an upward normal and the right distance", () => {
+        const backend = create();
+        const ground = floor(backend);
+        const hit = backend.raycast({ origin: [0, 3, 0], direction: [0, -1, 0], maxDistance: 10 });
+        expect(hit).not.toBeNull();
+        expect(hit.body).toBe(ground);
+        expect(hit.distance).toBeCloseTo(3, 3);
+        expect(hit.normal[1]).toBeCloseTo(1, 3);
+        expect(backend.raycast({ origin: [0, 3, 0], direction: [0, -1, 0], maxDistance: 1 })).toBeNull();
+    });
+    test("shapecast stops at a wall with a normal facing the mover", () => {
+        const backend = create();
+        backend.addBody({ shape: { kind: "box", halfExtents: [0.5, 2, 5] }, position: [5, 2, 0], kind: "static" });
+        const hit = backend.shapecast({
+            shape: { kind: "capsule", radius: 0.4, halfHeight: 0.5 },
+            position: [0, 1, 0],
+            motion: [10, 0, 0],
+        });
+        expect(hit).not.toBeNull();
+        expect(hit.toi).toBeGreaterThan(0.3);
+        expect(hit.toi).toBeLessThan(0.5);
+        expect(hit.normal[0]).toBeCloseTo(-1, 3);
+        expect(backend.shapecast({ shape: { kind: "sphere", radius: 0.4 }, position: [0, 1, 0], motion: [2, 0, 0] })).toBeNull();
+    });
+    test("overlap finds bodies at a point and nowhere else", () => {
+        const backend = create();
+        const crate = backend.addBody({ shape: { kind: "box", halfExtents: [0.5, 0.5, 0.5] }, position: [0, 0.5, 0], kind: "static" });
+        expect(backend.overlap({ shape: { kind: "sphere", radius: 0.2 }, position: [0.3, 0.5, 0] })).toContain(crate);
+        expect(backend.overlap({ shape: { kind: "sphere", radius: 0.2 }, position: [3, 0.5, 0] })).toEqual([]);
+    });
+    test("layer masks filter rays and casts", () => {
+        const backend = create();
+        backend.addBody({ shape: { kind: "box", halfExtents: [1, 1, 1] }, position: [0, 1, 0], kind: "static", layers: 2 });
+        expect(backend.raycast({ origin: [0, 5, 0], direction: [0, -1, 0], maxDistance: 10, mask: 1 })).toBeNull();
+        expect(backend.raycast({ origin: [0, 5, 0], direction: [0, -1, 0], maxDistance: 10, mask: 2 })).not.toBeNull();
+    });
+    test("a kinematic target moves the body and reports its velocity", () => {
+        const backend = create();
+        const platform = backend.addBody({ shape: { kind: "box", halfExtents: [2, 0.25, 2] }, position: [0, 1, 0], kind: "kinematic" });
+        backend.setKinematicTarget(platform, [0.5, 1, 0]);
+        backend.step(1 / 60);
+        const state = backend.body(platform);
+        expect(state.position[0]).toBeCloseTo(0.5, 3);
+        expect(state.velocity[0]).toBeGreaterThan(20);
+    });
+    test("contacts are reported when a body lands", () => {
+        const backend = create();
+        const ground = floor(backend);
+        const crate = backend.addBody({ shape: { kind: "box", halfExtents: [0.5, 0.5, 0.5] }, position: [0, 3, 0] });
+        const pairs = [];
+        backend.onContact((event) => {
+            pairs.push([event.a, event.b].sort((x, y) => x - y).join(":"));
+        });
+        settle(backend, 2);
+        expect(pairs).toContain([ground, crate].sort((x, y) => x - y).join(":"));
+    });
+    test("snapshot and restore round-trip state with stable handles", () => {
+        const backend = create();
+        floor(backend);
+        const crate = backend.addBody({ shape: { kind: "box", halfExtents: [0.5, 0.5, 0.5] }, position: [0, 5, 0] });
+        settle(backend, 0.5);
+        const saved = backend.snapshot();
+        const at = backend.body(crate).position[1];
+        settle(backend, 1);
+        expect(backend.body(crate).position[1]).not.toBe(at);
+        backend.restore(saved);
+        expect(backend.hasBody(crate)).toBe(true);
+        expect(backend.body(crate).position[1]).toBeCloseTo(at, 5);
+        const later = backend.addBody({ shape: { kind: "sphere", radius: 0.3 }, position: [2, 2, 2] });
+        expect(later).not.toBe(crate);
+    });
+    test("applyForce accelerates at F/m for one step and then stops acting", () => {
+        const backend = create();
+        const held = backend.addBody({ shape: { kind: "sphere", radius: 0.5 }, position: [0, 20, 0], mass: 2 });
+        const once = backend.addBody({ shape: { kind: "sphere", radius: 0.5 }, position: [10, 20, 0], mass: 2 });
+        backend.applyForce(once, [4, 0, 0]);
+        for (let i = 0; i < 60; i += 1) {
+            backend.applyForce(held, [4, 0, 0]);
+            backend.step(1 / 60);
+        }
+        expect(backend.body(held).velocity[0]).toBeGreaterThan(1.6);
+        expect(backend.body(held).velocity[0]).toBeLessThan(2.2);
+        expect(backend.body(once).velocity[0]).toBeGreaterThan(0.02);
+        expect(backend.body(once).velocity[0]).toBeLessThan(0.05);
+    });
+    test("linear damping bleeds a body's speed faster than an undamped twin", () => {
+        const backend = create();
+        const damped = backend.addBody({ shape: { kind: "sphere", radius: 0.5 }, position: [0, 30, 0], velocity: [10, 0, 0], linearDamping: 1.5 });
+        const free = backend.addBody({ shape: { kind: "sphere", radius: 0.5 }, position: [0, 30, 20], velocity: [10, 0, 0] });
+        settle(backend, 1);
+        expect(backend.body(damped).velocity[0]).toBeLessThan(backend.body(free).velocity[0] * 0.5);
+    });
+    test("applyTorque spins a body on rotation backends and is harmless elsewhere", () => {
+        const backend = create();
+        const wheel = backend.addBody({ shape: { kind: "box", halfExtents: [0.5, 0.5, 0.5] }, position: [0, 30, 0] });
+        for (let i = 0; i < 30; i += 1) {
+            backend.applyTorque(wheel, [0, 2, 0]);
+            backend.step(1 / 60);
+        }
+        const spin = backend.body(wheel).angularVelocity[1];
+        if (backend.capabilities.rotation)
+            expect(spin).toBeGreaterThan(0.1);
+        else
+            expect(spin).toBe(0);
+    });
+    test("capabilities describe the backend", () => {
+        const backend = create();
+        expect(backend.capabilities.shapes.length).toBeGreaterThan(1);
+        expect(typeof backend.capabilities.rotation).toBe("boolean");
+    });
+}

package/dist/physics/physicsWorldBackend.d.ts

@@ -0,0 +1,45 @@
+import { type BodyHandle, type BodyKind, type BodyShape, type JointDesc, type JointHandle, type PhysicsBackend, type PhysicsBackendConfig } from "./physicsBackend.js";
+import { type PhysicsBounds, type PhysicsPrecision } from "./physicsWorld.js";
+/** Construction options: the `PhysicsWorld` capacity and bounds plus the shared backend config. */
+export interface PhysicsWorldBackendOptions extends PhysicsBackendConfig {
+    capacity: number;
+    bounds: PhysicsBounds;
+    precision?: PhysicsPrecision;
+    friction?: number;
+    restitution?: number;
+    /** Warn (once) when a body asks for rotation or a shape this backend approximates. Default `true`. */
+    warn?: boolean;
+}
+interface SavedBody {
+    handle: BodyHandle;
+    shape: BodyShape;
+    kind: BodyKind;
+    layers: number;
+    mask: number;
+    userData: unknown;
+    mass: number;
+    position: [number, number, number];
+    velocity: [number, number, number];
+    sleeping: boolean;
+    linearDamping?: number;
+}
+/** Serializable backend state: every live body and joint, with handles preserved. */
+export interface PhysicsWorldBackendState {
+    nextHandle: number;
+    nextJoint: number;
+    bodies: SavedBody[];
+    joints: {
+        handle: JointHandle;
+        desc: JointDesc;
+    }[];
+}
+/**
+ * `PhysicsWorld` behind the {@link PhysicsBackend} interface: zero dependencies, translation-only. Capsules,
+ * convex hulls, meshes, and heightfields collide as their bounding boxes; rotation, angular velocity, CCD, and
+ * hinge limits are accepted and ignored (see {@link PhysicsBackend.capabilities}). Reach for `@jgengine/rapier`
+ * when a game needs those for real; the seam is the same.
+ *
+ * @capability physics-world-backend the zero-dependency PhysicsWorld solver exposed through the PhysicsBackend seam
+ */
+export declare function createPhysicsWorldBackend(options: PhysicsWorldBackendOptions): PhysicsBackend;
+export {};