@woosh/meep-engine 2.139.0 → 2.140.0

package/src/engine/physics/narrowphase/sphere_box_contact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sphere_box_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_box_contact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wCAjBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,UACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,OAAO,CA+FnB"}
+{"version":3,"file":"sphere_box_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_box_contact.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wCAjBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,UACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,OAAO,CA8EnB"}

package/src/engine/physics/narrowphase/sphere_box_contact.js

@@ -1,3 +1,13 @@
+import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
+import { v3_quat3_apply_inverse } from "../../../core/geom/vec3/v3_quat3_apply_inverse.js";
+
+/**
+ * Scratch for the world→box-local rotation of the sphere centre at the
+ * top of {@link sphere_box_contact}. 3 floats; allocation-free.
+ * @type {Float64Array}
+ */
+const scratch_local = new Float64Array(3);
+
 /**
  * Closed-form contact generation for a unit sphere vs. an oriented box.
  *
@@ -43,18 +53,10 @@ export function sphere_box_contact(
 ) {
     // Step 1: bring the sphere centre into box-local space via the conjugate
     // quaternion. v_local = q* · (s - b) · q
-    const dx = sx - bx, dy = sy - by, dz = sz - bz;
-
-    // Apply conjugate (-qx,-qy,-qz, qw) to (dx,dy,dz,0):
-    const cx = -bqx, cy = -bqy, cz = -bqz;
-    const tx0 = bqw * dx + cy * dz - cz * dy;
-    const ty0 = bqw * dy + cz * dx - cx * dz;
-    const tz0 = bqw * dz + cx * dy - cy * dx;
-    const tw0 = -cx * dx - cy * dy - cz * dz;
-    // Then multiply by c* = (qx,qy,qz,qw) (the original quaternion):
-    const lx = tx0 * bqw + tw0 * bqx + ty0 * bqz - tz0 * bqy;
-    const ly = ty0 * bqw + tw0 * bqy + tz0 * bqx - tx0 * bqz;
-    const lz = tz0 * bqw + tw0 * bqz + tx0 * bqy - ty0 * bqx;
+    v3_quat3_apply_inverse(scratch_local, 0, sx - bx, sy - by, sz - bz, bqx, bqy, bqz, bqw);
+    const lx = scratch_local[0];
+    const ly = scratch_local[1];
+    const lz = scratch_local[2];
 
     // Step 2: closest point on the box to the sphere centre, in body frame.
     const clx = lx < -hx ? -hx : (lx > hx ? hx : lx);
@@ -100,18 +102,9 @@ export function sphere_box_contact(
     }
 
     // Step 3: rotate normal and surface point back to world. v_world = q · v · q*
-    function rotate_to_world(out_arr, off, vx, vy, vz) {
-        const ix = bqw * vx + bqy * vz - bqz * vy;
-        const iy = bqw * vy + bqz * vx - bqx * vz;
-        const iz = bqw * vz + bqx * vy - bqy * vx;
-        const iw = -bqx * vx - bqy * vy - bqz * vz;
-        out_arr[off]     = ix * bqw + iw * (-bqx) + iy * (-bqz) - iz * (-bqy);
-        out_arr[off + 1] = iy * bqw + iw * (-bqy) + iz * (-bqx) - ix * (-bqz);
-        out_arr[off + 2] = iz * bqw + iw * (-bqz) + ix * (-bqy) - iy * (-bqx);
-    }
 
     // World normal (box → sphere).
-    rotate_to_world(out, 0, nlx, nly, nlz);
+    v3_quat3_apply(out, 0, nlx, nly, nlz, bqx, bqy, bqz, bqw);
     const nx = out[0], ny = out[1], nz = out[2];
     out[3] = radius - dist;
 
@@ -121,7 +114,7 @@ export function sphere_box_contact(
     out[6] = sz - nz * radius;
 
     // World contact on box: rotate the local-space clamped point to world, plus box centre.
-    rotate_to_world(out, 7, clx, cly, clz);
+    v3_quat3_apply(out, 7, clx, cly, clz, bqx, bqy, bqz, bqw);
     out[7] += bx;
     out[8] += by;
     out[9] += bz;

package/src/engine/physics/narrowphase/sphere_triangle_contact.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Closed-form contact generation for a sphere vs. a triangle.
+ *
+ * Algorithm: find the closest point on the triangle to the sphere centre
+ * via Ericson barycentric voronoi-region projection, then compare the
+ * distance to the sphere radius. The result is closed-form, exact for
+ * the geometric primitives involved, and avoids the precision wall that
+ * GJK+EPA hits on {@link Triangle3D} — whose support function is
+ * degenerate along the face normal (all 3 vertices project to the same
+ * value) and produces noisy depths at small penetrations.
+ *
+ * Sphere-vs-triangle is the building block for sphere-vs-concave
+ * (mesh, heightmap) narrowphase: the concave dispatch in
+ * {@link narrowphase_step} decomposes the concave shape into world-space
+ * triangles and runs this function per triangle.
+ *
+ * Output convention (mirrors {@link sphere_box_contact} and
+ * {@link sphere_sphere_contact}): the normal in `out[0..2]` points
+ * from the triangle's surface toward the sphere centre — i.e. the
+ * direction the sphere should be pushed to separate; `out[3]` is the
+ * positive penetration depth; `out[4..6]` is the world contact on
+ * the sphere's surface; `out[7..9]` is the world contact on the
+ * triangle's surface (the closest point).
+ *
+ * Singular case: when the sphere centre lies exactly on the triangle's
+ * plane (distance == 0), the normal direction is geometrically undefined.
+ * We fall back to the triangle's face normal (CCW winding), which is the
+ * direction the surrounding solid is "outward" from for closed meshes
+ * and heightmaps.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @param {number} sx sphere centre x (world)
+ * @param {number} sy
+ * @param {number} sz
+ * @param {number} radius
+ * @param {number} ax triangle vertex A x (world)
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx triangle vertex B x (world)
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} cx triangle vertex C x (world)
+ * @param {number} cy
+ * @param {number} cz
+ * @returns {boolean} true if sphere overlaps the triangle
+ */
+export function sphere_triangle_contact(out: number[] | Float64Array, sx: number, sy: number, sz: number, radius: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number): boolean;
+//# sourceMappingURL=sphere_triangle_contact.d.ts.map

