@jgengine/core 0.18.0 → 0.18.1

package/dist/nav/navMesh.js

@@ -0,0 +1,164 @@
+function vertex(mesh, index) {
+    return [mesh.verts[index * 3] ?? 0, mesh.verts[index * 3 + 1] ?? 0, mesh.verts[index * 3 + 2] ?? 0];
+}
+function center(mesh, poly) {
+    const result = [0, 0, 0];
+    for (const index of poly) {
+        const point = vertex(mesh, index);
+        result[0] += point[0];
+        result[1] += point[1];
+        result[2] += point[2];
+    }
+    const scale = poly.length > 0 ? 1 / poly.length : 0;
+    return [result[0] * scale, result[1] * scale, result[2] * scale];
+}
+function distance(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+/** Build polygon adjacency from shared edges and explicit off-mesh links. */
+export function buildNavAdjacency(mesh) {
+    const edges = new Map();
+    mesh.polys.forEach((poly, polyIndex) => {
+        for (let i = 0; i < poly.length; i += 1) {
+            const a = poly[i];
+            const b = poly[(i + 1) % poly.length];
+            const key = a < b ? `${a}:${b}` : `${b}:${a}`;
+            const owners = edges.get(key) ?? [];
+            owners.push(polyIndex);
+            edges.set(key, owners);
+        }
+    });
+    const result = mesh.polys.map(() => ({ neighbors: [], cost: 1 }));
+    for (const owners of edges.values()) {
+        for (const a of owners)
+            for (const b of owners) {
+                if (a !== b && !result[a].neighbors.includes(b))
+                    result[a].neighbors.push(b);
+            }
+    }
+    for (const link of mesh.links ?? []) {
+        if (!result[link.from] || !result[link.to])
+            continue;
+        if (!result[link.from].neighbors.includes(link.to))
+            result[link.from].neighbors.push(link.to);
+    }
+    return result;
+}
+function pointInPoly(mesh, poly, point) {
+    let inside = false;
+    for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+        const a = vertex(mesh, poly[i]);
+        const b = vertex(mesh, poly[j]);
+        const cross = (point[0] - a[0]) * (b[2] - a[2]) - (point[2] - a[2]) * (b[0] - a[0]);
+        const dot = (point[0] - a[0]) * (point[0] - b[0]) + (point[2] - a[2]) * (point[2] - b[2]);
+        if (Math.abs(cross) < 1e-8 && dot <= 1e-8)
+            return true;
+        if ((a[2] > point[2]) !== (b[2] > point[2]) && point[0] < (b[0] - a[0]) * (point[2] - a[2]) / (b[2] - a[2]) + a[0])
+            inside = !inside;
+    }
+    return inside;
+}
+function closestOnSegment(point, a, b) {
+    const dx = b[0] - a[0], dy = b[1] - a[1], dz = b[2] - a[2];
+    const len = dx * dx + dy * dy + dz * dz;
+    const t = len > 0 ? Math.max(0, Math.min(1, ((point[0] - a[0]) * dx + (point[1] - a[1]) * dy + (point[2] - a[2]) * dz) / len)) : 0;
+    return [a[0] + dx * t, a[1] + dy * t, a[2] + dz * t];
+}
+/** Return the closest point on the mesh surface, or null for an empty mesh. */
+export function closestPoint(mesh, point) {
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const poly of mesh.polys) {
+        if (pointInPoly(mesh, poly, point))
+            return [point[0], center(mesh, poly)[1], point[2]];
+        for (let i = 0; i < poly.length; i += 1) {
+            const candidate = closestOnSegment(point, vertex(mesh, poly[i]), vertex(mesh, poly[(i + 1) % poly.length]));
+            const d = distance(point, candidate);
+            if (d < bestDistance) {
+                bestDistance = d;
+                best = candidate;
+            }
+        }
+    }
+    return best;
+}
+function polyAt(mesh, point) {
+    for (let i = 0; i < mesh.polys.length; i += 1)
+        if (pointInPoly(mesh, mesh.polys[i], point))
+            return i;
+    const nearest = closestPoint(mesh, point);
+    if (!nearest)
+        return null;
+    let best = 0;
+    let score = Number.POSITIVE_INFINITY;
+    mesh.polys.forEach((poly, i) => { const d = distance(nearest, center(mesh, poly)); if (d < score) {
+        score = d;
+        best = i;
+    } });
+    return best;
+}
+/** A* over polygon centers, followed by deterministic visibility string-pulling. */
+export function findPath(mesh, from, to) {
+    if (mesh.polys.length === 0)
+        return null;
+    const start = polyAt(mesh, from), goal = polyAt(mesh, to);
+    if (start === null || goal === null)
+        return null;
+    const adjacency = buildNavAdjacency(mesh);
+    const g = new Map([[start, 0]]);
+    const came = new Map();
+    const open = [start];
+    while (open.length) {
+        open.sort((a, b) => (g.get(a) + distance(center(mesh, mesh.polys[a]), center(mesh, mesh.polys[goal]))) - (g.get(b) + distance(center(mesh, mesh.polys[b]), center(mesh, mesh.polys[goal]))));
+        const current = open.shift();
+        if (current === goal)
+            break;
+        for (const next of adjacency[current].neighbors) {
+            const link = mesh.links.find((candidate) => candidate.from === current && candidate.to === next);
+            const cost = link?.cost ?? distance(center(mesh, mesh.polys[current]), center(mesh, mesh.polys[next]));
+            const nextG = g.get(current) + Math.max(0, cost);
+            if (nextG < (g.get(next) ?? Number.POSITIVE_INFINITY)) {
+                g.set(next, nextG);
+                came.set(next, current);
+                if (!open.includes(next))
+                    open.push(next);
+            }
+        }
+    }
+    if (start !== goal && !came.has(goal))
+        return null;
+    const polys = [goal];
+    while (polys[0] !== start)
+        polys.unshift(came.get(polys[0]));
+    const anchors = [from, ...polys.slice(1, -1).map((i) => center(mesh, mesh.polys[i])), to];
+    const points = [anchors[0]];
+    let anchor = 0;
+    for (let i = 2; i < anchors.length; i += 1) {
+        const steps = 24;
+        let visible = true;
+        for (let step = 1; step < steps; step += 1) {
+            const t = step / steps;
+            const p = [anchors[anchor][0] + (anchors[i][0] - anchors[anchor][0]) * t, anchors[anchor][1] + (anchors[i][1] - anchors[anchor][1]) * t, anchors[anchor][2] + (anchors[i][2] - anchors[anchor][2]) * t];
+            if (!mesh.polys.some((poly) => pointInPoly(mesh, poly, p))) {
+                visible = false;
+                break;
+            }
+        }
+        if (!visible) {
+            points.push(anchors[i - 1]);
+            anchor = i - 1;
+        }
+    }
+    points.push(anchors[anchors.length - 1]);
+    return { points, polys };
+}
+/** True when the segment remains over walkable polygons. */
+export function raycastNav(mesh, from, to) {
+    for (let i = 0; i <= 32; i += 1) {
+        const t = i / 32;
+        const point = [from[0] + (to[0] - from[0]) * t, from[1] + (to[1] - from[1]) * t, from[2] + (to[2] - from[2]) * t];
+        if (!mesh.polys.some((poly) => pointInPoly(mesh, poly, point)))
+            return false;
+    }
+    return true;
+}

