@adobe/data-gpu 0.9.87 → 0.9.88

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
@@ -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
                     }