@aura3d/physics 1.5.2 → 2.0.1

package/dist/FightingCharacterController.js

@@ -0,0 +1,76 @@
+import { KinematicBody } from "./KinematicBody.js";
+/** Authored-unit fighting movement; this is not a physical-simulation controller. */
+export class FightingCharacterController {
+    body;
+    walkSpeed;
+    crouchSpeed;
+    fastFallSpeed;
+    #state = "idle";
+    constructor(descriptor = {}) {
+        this.walkSpeed = positive(descriptor.walkSpeed ?? descriptor.maxSpeed ?? 4.5, "fighting controller walkSpeed");
+        this.crouchSpeed = positive(descriptor.crouchSpeed ?? this.walkSpeed * 0.45, "fighting controller crouchSpeed");
+        this.fastFallSpeed = positive(descriptor.fastFallSpeed ?? descriptor.maxFallSpeed ?? 20, "fighting controller fastFallSpeed");
+        this.body = new KinematicBody({
+            ...descriptor,
+            id: descriptor.id ?? "fighter",
+            halfExtents: descriptor.halfExtents ?? [0.32, 0.9, 0.25],
+            maxSpeed: descriptor.maxSpeed ?? this.walkSpeed,
+            acceleration: descriptor.acceleration ?? 54,
+            airAcceleration: descriptor.airAcceleration ?? 24,
+            groundFriction: descriptor.groundFriction ?? 56,
+            airFriction: descriptor.airFriction ?? 4,
+            gravity: descriptor.gravity ?? 26,
+            jumpSpeed: descriptor.jumpSpeed ?? 9.4,
+            maxFallSpeed: descriptor.maxFallSpeed ?? Math.max(this.fastFallSpeed, 20),
+            dashSpeed: descriptor.dashSpeed ?? 8.6,
+            dashDuration: descriptor.dashDuration ?? 0.12,
+            dashCooldown: descriptor.dashCooldown ?? 0.18,
+            groundSnapDistance: descriptor.groundSnapDistance ?? 0.06,
+            lockDepth: descriptor.lockDepth ?? true
+        });
+    }
+    walk(direction, speed) {
+        const magnitude = Math.min(1, Math.abs(finiteOrZero(direction)));
+        const facing = direction < 0 ? -1 : 1;
+        const targetSpeed = speed ?? (this.body.snapshot().crouching ? this.crouchSpeed : this.walkSpeed);
+        const normalizedSpeed = this.body.maxSpeed > 0 ? Math.min(1, positive(targetSpeed, "fighting controller walk speed") / this.body.maxSpeed) : 0;
+        this.body.move(facing * magnitude * normalizedSpeed);
+        this.#state = magnitude > 0 ? "walk" : this.#derive([]);
+    }
+    stop() { this.body.move(0); this.#state = this.#derive([]); }
+    jump() { this.body.jump(); this.#state = "jump"; }
+    dash(direction) { this.body.dash(direction); this.#state = "dash"; }
+    fastFall(speed = this.fastFallSpeed) { this.body.fastFall(speed); if (!this.body.grounded)
+        this.#state = "fast-fall"; }
+    crouch(active = true) { this.body.crouch(active); this.#state = active ? "crouch" : this.#derive([]); }
+    step(dt, options = {}) {
+        const events = this.body.step(dt, options);
+        this.#state = this.#derive(events);
+        return events;
+    }
+    snapshot() {
+        return { ...this.body.snapshot(), state: this.#state, walkSpeed: this.walkSpeed, crouchSpeed: this.crouchSpeed, fastFallSpeed: this.fastFallSpeed };
+    }
+    #derive(events) {
+        if (events.some((event) => event.type === "land"))
+            return "landing";
+        const snapshot = this.body.snapshot();
+        if (snapshot.crouching)
+            return "crouch";
+        if (snapshot.dashFramesRemaining > 0)
+            return "dash";
+        if (!snapshot.grounded)
+            return snapshot.velocity[1] < -this.fastFallSpeed * 0.5 ? "fast-fall" : "jump";
+        return Math.abs(snapshot.velocity[0]) > 0.05 ? "walk" : "idle";
+    }
+}
+export function createFightingCharacterController(descriptor = {}) {
+    return new FightingCharacterController(descriptor);
+}
+function positive(value, label) {
+    if (!Number.isFinite(value) || value <= 0)
+        throw new RangeError(`${label} must be finite and positive.`);
+    return value;
+}
+function finiteOrZero(value) { return Number.isFinite(value) ? value : 0; }
+//# sourceMappingURL=FightingCharacterController.js.map

package/dist/FightingCharacterController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FightingCharacterController.js","sourceRoot":"","sources":["../../../../packages/physics/src/FightingCharacterController.ts"],"names":[],"mappings":"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"}

package/dist/MeshBVH.d.ts

@@ -0,0 +1,72 @@
+import type { Vec3 } from "./Shape.js";
+/**
+ * Bounding volume hierarchy over an indexed triangle mesh.
+ *
+ * ## Why this exists
+ *
+ * Every grounding system in the library was solving against an *approximation of* a
+ * surface rather than the surface itself. Turbo Drift sampled
+ * `TRACK_SURFACE_Y - VERGE_DROP * shoulderFraction` — a flat plane plus an analytic
+ * ramp — so on a banked or crowned corner the returned height was wrong and the car's
+ * tyres passed through the visible road. The fix is to ask the real triangles, which
+ * needs a spatial index: a naive per-sample scan over a 40k-triangle circuit is far too
+ * slow to run four times per frame.
+ *
+ * ## Determinism
+ *
+ * Construction must not depend on iteration order or floating-point tie-breaking, or two
+ * runs over the same mesh produce different trees and the same query returns different
+ * hits. Splits use the median along the widest axis with a stable index-based tiebreak,
+ * so the tree is a pure function of the input arrays.
+ */
+export interface MeshBVHBuildOptions {
+    /** Stop splitting at this triangle count. Larger leaves trade traversal for tests. */
+    readonly maxLeafTriangles?: number | undefined;
+    /** Hard depth cap, a safety valve against degenerate geometry. */
+    readonly maxDepth?: number | undefined;
+}
+interface BVHNode {
+    readonly min: [number, number, number];
+    readonly max: [number, number, number];
+    /** Triangle indices, leaf nodes only. */
+    readonly triangles?: readonly number[] | undefined;
+    readonly left?: number | undefined;
+    readonly right?: number | undefined;
+}
+export interface MeshBVH {
+    readonly kind: "aura-mesh-bvh";
+    readonly nodes: readonly BVHNode[];
+    readonly positions: Float32Array;
+    readonly indices: Uint32Array;
+    readonly triangleCount: number;
+    readonly maxDepth: number;
+}
+export declare function buildMeshBVH(positions: Float32Array, indices: Uint32Array, options?: MeshBVHBuildOptions): MeshBVH;
+export interface MeshRayHit {
+    readonly triangle: number;
+    readonly distance: number;
+    readonly point: Vec3;
+    /** Geometric normal, unit length, oriented against the ray. */
+    readonly normal: Vec3;
+    /** Barycentric coordinates, for interpolating vertex attributes. */
+    readonly barycentric: Vec3;
+    /** True when the ray struck the back face. */
+    readonly backFace: boolean;
+}
+export interface RaycastMeshOptions {
+    readonly maxDistance?: number | undefined;
+    /** Skip back faces. Off by default so a ray starting inside geometry still reports. */
+    readonly cullBackFaces?: boolean | undefined;
+}
+/**
+ * Nearest triangle hit along a ray, using the BVH.
+ *
+ * The direction is normalised internally so `distance` is always in world units; a
+ * caller passing an unnormalised direction otherwise gets a distance scaled by its
+ * length, which is a silent and very confusing error.
+ */
+export declare function raycastMesh(bvh: MeshBVH, origin: Vec3, direction: Vec3, options?: RaycastMeshOptions): MeshRayHit | undefined;
+/** Reference implementation, for testing the BVH. Never use in a hot path. */
+export declare function raycastMeshBruteForce(bvh: MeshBVH, origin: Vec3, direction: Vec3, options?: RaycastMeshOptions): MeshRayHit | undefined;
+export {};
+//# sourceMappingURL=MeshBVH.d.ts.map

package/dist/MeshBVH.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeshBVH.d.ts","sourceRoot":"","sources":["../../../../packages/physics/src/MeshBVH.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED,UAAU,OAAO;IACf,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AA0BD,wBAAgB,YAAY,CAC1B,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CA0ET;AA2BD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAiED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,uFAAuF;IACvF,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,IAAI,EACZ,SAAS,EAAE,IAAI,EACf,OAAO,GAAE,kBAAuB,GAC/B,UAAU,GAAG,SAAS,CAkCxB;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,IAAI,EACZ,SAAS,EAAE,IAAI,EACf,OAAO,GAAE,kBAAuB,GAC/B,UAAU,GAAG,SAAS,CAaxB"}

package/dist/MeshBVH.js

@@ -0,0 +1,244 @@
+function triangleBounds(positions, indices, triangle) {
+    const a = indices[triangle * 3] * 3;
+    const b = indices[triangle * 3 + 1] * 3;
+    const c = indices[triangle * 3 + 2] * 3;
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    for (const base of [a, b, c]) {
+        for (let axis = 0; axis < 3; axis += 1) {
+            const value = positions[base + axis];
+            if (value < min[axis])
+                min[axis] = value;
+            if (value > max[axis])
+                max[axis] = value;
+        }
+    }
+    return {
+        min,
+        max,
+        centroid: [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2]
+    };
+}
+export function buildMeshBVH(positions, indices, options = {}) {
+    if (indices.length % 3 !== 0) {
+        throw new Error("buildMeshBVH requires an index count divisible by 3.");
+    }
+    const triangleCount = indices.length / 3;
+    const maxLeafTriangles = Math.max(1, options.maxLeafTriangles ?? 8);
+    const maxDepth = Math.max(1, options.maxDepth ?? 32);
+    const bounds = Array.from({ length: triangleCount }, (_, index) => triangleBounds(positions, indices, index));
+    const nodes = [];
+    let observedDepth = 0;
+    function build(triangles, depth) {
+        observedDepth = Math.max(observedDepth, depth);
+        const min = [Infinity, Infinity, Infinity];
+        const max = [-Infinity, -Infinity, -Infinity];
+        for (const triangle of triangles) {
+            const b = bounds[triangle];
+            for (let axis = 0; axis < 3; axis += 1) {
+                if (b.min[axis] < min[axis])
+                    min[axis] = b.min[axis];
+                if (b.max[axis] > max[axis])
+                    max[axis] = b.max[axis];
+            }
+        }
+        const index = nodes.length;
+        if (triangles.length <= maxLeafTriangles || depth >= maxDepth) {
+            nodes.push({ min, max, triangles: [...triangles] });
+            return index;
+        }
+        // Split on the widest axis; median split keeps the tree balanced regardless of
+        // how the mesh was authored.
+        let axis = 0;
+        let widest = -Infinity;
+        for (let candidate = 0; candidate < 3; candidate += 1) {
+            const extent = max[candidate] - min[candidate];
+            if (extent > widest) {
+                widest = extent;
+                axis = candidate;
+            }
+        }
+        // Stable sort: centroid, then triangle index. Without the index tiebreak, equal
+        // centroids order differently between runs and the tree stops being deterministic.
+        const sorted = [...triangles].sort((left, right) => {
+            const delta = bounds[left].centroid[axis] - bounds[right].centroid[axis];
+            return delta !== 0 ? delta : left - right;
+        });
+        const mid = Math.floor(sorted.length / 2);
+        const leftTriangles = sorted.slice(0, mid);
+        const rightTriangles = sorted.slice(mid);
+        if (leftTriangles.length === 0 || rightTriangles.length === 0) {
+            nodes.push({ min, max, triangles: [...triangles] });
+            return index;
+        }
+        // Reserve this slot before recursing so child indices are stable.
+        nodes.push({ min, max });
+        const left = build(leftTriangles, depth + 1);
+        const right = build(rightTriangles, depth + 1);
+        nodes[index] = { min, max, left, right };
+        return index;
+    }
+    if (triangleCount > 0) {
+        build(Array.from({ length: triangleCount }, (_, index) => index), 0);
+    }
+    else {
+        nodes.push({ min: [0, 0, 0], max: [0, 0, 0], triangles: [] });
+    }
+    return {
+        kind: "aura-mesh-bvh",
+        nodes,
+        positions,
+        indices,
+        triangleCount,
+        maxDepth: observedDepth
+    };
+}
+/** Slab test. `tMax` lets a caller reject nodes beyond an existing best hit. */
+function rayHitsAabb(origin, inverseDirection, node, tMax) {
+    let tMin = 0;
+    let tFar = tMax;
+    for (let axis = 0; axis < 3; axis += 1) {
+        const inv = inverseDirection[axis];
+        let tNear = (node.min[axis] - origin[axis]) * inv;
+        let tFarAxis = (node.max[axis] - origin[axis]) * inv;
+        if (tNear > tFarAxis) {
+            const swap = tNear;
+            tNear = tFarAxis;
+            tFarAxis = swap;
+        }
+        if (tNear > tMin)
+            tMin = tNear;
+        if (tFarAxis < tFar)
+            tFar = tFarAxis;
+        if (tMin > tFar)
+            return false;
+    }
+    return true;
+}
+/** Möller–Trumbore. Returns undefined for a miss or a degenerate triangle. */
+function intersectTriangle(positions, indices, triangle, origin, direction) {
+    const ia = indices[triangle * 3] * 3;
+    const ib = indices[triangle * 3 + 1] * 3;
+    const ic = indices[triangle * 3 + 2] * 3;
+    const ax = positions[ia], ay = positions[ia + 1], az = positions[ia + 2];
+    const bx = positions[ib], by = positions[ib + 1], bz = positions[ib + 2];
+    const cx = positions[ic], cy = positions[ic + 1], cz = positions[ic + 2];
+    const e1x = bx - ax, e1y = by - ay, e1z = bz - az;
+    const e2x = cx - ax, e2y = cy - ay, e2z = cz - az;
+    const px = direction[1] * e2z - direction[2] * e2y;
+    const py = direction[2] * e2x - direction[0] * e2z;
+    const pz = direction[0] * e2y - direction[1] * e2x;
+    const det = e1x * px + e1y * py + e1z * pz;
+    // A near-zero determinant means the ray is parallel to the plane, or the triangle is
+    // degenerate (zero area). Both are misses, and both would divide by ~0 below.
+    if (Math.abs(det) < 1e-12)
+        return undefined;
+    const invDet = 1 / det;
+    const tx = origin[0] - ax, ty = origin[1] - ay, tz = origin[2] - az;
+    const u = (tx * px + ty * py + tz * pz) * invDet;
+    if (u < -1e-9 || u > 1 + 1e-9)
+        return undefined;
+    const qx = ty * e1z - tz * e1y;
+    const qy = tz * e1x - tx * e1z;
+    const qz = tx * e1y - ty * e1x;
+    const v = (direction[0] * qx + direction[1] * qy + direction[2] * qz) * invDet;
+    if (v < -1e-9 || u + v > 1 + 1e-9)
+        return undefined;
+    const t = (e2x * qx + e2y * qy + e2z * qz) * invDet;
+    if (t < 0)
+        return undefined;
+    let nx = e1y * e2z - e1z * e2y;
+    let ny = e1z * e2x - e1x * e2z;
+    let nz = e1x * e2y - e1y * e2x;
+    const length = Math.hypot(nx, ny, nz);
+    if (length < 1e-12)
+        return undefined;
+    nx /= length;
+    ny /= length;
+    nz /= length;
+    // Orient the normal against the ray so callers always get an outward-facing surface.
+    const facing = nx * direction[0] + ny * direction[1] + nz * direction[2];
+    const backFace = facing > 0;
+    if (backFace) {
+        nx = -nx;
+        ny = -ny;
+        nz = -nz;
+    }
+    return {
+        triangle,
+        distance: t,
+        point: [origin[0] + direction[0] * t, origin[1] + direction[1] * t, origin[2] + direction[2] * t],
+        normal: [nx, ny, nz],
+        barycentric: [1 - u - v, u, v],
+        backFace
+    };
+}
+/**
+ * Nearest triangle hit along a ray, using the BVH.
+ *
+ * The direction is normalised internally so `distance` is always in world units; a
+ * caller passing an unnormalised direction otherwise gets a distance scaled by its
+ * length, which is a silent and very confusing error.
+ */
+export function raycastMesh(bvh, origin, direction, options = {}) {
+    const length = Math.hypot(direction[0], direction[1], direction[2]);
+    if (!Number.isFinite(length) || length < 1e-12)
+        return undefined;
+    const dir = [direction[0] / length, direction[1] / length, direction[2] / length];
+    const maxDistance = options.maxDistance ?? Infinity;
+    const inverse = [
+        1 / (dir[0] === 0 ? 1e-30 : dir[0]),
+        1 / (dir[1] === 0 ? 1e-30 : dir[1]),
+        1 / (dir[2] === 0 ? 1e-30 : dir[2])
+    ];
+    let best;
+    let bestDistance = maxDistance;
+    const stack = bvh.nodes.length > 0 ? [0] : [];
+    while (stack.length > 0) {
+        const nodeIndex = stack.pop();
+        const node = bvh.nodes[nodeIndex];
+        if (!node)
+            continue;
+        if (!rayHitsAabb(origin, inverse, node, bestDistance))
+            continue;
+        if (node.triangles) {
+            for (const triangle of node.triangles) {
+                const hit = intersectTriangle(bvh.positions, bvh.indices, triangle, origin, dir);
+                if (!hit)
+                    continue;
+                if (hit.distance > bestDistance)
+                    continue;
+                if (options.cullBackFaces && hit.backFace)
+                    continue;
+                best = hit;
+                bestDistance = hit.distance;
+            }
+            continue;
+        }
+        if (node.left !== undefined)
+            stack.push(node.left);
+        if (node.right !== undefined)
+            stack.push(node.right);
+    }
+    return best;
+}
+/** Reference implementation, for testing the BVH. Never use in a hot path. */
+export function raycastMeshBruteForce(bvh, origin, direction, options = {}) {
+    const length = Math.hypot(direction[0], direction[1], direction[2]);
+    if (!Number.isFinite(length) || length < 1e-12)
+        return undefined;
+    const dir = [direction[0] / length, direction[1] / length, direction[2] / length];
+    const maxDistance = options.maxDistance ?? Infinity;
+    let best;
+    for (let triangle = 0; triangle < bvh.triangleCount; triangle += 1) {
+        const hit = intersectTriangle(bvh.positions, bvh.indices, triangle, origin, dir);
+        if (!hit || hit.distance > maxDistance)
+            continue;
+        if (options.cullBackFaces && hit.backFace)
+            continue;
+        if (!best || hit.distance < best.distance)
+            best = hit;
+    }
+    return best;
+}
+//# sourceMappingURL=MeshBVH.js.map

package/dist/MeshBVH.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeshBVH.js","sourceRoot":"","sources":["../../../../packages/physics/src/MeshBVH.ts"],"names":[],"mappings":"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"}

package/dist/PhysicsDebugDraw.d.ts

@@ -4,8 +4,47 @@ export type DebugLine = {
     readonly from: Vec3;
     readonly to: Vec3;
     readonly color: Vec3;
+    /**
+     * What this line represents, so a consumer can filter or legend it.
+     *
+     * Without a category every line is an anonymous coloured segment, and a debug overlay that
+     * cannot say "these are contacts and those are joints" is decoration rather than a tool.
+     */
+    readonly category?: DebugLineCategory;
 };
+export type DebugLineCategory = "collider" | "sensor" | "contact" | "normal" | "joint" | "sleeping" | "raycast";
+/** A raycast to draw, so a developer can see the query they cannot otherwise observe. */
+export type DebugRaycast = {
+    readonly origin: Vec3;
+    readonly direction: Vec3;
+    readonly distance: number;
+    /** True when the ray hit something; drawn in a different colour. */
+    readonly hit?: boolean;
+};
+export type PhysicsDebugDrawOptions = {
+    /** Draw contact points and their normals. */
+    readonly contacts?: boolean;
+    /** Draw joint anchors and the segment between them. */
+    readonly joints?: boolean;
+    /** Tint sleeping bodies differently from awake ones. */
+    readonly sleeping?: boolean;
+    /** Extra rays to visualise, which the world cannot know about. */
+    readonly raycasts?: readonly DebugRaycast[];
+    /** Length of a drawn contact normal, in world units. */
+    readonly normalLength?: number;
+};
+type DebugWorld = Pick<PhysicsWorld, "colliders" | "getBody"> & Partial<Pick<PhysicsWorld, "snapshot" | "constraints">>;
 export declare class PhysicsDebugDraw {
-    buildLines(world: Pick<PhysicsWorld, "colliders" | "getBody">): readonly DebugLine[];
+    /**
+     * Build debug geometry for a world.
+     *
+     * WS-1.7 asks for colliders, contacts, normals, joints, sleeping state and raycasts. Only
+     * colliders existed, which is why the capability sat at "unproven with 0 consumers" — there was
+     * not enough here for a route to consume.
+     *
+     * Options default to off so the existing single-argument call keeps its previous output exactly.
+     */
+    buildLines(world: DebugWorld, options?: PhysicsDebugDrawOptions): readonly DebugLine[];
 }
+export {};
 //# sourceMappingURL=PhysicsDebugDraw.d.ts.map

package/dist/PhysicsDebugDraw.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PhysicsDebugDraw.d.ts","sourceRoot":"","sources":["../../../../packages/physics/src/PhysicsDebugDraw.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;CACtB,CAAC;AAEF,qBAAa,gBAAgB;IAC3B,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,SAAS,CAAC,GAAG,SAAS,SAAS,EAAE;CAWrF"}
+{"version":3,"file":"PhysicsDebugDraw.d.ts","sourceRoot":"","sources":["../../../../packages/physics/src/PhysicsDebugDraw.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,GACP,UAAU,GACV,SAAS,CAAC;AAEd,yFAAyF;AACzF,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC5C,wDAAwD;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,KAAK,UAAU,GAAG,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,SAAS,CAAC,GAC3D,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,aAAa,CAAC,CAAC,CAAC;AAE1D,qBAAa,gBAAgB;IAC3B;;;;;;;;OAQG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,uBAA4B,GAAG,SAAS,SAAS,EAAE;CAuE3F"}

package/dist/PhysicsDebugDraw.js

@@ -1,18 +1,88 @@
 export class PhysicsDebugDraw {
-    buildLines(world) {
+    /**
+     * Build debug geometry for a world.
+     *
+     * WS-1.7 asks for colliders, contacts, normals, joints, sleeping state and raycasts. Only
+     * colliders existed, which is why the capability sat at "unproven with 0 consumers" — there was
+     * not enough here for a route to consume.
+     *
+     * Options default to off so the existing single-argument call keeps its previous output exactly.
+     */
+    buildLines(world, options = {}) {
         const lines = [];
+        const snapshot = options.contacts || options.sleeping ? world.snapshot?.() : undefined;
+        const sleepingIds = new Set();
+        if (options.sleeping && snapshot) {
+            for (const body of snapshot.bodies) {
+                if (body.sleeping)
+                    sleepingIds.add(body.id);
+            }
+        }
         for (const collider of world.colliders()) {
             const body = world.getBody(collider.bodyId);
             if (!body) {
                 continue;
             }
-            appendColliderLines(lines, collider, body.position);
+            appendColliderLines(lines, collider, body.position, sleepingIds.has(body.id));
+        }
+        if (options.contacts && snapshot) {
+            const normalLength = options.normalLength ?? 0.25;
+            for (const contact of snapshot.contacts) {
+                const point = contact.point;
+                if (!point)
+                    continue;
+                // A short cross at the contact point, then the normal as a ray out of it. Penetration is
+                // the number that matters for "is this body inside that one", so it tints the cross.
+                const penetrating = contact.penetration > 1e-4;
+                const crossColor = penetrating ? [1, 0.2, 0.2] : [0.2, 1, 0.4];
+                const size = normalLength * 0.25;
+                lines.push({ from: [point[0] - size, point[1], point[2]], to: [point[0] + size, point[1], point[2]], color: crossColor, category: "contact" });
+                lines.push({ from: [point[0], point[1] - size, point[2]], to: [point[0], point[1] + size, point[2]], color: crossColor, category: "contact" });
+                lines.push({
+                    from: point,
+                    to: [
+                        point[0] + contact.normal[0] * normalLength,
+                        point[1] + contact.normal[1] * normalLength,
+                        point[2] + contact.normal[2] * normalLength
+                    ],
+                    color: [1, 1, 0.3],
+                    category: "normal"
+                });
+            }
+        }
+        if (options.joints && world.constraints) {
+            for (const constraint of world.constraints()) {
+                const a = world.getBody(constraint.bodyA.id);
+                const b = world.getBody(constraint.bodyB.id);
+                if (!a || !b)
+                    continue;
+                // The segment between the two bodies a joint connects. A joint that has come apart is
+                // visible as a segment that keeps growing, which is exactly the failure mode that made
+                // the former silent backend divergence so hard to spot.
+                lines.push({ from: a.position, to: b.position, color: [0.9, 0.4, 1], category: "joint" });
+            }
+        }
+        for (const ray of options.raycasts ?? []) {
+            const length = Number.isFinite(ray.distance) ? ray.distance : 1;
+            lines.push({
+                from: ray.origin,
+                to: [
+                    ray.origin[0] + ray.direction[0] * length,
+                    ray.origin[1] + ray.direction[1] * length,
+                    ray.origin[2] + ray.direction[2] * length
+                ],
+                color: ray.hit ? [1, 0.35, 0.35] : [0.5, 0.5, 0.55],
+                category: "raycast"
+            });
         }
         return lines;
     }
 }
-function appendColliderLines(lines, collider, position) {
-    const color = collider.sensor ? [1, 0.75, 0] : [0.1, 0.8, 1];
+function appendColliderLines(lines, collider, position, sleeping = false) {
+    // Sleeping bodies are drawn dim: a body that has gone to sleep and should not have is otherwise
+    // indistinguishable from one that is simply not moving.
+    const color = sleeping ? [0.4, 0.42, 0.5] : collider.sensor ? [1, 0.75, 0] : [0.1, 0.8, 1];
+    const category = sleeping ? "sleeping" : collider.sensor ? "sensor" : "collider";
     if (collider.shape.kind === "box") {
         const h = collider.shape.halfExtents;
         const corners = [
@@ -27,24 +97,24 @@ function appendColliderLines(lines, collider, position) {
         ];
         const pairs = [[0, 1], [1, 2], [2, 3], [3, 0], [4, 5], [5, 6], [6, 7], [7, 4], [0, 4], [1, 5], [2, 6], [3, 7]];
         for (const [a, b] of pairs) {
-            lines.push({ from: corners[a], to: corners[b], color });
+            lines.push({ from: corners[a], to: corners[b], color, category });
         }
     }
     else if (collider.shape.kind === "sphere") {
         const r = collider.shape.radius;
-        lines.push({ from: [position[0] - r, position[1], position[2]], to: [position[0] + r, position[1], position[2]], color });
-        lines.push({ from: [position[0], position[1] - r, position[2]], to: [position[0], position[1] + r, position[2]], color });
-        lines.push({ from: [position[0], position[1], position[2] - r], to: [position[0], position[1], position[2] + r], color });
+        lines.push({ from: [position[0] - r, position[1], position[2]], to: [position[0] + r, position[1], position[2]], color, category });
+        lines.push({ from: [position[0], position[1] - r, position[2]], to: [position[0], position[1] + r, position[2]], color, category });
+        lines.push({ from: [position[0], position[1], position[2] - r], to: [position[0], position[1], position[2] + r], color, category });
     }
     else if (collider.shape.kind === "plane") {
-        lines.push({ from: [-10, position[1], 0], to: [10, position[1], 0], color });
-        lines.push({ from: [0, position[1], -10], to: [0, position[1], 10], color });
+        lines.push({ from: [-10, position[1], 0], to: [10, position[1], 0], color, category });
+        lines.push({ from: [0, position[1], -10], to: [0, position[1], 10], color, category });
     }
     else if (collider.shape.kind === "capsule") {
         const r = collider.shape.radius;
         const h = collider.shape.halfHeight;
-        lines.push({ from: [position[0], position[1] - h - r, position[2]], to: [position[0], position[1] + h + r, position[2]], color });
-        lines.push({ from: [position[0] - r, position[1], position[2]], to: [position[0] + r, position[1], position[2]], color });
+        lines.push({ from: [position[0], position[1] - h - r, position[2]], to: [position[0], position[1] + h + r, position[2]], color, category });
+        lines.push({ from: [position[0] - r, position[1], position[2]], to: [position[0] + r, position[1], position[2]], color, category });
     }
     else if (collider.shape.kind === "mesh" || collider.shape.kind === "convex-hull") {
         const { vertices, indices } = collider.shape;
@@ -52,9 +122,9 @@ function appendColliderLines(lines, collider, position) {
             const a = translate(vertices[indices[index]], position);
             const b = translate(vertices[indices[index + 1]], position);
             const c = translate(vertices[indices[index + 2]], position);
-            lines.push({ from: a, to: b, color });
-            lines.push({ from: b, to: c, color });
-            lines.push({ from: c, to: a, color });
+            lines.push({ from: a, to: b, color, category });
+            lines.push({ from: b, to: c, color, category });
+            lines.push({ from: c, to: a, color, category });
         }
     }
     else {
@@ -69,9 +139,9 @@ function appendColliderLines(lines, collider, position) {
         for (let row = 0; row < shape.rows; row += 1) {
             for (let column = 0; column < shape.columns; column += 1) {
                 if (column + 1 < shape.columns)
-                    lines.push({ from: sample(row, column), to: sample(row, column + 1), color });
+                    lines.push({ from: sample(row, column), to: sample(row, column + 1), color, category });
                 if (row + 1 < shape.rows)
-                    lines.push({ from: sample(row, column), to: sample(row + 1, column), color });
+                    lines.push({ from: sample(row, column), to: sample(row + 1, column), color, category });
             }
         }
     }