package/src/engine/physics/narrowphase/sphere_triangle_contact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sphere_triangle_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_triangle_contact.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,6CAhBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,UACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,OAAO,CAwFnB"}

package/src/engine/physics/narrowphase/sphere_triangle_contact.js

@@ -0,0 +1,143 @@
+import { computeTriangleClosestPointToPointBarycentric } from "../../../core/geom/3d/triangle/computeTriangleClosestPointToPointBarycentric.js";
+
+/**
+ * Closest-point on triangle, written into the first two floats of `out`
+ * as `(alpha_A, alpha_B)` — `alpha_C = 1 - alpha_A - alpha_B`. Reused
+ * across the {@link sphere_triangle_contact} body to avoid allocation.
+ * @type {Float64Array}
+ */
+const scratch_bary = new Float64Array(2);
+
+/**
+ * Closed-form contact generation for a sphere vs. a triangle.
+ *
+ * Algorithm: find the closest point on the triangle to the sphere centre
+ * via Ericson barycentric voronoi-region projection, then compare the
+ * distance to the sphere radius. The result is closed-form, exact for
+ * the geometric primitives involved, and avoids the precision wall that
+ * GJK+EPA hits on {@link Triangle3D} — whose support function is
+ * degenerate along the face normal (all 3 vertices project to the same
+ * value) and produces noisy depths at small penetrations.
+ *
+ * Sphere-vs-triangle is the building block for sphere-vs-concave
+ * (mesh, heightmap) narrowphase: the concave dispatch in
+ * {@link narrowphase_step} decomposes the concave shape into world-space
+ * triangles and runs this function per triangle.
+ *
+ * Output convention (mirrors {@link sphere_box_contact} and
+ * {@link sphere_sphere_contact}): the normal in `out[0..2]` points
+ * from the triangle's surface toward the sphere centre — i.e. the
+ * direction the sphere should be pushed to separate; `out[3]` is the
+ * positive penetration depth; `out[4..6]` is the world contact on
+ * the sphere's surface; `out[7..9]` is the world contact on the
+ * triangle's surface (the closest point).
+ *
+ * Singular case: when the sphere centre lies exactly on the triangle's
+ * plane (distance == 0), the normal direction is geometrically undefined.
+ * We fall back to the triangle's face normal (CCW winding), which is the
+ * direction the surrounding solid is "outward" from for closed meshes
+ * and heightmaps.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @param {number} sx sphere centre x (world)
+ * @param {number} sy
+ * @param {number} sz
+ * @param {number} radius
+ * @param {number} ax triangle vertex A x (world)
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx triangle vertex B x (world)
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} cx triangle vertex C x (world)
+ * @param {number} cy
+ * @param {number} cz
+ * @returns {boolean} true if sphere overlaps the triangle
+ */
+export function sphere_triangle_contact(
+    out,
+    sx, sy, sz, radius,
+    ax, ay, az,
+    bx, by, bz,
+    cx, cy, cz
+) {
+    // Degenerate-triangle guard. For zero-area triangles (colinear or
+    // duplicate vertices) the closest-point algorithm still returns
+    // a point on the degenerate "line" but the surrounding geometry
+    // has no meaningful face — emitting a contact would mislead the
+    // solver. Catch this upfront via the face-normal cross product;
+    // the same magnitude is reused for the dist=0 fallback below.
+    //
+    // Cost: 9 flops + 1 sqrt. Negligible vs. the rest of the function
+    // and saves the caller from having to pre-filter its input.
+    const e1x = bx - ax, e1y = by - ay, e1z = bz - az;
+    const e2x = cx - ax, e2y = cy - ay, e2z = cz - az;
+    const fnx = e1y * e2z - e1z * e2y;
+    const fny = e1z * e2x - e1x * e2z;
+    const fnz = e1x * e2y - e1y * e2x;
+    const fn_mag_sqr = fnx * fnx + fny * fny + fnz * fnz;
+    if (fn_mag_sqr === 0) return false;
+
+    // Closest-point on triangle to sphere centre — barycentric output.
+    computeTriangleClosestPointToPointBarycentric(
+        scratch_bary, 0,
+        sx, sy, sz,
+        ax, ay, az,
+        bx, by, bz,
+        cx, cy, cz
+    );
+    const alpha_a = scratch_bary[0];
+    const alpha_b = scratch_bary[1];
+    const alpha_c = 1 - alpha_a - alpha_b;
+
+    // Reconstruct the closest world-space point.
+    const px = alpha_a * ax + alpha_b * bx + alpha_c * cx;
+    const py = alpha_a * ay + alpha_b * by + alpha_c * cy;
+    const pz = alpha_a * az + alpha_b * bz + alpha_c * cz;
+
+    // Vector from closest point to sphere centre.
+    const dx = sx - px;
+    const dy = sy - py;
+    const dz = sz - pz;
+    const dist_sqr = dx * dx + dy * dy + dz * dz;
+
+    if (dist_sqr >= radius * radius) {
+        return false;
+    }
+
+    const dist = Math.sqrt(dist_sqr);
+    let nx, ny, nz;
+    if (dist > 0) {
+        const inv = 1 / dist;
+        nx = dx * inv;
+        ny = dy * inv;
+        nz = dz * inv;
+    } else {
+        // Sphere centre lies on the triangle's surface — direction is
+        // undefined. Fall back to the triangle's face normal (CCW
+        // winding: (B - A) × (C - A)), which is the outward direction
+        // for closed meshes and heightmaps. The cross product was
+        // already computed for the degeneracy guard at the top of
+        // the function; reuse fn_mag_sqr.
+        const fn_mag = Math.sqrt(fn_mag_sqr);
+        const inv_fn = 1 / fn_mag;
+        nx = fnx * inv_fn;
+        ny = fny * inv_fn;
+        nz = fnz * inv_fn;
+    }
+
+    out[0] = nx;
+    out[1] = ny;
+    out[2] = nz;
+    out[3] = radius - dist;
+    // Sphere surface point: centre minus normal*radius (the point on
+    // the sphere nearest the triangle).
+    out[4] = sx - nx * radius;
+    out[5] = sy - ny * radius;
+    out[6] = sz - nz * radius;
+    // Triangle surface point: the closest point we already computed.
+    out[7] = px;
+    out[8] = py;
+    out[9] = pz;
+    return true;
+}

