@adobe/data-gpu 0.9.87 → 0.9.89

package/src/physics/solvers/jolt-solver-plugin.ts

@@ -2,6 +2,7 @@
 
 import initJolt from "jolt-physics";
 import { Database, type Entity } from "@adobe/data/ecs";
+import type { Line3, Vec3 } from "@adobe/data/math";
 import { isVoxelShapePhysicsPending } from "../is-voxel-shape-physics-pending.js";
 import { True } from "@adobe/data/schema";
 import { physicsClock } from "../physics-clock-plugin.js";
@@ -11,6 +12,10 @@ import { BodyType } from "../body/body-type/body-type.js";
 import { ColliderShape } from "../body/collider-shape/collider-shape.js";
 import type { ColliderMesh } from "../body/collider-mesh.js";
 import { massFromVolume } from "../body/collider-shape/mass-from-volume.js";
+import type { PhysicsQuery } from "../physics-query.js";
+import type { PhysicsHit } from "../physics-hit.js";
+import { orientNormalAgainstRay } from "./orient-normal-against-ray.js";
+import { newHit, type MutableHit } from "./mutable-hit.js";
 
 /**
  * A third rigid-body solver behind the same `physicsData` seam — Jolt Physics
@@ -61,6 +66,8 @@ type JQuat = InstanceType<JoltModule["Quat"]>;
 type JVec3 = InstanceType<JoltModule["Vec3"]>;
 type JShape = InstanceType<JoltModule["Shape"]>;
 type JPhysicsSystem = InstanceType<JoltModule["PhysicsSystem"]>;
+type JRayCastResult = InstanceType<JoltModule["RayCastResult"]>;
+type JShapeCastResult = InstanceType<JoltModule["ShapeCastResult"]>;
 
 interface MatProps { density: number; restitution: number; friction: number }
 
@@ -78,8 +85,8 @@ export interface JoltContext {
 export const joltSolver = Database.Plugin.create({
     extends: Database.Plugin.combine(physicsData, jointData, physicsClock),
     components: {
-        _joltBody: { ...True.schema, nonPersistent: true }, // tag: this body has been mirrored into the Jolt world
-        _joltJoint: { ...True.schema, nonPersistent: true }, // tag: this joint has been mirrored into the Jolt world
+        _joltBody: { ...True.schema, default: undefined, nonPersistent: true }, // tag: this body has been mirrored into the Jolt world
+        _joltJoint: { ...True.schema, default: undefined, nonPersistent: true }, // tag: this joint has been mirrored into the Jolt world
     },
     resources: {
         _joltContext: { default: null as JoltContext | null, nonPersistent: true },
@@ -210,6 +217,7 @@ export const joltSolver = Database.Plugin.create({
                         }
                     }
                     const body = bi.CreateBody(settings);
+                    body.SetUserData(id); // reverse lookup for ray-pick: hit body id → entity
                     bi.AddBody(body.GetID(), motion === "static" ? jolt.EActivation_DontActivate : jolt.EActivation_Activate);
                     if (motion === "dynamic" && (vx || vy || vz || wx || wy || wz)) {
                         const lv = new jolt.Vec3(vx, vy, vz), av = new jolt.Vec3(wx, wy, wz);
@@ -222,6 +230,116 @@ export const joltSolver = Database.Plugin.create({
                     if (half) jolt.destroy(half);
                 };
 
+                // Solver-agnostic ray-pick over the live Jolt world. As in the Rapier
+                // plugin, the segment vector (b − a) is the cast direction, so the hit
+                // fraction is the parametric α ∈ [0,1] along the segment directly
+                // (matching PhysicsHit). Accept-all filters + reusable settings are
+                // created once here; per-call WASM temporaries are freed after each pick.
+                const makeQuery = (jolt: JoltModule, ps: JPhysicsSystem, bi: JBodyInterface): PhysicsQuery => {
+                    const narrow = ps.GetNarrowPhaseQuery();
+                    const bpFilter = new jolt.BroadPhaseLayerFilter();
+                    const objFilter = new jolt.ObjectLayerFilter();
+                    const bodyFilter = new jolt.BodyFilter();
+                    const shapeFilter = new jolt.ShapeFilter();
+                    const raySettings = new jolt.RayCastSettings();
+                    const shapeSettings = new jolt.ShapeCastSettings();
+                    const baseOffset = new jolt.RVec3(0, 0, 0); // results in world space
+                    const unitScale = new jolt.Vec3(1, 1, 1);
+
+                    // Fill `out` from one ray result. Surface normal comes from the body
+                    // we already hold (no body-lock round-trip). Reads every field into JS
+                    // before any collector is destroyed. userData = entity id.
+                    const fillRay = (out: MutableHit, hit: JRayCastResult, a: Vec3, dx: number, dy: number, dz: number): void => {
+                        const alpha = hit.get_mFraction();
+                        const entity = bi.GetUserData(hit.get_mBodyID()) as Entity;
+                        out.entity = entity; out.distance = alpha;
+                        out.point[0] = a[0] + dx * alpha; out.point[1] = a[1] + dy * alpha; out.point[2] = a[2] + dz * alpha;
+                        out.normal[0] = 0; out.normal[1] = 0; out.normal[2] = 0;
+                        const body = bodies.get(entity);
+                        if (body) {
+                            const p = new jolt.RVec3(out.point[0], out.point[1], out.point[2]);
+                            const nv = body.GetWorldSpaceSurfaceNormal(hit.get_mSubShapeID2(), p);
+                            out.normal[0] = nv.GetX(); out.normal[1] = nv.GetY(); out.normal[2] = nv.GetZ();
+                            jolt.destroy(p);
+                        }
+                        orientNormalAgainstRay(out.normal, dx, dy, dz);
+                    };
+                    // Fill `out` from one swept-sphere result (contact point + penetration
+                    // axis; both world-space with baseOffset = 0).
+                    const fillShape = (out: MutableHit, hit: JShapeCastResult, dx: number, dy: number, dz: number): void => {
+                        const cp = hit.get_mContactPointOn2();
+                        out.entity = bi.GetUserData(hit.get_mBodyID2()) as Entity; out.distance = hit.get_mFraction();
+                        out.point[0] = cp.GetX(); out.point[1] = cp.GetY(); out.point[2] = cp.GetZ();
+                        const pax = hit.get_mPenetrationAxis();
+                        out.normal[0] = pax.GetX(); out.normal[1] = pax.GetY(); out.normal[2] = pax.GetZ();
+                        orientNormalAgainstRay(out.normal, dx, dy, dz);
+                    };
+
+                    const scratch = newHit(); // reused across castRayEach visits (zero-alloc)
+                    return {
+                        castRay(ray: Line3, options): PhysicsHit | null {
+                            const a = ray.a, b = ray.b;
+                            const dx = b[0] - a[0], dy = b[1] - a[1], dz = b[2] - a[2];
+                            const out = newHit();
+                            if ((options?.radius ?? 0) > 0) {
+                                // sphere of `radius` swept along the segment
+                                const shape = new jolt.SphereShape(options!.radius!);
+                                const startPos = new jolt.RVec3(a[0], a[1], a[2]);
+                                const comStart = jolt.RMat44.prototype.sTranslation(startPos);
+                                const dir = new jolt.Vec3(dx, dy, dz);
+                                const shapeCast = new jolt.RShapeCast(shape, unitScale, comStart, dir);
+                                const collector = new jolt.CastShapeClosestHitCollisionCollector();
+                                narrow.CastShape(shapeCast, shapeSettings, baseOffset, collector, bpFilter, objFilter, bodyFilter, shapeFilter);
+                                const hadHit = collector.HadHit();
+                                if (hadHit) fillShape(out, collector.mHit, dx, dy, dz);
+                                jolt.destroy(shape); jolt.destroy(startPos); jolt.destroy(comStart); jolt.destroy(dir); jolt.destroy(shapeCast); jolt.destroy(collector);
+                                return hadHit ? out : null;
+                            }
+                            const origin = new jolt.RVec3(a[0], a[1], a[2]);
+                            const dir = new jolt.Vec3(dx, dy, dz);
+                            const rc = new jolt.RRayCast(origin, dir);
+                            const collector = new jolt.CastRayClosestHitCollisionCollector();
+                            narrow.CastRay(rc, raySettings, collector, bpFilter, objFilter, bodyFilter, shapeFilter);
+                            const hadHit = collector.HadHit();
+                            if (hadHit) fillRay(out, collector.mHit, a, dx, dy, dz);
+                            jolt.destroy(origin); jolt.destroy(dir); jolt.destroy(rc); jolt.destroy(collector);
+                            return hadHit ? out : null;
+                        },
+                        castRayEach(ray: Line3, visit, options): void {
+                            const a = ray.a, b = ray.b;
+                            const dx = b[0] - a[0], dy = b[1] - a[1], dz = b[2] - a[2];
+                            if ((options?.radius ?? 0) > 0) {
+                                // Jolt has a native swept-sphere all-hits query.
+                                const shape = new jolt.SphereShape(options!.radius!);
+                                const startPos = new jolt.RVec3(a[0], a[1], a[2]);
+                                const comStart = jolt.RMat44.prototype.sTranslation(startPos);
+                                const dir = new jolt.Vec3(dx, dy, dz);
+                                const shapeCast = new jolt.RShapeCast(shape, unitScale, comStart, dir);
+                                const collector = new jolt.CastShapeAllHitCollisionCollector();
+                                narrow.CastShape(shapeCast, shapeSettings, baseOffset, collector, bpFilter, objFilter, bodyFilter, shapeFilter);
+                                if (collector.HadHit()) {
+                                    collector.Sort(); // near→far
+                                    const hits = collector.get_mHits();
+                                    for (let i = 0, len = hits.size(); i < len; i++) { fillShape(scratch, hits.at(i), dx, dy, dz); if (visit(scratch) === false) break; }
+                                }
+                                jolt.destroy(shape); jolt.destroy(startPos); jolt.destroy(comStart); jolt.destroy(dir); jolt.destroy(shapeCast); jolt.destroy(collector);
+                                return;
+                            }
+                            const origin = new jolt.RVec3(a[0], a[1], a[2]);
+                            const dir = new jolt.Vec3(dx, dy, dz);
+                            const rc = new jolt.RRayCast(origin, dir);
+                            const collector = new jolt.CastRayAllHitCollisionCollector();
+                            narrow.CastRay(rc, raySettings, collector, bpFilter, objFilter, bodyFilter, shapeFilter);
+                            if (collector.HadHit()) {
+                                collector.Sort(); // near→far
+                                const hits = collector.get_mHits();
+                                for (let i = 0, len = hits.size(); i < len; i++) { fillRay(scratch, hits.at(i), a, dx, dy, dz); if (visit(scratch) === false) break; }
+                            }
+                            jolt.destroy(origin); jolt.destroy(dir); jolt.destroy(rc); jolt.destroy(collector);
+                        },
+                    };
+                };
+
                 return () => {
                     if (!J || !bodyInterface || !joltInterface) {
                         if (!initStarted) {
@@ -229,6 +347,7 @@ export const joltSolver = Database.Plugin.create({
                             initJolt().then((j: JoltModule) => {
                                 J = j; setup(j);
                                 db.store.resources._joltContext = { jolt: j, physicsSystem: physicsSystem!, bodyInterface: bodyInterface!, ragdollLayer: L_RAGDOLL };
+                                db.store.resources.physicsQuery = makeQuery(j, physicsSystem!, bodyInterface!);
                             });
                         }
                         return; // WASM not ready yet

package/src/physics/solvers/mutable-hit.ts

@@ -0,0 +1,18 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Entity } from "@adobe/data/ecs";
+
+/**
+ * Internal mutable form of `PhysicsHit` used by the solver query
+ * implementations. `castRay` fills a fresh one (retainable return value);
+ * `castRayEach` fills and re-visits a single reused instance (zero-alloc).
+ * Assignable to the public read-only `PhysicsHit` at the seam.
+ */
+export interface MutableHit {
+    entity: Entity;
+    distance: number;
+    point: [number, number, number];
+    normal: [number, number, number];
+}
+
+export const newHit = (): MutableHit => ({ entity: 0 as Entity, distance: 0, point: [0, 0, 0], normal: [0, 0, 0] });

