@woosh/meep-engine 3.25.0 → 3.26.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.25.0",
+  "version": "3.26.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/core/geom/3d/shape/HeightMapShape3D.d.ts

@@ -158,6 +158,65 @@ export class HeightMapShape3D extends AbstractShape3D {
      * site is forced to handle heightmaps explicitly.
      */
     support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    /**
+     * Nearest ray hit against the height-field SURFACE, in the shape's body-local
+     * frame. Writes `[px, py, pz, nx, ny, nz]` into `hit` and returns true; a miss
+     * returns false and leaves `hit` untouched.
+     *
+     * ## What is hit
+     *
+     * The surface, not the solid. The class models a closed volume (floor at h=0,
+     * height field above), but a ray meets only the height field — there is no
+     * floor quad and no side skirt, so a ray that passes under the terrain or
+     * enters through the footprint edge below the surface reports a miss. That is
+     * the same body {@link heightmap_enumerate_triangles} hands the contact
+     * narrowphase, and the same body the terrain renderer draws; a raycast that
+     * answered for the skirt would disagree with both. Mirrors
+     * {@link MeshShape3D#raycast}, which is likewise surface-only.
+     *
+     * Precisely the same triangles, too: the traversal reads its corner heights at
+     * the identical `i / seg_u` / `j / seg_v` UVs through the identical Catmull-Rom
+     * filter, and splits each sub-cell on the same lower-left diagonal
+     * (`(A,D,B)`, `(D,C,B)`), so a cast and a contact resolve against a surface
+     * that agrees bit for bit — {@link tessellation} included.
+     *
+     * NORMAL: the triangle's geometric normal, flipped to face the incoming ray
+     * (the shared {@link tri3_raycast} convention). A cast from below the terrain
+     * therefore reports a downward normal, not the surface's true upward one.
+     *
+     * A hit landing exactly ON a sub-cell boundary gets the normal of one of the
+     * facets meeting there, and which one follows from traversal order: this walks
+     * the grid along the ray, the narrowphase enumerates it row-major, so on a grid
+     * line — and especially a grid corner, where four facets meet — the two can
+     * name different facets. The hit POINT still agrees; a faceted surface simply
+     * has no single normal at a seam. Measure-zero, and called out because it is
+     * the only place the two answers part company.
+     *
+     * `size.y` does NOT bound the query. Sampler values are not clamped to it (see
+     * the class docstring), so clipping the ray to the height range that
+     * {@link compute_bounding_box} reports could reject real surface standing above
+     * it; only the footprint is clipped against.
+     *
+     * ## Cost
+     *
+     * A 2-D DDA over the `(W−1)·N × (H−1)·N` sub-cell grid, two triangles per cell,
+     * stopping at the first cell that hits — cells are visited in increasing ray
+     * order and a sub-cell's triangles project exactly onto its own footprint
+     * rectangle, so nothing behind can be nearer. O(cells the ray crosses), not
+     * O(cells in the ray's bounding box): a long diagonal cast costs the grid's
+     * diagonal rather than its area.
+     *
+     * Four Catmull-Rom evaluations per cell, uncached — deliberately unlike
+     * {@link heightmap_enumerate_triangles}, whose corner-row cache exists because
+     * the contact narrowphase re-samples the same rect every substep. A ray walks
+     * a diagonal, visits each cell once, and stops early; there is nothing to
+     * amortise against.
+     *
+     * @param {Float32Array|number[]} hit out: [px, py, pz, nx, ny, nz]
+     * @param {Ray3} ray body-local ray (unit direction; `ray[6]` = tMax)
+     * @returns {boolean} whether anything was hit
+     */
+    raycast(hit: Float32Array | number[], ray: Ray3): boolean;
     sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
     /**
      * @param {HeightMapShape3D} other

package/src/core/geom/3d/shape/HeightMapShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HeightMapShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/HeightMapShape3D.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IA4DI;;;;;;;;;;;OAWG;IACH,wCATW,MAAM,UACN,MAAM,UACN,MAAM,gBACN,OAAO,iBACP,MAAM,GAGJ,gBAAgB,CAqB5B;IA1FD;;;;;OAKG;IACH,sBAFU,OAAO,CAEkB;IAEnC;;;;;;;OAOG;IACH,eAFU,OAAO,CAEW;IAE5B;;;;;OAKG;IACH,SAFU,YAAY,IAAI,CAEX;IAEf;;;;;;;;;;;;;;;;OAgBG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;OAKG;IACH,eAA6B;IAG7B,6BAA2B;IAE3B,6BAA2B;IAC3B,6BAA2B;IAmC3B;;;;;;;;;OASG;IACH,sBA+CC;IAED;;;;;;OAMG;IACH,yBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,8BALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAelB;IAED,wCA8BC;IAED,oCA2BC;IAED;;;;;;;;OAQG;IACH,6CAmBC;IAED;;;;OAIG;IACH,4DA2BC;IAED;;;;;;;;;OASG;IACH,qGAEC;IAED,kFAiBC;IA6CD;;;OAGG;IACH,cAHW,gBAAgB,GACd,OAAO,CAUnB;IAWL;;;;;;OAMG;IACH,6BAFU,OAAO,CAE4B;CAT5C;gCAhc+B,sBAAsB;wBAD9B,kBAAkB"}
+{"version":3,"file":"HeightMapShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/HeightMapShape3D.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IA4DI;;;;;;;;;;;OAWG;IACH,wCATW,MAAM,UACN,MAAM,UACN,MAAM,gBACN,OAAO,iBACP,MAAM,GAGJ,gBAAgB,CAqB5B;IA1FD;;;;;OAKG;IACH,sBAFU,OAAO,CAEkB;IAEnC;;;;;;;OAOG;IACH,eAFU,OAAO,CAEW;IAE5B;;;;;OAKG;IACH,SAFU,YAAY,IAAI,CAEX;IAEf;;;;;;;;;;;;;;;;OAgBG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;OAKG;IACH,eAA6B;IAG7B,6BAA2B;IAE3B,6BAA2B;IAC3B,6BAA2B;IAmC3B;;;;;;;;;OASG;IACH,sBA+CC;IAED;;;;;;OAMG;IACH,yBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,8BALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAelB;IAED,wCA8BC;IAED,oCA2BC;IAED;;;;;;;;OAQG;IACH,6CAmBC;IAED;;;;OAIG;IACH,4DA2BC;IAED;;;;;;;;;OASG;IACH,qGAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyDG;IACH,aAJW,YAAY,GAAC,MAAM,EAAE,cAEnB,OAAO,CAyNnB;IAED,kFAiBC;IA6CD;;;OAGG;IACH,cAHW,gBAAgB,GACd,OAAO,CAUnB;IAWL;;;;;;OAMG;IACH,6BAFU,OAAO,CAE4B;CAT5C;gCA5tB+B,sBAAsB;wBAD9B,kBAAkB"}

package/src/core/geom/3d/shape/HeightMapShape3D.js

@@ -4,10 +4,20 @@ import { assert } from "../../../assert.js";
 import { clamp } from "../../../math/clamp.js";
 import { optional_equality } from "../../../model/object/optional_equality.js";
 import { optional_hash } from "../../../model/object/optional_hash.js";
+import { tri3_raycast } from "../triangle/tri3_raycast.js";
 import { v3_length } from "../../vec3/v3_length.js";
 import { Vector3 } from "../../Vector3.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 
+/**
+ * Below this, a ray's footprint-plane velocity component counts as zero in
+ * {@link HeightMapShape3D#raycast}'s slab clip — the reciprocal a smaller value
+ * would produce is not a usable slab distance. Matches the concave narrowphase's
+ * `refine_ray_concave`, so the two agree on rays that graze the footprint edge.
+ * @type {number}
+ */
+const RAY_SLAB_EPSILON = 1e-12;
+
 /**
  * Heightmap shape, intended primarily for terrain.
  *
@@ -371,6 +381,281 @@ export class HeightMapShape3D extends AbstractShape3D {
         throw new Error("HeightMapShape3D.support: heightmaps are non-convex; the narrowphase must dispatch grid-traversal instead.");
     }
 
+    /**
+     * Nearest ray hit against the height-field SURFACE, in the shape's body-local
+     * frame. Writes `[px, py, pz, nx, ny, nz]` into `hit` and returns true; a miss
+     * returns false and leaves `hit` untouched.
+     *
+     * ## What is hit
+     *
+     * The surface, not the solid. The class models a closed volume (floor at h=0,
+     * height field above), but a ray meets only the height field — there is no
+     * floor quad and no side skirt, so a ray that passes under the terrain or
+     * enters through the footprint edge below the surface reports a miss. That is
+     * the same body {@link heightmap_enumerate_triangles} hands the contact
+     * narrowphase, and the same body the terrain renderer draws; a raycast that
+     * answered for the skirt would disagree with both. Mirrors
+     * {@link MeshShape3D#raycast}, which is likewise surface-only.
+     *
+     * Precisely the same triangles, too: the traversal reads its corner heights at
+     * the identical `i / seg_u` / `j / seg_v` UVs through the identical Catmull-Rom
+     * filter, and splits each sub-cell on the same lower-left diagonal
+     * (`(A,D,B)`, `(D,C,B)`), so a cast and a contact resolve against a surface
+     * that agrees bit for bit — {@link tessellation} included.
+     *
+     * NORMAL: the triangle's geometric normal, flipped to face the incoming ray
+     * (the shared {@link tri3_raycast} convention). A cast from below the terrain
+     * therefore reports a downward normal, not the surface's true upward one.
+     *
+     * A hit landing exactly ON a sub-cell boundary gets the normal of one of the
+     * facets meeting there, and which one follows from traversal order: this walks
+     * the grid along the ray, the narrowphase enumerates it row-major, so on a grid
+     * line — and especially a grid corner, where four facets meet — the two can
+     * name different facets. The hit POINT still agrees; a faceted surface simply
+     * has no single normal at a seam. Measure-zero, and called out because it is
+     * the only place the two answers part company.
+     *
+     * `size.y` does NOT bound the query. Sampler values are not clamped to it (see
+     * the class docstring), so clipping the ray to the height range that
+     * {@link compute_bounding_box} reports could reject real surface standing above
+     * it; only the footprint is clipped against.
+     *
+     * ## Cost
+     *
+     * A 2-D DDA over the `(W−1)·N × (H−1)·N` sub-cell grid, two triangles per cell,
+     * stopping at the first cell that hits — cells are visited in increasing ray
+     * order and a sub-cell's triangles project exactly onto its own footprint
+     * rectangle, so nothing behind can be nearer. O(cells the ray crosses), not
+     * O(cells in the ray's bounding box): a long diagonal cast costs the grid's
+     * diagonal rather than its area.
+     *
+     * Four Catmull-Rom evaluations per cell, uncached — deliberately unlike
+     * {@link heightmap_enumerate_triangles}, whose corner-row cache exists because
+     * the contact narrowphase re-samples the same rect every substep. A ray walks
+     * a diagonal, visits each cell once, and stops early; there is nothing to
+     * amortise against.
+     *
+     * @param {Float32Array|number[]} hit out: [px, py, pz, nx, ny, nz]
+     * @param {Ray3} ray body-local ray (unit direction; `ray[6]` = tMax)
+     * @returns {boolean} whether anything was hit
+     */
+    raycast(hit, ray) {
+        const sampler = this.sampler;
+
+        if (sampler === null) {
+            return false;
+        }
+
+        const size_x = this.size[0];
+        const size_z = this.size[2];
+
+        if (size_x <= 0 || size_z <= 0) {
+            return false;
+        }
+
+        // The collision grid heightmap_enumerate_triangles builds. A sampler too
+        // thin to hold one cell on an axis (width or height < 2), or tessellation
+        // 0, collapses it — no triangles exist, so nothing can be hit.
+        const seg_u = (sampler.width - 1) * this.tessellation;
+        const seg_v = (sampler.height - 1) * this.tessellation;
+
+        if (seg_u < 1 || seg_v < 1) {
+            return false;
+        }
+
+        this._ensure_basis();
+
+        const b = this._basis;
+
+        const o_x = ray[0], o_y = ray[1], o_z = ray[2];
+        const d_x = ray[3], d_y = ray[4], d_z = ray[5];
+
+        // Body → heightmap-local footprint coordinates. The basis is orthonormal,
+        // so the direction stays unit and `t` is the same distance in both frames;
+        // the height component is never needed, the triangles carry it.
+        const o_u = b[0] * o_x + b[1] * o_y + b[2] * o_z;
+        const o_v = b[3] * o_x + b[4] * o_y + b[5] * o_z;
+        const d_u = b[0] * d_x + b[1] * d_y + b[2] * d_z;
+        const d_v = b[3] * d_x + b[4] * d_y + b[5] * d_z;
+
+        const half_u = size_x * 0.5;
+        const half_v = size_z * 0.5;
+
+        const t_max = ray[6];
+
+        // ── Clip to the footprint slabs → the segment the DDA walks ──────────
+        let t_enter = 0;
+        let t_exit = t_max;
+
+        if (d_u > RAY_SLAB_EPSILON || d_u < -RAY_SLAB_EPSILON) {
+            const inv = 1 / d_u;
+            let t0 = (-half_u - o_u) * inv;
+            let t1 = (half_u - o_u) * inv;
+            if (t0 > t1) { const s = t0; t0 = t1; t1 = s; }
+            if (t0 > t_enter) t_enter = t0;
+            if (t1 < t_exit) t_exit = t1;
+        } else if (o_u < -half_u || o_u > half_u) {
+            return false;
+        }
+
+        if (d_v > RAY_SLAB_EPSILON || d_v < -RAY_SLAB_EPSILON) {
+            const inv = 1 / d_v;
+            let t0 = (-half_v - o_v) * inv;
+            let t1 = (half_v - o_v) * inv;
+            if (t0 > t1) { const s = t0; t0 = t1; t1 = s; }
+            if (t0 > t_enter) t_enter = t0;
+            if (t1 < t_exit) t_exit = t1;
+        } else if (o_v < -half_v || o_v > half_v) {
+            return false;
+        }
+
+        if (t_exit < t_enter) {
+            return false;
+        }
+
+        // ── Amanatides–Woo setup on the sub-cell grid ────────────────────────
+        //
+        // Grid coordinates run [0, seg_u] × [0, seg_v] across the footprint. A
+        // ray with no footprint-plane velocity (cast straight down the
+        // orientation axis) keeps both rates at 0, both t_next at Infinity, and
+        // the loop tests its single cell and stops.
+        const per_cell_u = seg_u / size_x;
+        const per_cell_v = seg_v / size_z;
+
+        const rate_u = d_u * per_cell_u;
+        const rate_v = d_v * per_cell_v;
+
+        const g_u = (o_u + d_u * t_enter + half_u) * per_cell_u;
+        const g_v = (o_v + d_v * t_enter + half_v) * per_cell_v;
+
+        // Clamped because the slab clip lands the entry point ON the boundary,
+        // where rounding can put it a ULP outside the grid.
+        let i = Math.floor(g_u);
+        let j = Math.floor(g_v);
+
+        if (i < 0) i = 0; else if (i > seg_u - 1) i = seg_u - 1;
+        if (j < 0) j = 0; else if (j > seg_v - 1) j = seg_v - 1;
+
+        let step_i = 0, t_delta_u = Infinity, t_next_u = Infinity;
+        if (rate_u > 0) {
+            step_i = 1;
+            t_delta_u = 1 / rate_u;
+            t_next_u = t_enter + (i + 1 - g_u) * t_delta_u;
+        } else if (rate_u < 0) {
+            step_i = -1;
+            t_delta_u = -1 / rate_u;
+            t_next_u = t_enter + (i - g_u) / rate_u;
+        }
+
+        let step_j = 0, t_delta_v = Infinity, t_next_v = Infinity;
+        if (rate_v > 0) {
+            step_j = 1;
+            t_delta_v = 1 / rate_v;
+            t_next_v = t_enter + (j + 1 - g_v) * t_delta_v;
+        } else if (rate_v < 0) {
+            step_j = -1;
+            t_delta_v = -1 / rate_v;
+            t_next_v = t_enter + (j - g_v) / rate_v;
+        }
+
+        const inv_seg_u = 1 / seg_u;
+        const inv_seg_v = 1 / seg_v;
+
+        const ux = b[0], uy = b[1], uz = b[2];
+        const vx = b[3], vy = b[4], vz = b[5];
+        const nx = b[6], ny = b[7], nz = b[8];
+
+        // Every iteration but the last ends by crossing one grid line, and a
+        // straight line crosses fewer than seg_u + seg_v of them (a corner costs
+        // two iterations to move diagonally — one per axis — but no extra lines).
+        // The walk normally ends on t_exit; this is the bound that holds when a
+        // near-denormal rate makes t_exit unreachable.
+        const max_steps = seg_u + seg_v + 2;
+
+        for (let step = 0; step < max_steps; step++) {
+            // ── The sub-cell's two triangles, built exactly as the enumerator
+            //    builds them: corners (A,B,C,D) = (i,j), (i+1,j), (i+1,j+1),
+            //    (i,j+1), split (A,D,B) and (D,C,B).
+            const u01_lo = i * inv_seg_u;
+            const u01_hi = (i + 1) * inv_seg_u;
+            const v01_lo = j * inv_seg_v;
+            const v01_hi = (j + 1) * inv_seg_v;
+
+            const u_lo = -half_u + size_x * u01_lo;
+            const u_hi = -half_u + size_x * u01_hi;
+            const v_lo = -half_v + size_z * v01_lo;
+            const v_hi = -half_v + size_z * v01_hi;
+
+            const hA = sampler.sampleChannelCatmullRomUV(u01_lo, v01_lo, 0);
+            const hB = sampler.sampleChannelCatmullRomUV(u01_hi, v01_lo, 0);
+            const hC = sampler.sampleChannelCatmullRomUV(u01_hi, v01_hi, 0);
+            const hD = sampler.sampleChannelCatmullRomUV(u01_lo, v01_hi, 0);
+
+            const Ax = ux * u_lo + vx * v_lo + nx * hA;
+            const Ay = uy * u_lo + vy * v_lo + ny * hA;
+            const Az = uz * u_lo + vz * v_lo + nz * hA;
+
+            const Bx = ux * u_hi + vx * v_lo + nx * hB;
+            const By = uy * u_hi + vy * v_lo + ny * hB;
+            const Bz = uz * u_hi + vz * v_lo + nz * hB;
+
+            const Cx = ux * u_hi + vx * v_hi + nx * hC;
+            const Cy = uy * u_hi + vy * v_hi + ny * hC;
+            const Cz = uz * u_hi + vz * v_hi + nz * hC;
+
+            const Dx = ux * u_lo + vx * v_hi + nx * hD;
+            const Dy = uy * u_lo + vy * v_hi + ny * hD;
+            const Dz = uz * u_lo + vz * v_hi + nz * hD;
+
+            // tri3_raycast writes hit[3..5] only for a hit inside the budget it
+            // was given, so handing the second triangle the first's distance
+            // leaves the nearer one's normal standing. Both can claim a point on
+            // the shared D–B diagonal, and this keeps the second where the
+            // narrowphase's copy of the same test keeps the first — the seam case
+            // the docstring calls out.
+            let best = tri3_raycast(
+                hit, 3, o_x, o_y, o_z, d_x, d_y, d_z, t_max,
+                Ax, Ay, Az, Dx, Dy, Dz, Bx, By, Bz
+            );
+
+            const t_second = tri3_raycast(
+                hit, 3, o_x, o_y, o_z, d_x, d_y, d_z, best < t_max ? best : t_max,
+                Dx, Dy, Dz, Cx, Cy, Cz, Bx, By, Bz
+            );
+
+            if (t_second < best) {
+                best = t_second;
+            }
+
+            if (best !== Infinity) {
+                hit[0] = o_x + d_x * best;
+                hit[1] = o_y + d_y * best;
+                hit[2] = o_z + d_z * best;
+
+                return true;
+            }
+
+            // ── Advance to the next cell along the ray ───────────────────────
+            if (t_next_u < t_next_v) {
+                if (t_next_u > t_exit) break;
+                i += step_i;
+                if (i < 0 || i >= seg_u) break;
+                t_next_u += t_delta_u;
+            } else if (t_next_v !== Infinity) {
+                if (t_next_v > t_exit) break;
+                j += step_j;
+                if (j < 0 || j >= seg_v) break;
+                t_next_v += t_delta_v;
+            } else {
+                // Both rates are zero: the ray runs along the orientation axis and
+                // never leaves the cell it started in.
+                break;
+            }
+        }
+
+        return false;
+    }
+
     sample_random_point_in_volume(result, result_offset, random) {
         const u01 = random();
         const v01 = random();

package/src/core/geom/3d/shape/PosedShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CAClB;IAEb,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IAEP;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAe1D;IAED;;;;;;;;;;;;;;;OAeG;IACH,wBATW,eAAe,MACf,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAMhB;IAyED,wCASC;IA4BD;;;;;;;OAOG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CAKlB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,OAAO,CAKnB;IAGL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;gCAtN+B,sBAAsB"}
+{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CAClB;IAEb,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IAEP;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAe1D;IAED;;;;;;;;;;;;;;;OAeG;IACH,wBATW,eAAe,MACf,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAMhB;IA+HD,wCASC;IA4BD;;;;;;;OAOG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CAKlB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,OAAO,CAKnB;IAGL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;gCA5Q+B,sBAAsB"}

package/src/core/geom/3d/shape/PosedShape3D.js

@@ -1,5 +1,8 @@
 import { assert } from "../../../assert.js";
+import { v3_quaternion_apply } from "../../vec3/v3_quaternion_apply.js";
+import { v3_quaternion_apply_inverse } from "../../vec3/v3_quaternion_apply_inverse.js";
 import { aabb3_transform_oriented } from "../aabb/aabb3_transform_oriented.js";
+import { Ray3 } from "../ray/Ray3.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 
 const scratch_local = new Float64Array(3);
@@ -154,6 +157,60 @@ export class PosedShape3D extends AbstractShape3D {
         result[result_offset + 2] = tsz * qw - tsw * qz - tsx * qy + tsy * qx + this.pz;
     }
 
+    /**
+     * Ray ↔ posed shape, with the ray given in the WRAPPER's frame. The inverse pose carries it into
+     * the subject's frame (translate by −position, rotate by the conjugate quaternion), the subject
+     * answers there, and the answer is rotated back — the point re-translated, the normal not.
+     *
+     * A rigid pose is an isometry, so the crossing changes nothing about the ray's parametrisation:
+     * the rotated direction is still unit, `tMax` goes through untouched, and the distance the subject
+     * measures IS the distance here. The normal's ORIENTATION survives for the same reason — a rotation
+     * preserves the angle between normal and direction, so a subject that turned its normal to meet the
+     * ray has turned this one to meet it too, and there is nothing to re-check.
+     *
+     * `hit` is handed straight to the subject rather than buffered and copied back: on a hit its
+     * contents are mapped in place, and on a miss the subject leaves it untouched — which is the
+     * convention this class owes its own caller, so it is passed on intact.
+     *
+     * The physics ray query does not come through here; it uses `refine_ray_posed`, which performs the
+     * same mapping on loose scalars. That path reports a distance rather than a point, so it never
+     * rotates anything but the normal.
+     *
+     * @param {Float32Array|number[]} hit out: [px, py, pz, nx, ny, nz]
+     * @param {Ray3} ray wrapper-frame ray (origin in [0..2], unit direction in [3..5], tMax in [6])
+     * @returns {boolean} whether anything was hit
+     */
+    raycast(hit, ray) {
+        const shape = this.shape;
+
+        if (shape === null) {
+            return false;
+        }
+
+        const qx = this.qx, qy = this.qy, qz = this.qz, qw = this.qw;
+
+        // Allocated per call rather than kept as a module scratch: a posed shape may wrap another
+        // wrapper, and every level of that recursion needs its own sub-ray alive across the call below.
+        const local_ray = new Ray3();
+
+        v3_quaternion_apply_inverse(local_ray, 0, ray[0] - this.px, ray[1] - this.py, ray[2] - this.pz, qx, qy, qz, qw);
+        v3_quaternion_apply_inverse(local_ray, 3, ray[3], ray[4], ray[5], qx, qy, qz, qw);
+        local_ray[6] = ray[6];
+
+        if (!shape.raycast(hit, local_ray)) {
+            return false;
+        }
+
+        v3_quaternion_apply(hit, 0, hit[0], hit[1], hit[2], qx, qy, qz, qw);
+        v3_quaternion_apply(hit, 3, hit[3], hit[4], hit[5], qx, qy, qz, qw);
+
+        hit[0] += this.px;
+        hit[1] += this.py;
+        hit[2] += this.pz;
+
+        return true;
+    }
+
     compute_bounding_box(result) {
         this.shape.compute_bounding_box(scratch_local_aabb);
         aabb3_transform_oriented(

package/src/core/geom/3d/shape/TransformedShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TransformedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/TransformedShape3D.js"],"names":[],"mappings":"AAwBA;IAwCI;;;;;OAKG;IACH,wBAHW,eAAe,MADf,MAAM,EAAE,GAAC,YAAY,OAAK,GAExB,kBAAkB,CAS9B;IAED;;;;;OAKG;IACH,uCAJW,eAAe,eACf,MAAM,EAAE,SACR,MAAM,EAAE,sBAiBlB;IAED;;;;OAIG;IACH,iCAHW,eAAe,eACf,MAAM,EAAE,sBAIlB;IAED;;;;;OAKG;IACH,2BAHW,eAAe,SACf,MAAM,EAAE,GAAC,YAAY,OAAK,GAFxB,kBAAkB,CAM9B;IA9FD;;;;OAIG;IACH,iBAAgC;IAEhC;;;;OAIG;IACH,yBAAwC;IAExC;;;;OAIG;IACH,kBAAiB;IAEjB;;;OAGG;IACH,+BAEC;IAqED;;;OAGG;IACH,0CAIC;IAED,yCAEC;IAED;;;;;;;OAOG;IACH,6BAEC;IAUD,wCAKC;IAED,mEAyDC;IAED,6CAEC;IAED,oCAKC;IAED,kFAIC;IAED,qGAwCC;IAED;;;;OAIG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAOnB;IAQL;;;;;OAKG;IACH,+BAFU,OAAO,CAEgC;CARhD;gCA9R+B,sBAAsB"}
+{"version":3,"file":"TransformedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/TransformedShape3D.js"],"names":[],"mappings":"AAyBA;IAwCI;;;;;OAKG;IACH,wBAHW,eAAe,MADf,MAAM,EAAE,GAAC,YAAY,OAAK,GAExB,kBAAkB,CAS9B;IAED;;;;;OAKG;IACH,uCAJW,eAAe,eACf,MAAM,EAAE,SACR,MAAM,EAAE,sBAiBlB;IAED;;;;OAIG;IACH,iCAHW,eAAe,eACf,MAAM,EAAE,sBAIlB;IAED;;;;;OAKG;IACH,2BAHW,eAAe,SACf,MAAM,EAAE,GAAC,YAAY,OAAK,GAFxB,kBAAkB,CAM9B;IA9FD;;;;OAIG;IACH,iBAAgC;IAEhC;;;;OAIG;IACH,yBAAwC;IAExC;;;;OAIG;IACH,kBAAiB;IAEjB;;;OAGG;IACH,+BAEC;IAqED;;;OAGG;IACH,0CAIC;IAED,yCAEC;IAED;;;;;;;OAOG;IACH,6BAEC;IAUD,wCAKC;IAED,mEAyDC;IAED,6CAEC;IAED,oCAKC;IAED,kFAIC;IAED,qGAwCC;IAuGD;;;;OAIG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAOnB;IAQL;;;;;OAKG;IACH,+BAFU,OAAO,CAEgC;CARhD;gCAnY+B,sBAAsB"}

package/src/core/geom/3d/shape/TransformedShape3D.js

@@ -8,6 +8,7 @@ import { aabb3_matrix4_project } from "../aabb/aabb3_matrix4_project.js";
 import { m4_extract_scale } from "../mat4/m4_extract_scale.js";
 import { m4_invert } from "../mat4/m4_invert.js";
 import { m4_make_scale } from "../mat4/m4_make_scale.js";
+import { Ray3 } from "../ray/Ray3.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 
 /**
@@ -278,6 +279,107 @@ export class TransformedShape3D extends AbstractShape3D {
         v3_matrix4_multiply(result, result_offset, scratch_v3_0, 0, this.__matrix);
     }
 
+    /**
+     * Ray ↔ transformed shape, with the ray given in the WRAPPER's frame. The cached inverse matrix
+     * carries the ray into the subject's frame, the subject answers there, and the answer comes back
+     * by two different maps: the point through the forward matrix, the normal through the inverse
+     * TRANSPOSE.
+     *
+     * Three things an affine transform does to a ray that a rigid pose ({@link PosedShape3D#raycast})
+     * does not:
+     *
+     *  - DISTANCE. The mapped direction is no longer unit — a scaled shape stretches travel along the
+     *    ray — so it is renormalised and the stretch factor is carried on `tMax` INTO the subject.
+     *    Nothing carries it back out, because the hit point is mapped by the matrix rather than
+     *    rebuilt from a distance, and an affine map takes the subject's point on its ray to this
+     *    ray's point at the matching parameter. So a caller recovering `t` as `(p − origin)·direction`
+     *    still gets the distance in THIS frame, which is what the family contract promises.
+     *  - NORMAL. It maps by (M⁻¹)ᵀ rather than by M — that is what keeps a normal perpendicular to
+     *    its surface under non-uniform scale — and is renormalised afterwards, because that map does
+     *    not preserve length. Done inline against the cached {@link inverse_transform}, not through
+     *    `v3_matrix4_rotate_normal`, which would invert the matrix again on every ray.
+     *  - ORIENTATION. Nothing to fix, as it happens: `n_here · d_here = scale · (n_subject ·
+     *    d_subject)` with `scale > 0`, so a normal the subject turned to meet its ray meets this one
+     *    too. True even of a mirroring matrix — its determinant is negative, but that scale, a vector
+     *    length, is not.
+     *
+     * A transform that was never successfully inverted — a singular matrix, or a shape whose
+     * `transform` was never set — leaves the cached inverse zeroed, and the mapped direction with it;
+     * that is reported as a miss rather than propagated onward as NaN. Note the narrower case this
+     * does NOT rescue: {@link m4_invert} leaves a PREVIOUS inverse in place when it refuses, so a
+     * shape handed a singular transform after a good one goes on casting against the older one. That
+     * hazard belongs to every method here that reads the cached inverse, not to this one.
+     *
+     * The physics ray query does not come through here; it uses `refine_ray_transformed`, which does
+     * the same mapping on loose scalars and, reporting a distance rather than a point, divides that
+     * distance by the stretch factor instead of pushing a point through the matrix.
+     *
+     * @param {Float32Array|number[]} hit out: [px, py, pz, nx, ny, nz]
+     * @param {Ray3} ray wrapper-frame ray (origin in [0..2], unit direction in [3..5], tMax in [6])
+     * @returns {boolean} whether anything was hit
+     */
+    raycast(hit, ray) {
+        const subject = this.__subject;
+
+        if (subject === null) {
+            return false;
+        }
+
+        const inverse = this.__inverse_matrix;
+
+        // Direction takes the linear part only, so it is written out rather than run through
+        // v3_matrix4_multiply — and its length is needed anyway.
+        const dx = ray[3], dy = ray[4], dz = ray[5];
+
+        const sdx = inverse[0] * dx + inverse[4] * dy + inverse[8] * dz;
+        const sdy = inverse[1] * dx + inverse[5] * dy + inverse[9] * dz;
+        const sdz = inverse[2] * dx + inverse[6] * dy + inverse[10] * dz;
+
+        // How much longer one unit of travel here is in the subject's frame.
+        const scale = Math.sqrt(sdx * sdx + sdy * sdy + sdz * sdz);
+
+        if (!(scale > 0)) {
+            // Singular (or never-inverted) transform: the direction has no image to cast along.
+            return false;
+        }
+
+        const inv_scale = 1 / scale;
+
+        // Allocated per call rather than kept as a module scratch: a transformed shape may wrap another
+        // wrapper, and every level of that recursion needs its own sub-ray alive across the call below.
+        const subject_ray = new Ray3();
+
+        v3_matrix4_multiply(subject_ray, 0, ray, 0, inverse);
+
+        subject_ray[3] = sdx * inv_scale;
+        subject_ray[4] = sdy * inv_scale;
+        subject_ray[5] = sdz * inv_scale;
+        subject_ray[6] = ray[6] * scale;
+
+        if (!subject.raycast(hit, subject_ray)) {
+            return false;
+        }
+
+        // Point: the full forward transform, in place. v3_matrix4_multiply reads all three components
+        // before writing any, so `hit` may be both its source and its destination.
+        v3_matrix4_multiply(hit, 0, hit, 0, this.__matrix);
+
+        // Normal: (M⁻¹)ᵀ · n, then renormalised.
+        const nx = hit[3], ny = hit[4], nz = hit[5];
+
+        const wx = inverse[0] * nx + inverse[1] * ny + inverse[2] * nz;
+        const wy = inverse[4] * nx + inverse[5] * ny + inverse[6] * nz;
+        const wz = inverse[8] * nx + inverse[9] * ny + inverse[10] * nz;
+
+        const inv_length = 1 / Math.sqrt(wx * wx + wy * wy + wz * wz);
+
+        hit[3] = wx * inv_length;
+        hit[4] = wy * inv_length;
+        hit[5] = wz * inv_length;
+
+        return true;
+    }
+
     /**
      *
      * @param {TransformedShape3D} other

package/src/core/geom/3d/shape/UnionShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UnionShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnionShape3D.js"],"names":[],"mappings":"AA2BA;IAkII;;;;OAIG;IACH,sBAHW,eAAe,EAAE,GACf,YAAY,CAYxB;IAhJD;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,kCAA+B;IAE/B,qBAAkB;IAClB,qBAAmB;IACnB,uBAAqB;IAErB,wCAgCC;IAED;;;OAGG;IACH,mCAkBC;IAED;;;OAGG;IACH,2CA+CC;IA2DD,mEAEC;IAED,6CAaC;IAED,oCAYC;IAED,kFAoDC;IAED,qGAyBC;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;IA6BL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;CApBpC;gCArV+B,sBAAsB"}
+{"version":3,"file":"UnionShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnionShape3D.js"],"names":[],"mappings":"AA4BA;IAkII;;;;OAIG;IACH,sBAHW,eAAe,EAAE,GACf,YAAY,CAYxB;IAhJD;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,kCAA+B;IAE/B,qBAAkB;IAClB,qBAAmB;IACnB,uBAAqB;IAErB,wCAgCC;IAED;;;OAGG;IACH,mCAkBC;IAED;;;OAGG;IACH,2CA+CC;IA2DD,mEAEC;IAED,6CAaC;IAED,oCAYC;IAED,kFAoDC;IAED,qGAyBC;IAiED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;IA6BL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;CApBpC;gCApZ+B,sBAAsB"}