@woosh/meep-engine 2.141.0 → 2.143.0

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

@@ -8,42 +8,67 @@ import {
 } 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";
+import { refine_ray_hit, RAY_REFINE_UNSUPPORTED } from "../narrowphase/refine_ray_hit.js";
 
 const stack = SCRATCH_UINT32_TRAVERSAL_STACK;
 
 /**
- * Walk a single BVH along a ray and update the running nearest hit.
+ * Reusable nearest-hit accumulator + scratch. 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}}
+ */
+const acc = { best_t: Infinity, best_body: 0 };
+const best_normal = new Float64Array(3); // winning hit's world normal
+const cand_normal = new Float64Array(3); // per-leaf candidate normal
+
+/**
+ * Outward AABB-face normal at a hit point — the fallback normal for a leaf
+ * whose shape has no exact ray test (composite convex). The hit point is
+ * projected into the AABB's normalised local space (centre = 0, faces = ±1);
+ * the dominant component's axis is the entry face and its sign the outward
+ * normal.
+ */
+function aabb_face_normal(out, min_x, min_y, min_z, max_x, max_y, max_z, hx, hy, hz) {
+    const cx = (min_x + max_x) * 0.5;
+    const cy = (min_y + max_y) * 0.5;
+    const cz = (min_z + max_z) * 0.5;
+    const px = (hx - cx) * 2 / (max_x - min_x);
+    const py = (hy - cy) * 2 / (max_y - min_y);
+    const pz = (hz - cz) * 2 / (max_z - min_z);
+    const apx = px < 0 ? -px : px;
+    const apy = py < 0 ? -py : py;
+    const apz = pz < 0 ? -pz : pz;
+    if (apx >= apy && apx >= apz) { out[0] = px >= 0 ? 1 : -1; out[1] = 0; out[2] = 0; }
+    else if (apy >= apz) { out[0] = 0; out[1] = py >= 0 ? 1 : -1; out[2] = 0; }
+    else { out[0] = 0; out[1] = 0; out[2] = pz >= 0 ? 1 : -1; }
+}
+
+/**
+ * Walk a single BVH along a ray, refining each crossing leaf against its true
+ * shape geometry and keeping the nearest confirmed hit.
  *
- * Hit refinement is broadphase-only: the returned `t` is the distance to
- * the inflated leaf AABB. Narrowphase shape refinement is a follow-up.
+ * Pruning stays on the *inflated leaf AABB* entry distance `t_near`: a shape
+ * hit is always at or beyond its tight AABB entry, which is at or beyond the
+ * inflated-AABB entry, so a subtree whose AABB entry is past the current best
+ * cannot contain a closer hit. A leaf whose ray crosses the fat AABB but misses
+ * the true shape contributes nothing — the correctness gain over broadphase.
  *
- * @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 {BVH} bvh @param {number} root
+ * @param {PhysicsSystem} system
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (unit)
+ * @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
+ * @param {(entity:number, collider:Collider)=>boolean} filter
  */
 function bvh_raycast_nearest(
-    bvh, root,
-    ox, oy, oz,
-    dx, dy, dz,
+    bvh, root, system,
+    ox, oy, oz, dx, dy, dz,
     inv_dx, inv_dy, inv_dz,
-    max_distance,
-    acc,
-    test
+    max_distance, filter
 ) {
-    if (root === NULL_NODE) {
-        return;
-    }
+    if (root === NULL_NODE) return;
 
     const float32 = bvh.__data_float32;
     const uint32 = bvh.__data_uint32;
@@ -66,181 +91,105 @@ function bvh_raycast_nearest(
         );
 
         // No intersection or this subtree can't beat the best known hit — prune.
-        if (t_near >= acc.best_t) {
-            continue;
-        }
+        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)) {
+            continue;
+        }
+
+        // Leaf — refine against the true shape.
+        const body_id = uint32[address + COLUMN_USER_DATA];
+        const entity = system.entityOf(body_id);
+        if (entity < 0) continue; // unlinked concurrently
+        const idx = system.__index_of(body_id);
+        const collider = system.__primary_collider(idx);
+        if (collider === null) continue;
+        if (!filter(entity, collider)) continue;
+
+        const tr = system.__transforms[idx];
+        const refined = refine_ray_hit(
+            collider.shape, tr.position, tr.rotation,
+            ox, oy, oz, dx, dy, dz, acc.best_t, cand_normal
+        );
+
+        if (refined === RAY_REFINE_UNSUPPORTED) {
+            // No exact ray test for this shape — keep the broadphase AABB hit.
+            if (t_near < acc.best_t) {
                 acc.best_t = t_near;
                 acc.best_body = body_id;
-                acc.best_node = node;
-                acc.best_bvh = bvh;
+                aabb_face_normal(best_normal,
+                    float32[address], float32[address + 1], float32[address + 2],
+                    float32[address + 3], float32[address + 4], float32[address + 5],
+                    ox + dx * t_near, oy + dy * t_near, oz + dz * t_near);
             }
+        } else if (refined < acc.best_t) { // a refined miss is Infinity → never wins
+            acc.best_t = refined;
+            acc.best_body = body_id;
+            best_normal[0] = cand_normal[0];
+            best_normal[1] = cand_normal[1];
+            best_normal[2] = cand_normal[2];
         }
     }
 
     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.
