@woosh/meep-engine 2.138.20 → 2.140.0

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

@@ -0,0 +1,38 @@
+/**
+ * Closed-form contact generation for a unit sphere vs. an oriented box.
+ *
+ * Algorithm: transform the sphere centre into the box's body frame, clamp it
+ * to the box's half-extents to get the closest surface point in body space,
+ * measure the distance, and (when overlapping) rotate the resulting normal
+ * and surface point back into world.
+ *
+ * Singular cases:
+ *  - If the sphere centre is inside the box (distance == 0 in body frame),
+ *    the closest-face vector is undefined; we pick the smallest-overlap face
+ *    direction as a deterministic tie-break.
+ *
+ * Output convention (mirrors {@link sphere_sphere_contact}): the normal in
+ * `out[0..2]` points from the box surface toward the sphere centre; `out[3]`
+ * is the (positive) penetration depth; `out[4..6]` is the world-space contact
+ * point on the sphere's surface; `out[7..9]` is the world-space contact point
+ * on the box's surface.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @param {number} sx sphere centre x
+ * @param {number} sy
+ * @param {number} sz
+ * @param {number} radius
+ * @param {number} bx box centre x
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} bqx box rotation quaternion x
+ * @param {number} bqy
+ * @param {number} bqz
+ * @param {number} bqw
+ * @param {number} hx box half-extent x (body frame)
+ * @param {number} hy
+ * @param {number} hz
+ * @returns {boolean} true if overlap
+ */
+export function sphere_box_contact(out: number[] | Float64Array, sx: number, sy: number, sz: number, radius: number, bx: number, by: number, bz: number, bqx: number, bqy: number, bqz: number, bqw: number, hx: number, hy: number, hz: number): boolean;
+//# sourceMappingURL=sphere_box_contact.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,123 @@
+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.
+ *
+ * Algorithm: transform the sphere centre into the box's body frame, clamp it
+ * to the box's half-extents to get the closest surface point in body space,
+ * measure the distance, and (when overlapping) rotate the resulting normal
+ * and surface point back into world.
+ *
+ * Singular cases:
+ *  - If the sphere centre is inside the box (distance == 0 in body frame),
+ *    the closest-face vector is undefined; we pick the smallest-overlap face
+ *    direction as a deterministic tie-break.
+ *
+ * Output convention (mirrors {@link sphere_sphere_contact}): the normal in
+ * `out[0..2]` points from the box surface toward the sphere centre; `out[3]`
+ * is the (positive) penetration depth; `out[4..6]` is the world-space contact
+ * point on the sphere's surface; `out[7..9]` is the world-space contact point
+ * on the box's surface.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @param {number} sx sphere centre x
+ * @param {number} sy
+ * @param {number} sz
+ * @param {number} radius
+ * @param {number} bx box centre x
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} bqx box rotation quaternion x
+ * @param {number} bqy
+ * @param {number} bqz
+ * @param {number} bqw
+ * @param {number} hx box half-extent x (body frame)
+ * @param {number} hy
+ * @param {number} hz
+ * @returns {boolean} true if overlap
+ */
+export function sphere_box_contact(
+    out,
+    sx, sy, sz, radius,
+    bx, by, bz,
+    bqx, bqy, bqz, bqw,
+    hx, hy, hz
+) {
+    // Step 1: bring the sphere centre into box-local space via the conjugate
+    // quaternion. v_local = q* · (s - b) · q
+    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);
+    const cly = ly < -hy ? -hy : (ly > hy ? hy : ly);
+    const clz = lz < -hz ? -hz : (lz > hz ? hz : lz);
+
+    const inside = clx === lx && cly === ly && clz === lz;
+
+    let nlx, nly, nlz, dist;
+    if (!inside) {
+        // Centre is outside the box: normal is from clamped point toward centre.
+        const ex = lx - clx, ey = ly - cly, ez = lz - clz;
+        const dist_sqr = ex * ex + ey * ey + ez * ez;
+        if (dist_sqr >= radius * radius) {
+            return false;
+        }
+        dist = Math.sqrt(dist_sqr);
+        if (dist > 0) {
+            const inv = 1 / dist;
+            nlx = ex * inv; nly = ey * inv; nlz = ez * inv;
+        } else {
+            // Centre lies exactly on a face — pick +X as a tie-break.
+            nlx = 1; nly = 0; nlz = 0;
+        }
+    } else {
+        // Centre is inside the box. Closest face is the one we're nearest to.
+        // Compute the per-axis "distance to face" (positive); pick min.
+        const dx_face = hx - Math.abs(lx);
+        const dy_face = hy - Math.abs(ly);
+        const dz_face = hz - Math.abs(lz);
+
+        // Pick smallest depth-to-face; ties broken X > Y > Z (deterministic).
+        if (dx_face <= dy_face && dx_face <= dz_face) {
+            nlx = lx >= 0 ? 1 : -1; nly = 0; nlz = 0;
+            dist = -dx_face;
+        } else if (dy_face <= dz_face) {
+            nlx = 0; nly = ly >= 0 ? 1 : -1; nlz = 0;
+            dist = -dy_face;
+        } else {
+            nlx = 0; nly = 0; nlz = lz >= 0 ? 1 : -1;
+            dist = -dz_face;
+        }
+    }
+
+    // Step 3: rotate normal and surface point back to world. v_world = q · v · q*
+
+    // World normal (box → sphere).
+    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;
+
+    // World contact on sphere = sphere_center - normal * radius.
+    out[4] = sx - nx * radius;
+    out[5] = sy - ny * radius;
+    out[6] = sz - nz * radius;
+
+    // World contact on box: rotate the local-space clamped point to world, plus box centre.
+    v3_quat3_apply(out, 7, clx, cly, clz, bqx, bqy, bqz, bqw);
+    out[7] += bx;
+    out[8] += by;
+    out[9] += bz;
+
+    return true;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Closed-form contact generation for two unit spheres positioned in world
+ * space. Returns whether the spheres overlap. On overlap, `out` is populated
+ * with `[nx, ny, nz, depth]` where the normal points from B toward A and
+ * `depth` is the positive penetration distance.
+ *
+ * Both spheres have radius 1 (the {@link UnitSphereShape3D} convention); any
+ * scaling on the body's transform is irrelevant under our "no scale on
+ * physics transforms" assumption.
+ *
+ * Centres-coincident is a singular case for the general normal but is
+ * resolved here by picking +X as a deterministic tie-break direction.
+ *
+ * @param {number[]|Float64Array} out length >= 4
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} radius_a
+ * @param {number} radius_b
+ * @returns {boolean} true if spheres overlap
+ */
+export function sphere_sphere_contact(out: number[] | Float64Array, ax: number, ay: number, az: number, bx: number, by: number, bz: number, radius_a: number, radius_b: number): boolean;
+//# sourceMappingURL=sphere_sphere_contact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sphere_sphere_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_sphere_contact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,2CAXW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,YACN,MAAM,YACN,MAAM,GACJ,OAAO,CA4BnB"}

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

