@woosh/meep-engine 2.138.20 → 2.140.0

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/raycast.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Raycast against both broadphase trees (static + dynamic) of a
+ * {@link PhysicsSystem}, filling `result` with the nearest hit and returning
+ * `true` on hit, `false` on miss.
+ *
+ * Hit normal is the AABB face normal — exact for AABB-shaped colliders,
+ * a stable approximation for general convex shapes (an upcoming narrowphase
+ * refinement pass will replace this with the true shape normal at the same
+ * call site, no API change).
+ *
+ * @param {PhysicsSystem} system
+ * @param {Ray3} ray  origin + unit direction + `tMax`
+ * @param {PhysicsSurfacePoint} result  populated on hit; untouched on miss
+ * @param {(entity:number, collider:Collider)=>boolean} [filter] mandatory in
+ *   contract; defaults to {@link returnTrue} (accept everything). Called once
+ *   per BVH leaf that crosses the ray.
+ * @returns {boolean} true on hit, false on miss
+ */
+export function raycast(system: PhysicsSystem, ray: Ray3, result: PhysicsSurfacePoint, filter?: (entity: number, collider: Collider) => boolean): boolean;
+//# sourceMappingURL=raycast.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"raycast.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/raycast.js"],"names":[],"mappings":"AA2HA;;;;;;;;;;;;;;;;;GAiBG;AACH,yGALmB,MAAM,yBAAsB,OAAO,GAGzC,OAAO,CA6GnB"}

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