+ * {@link PhysicsSystem}, refined against each candidate's true shape geometry.
+ * Fills `result` with the nearest hit and returns `true` on hit, `false` on
+ * miss. `result.t` is the exact surface distance and `result.normal` the true
+ * surface normal for sphere / box / capsule / mesh / heightmap colliders;
+ * composite convex shapes (no exact ray test yet) fall back to the broadphase
+ * AABB hit + AABB-face normal.
  *
- * 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).
+ * Multi-collider bodies resolve their primary (first-attached) collider — the
+ * BVH leaf encodes only `body_id`; per-collider rays need the leaf user-data to
+ * carry the collider index (future work).
  *
  * @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.
+ * @param {(entity:number, collider:Collider)=>boolean} [filter] called once per
+ *   crossing leaf; defaults to {@link returnTrue}.
  * @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 ox = ray.origin_x, oy = ray.origin_y, oz = ray.origin_z;
+    const dx = ray.direction_x, dy = ray.direction_y, 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;
+    best_normal[0] = 0; best_normal[1] = 0; best_normal[2] = 0;
 
-    bound_system = system;
-    bound_filter = filter;
-
-    const inv_dx = 1 / dx;
-    const inv_dy = 1 / dy;
-    const inv_dz = 1 / dz;
+    const inv_dx = 1 / dx, inv_dy = 1 / dy, 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
+        system.staticBvh, system.staticBvh.root, system,
+        ox, oy, oz, dx, dy, dz, inv_dx, inv_dy, inv_dz, max_distance, filter
     );
-
     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
+        system.dynamicBvh, system.dynamicBvh.root, system,
+        ox, oy, oz, dx, dy, dz, inv_dx, inv_dy, inv_dz, max_distance, filter
     );
 
-    if (acc.best_bvh === null || acc.best_t >= max_distance) {
-        return false;
-    }
+    // Any hit updates best_t to strictly below max_distance (both the refined
+    // and AABB-fallback paths require t < current best); a miss leaves it at
+    // max_distance. This is body_id-agnostic — the first body packs to id 0.
+    if (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;
-    }
+    if (entity < 0) return false; // body unlinked concurrently → treat as miss
 
-    // 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;
+    rp[0] = ox + dx * t; rp[1] = oy + dy * t; rp[2] = oz + dz * t;
+    rn[0] = best_normal[0]; rn[1] = best_normal[1]; rn[2] = best_normal[2];
     result.t = t;
     result.entity = entity;
     result.body_id = acc.best_body;

package/src/engine/physics/vehicle/RaycastVehicle.d.ts

@@ -0,0 +1,114 @@
+/**
+ * One wheel's config + per-frame runtime state. The runtime fields
+ * (`inContact`, `compression`, contact point/normal, `rotation`, …) are read by
+ * rendering / gameplay; do not write them.
+ */
+export class Wheel {
+    /** Mount point on the chassis, local. @type {Float64Array} */
+    localPosition: Float64Array;
+    /** Suspension direction (local, unit, points "down"). @type {Float64Array} */
+    localSuspensionDir: Float64Array;
+    /** Forward / rolling direction (local, unit). @type {Float64Array} */
+    localForward: Float64Array;
+    suspensionRestLength: number;
+    suspensionStiffness: number;
+    suspensionDamping: number;
+    suspensionMaxForce: number;
+    radius: number;
+    friction: number;
+    steered: boolean;
+    driven: boolean;
+    inContact: boolean;
+    suspensionLength: number;
+    compression: number;
+    /** World contact point. @type {Float64Array} */
+    contactPoint: Float64Array;
+    /** World contact normal. @type {Float64Array} */
+    contactNormal: Float64Array;
+    /** Body id of the surface under the wheel, or −1. */
+    contactBodyId: number;
+    /** Current steering angle (rad), set via {@link RaycastVehicle#setSteering}. */
+    steering: number;
+    /** Accumulated spin angle (rad) for rendering. */
+    rotation: number;
+    /** Forward ground speed at the contact (m/s). */
+    forwardSpeed: number;
+    /** Suspension force magnitude applied this frame (N). */
+    suspensionForce: number;
+}
+export class RaycastVehicle {
+    /**
+     * @param {PhysicsSystem} system
+     * @param {RigidBody} chassisBody  the chassis rigid body (Dynamic)
+     * @param {Transform} chassisTransform  its world transform
+     */
+    constructor(system: PhysicsSystem, chassisBody: RigidBody, chassisTransform: Transform);
+    system: PhysicsSystem;
+    chassisBody: RigidBody;
+    chassisTransform: Transform;
+    /** @type {Wheel[]} */
+    wheels: Wheel[];
+    __driveForce: number;
+    __brakeForce: number;
+    __drivenCount: number;
+    __ray: Ray3;
+    __hit: PhysicsSurfacePoint;
+    __filter: (entity: any, collider: any) => boolean;
+    __force: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    __point: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * Add a wheel. Returns the created {@link Wheel} (also pushed to
+     * {@link wheels}); set any further config fields on it before stepping.
+     *
+     * @param {object} opts
+     * @param {number[]} opts.localPosition  mount point on the chassis, local.
+     * @param {number[]} [opts.localSuspensionDir]  unit "down", default (0,−1,0).
+     * @param {number[]} [opts.localForward]  unit rolling dir, default (0,0,1).
+     * @param {number} [opts.suspensionRestLength]
+     * @param {number} [opts.suspensionStiffness]  N/m.
+     * @param {number} [opts.suspensionDamping]  N·s/m.
+     * @param {number} [opts.suspensionMaxForce]  N (clamp).
+     * @param {number} [opts.radius]
+     * @param {number} [opts.friction]  tyre friction coefficient μ.
+     * @param {boolean} [opts.steered]
+     * @param {boolean} [opts.driven]
+     * @returns {Wheel}
+     */
+    addWheel(opts: {
+        localPosition: number[];
+        localSuspensionDir?: number[];
+        localForward?: number[];
+        suspensionRestLength?: number;
+        suspensionStiffness?: number;
+        suspensionDamping?: number;
+        suspensionMaxForce?: number;
+        radius?: number;
+        friction?: number;
+        steered?: boolean;
+        driven?: boolean;
+    }): Wheel;
+    /** Set the steering angle (rad) on every steered wheel. */
+    setSteering(angle: any): void;
+    /** Total engine drive force (N), split evenly across the driven wheels. */
+    setDriveForce(force: any): void;
+    /** Brake force (N) per wheel, opposing each wheel's forward motion. */
+    setBrake(force: any): void;
+    /**
+     * Step the vehicle: cast suspension rays, apply suspension + tyre forces.
+     * Call once per frame **before** `PhysicsSystem.fixedUpdate(dt)` with the
+     * same `dt`.
+     * @param {number} dt
+     */
+    update(dt: number): void;
+}
+import { Ray3 } from "../../../core/geom/3d/ray/Ray3.js";
+import { PhysicsSurfacePoint } from "../queries/PhysicsSurfacePoint.js";
+//# sourceMappingURL=RaycastVehicle.d.ts.map