package/src/engine/physics/queries/overlap_shape.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Test what bodies overlap a convex shape placed at a given pose. Each
+ * overlapping body's `body_id` is written to `output` starting at
+ * `output_offset`; the function returns the number of body ids written.
+ *
+ * Use case: speculative physics queries for kinematic / character
+ * controllers. An external system can ask "would my body collide with
+ * anything if I moved it here?" without committing a tick of
+ * simulation. The output is a flat list of body ids so the caller can
+ * decide what to do per hit (skip, push, slide, etc.).
+ *
+ * The pipeline mirrors the narrowphase pair test:
+ *   1. Build the query shape's world AABB.
+ *   2. Pull candidates from both broadphase trees that overlap that AABB.
+ *   3. For each candidate, run GJK in world frame. Convex candidates
+ *      go through one GJK call; concave candidates (heightmap / mesh)
+ *      go through the per-triangle decomposition path.
+ *   4. Apply the optional `filter` callback (same signature as in
+ *      raycast / shapeCast) before the GJK test — early-out on bodies
+ *      the caller already wants to skip (themselves, allies, etc.).
+ *
+ * The query shape must be convex (`is_convex === true`). Concave shapes
+ * are typically static terrain and not used as kinematic query
+ * probes; rejecting them avoids the M×N triangle-pair cost.
+ *
+ * @param {PhysicsSystem} system
+ * @param {AbstractShape3D} shape  query shape, convex; expressed in
+ *   its own local frame
+ * @param {{x:number,y:number,z:number}} position world position of the
+ *   query shape
+ * @param {{x:number,y:number,z:number,w:number}} rotation world rotation
+ *   of the query shape (unit quaternion)
+ * @param {Uint32Array|number[]} output buffer to write body_ids into.
+ *   Caller is responsible for sizing it; ids past its end are dropped.
+ * @param {number} output_offset float-index in output to start writing at
+ * @param {(entity:number, collider:Collider)=>boolean} [filter]
+ *   defaults to {@link returnTrue} (accept every candidate)
+ * @returns {number} number of overlapping bodies written
+ * @throws {Error} if `shape.is_convex === false`
+ */
+export function overlap_shape(system: PhysicsSystem, shape: AbstractShape3D, position: {
+    x: number;
+    y: number;
+    z: number;
+}, rotation: {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}, output: Uint32Array | number[], output_offset: number, filter?: (entity: number, collider: Collider) => boolean): number;
+//# sourceMappingURL=overlap_shape.d.ts.map