@@ -0,0 +1,51 @@
+/**
+ * Closed-form contact generation for two unit spheres positioned in world
+ * space. Returns whether the spheres overlap. On overlap, `out` is populated
+ * with `[nx, ny, nz, depth]` where the normal points from B toward A and
+ * `depth` is the positive penetration distance.
+ *
+ * Both spheres have radius 1 (the {@link UnitSphereShape3D} convention); any
+ * scaling on the body's transform is irrelevant under our "no scale on
+ * physics transforms" assumption.
+ *
+ * Centres-coincident is a singular case for the general normal but is
+ * resolved here by picking +X as a deterministic tie-break direction.
+ *
+ * @param {number[]|Float64Array} out length >= 4
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} radius_a
+ * @param {number} radius_b
+ * @returns {boolean} true if spheres overlap
+ */
+export function sphere_sphere_contact(out, ax, ay, az, bx, by, bz, radius_a, radius_b) {
+    const dx = ax - bx;
+    const dy = ay - by;
+    const dz = az - bz;
+    const dist_sqr = dx * dx + dy * dy + dz * dz;
+
+    const sum = radius_a + radius_b;
+    if (dist_sqr >= sum * sum) {
+        return false;
+    }
+
+    const dist = Math.sqrt(dist_sqr);
+    if (dist > 0) {
+        const inv = 1 / dist;
+        out[0] = dx * inv;
+        out[1] = dy * inv;
+        out[2] = dz * inv;
+    } else {
+        // Centres coincide. Pick +X deterministically (no RNG); penetration is
+        // the full sum of radii.
+        out[0] = 1;
+        out[1] = 0;
+        out[2] = 0;
+    }
+    out[3] = sum - dist;
+    return true;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Result of a {@link PhysicsSystem} query that resolves to a single surface
+ * contact — raycast hit, sphere overlap nearest-point, shape-cast first
+ * blocker, etc.
+ *
+ * The class is an *output parameter*: callers pre-allocate one (or pull one
+ * from a frame-pool) and pass it into the query. The query writes the fields
+ * on hit and returns `true`; on miss it returns `false` and leaves the
+ * fields untouched.
+ *
+ * Pre-allocation matters because a query that gets called every frame (a
+ * ground sensor, a hover beam) would otherwise drop a small object on the
+ * GC per call. Reusing the same `PhysicsSurfacePoint` keeps that allocation
+ * out of the hot path.
+ *
+ * Field layout chosen to match what gameplay code typically needs:
+ *   - `position` — world-space point on the surface
+ *   - `normal` — surface normal at that point (broadphase queries return
+ *     the AABB face normal as an approximation; narrowphase-refined queries
+ *     would return the true shape normal at the same call site)
+ *   - `t` — distance along the input ray, sphere-cast, etc. Useful when the
+ *     caller wants to interpolate or step along the query primitive
+ *     (`origin + t·direction` reconstructs the hit point exactly without
+ *     reading `position`, which the deferred-execution physics events bus
+ *     would otherwise need to copy).
+ *   - `entity` — entity id that owns the hit body
+ *   - `body_id` — packed body id (index << 8 | generation); stale after the
+ *     body is unlinked, so prefer `entity` for any cross-frame retention.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PhysicsSurfacePoint {
+    /**
+     * World-space point on the hit surface.
+     * @readonly
+     * @type {Vector3}
+     */
+    readonly position: Vector3;
+    /**
+     * Surface normal at {@link position}, unit length. For broadphase-only
+     * queries this is the AABB face normal (axis-aligned), which is exact
+     * for AABB-shaped colliders and a stable approximation otherwise.
+     * @readonly
+     * @type {Vector3}
+     */
+    readonly normal: Vector3;
+    /**
+     * Parametric distance from the query origin to {@link position}, in
+     * the same units as the input direction's magnitude (so for a unit-
+     * length ray direction this is metres).
+     * @type {number}
+     */
+    t: number;
+    /**
+     * Entity that owns the hit body, or `-1` if no body owns it.
+     * @type {number}
+     */
+    entity: number;
+    /**
+     * Packed body id (index << 8 | generation). Goes stale once the body
+     * is unlinked from the {@link PhysicsSystem}; prefer {@link entity}
+     * for any cross-frame use.
+     * @type {number}
+     */
+    body_id: number;
+    /**
+     * Reset to a "no hit" state. Optional — the query convention is that the
+     * fields are only meaningful when the call returns `true`, so callers
+     * that always branch on the return value don't need to reset. Useful for
+     * debugger inspection and for tests that want to verify the query
+     * doesn't accidentally touch the result on miss.
+     */
+    reset(): void;
+    /**
+     * Fast type-check marker.
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isPhysicsSurfacePoint: boolean;
+}
+import Vector3 from "../../../core/geom/Vector3.js";
+//# sourceMappingURL=PhysicsSurfacePoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PhysicsSurfacePoint.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/PhysicsSurfacePoint.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH;IAGQ;;;;OAIG;IACH,mBAFU,OAAO,CAEY;IAE7B;;;;;;OAMG;IACH,iBAFU,OAAO,CAEU;IAE3B;;;;;OAKG;IACH,GAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,SAFU,MAAM,CAEC;IAGrB;;;;;;OAMG;IACH,cAQC;IAGL;;;;OAIG;IACH,gCAFU,OAAO,CAEkC;CAPlD;oBA5FmB,+BAA+B"}

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

@@ -0,0 +1,100 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+
+/**
+ * Result of a {@link PhysicsSystem} query that resolves to a single surface
+ * contact — raycast hit, sphere overlap nearest-point, shape-cast first
+ * blocker, etc.
+ *
+ * The class is an *output parameter*: callers pre-allocate one (or pull one
+ * from a frame-pool) and pass it into the query. The query writes the fields
+ * on hit and returns `true`; on miss it returns `false` and leaves the
+ * fields untouched.
+ *
+ * Pre-allocation matters because a query that gets called every frame (a
+ * ground sensor, a hover beam) would otherwise drop a small object on the
+ * GC per call. Reusing the same `PhysicsSurfacePoint` keeps that allocation
+ * out of the hot path.
+ *
+ * Field layout chosen to match what gameplay code typically needs:
+ *   - `position` — world-space point on the surface
+ *   - `normal` — surface normal at that point (broadphase queries return
+ *     the AABB face normal as an approximation; narrowphase-refined queries
+ *     would return the true shape normal at the same call site)
+ *   - `t` — distance along the input ray, sphere-cast, etc. Useful when the
+ *     caller wants to interpolate or step along the query primitive
+ *     (`origin + t·direction` reconstructs the hit point exactly without
+ *     reading `position`, which the deferred-execution physics events bus
+ *     would otherwise need to copy).
+ *   - `entity` — entity id that owns the hit body
+ *   - `body_id` — packed body id (index << 8 | generation); stale after the
+ *     body is unlinked, so prefer `entity` for any cross-frame retention.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PhysicsSurfacePoint {
+
+    constructor() {
+        /**
+         * World-space point on the hit surface.
+         * @readonly
+         * @type {Vector3}
+         */
+        this.position = new Vector3();
+
+        /**
+         * Surface normal at {@link position}, unit length. For broadphase-only
+         * queries this is the AABB face normal (axis-aligned), which is exact
+         * for AABB-shaped colliders and a stable approximation otherwise.
+         * @readonly
+         * @type {Vector3}
+         */
+        this.normal = new Vector3();
+
+        /**
+         * Parametric distance from the query origin to {@link position}, in
+         * the same units as the input direction's magnitude (so for a unit-
+         * length ray direction this is metres).
+         * @type {number}
+         */
+        this.t = 0;
+
+        /**
+         * Entity that owns the hit body, or `-1` if no body owns it.
+         * @type {number}
+         */
+        this.entity = -1;
+
+        /**
+         * Packed body id (index << 8 | generation). Goes stale once the body
+         * is unlinked from the {@link PhysicsSystem}; prefer {@link entity}
+         * for any cross-frame use.
+         * @type {number}
+         */
+        this.body_id = -1;
+    }
+
+    /**
+     * Reset to a "no hit" state. Optional — the query convention is that the
+     * fields are only meaningful when the call returns `true`, so callers
+     * that always branch on the return value don't need to reset. Useful for
+     * debugger inspection and for tests that want to verify the query
+     * doesn't accidentally touch the result on miss.
+     */
+    reset() {
+        const p = this.position;
+        const n = this.normal;
+        p[0] = 0; p[1] = 0; p[2] = 0;
+        n[0] = 0; n[1] = 0; n[2] = 0;
+        this.t = 0;
+        this.entity = -1;
+        this.body_id = -1;
+    }
+}
+
+/**
+ * Fast type-check marker.
+ * @readonly
+ * @type {boolean}
+ */
+PhysicsSurfacePoint.prototype.isPhysicsSurfacePoint = true;