package/src/physics/solvers/orient-normal-against-ray.test.ts

@@ -0,0 +1,31 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect } from "vitest";
+import { orientNormalAgainstRay } from "./orient-normal-against-ray.js";
+
+describe("orientNormalAgainstRay", () => {
+    it("normalizes the normal to unit length", () => {
+        const n: [number, number, number] = [0, 3, 0];
+        orientNormalAgainstRay(n, 1, 0, 0); // ray perpendicular → no flip
+        expect(Math.hypot(...n)).toBeCloseTo(1, 6);
+        expect(n[1]).toBeCloseTo(1, 6);
+    });
+
+    it("flips a normal that points along the ray so it opposes it", () => {
+        const n: [number, number, number] = [0, -1, 0]; // points down, same as a downward ray
+        orientNormalAgainstRay(n, 0, -20, 0);            // downward ray
+        expect(n[1]).toBeGreaterThan(0);                 // now points up, opposing the ray
+    });
+
+    it("leaves a normal that already opposes the ray unchanged in direction", () => {
+        const n: [number, number, number] = [0, 1, 0];
+        orientNormalAgainstRay(n, 0, -20, 0);
+        expect(n[1]).toBeCloseTo(1, 6);
+    });
+
+    it("leaves a zero-length normal as the zero vector (no divide-by-zero)", () => {
+        const n: [number, number, number] = [0, 0, 0];
+        orientNormalAgainstRay(n, 0, -1, 0);
+        expect(n).toEqual([0, 0, 0]);
+    });
+});