package/dist/physics/flightDynamics.d.ts

@@ -1,3 +1,5 @@
+import type { AxisBinding } from "../input/axisInput.js";
+import type { ChaseCameraTuning } from "../runtime/cameraDirector.js";
 import { type GravityField } from "./gravityField.js";
 /** Three-dimensional world-space vector used by the flight model. */
 export type FlightVector = readonly [number, number, number];
@@ -23,6 +25,8 @@ export interface FlightControlRates {
     damping: number;
     stability: number;
 }
+/** Axes an aircraft can bind — which actions drive each flight control. */
+export type AircraftAxis = "pitch" | "roll" | "yaw" | "throttle" | "collective" | "airbrake" | "afterburner" | "vectoring";
 /** Data-first physical tuning shared by all aircraft instances of one catalog type. */
 export interface AircraftTuning {
     kind: AircraftKind;
@@ -41,6 +45,10 @@ export interface AircraftTuning {
     groundEffectHeight?: number;
     vtolTransitionSpeed?: number;
     groundClearance?: number;
+    /** Per-axis bindings for this aircraft — which actions drive each control. Unlisted axes keep the defaults (WASD + flightThrottleUp/Down etc.). */
+    bindings?: Partial<Record<AircraftAxis, AxisBinding>>;
+    /** Camera POV while this aircraft is piloted — chase tuning overlay applied on mount, cleared on dismount. */
+    camera?: ChaseCameraTuning | null;
 }
 /** Spawn state and injectable world-field samplers for an aircraft instance. */
 export interface AircraftOptions {

package/dist/physics/kinematicVehicle.d.ts

@@ -1,4 +1,5 @@
-import type { AxisInput } from "../input/axisInput.js";
+import type { AxisBinding, AxisInput } from "../input/axisInput.js";
+import type { ChaseCameraTuning } from "../runtime/cameraDirector.js";
 import { type GripCurve } from "./vehicleBody.js";
 export interface KinematicVehicleTuning {
     engineAccel: number;
@@ -47,6 +48,10 @@ export interface KinematicVehicleTuning {
      * Omit to preserve the direct arcade acceleration model exactly.
      */
     chassis?: KinematicChassisTuning;
+    /** Per-axis bindings for this vehicle — which actions drive throttle/brake/steer/handbrake. Unlisted axes keep car defaults (W/S/A/D/Space). */
+    bindings?: Partial<Record<"throttle" | "brake" | "steer" | "handbrake", AxisBinding>>;
+    /** Camera POV while this vehicle is piloted — chase tuning overlay applied on mount, cleared on dismount. */
+    camera?: ChaseCameraTuning | null;
 }
 /**
  * Mass-and-force chassis layer (#1051); when present it supersedes `engineAccel`/`brakeAccel` with

package/dist/physics/physicsBackend.d.ts

@@ -0,0 +1,191 @@
+/** `[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;
+    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;
+    /** 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,117 @@
+/**
+ * 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("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,44 @@
+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;
+}
+/** 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 {};