package/src/engine/physics/queries/overlap_shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AA4CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAE5B;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,UAErC,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,oBACE,MAAM,yBAAsB,OAAO,GAEzC,MAAM,CAqGlB"}

package/src/engine/physics/queries/overlap_shape.js

@@ -0,0 +1,183 @@
+import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js";
+import { returnTrue } from "../../../core/function/returnTrue.js";
+import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
+import { Triangle3D } from "../../../core/geom/3d/shape/Triangle3D.js";
+import { body_id_index } from "../body/BodyStorage.js";
+import { gjk } from "../gjk/gjk.js";
+import { aabb_world_to_local } from "../narrowphase/decomposition/aabb_world_to_local.js";
+import { decompose_to_triangles } from "../narrowphase/decomposition/decompose_to_triangles.js";
+import { TRIANGLE_FLOAT_STRIDE } from "../narrowphase/decomposition/triangle_buffer_layout.js";
+import { PosedShape } from "../narrowphase/PosedShape.js";
+
+/**
+ * Scratch state — module-scoped to avoid per-query allocation. Safe
+ * because PhysicsSystem queries run on the main thread, sequentially.
+ */
+const local_aabb = new Float64Array(6);
+const world_aabb = new Float64Array(6);
+const concave_query_aabb = new Float64Array(6);
+const simplex_buf = new Float64Array(12);
+
+const query_posed = new PosedShape();
+const candidate_posed = new PosedShape();
+const triangle_shape = new Triangle3D();
+
+/**
+ * Maximum triangles a concave candidate can emit per overlap pair.
+ * Same rationale as the narrowphase's `MAX_TRIANGLES_PER_PAIR`: the
+ * broadphase has already bounded the query AABB to the query shape's
+ * envelope, so a single candidate typically yields tens of triangles.
+ * Excess triangles are dropped by the enumerator's bounds check —
+ * worst case is a missed overlap on a far edge of the candidate's
+ * geometry, recovered next query.
+ * @type {number}
+ */
+const MAX_TRIANGLES_PER_PAIR = 1024;
+
+const triangle_buffer = new Float64Array(MAX_TRIANGLES_PER_PAIR * TRIANGLE_FLOAT_STRIDE);
+
+/**
+ * Broadphase candidate buffer. Grows by doubling on overflow.
+ * @type {Uint32Array}
+ */
+let scratch_candidates = new Uint32Array(64);
+
+/**
+ * Test what bodies overlap a convex shape placed at a given pose. Each
+ * overlapping body's `body_id` is written to `output` starting at
+ * `output_offset`; the function returns the number of body ids written.
+ *
+ * Use case: speculative physics queries for kinematic / character
+ * controllers. An external system can ask "would my body collide with
+ * anything if I moved it here?" without committing a tick of
+ * simulation. The output is a flat list of body ids so the caller can
+ * decide what to do per hit (skip, push, slide, etc.).
+ *
+ * The pipeline mirrors the narrowphase pair test:
+ *   1. Build the query shape's world AABB.
+ *   2. Pull candidates from both broadphase trees that overlap that AABB.
+ *   3. For each candidate, run GJK in world frame. Convex candidates
+ *      go through one GJK call; concave candidates (heightmap / mesh)
+ *      go through the per-triangle decomposition path.
+ *   4. Apply the optional `filter` callback (same signature as in
+ *      raycast / shapeCast) before the GJK test — early-out on bodies
+ *      the caller already wants to skip (themselves, allies, etc.).
+ *
+ * The query shape must be convex (`is_convex === true`). Concave shapes
+ * are typically static terrain and not used as kinematic query
+ * probes; rejecting them avoids the M×N triangle-pair cost.
+ *
+ * @param {PhysicsSystem} system
+ * @param {AbstractShape3D} shape  query shape, convex; expressed in
+ *   its own local frame
+ * @param {{x:number,y:number,z:number}} position world position of the
+ *   query shape
+ * @param {{x:number,y:number,z:number,w:number}} rotation world rotation
+ *   of the query shape (unit quaternion)
+ * @param {Uint32Array|number[]} output buffer to write body_ids into.
+ *   Caller is responsible for sizing it; ids past its end are dropped.
+ * @param {number} output_offset float-index in output to start writing at
+ * @param {(entity:number, collider:Collider)=>boolean} [filter]
+ *   defaults to {@link returnTrue} (accept every candidate)
+ * @returns {number} number of overlapping bodies written
+ * @throws {Error} if `shape.is_convex === false`
+ */
+export function overlap_shape(system, shape, position, rotation, output, output_offset, filter = returnTrue) {
+    if (shape.is_convex === false) {
+        throw new Error(`overlap_shape: query shape must be convex; received \`${shape.constructor.name}\` (is_convex=false)`);
+    }
+
+    // ── 1. Query shape's world AABB ─────────────────────────────────
+    shape.compute_bounding_box(local_aabb);
+    aabb3_transform_oriented(
+        world_aabb, 0,
+        local_aabb[0], local_aabb[1], local_aabb[2],
+        local_aabb[3], local_aabb[4], local_aabb[5],
+        position.x, position.y, position.z,
+        rotation.x, rotation.y, rotation.z, rotation.w
+    );
+
+    // ── 2. Gather broadphase candidates ─────────────────────────────
+    const n_static = bvh_query_user_data_overlaps_aabb(
+        scratch_candidates, 0, system.staticBvh, world_aabb
+    );
+    const n_dynamic = bvh_query_user_data_overlaps_aabb(
+        scratch_candidates, n_static, system.dynamicBvh, world_aabb
+    );
+    const n_total = n_static + n_dynamic;
+    if (n_total === 0) return 0;
+
+    // ── 3. Set up query PosedShape (constant across candidates) ─────
+    query_posed.setup(shape, position, rotation);
+
+    // ── 4. Per-candidate narrowphase ────────────────────────────────
+    const output_capacity = output.length - output_offset;
+    let count = 0;
+    let cursor = output_offset;
+
+    for (let i = 0; i < n_total; i++) {
+        if (count >= output_capacity) break;
+
+        const body_id = scratch_candidates[i];
+        const body_idx = body_id_index(body_id);
+
+        const entity = system.entityOf(body_id);
+        if (entity < 0) continue;
+
+        const collider = system.__primary_collider(body_idx);
+        if (collider === null) continue;
+        if (!filter(entity, collider)) continue;
+
+        const candidate_tr = system.__transforms[body_idx];
+
+        let overlaps = false;
+
+        if (collider.shape.is_convex !== false) {
+            candidate_posed.setup(collider.shape, candidate_tr.position, candidate_tr.rotation);
+            overlaps = gjk(simplex_buf, query_posed, candidate_posed);
+        } else {
+            // Concave candidate: project the query's world AABB into
+            // the candidate's body-local frame, decompose to triangles,
+            // run per-triangle GJK until one overlap is found.
+            aabb_world_to_local(
+                concave_query_aabb, 0,
+                world_aabb,
+                candidate_tr.position.x, candidate_tr.position.y, candidate_tr.position.z,
+                candidate_tr.rotation.x, candidate_tr.rotation.y, candidate_tr.rotation.z, candidate_tr.rotation.w
+            );
+
+            const tri_count = decompose_to_triangles(
+                triangle_buffer, 0, collider.shape,
+                concave_query_aabb[0], concave_query_aabb[1], concave_query_aabb[2],
+                concave_query_aabb[3], concave_query_aabb[4], concave_query_aabb[5]
+            );
+
+            // Re-pose candidate as the concave body, rebinding the
+            // flyweight triangle per iteration.
+            candidate_posed.shape = triangle_shape;
+            candidate_posed.px = candidate_tr.position.x;
+            candidate_posed.py = candidate_tr.position.y;
+            candidate_posed.pz = candidate_tr.position.z;
+            candidate_posed.qx = candidate_tr.rotation.x;
+            candidate_posed.qy = candidate_tr.rotation.y;
+            candidate_posed.qz = candidate_tr.rotation.z;
+            candidate_posed.qw = candidate_tr.rotation.w;
+
+            for (let t = 0; t < tri_count; t++) {
+                triangle_shape.bind(triangle_buffer, t * TRIANGLE_FLOAT_STRIDE);
+                if (gjk(simplex_buf, query_posed, candidate_posed)) {
+                    overlaps = true;
+                    break;
+                }
+            }
+        }
+
+        if (overlaps) {
+            output[cursor] = body_id;
+            cursor++;
+            count++;
+        }
+    }
+
+    return count;
+}