package/src/physics/solvers/orient-normal-against-ray.ts

@@ -0,0 +1,18 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * Normalize `n` in place and flip it so it opposes the ray direction
+ * `(dx,dy,dz)` — the standard picking convention (the returned normal points
+ * back toward the ray origin, i.e. outward from the hit surface).
+ *
+ * Unifies the normal convention across engines and across ray-cast vs.
+ * shape-cast, whose raw normals (surface normal, contact normal, penetration
+ * axis) don't otherwise agree on sign. A zero-length input is left as the zero
+ * vector (guarded so a degenerate hit doesn't divide by zero).
+ */
+export const orientNormalAgainstRay = (n: [number, number, number], dx: number, dy: number, dz: number): void => {
+    const len = Math.hypot(n[0], n[1], n[2]);
+    if (len === 0) return;
+    n[0] /= len; n[1] /= len; n[2] /= len;
+    if (n[0] * dx + n[1] * dy + n[2] * dz > 0) { n[0] = -n[0]; n[1] = -n[1]; n[2] = -n[2]; }
+};

package/src/physics/solvers/pick-ray-conformance.test.ts

@@ -0,0 +1,200 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect, beforeAll } from "vitest";
+import { Database } from "@adobe/data/ecs";
+import type { Line3 } from "@adobe/data/math";
+import { rapierSolver } from "./rapier-solver-plugin.js";
+import { joltSolver } from "./jolt-solver-plugin.js";
+import type { PhysicsHit } from "../physics-hit.js";
+
+/**
+ * Abstract picking conformance suite: the SAME expected outcomes are asserted
+ * against every solver behind the `physicsData` seam. Building a fixed static
+ * scene and running identical `pickRay` calls proves both engines fulfil the
+ * `PhysicsQuery` contract interchangeably (entity, parametric α, hit point,
+ * and a ray-opposing normal), including the with/without-radius variants.
+ *
+ *   npx vitest --run src/physics/solvers/pick-ray-conformance.test.ts
+ */
+
+// The solver plugin extends `physicsData`, so the StaticCollider archetype, the
+// `frameTime` resource, and the `pickRay` action all exist on the created db.
+// The scene is driven dynamically, so the db is used through a loose shape
+// (runtime invariant: these members exist on any physicsData solver).
+interface LooseDb {
+    store: {
+        archetypes: Record<string, { insert(v: unknown): number }>;
+        resources: Record<string, unknown>;
+    };
+    system: { functions: Record<string, () => unknown>; order?: string[][] };
+    actions: {
+        pickRay(args: { ray: Line3; radius?: number }): PhysicsHit | null;
+        pickRayEach(args: { ray: Line3; visit: (hit: PhysicsHit) => boolean | void; radius?: number }): void;
+    };
+}
+
+const yieldToEventLoop = () => new Promise<void>(r => setTimeout(r, 0));
+
+interface Scene { db: LooseDb; floor: number; ball: number; box: number }
+
+// Build a fixed scene of static colliders and drive the sim until the solver's
+// WASM world is live, the bodies are mirrored, and the query pipeline is
+// populated (both engines need at least one step for that). Picks are read-only,
+// so one scene is shared across all cases for a solver.
+async function buildScene(solver: Database.Plugin): Promise<Scene> {
+    const db = Database.create(solver) as unknown as LooseDb;
+
+    // Floor: wide thick box, top face at y = 0.
+    const floor = db.store.archetypes.StaticCollider.insert({
+        colliderShape: "box", halfExtents: [10, 1, 10], material: 0,
+        position: [0, -1, 0], rotation: [0, 0, 0, 1],
+    });
+    // Sphere radius 1 centred at (0, 3, 0) → top at y = 4.
+    const ball = db.store.archetypes.StaticCollider.insert({
+        colliderShape: "sphere", halfExtents: [1, 0, 0], material: 0,
+        position: [0, 3, 0], rotation: [0, 0, 0, 1],
+    });
+    // Unit box centred at (5, 3, 0) → top at y = 4, off to the side.
+    const box = db.store.archetypes.StaticCollider.insert({
+        colliderShape: "box", halfExtents: [1, 1, 1], material: 0,
+        position: [5, 3, 0], rotation: [0, 0, 0, 1],
+    });
+
+    const order = db.system.order;
+    const names = order ? order.flat() : Object.keys(db.system.functions);
+    const runNames = names.filter(n => n !== "_frameTime" && n !== "schedulerSystem");
+    const dt = 1 / 60;
+    const tick = (f: number): void => {
+        db.store.resources.frameTime = { now: f * dt * 1000, dt, elapsed: f * dt };
+        for (const n of runNames) { const fn = db.system.functions[n]; if (fn) fn(); }
+    };
+
+    // Drive until the solver publishes its query, then a few more steps so the
+    // bodies are mirrored and the broad/narrow phase is populated.
+    let f = 0;
+    for (; f < 300 && db.store.resources.physicsQuery == null; f++) { tick(f); await yieldToEventLoop(); }
+    for (let k = 0; k < 30; k++, f++) { tick(f); await yieldToEventLoop(); }
+
+    return { db, floor, ball, box };
+}
+
+function describePicking(name: string, solver: Database.Plugin): void {
+    describe(`pickRay conformance — ${name}`, () => {
+        let scene: Scene;
+        beforeAll(async () => { scene = await buildScene(solver); }, 60_000);
+
+        it("publishes a physicsQuery once the world is live", () => {
+            expect((scene.db.store.resources as { physicsQuery: unknown }).physicsQuery).not.toBeNull();
+        });
+
+        it("hits the sphere with a ray straight down through its centre", () => {
+            // segment y: 10 → −10 (span 20); sphere top at y = 4 ⇒ α = (10 − 4) / 20 = 0.3
+            const ray: Line3 = { a: [0, 10, 0], b: [0, -10, 0] };
+            const hit = scene.db.actions.pickRay({ ray });
+            expect(hit).not.toBeNull();
+            expect(hit!.entity).toBe(scene.ball);
+            expect(hit!.distance).toBeCloseTo(0.3, 1);
+            expect(hit!.point[1]).toBeCloseTo(4, 1);
+            // ray points down, so the surface normal points up (opposes the ray)
+            expect(hit!.normal[1]).toBeGreaterThan(0.5);
+        });
+
+        it("hits the box off to the side", () => {
+            const ray: Line3 = { a: [5, 10, 0], b: [5, -10, 0] };
+            const hit = scene.db.actions.pickRay({ ray });
+            expect(hit).not.toBeNull();
+            expect(hit!.entity).toBe(scene.box);
+            expect(hit!.point[1]).toBeCloseTo(4, 1); // box top face
+            expect(hit!.normal[1]).toBeGreaterThan(0.5);
+        });
+
+        it("returns the nearest collider when several lie along the ray", () => {
+            // straight down through the centre passes the sphere (top y = 4) before
+            // the floor (top y = 0) → the nearer sphere wins
+            const hit = scene.db.actions.pickRay({ ray: { a: [0, 10, 0], b: [0, -10, 0] } });
+            expect(hit!.entity).toBe(scene.ball);
+        });
+
+        it("returns null when the ray misses every collider", () => {
+            const ray: Line3 = { a: [100, 10, 100], b: [100, -10, 100] };
+            expect(scene.db.actions.pickRay({ ray })).toBeNull();
+        });
+
+        it("with/without radius: a grazing ray misses as a line but hits as a thick ray", () => {
+            // Short segment offset 1.4 in x from the sphere centre, kept above the
+            // floor (y: 5 → 2.5). As a thin line it clears the sphere (1.4 > radius 1)
+            // and never reaches the floor → miss. A 0.5-radius sweep has effective
+            // reach 1.5 > 1.4 → it grazes the sphere.
+            const ray: Line3 = { a: [1.4, 5, 0], b: [1.4, 2.5, 0] };
+            expect(scene.db.actions.pickRay({ ray })).toBeNull();
+
+            const hit = scene.db.actions.pickRay({ ray, radius: 0.5 });
+            expect(hit).not.toBeNull();
+            expect(hit!.entity).toBe(scene.ball);
+            expect(hit!.distance).toBeGreaterThanOrEqual(0);
+            expect(hit!.distance).toBeLessThanOrEqual(1);
+        });
+
+        it("castRayEach visits every collider along the ray, nearest first", () => {
+            // straight down at x = 0 crosses the sphere (top y = 4, α = 0.3) then the
+            // floor (top y = 0, α = 0.5); the box at x = 5 is not on the ray
+            const seen: number[] = [];
+            const dists: number[] = [];
+            scene.db.actions.pickRayEach({
+                ray: { a: [0, 10, 0], b: [0, -10, 0] },
+                visit: (h) => { seen.push(h.entity); dists.push(h.distance); },
+            });
+            expect(seen).toEqual([scene.ball, scene.floor]);
+            expect(dists).toEqual([...dists].sort((x, y) => x - y)); // ascending
+        });
+
+        it("castRayEach stops early when visit returns false", () => {
+            const seen: number[] = [];
+            scene.db.actions.pickRayEach({
+                ray: { a: [0, 10, 0], b: [0, -10, 0] },
+                visit: (h) => { seen.push(h.entity); return false; }, // stop after the nearest
+            });
+            expect(seen).toEqual([scene.ball]);
+        });
+
+        it("castRayEach visits nothing when the ray misses everything", () => {
+            let count = 0;
+            scene.db.actions.pickRayEach({
+                ray: { a: [100, 10, 100], b: [100, -10, 100] },
+                visit: () => { count++; },
+            });
+            expect(count).toBe(0);
+        });
+
+        it("castRayEach with radius visits at least the nearest swept hit on every solver", () => {
+            // The Rapier compat binding can't sweep-all, so radius degrades to the
+            // nearest there; Jolt returns all. Both must at least visit the nearest.
+            const seen: number[] = [];
+            scene.db.actions.pickRayEach({
+                ray: { a: [1.4, 5, 0], b: [1.4, 2.5, 0] },
+                radius: 0.5,
+                visit: (h) => { seen.push(h.entity); },
+            });
+            expect(seen.length).toBeGreaterThanOrEqual(1);
+            expect(seen[0]).toBe(scene.ball);
+        });
+
+        it("castRayEach reuses a single hit instance across visits (zero-alloc contract)", () => {
+            const refs: PhysicsHit[] = [];
+            scene.db.actions.pickRayEach({ ray: { a: [0, 10, 0], b: [0, -10, 0] }, visit: (h) => { refs.push(h); } });
+            expect(refs.length).toBe(2);
+            expect(refs[0]).toBe(refs[1]); // same object, refilled per visit — do not retain
+        });
+
+        it("castRay returns fresh, independent hits (safe to retain)", () => {
+            const h1 = scene.db.actions.pickRay({ ray: { a: [0, 10, 0], b: [0, -10, 0] } });
+            const h2 = scene.db.actions.pickRay({ ray: { a: [5, 10, 0], b: [5, -10, 0] } });
+            expect(h1).not.toBe(h2);
+            expect(h1!.entity).toBe(scene.ball); // unaffected by the second pick
+            expect(h2!.entity).toBe(scene.box);
+        });
+    });
+}
+
+describePicking("rapierSolver", rapierSolver);
+describePicking("joltSolver", joltSolver);