package/src/engine/physics/vehicle/RaycastVehicle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RaycastVehicle.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/vehicle/RaycastVehicle.js"],"names":[],"mappings":"AAyEA;;;;GAIG;AACH;IAGQ,8DAA8D;IAC9D,eAD8C,YAAY,CAClB;IACxC,8EAA8E;IAC9E,oBAD8D,YAAY,CACnB;IACvD,sEAAsE;IACtE,cADsD,YAAY,CAClB;IAChD,6BAA+B;IAC/B,4BAA8B;IAC9B,0BAA2B;IAC3B,2BAAkC;IAClC,eAAiB;IACjB,iBAAmB;IACnB,iBAAoB;IACpB,gBAAmB;IAGnB,mBAAsB;IACtB,yBAAiD;IACjD,oBAAoB;IACpB,gDAAgD;IAChD,cADgC,YAAY,CACL;IACvC,iDAAiD;IACjD,eADiC,YAAY,CACI;IACjD,qDAAqD;IACrD,sBAAuB;IACvB,gFAAgF;IAChF,iBAAiB;IACjB,kDAAkD;IAClD,iBAAiB;IACjB,iDAAiD;IACjD,qBAAqB;IACrB,yDAAyD;IACzD,wBAAwB;CAE/B;AAED;IACI;;;;OAIG;IACH,wFAoBC;IAnBG,sBAAoB;IACpB,uBAA8B;IAC9B,4BAAwC;IAExC,sBAAsB;IACtB,QADW,KAAK,EAAE,CACF;IAEhB,qBAAqB;IACrB,qBAAqB;IACrB,sBAAsB;IAEtB,YAAuB;IACvB,2BAAsC;IAEtC,kDAAmF;IAGnF;;;;MAAmC;IACnC;;;;MAAmC;IAGvC;;;;;;;;;;;;;;;;;OAiBG;IACH;QAb0B,aAAa,EAA5B,MAAM,EAAE;QACQ,kBAAkB,GAAlC,MAAM,EAAE;QACQ,YAAY,GAA5B,MAAM,EAAE;QACM,oBAAoB,GAAlC,MAAM;QACQ,mBAAmB,GAAjC,MAAM;QACQ,iBAAiB,GAA/B,MAAM;QACQ,kBAAkB,GAAhC,MAAM;QACQ,MAAM,GAApB,MAAM;QACQ,QAAQ,GAAtB,MAAM;QACS,OAAO,GAAtB,OAAO;QACQ,MAAM,GAArB,OAAO;QACL,KAAK,CA0BjB;IAED,2DAA2D;IAC3D,8BAIC;IAED,2EAA2E;IAC3E,gCAAmD;IAEnD,uEAAuE;IACvE,2BAA8C;IAE9C;;;;;OAKG;IACH,WAFW,MAAM,QA6HhB;CACJ;qBA5UoB,mCAAmC;oCACpB,mCAAmC"}