package/src/engine/physics/queries/shape_cast.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Sweep a convex shape along a ray and find the first body it would
+ * hit. Used by character controllers (sweep a capsule along intended
+ * movement to find blockers), high-speed projectile movement (avoid
+ * tunnelling without paying for full per-body CCD), and any kinematic
+ * "where would this body end up if I tried to move it?" query.
+ *
+ * Pipeline:
+ *   1. Build the swept AABB: the shape's local-frame AABB rotated
+ *      into world by `rotation`, translated to `ray.origin`, then
+ *      stretched along `ray.direction * ray.tMax`.
+ *   2. Query both broadphase BVHs (static + dynamic) for leaves whose
+ *      AABB overlaps the swept volume.
+ *   3. For each candidate, bisect the [0, best_t] interval for the
+ *      smallest `t` at which the swept shape overlaps the candidate's
+ *      collider. GJK on each midpoint.
+ *
+ * Picking `best_t` (rather than always running the full [0, tMax]
+ * bisection) is the early-termination optimisation: once we have a
+ * hit at some t, no later candidate can produce a smaller TOI by
+ * being checked at its full [0, tMax] interval.
+ *
+ * Output on hit:
+ *   - `result.t` — sweep distance to impact (in the same units as
+ *     `ray.direction`'s magnitude; for a unit-direction ray, this is
+ *     metres).
+ *   - `result.position` — `ray.origin + t * ray.direction`, i.e. the
+ *     centre of the swept shape at the moment of first contact. NOT
+ *     a point on the target's surface; that would need narrowphase
+ *     refinement which the broadphase-only architecture doesn't have
+ *     wired up yet.
+ *   - `result.normal` — target surface's outward normal at the kiss
+ *     point (unit length), computed by running GJK + EPA against the
+ *     just-overlapping configuration at the TOI. Falls back to
+ *     `-ray.direction` on the rare case EPA degenerates (NaN / zero
+ *     depth) — see comment near the EPA call.
+ *   - `result.entity` / `result.body_id` — the hit body.
+ *
+ * Output on miss: untouched; same convention as `raycast`.
+ *
+ * @param {PhysicsSystem} system
+ * @param {Ray3} ray  origin + unit direction + `tMax`
+ * @param {AbstractShape3D} shape  shape being swept, in its local frame
+ * @param {{x:number,y:number,z:number,w:number}} rotation  fixed orientation
+ * @param {PhysicsSurfacePoint} result  populated on hit; untouched on miss
+ * @param {(entity:number, collider:Collider)=>boolean} [filter] mandatory in
+ *   contract; defaults to {@link returnTrue}
+ * @returns {boolean}
+ */
+export function shape_cast(system: PhysicsSystem, ray: Ray3, shape: AbstractShape3D, rotation: {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}, result: PhysicsSurfacePoint, filter?: (entity: number, collider: Collider) => boolean): boolean;
+//# sourceMappingURL=shape_cast.d.ts.map

package/src/engine/physics/queries/shape_cast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape_cast.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/shape_cast.js"],"names":[],"mappings":"AAwEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,+FANW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,iDAE7B,MAAM,yBAAsB,OAAO,GAEzC,OAAO,CA2QnB"}