package/src/physics/solvers/rapier-solver-plugin.ts

@@ -2,6 +2,7 @@
 
 import RAPIER from "@dimforge/rapier3d-compat";
 import { Database, type Entity } from "@adobe/data/ecs";
+import type { Line3, Vec3 } from "@adobe/data/math";
 import { isVoxelShapePhysicsPending } from "../is-voxel-shape-physics-pending.js";
 import { True } from "@adobe/data/schema";
 import { physicsClock } from "../physics-clock-plugin.js";
@@ -9,6 +10,10 @@ import { physicsData } from "../physics-data-plugin.js";
 import { jointData } from "../joint/joint-plugin.js";
 import { BodyType } from "../body/body-type/body-type.js";
 import { ColliderShape } from "../body/collider-shape/collider-shape.js";
+import type { PhysicsQuery } from "../physics-query.js";
+import type { PhysicsHit } from "../physics-hit.js";
+import { orientNormalAgainstRay } from "./orient-normal-against-ray.js";
+import { newHit, type MutableHit } from "./mutable-hit.js";
 
 /**
  * A second rigid-body solver behind the same `physicsData` seam — the
@@ -48,8 +53,8 @@ interface MatProps { density: number; restitution: number; friction: number }
 export const rapierSolver = Database.Plugin.create({
     extends: Database.Plugin.combine(physicsData, jointData, physicsClock),
     components: {
-        _rapierBody: { ...True.schema, nonPersistent: true }, // tag: this body has been mirrored into the Rapier world
-        _rapierJoint: { ...True.schema, nonPersistent: true }, // tag: this joint has been mirrored into the Rapier world
+        _rapierBody: { ...True.schema, default: undefined, nonPersistent: true }, // tag: this body has been mirrored into the Rapier world
+        _rapierJoint: { ...True.schema, default: undefined, nonPersistent: true }, // tag: this joint has been mirrored into the Rapier world
     },
     systems: {
         rapierStep: {
@@ -84,6 +89,7 @@ export const rapierSolver = Database.Plugin.create({
                     desc.setTranslation(px, py, pz).setRotation({ x: q[0], y: q[1], z: q[2], w: q[3] });
                     if (motion === "dynamic") { desc.setLinvel(vx, vy, vz); desc.setAngvel({ x: wx, y: wy, z: wz }); }
                     const body = world.createRigidBody(desc);
+                    body.userData = id; // reverse lookup for ray-pick: collider → parent body → entity
                     // capsule: Y-aligned, halfHeight = cylinder half (hy), radius = hx.
                     // hull: convex hull of the authored point cloud (read once here).
                     let col: RAPIER.ColliderDesc | null;
@@ -107,11 +113,96 @@ export const rapierSolver = Database.Plugin.create({
                     bodies.set(id, body);
                 };
 
+                // Solver-agnostic ray-pick over the live Rapier world. Passing the
+                // segment vector (b − a) as the ray/shape-cast direction and capping
+                // the time-of-impact at 1 makes the returned toi the parametric α ∈
+                // [0,1] along the segment directly (matching PhysicsHit's convention).
+                const makeQuery = (w: RAPIER.World): PhysicsQuery => {
+                    // Fill `out` with a thin-ray hit. userData was set to the entity id
+                    // when the body was mirrored. Normal is oriented to oppose the ray.
+                    const fillRay = (out: MutableHit, entity: Entity, alpha: number, nx: number, ny: number, nz: number, a: Vec3, dx: number, dy: number, dz: number): void => {
+                        out.entity = entity; out.distance = alpha;
+                        out.point[0] = a[0] + dx * alpha; out.point[1] = a[1] + dy * alpha; out.point[2] = a[2] + dz * alpha;
+                        out.normal[0] = nx; out.normal[1] = ny; out.normal[2] = nz;
+                        orientNormalAgainstRay(out.normal, dx, dy, dz);
+                    };
+                    const nearest = (ray: Line3, options?: { radius?: number }): PhysicsHit | null => {
+                        const a = ray.a, b = ray.b;
+                        const dx = b[0] - a[0], dy = b[1] - a[1], dz = b[2] - a[2];
+                        const radius = options?.radius ?? 0;
+                        const out = newHit();
+                        if (radius > 0) {
+                            // sphere of `radius` swept along the segment
+                            const hit = w.castShape(
+                                { x: a[0], y: a[1], z: a[2] }, { x: 0, y: 0, z: 0, w: 1 }, { x: dx, y: dy, z: dz },
+                                new RAPIER.Ball(radius), 0, 1, true,
+                            );
+                            if (!hit) return null;
+                            const bod = hit.collider.parent();
+                            if (!bod) return null;
+                            const alpha = hit.time_of_impact;
+                            out.entity = bod.userData as Entity; out.distance = alpha;
+                            out.normal[0] = hit.normal1.x; out.normal[1] = hit.normal1.y; out.normal[2] = hit.normal1.z;
+                            orientNormalAgainstRay(out.normal, dx, dy, dz);
+                            // pull the swept-sphere centre at impact back onto the collider surface
+                            out.point[0] = a[0] + dx * alpha - out.normal[0] * radius;
+                            out.point[1] = a[1] + dy * alpha - out.normal[1] * radius;
+                            out.point[2] = a[2] + dz * alpha - out.normal[2] * radius;
+                            return out;
+                        }
+                        const hit = w.castRayAndGetNormal(new RAPIER.Ray({ x: a[0], y: a[1], z: a[2] }, { x: dx, y: dy, z: dz }), 1, true);
+                        if (!hit) return null;
+                        const bod = hit.collider.parent();
+                        if (!bod) return null;
+                        fillRay(out, bod.userData as Entity, hit.timeOfImpact, hit.normal.x, hit.normal.y, hit.normal.z, a, dx, dy, dz);
+                        return out;
+                    };
+                    // Zero-alloc scratch for castRayEach: one reused hit + a grow-only pool
+                    // of records. intersectionsWithRay reports crossings in broadphase-
+                    // arbitrary order, so records are collected then index-sorted near→far.
+                    const scratch = newHit();
+                    const pool: { entity: Entity; distance: number; nx: number; ny: number; nz: number }[] = [];
+                    const order: number[] = [];
+                    return {
+                        castRay: nearest,
+                        castRayEach(ray: Line3, visit, options): void {
+                            // The compat binding has no swept-shape all-hits query, so a
+                            // radius query degrades to the nearest hit (see PhysicsQuery).
+                            if ((options?.radius ?? 0) > 0) { const h = nearest(ray, options); if (h) visit(h); return; }
+                            const a = ray.a, b = ray.b;
+                            const dx = b[0] - a[0], dy = b[1] - a[1], dz = b[2] - a[2];
+                            let count = 0;
+                            w.intersectionsWithRay(new RAPIER.Ray({ x: a[0], y: a[1], z: a[2] }, { x: dx, y: dy, z: dz }), 1, true, (isect: RAPIER.RayColliderIntersection) => {
+                                const bod = isect.collider.parent();
+                                if (bod) {
+                                    let rec = pool[count];
+                                    if (!rec) { rec = { entity: 0 as Entity, distance: 0, nx: 0, ny: 0, nz: 0 }; pool[count] = rec; }
+                                    rec.entity = bod.userData as Entity; rec.distance = isect.timeOfImpact;
+                                    rec.nx = isect.normal.x; rec.ny = isect.normal.y; rec.nz = isect.normal.z;
+                                    count++;
+                                }
+                                return true; // keep collecting
+                            });
+                            for (let i = 0; i < count; i++) order[i] = i;
+                            order.length = count;
+                            order.sort((i, j) => pool[i].distance - pool[j].distance);
+                            for (let k = 0; k < count; k++) {
+                                const rec = pool[order[k]];
+                                fillRay(scratch, rec.entity, rec.distance, rec.nx, rec.ny, rec.nz, a, dx, dy, dz);
+                                if (visit(scratch) === false) break;
+                            }
+                        },
+                    };
+                };
+
                 return () => {
                     if (!world) {
                         if (!initStarted) {
                             initStarted = true;
-                            RAPIER.init().then(() => { world = new RAPIER.World({ x: 0, y: -GRAVITY, z: 0 }); });
+                            RAPIER.init().then(() => {
+                                world = new RAPIER.World({ x: 0, y: -GRAVITY, z: 0 });
+                                db.store.resources.physicsQuery = makeQuery(world);
+                            });
                         }
                         return; // WASM not ready yet
                     }