@@ -0,0 +1,249 @@
+import { SCRATCH_UINT32_TRAVERSAL_STACK } from "../../../core/collection/SCRATCH_UINT32_TRAVERSAL_STACK.js";
+import {
+    COLUMN_CHILD_1,
+    COLUMN_CHILD_2,
+    COLUMN_USER_DATA,
+    ELEMENT_WORD_COUNT,
+    NULL_NODE,
+} from "../../../core/bvh2/bvh3/BVH.js";
+import { returnTrue } from "../../../core/function/returnTrue.js";
+import { aabb3_near_distance_to_intersection_ray_segment } from "../../../core/geom/3d/aabb/aabb3_near_distance_to_intersection_ray_segment.js";
+
+const stack = SCRATCH_UINT32_TRAVERSAL_STACK;
+
+/**
+ * Walk a single BVH along a ray and update the running nearest hit.
+ *
+ * Hit refinement is broadphase-only: the returned `t` is the distance to
+ * the inflated leaf AABB. Narrowphase shape refinement is a follow-up.
+ *
+ * @param {BVH} bvh
+ * @param {number} root
+ * @param {number} ox
+ * @param {number} oy
+ * @param {number} oz
+ * @param {number} dx
+ * @param {number} dy
+ * @param {number} dz
+ * @param {number} inv_dx
+ * @param {number} inv_dy
+ * @param {number} inv_dz
+ * @param {number} max_distance
+ * @param {{best_t:number, best_body:number, best_node:number, best_bvh:BVH|null}} acc
+ * @param {(body_id:number)=>boolean} test  per-leaf filter
+ */
+function bvh_raycast_nearest(
+    bvh, root,
+    ox, oy, oz,
+    dx, dy, dz,
+    inv_dx, inv_dy, inv_dz,
+    max_distance,
+    acc,
+    test
+) {
+    if (root === NULL_NODE) {
+        return;
+    }
+
+    const float32 = bvh.__data_float32;
+    const uint32 = bvh.__data_uint32;
+
+    let pointer = stack.pointer;
+    const stack_top = pointer;
+    stack[pointer++] = root;
+
+    while (pointer > stack_top) {
+        pointer--;
+        const node = stack[pointer];
+        const address = node * ELEMENT_WORD_COUNT;
+
+        const t_near = aabb3_near_distance_to_intersection_ray_segment(
+            float32[address], float32[address + 1], float32[address + 2],
+            float32[address + 3], float32[address + 4], float32[address + 5],
+            ox, oy, oz,
+            inv_dx, inv_dy, inv_dz,
+            0, max_distance
+        );
+
+        // No intersection or this subtree can't beat the best known hit — prune.
+        if (t_near >= acc.best_t) {
+            continue;
+        }
+
+        const child_1 = uint32[address + COLUMN_CHILD_1];
+        if (child_1 !== NULL_NODE) {
+            stack[pointer++] = uint32[address + COLUMN_CHILD_2];
+            stack[pointer++] = child_1;
+        } else {
+            const body_id = uint32[address + COLUMN_USER_DATA];
+            if (test(body_id)) {
+                acc.best_t = t_near;
+                acc.best_body = body_id;
+                acc.best_node = node;
+                acc.best_bvh = bvh;
+            }
+        }
+    }
+
+    stack.pointer = stack_top;
+}
+
+/**
+ * Reusable nearest-hit accumulator. Module-scoped so {@link raycast} doesn't
+ * allocate per call. The physics step is single-threaded so contention isn't
+ * a concern.
+ * @type {{best_t:number, best_body:number, best_node:number, best_bvh:BVH|null}}
+ */
+const acc = { best_t: Infinity, best_body: 0, best_node: 0, best_bvh: null };
+
+/**
+ * Reusable closure bound to the current system + user filter so we don't
+ * allocate a new function object per call. Re-wired at the top of each
+ * {@link raycast} invocation. The BVH traversal sees a stable identity
+ * which helps V8 keep the call site monomorphic.
+ *
+ * Carries state via the module-scoped `bound_*` slots below.
+ * @type {(body_id:number)=>boolean}
+ */
+const bound_test = (body_id) => {
+    const system = bound_system;
+    const entity = system.entityOf(body_id);
+    if (entity < 0) return false;
+    // v1 limitation: when a multi-collider body's BVH leaf is hit, we pass
+    // the body's primary (first-attached) collider rather than the specific
+    // collider the ray actually crossed. Sufficient for entity-level
+    // filtering; per-collider filtering needs the BVH user_data scheme to
+    // encode collider index too — future work.
+    const collider = system.__primary_collider(system.__index_of(body_id));
+    return bound_filter(entity, collider);
+};
+
+let bound_system = null;
+let bound_filter = returnTrue;
+
+/**
+ * Raycast against both broadphase trees (static + dynamic) of a
+ * {@link PhysicsSystem}, filling `result` with the nearest hit and returning
+ * `true` on hit, `false` on miss.
+ *
+ * Hit normal is the AABB face normal — exact for AABB-shaped colliders,
+ * a stable approximation for general convex shapes (an upcoming narrowphase
+ * refinement pass will replace this with the true shape normal at the same
+ * call site, no API change).
+ *
+ * @param {PhysicsSystem} system
+ * @param {Ray3} ray  origin + unit direction + `tMax`
+ * @param {PhysicsSurfacePoint} result  populated on hit; untouched on miss
+ * @param {(entity:number, collider:Collider)=>boolean} [filter] mandatory in
+ *   contract; defaults to {@link returnTrue} (accept everything). Called once
+ *   per BVH leaf that crosses the ray.
+ * @returns {boolean} true on hit, false on miss
+ */
+export function raycast(system, ray, result, filter = returnTrue) {
+    const ox = ray.origin_x;
+    const oy = ray.origin_y;
+    const oz = ray.origin_z;
+    const dx = ray.direction_x;
+    const dy = ray.direction_y;
+    const dz = ray.direction_z;
+    const max_distance = ray.tMax;
+
+    acc.best_t = max_distance;
+    acc.best_body = 0;
+    acc.best_node = 0;
+    acc.best_bvh = null;
+
+    bound_system = system;
+    bound_filter = filter;
+
+    const inv_dx = 1 / dx;
+    const inv_dy = 1 / dy;
+    const inv_dz = 1 / dz;
+
+    bvh_raycast_nearest(
+        system.staticBvh, system.staticBvh.root,
+        ox, oy, oz,
+        dx, dy, dz,
+        inv_dx, inv_dy, inv_dz,
+        max_distance,
+        acc, bound_test
+    );
+
+    bvh_raycast_nearest(
+        system.dynamicBvh, system.dynamicBvh.root,
+        ox, oy, oz,
+        dx, dy, dz,
+        inv_dx, inv_dy, inv_dz,
+        max_distance,
+        acc, bound_test
+    );
+
+    if (acc.best_bvh === null || acc.best_t >= max_distance) {
+        return false;
+    }
+
+    const entity = system.entityOf(acc.best_body);
+    if (entity < 0) {
+        // Body was unlinked concurrently; treat as a miss.
+        return false;
+    }
+
+    // Hit position in world space.
+    const t = acc.best_t;
+    const hx = ox + dx * t;
+    const hy = oy + dy * t;
+    const hz = oz + dz * t;
+
+    // AABB face normal at the hit point. Read the best leaf's AABB back from
+    // its BVH; project the hit point into the AABB's normalised local space
+    // (centre = 0, faces = ±1); the dominant component is the entry-face
+    // axis, its sign gives the outward normal.
+    const bvh = acc.best_bvh;
+    const node_address = acc.best_node * ELEMENT_WORD_COUNT;
+    const f32 = bvh.__data_float32;
+    const aabb_min_x = f32[node_address];
+    const aabb_min_y = f32[node_address + 1];
+    const aabb_min_z = f32[node_address + 2];
+    const aabb_max_x = f32[node_address + 3];
+    const aabb_max_y = f32[node_address + 4];
+    const aabb_max_z = f32[node_address + 5];
+
+    const cx = (aabb_min_x + aabb_max_x) * 0.5;
+    const cy = (aabb_min_y + aabb_max_y) * 0.5;
+    const cz = (aabb_min_z + aabb_max_z) * 0.5;
+    // Multiplicative inverse of the half-extent saves one divide per axis.
+    // A degenerate AABB (zero extent on an axis) is impossible for live BVH
+    // leaves — physics shapes always have non-zero bounding extent.
+    const inv_half_x = 2 / (aabb_max_x - aabb_min_x);
+    const inv_half_y = 2 / (aabb_max_y - aabb_min_y);
+    const inv_half_z = 2 / (aabb_max_z - aabb_min_z);
+
+    const px = (hx - cx) * inv_half_x;
+    const py = (hy - cy) * inv_half_y;
+    const pz = (hz - cz) * inv_half_z;
+
+    const apx = px < 0 ? -px : px;
+    const apy = py < 0 ? -py : py;
+    const apz = pz < 0 ? -pz : pz;
+
+    let nx, ny, nz;
+    if (apx >= apy && apx >= apz) {
+        nx = px >= 0 ? 1 : -1; ny = 0; nz = 0;
+    } else if (apy >= apz) {
+        nx = 0; ny = py >= 0 ? 1 : -1; nz = 0;
+    } else {
+        nx = 0; ny = 0; nz = pz >= 0 ? 1 : -1;
+    }
+
+    // Fill result. Direct typed-array writes — Vector3 extends Float32Array,
+    // and there are no observers subscribed to a query-result vector.
+    const rp = result.position;
+    const rn = result.normal;
+    rp[0] = hx; rp[1] = hy; rp[2] = hz;
+    rn[0] = nx; rn[1] = ny; rn[2] = nz;
+    result.t = t;
+    result.entity = entity;
+    result.body_id = acc.best_body;
+
+    return true;
+}

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