@woosh/meep-engine 2.153.0 → 2.155.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.153.0",
+  "version": "2.155.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

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

@@ -0,0 +1,112 @@
+/**
+ * Convex polyhedron collider.
+ *
+ * Holds a convex triangle surface (`vertices` + outward-CCW `indices`) and the
+ * derived face half-spaces. Because it is convex (`is_convex === true`, the
+ * default), it routes straight through the narrowphase's GJK + EPA path via
+ * {@link support} — no tetrahedralisation, no per-triangle decomposition, no
+ * BVH. This is the right shape for authored convex geometry (props, crates,
+ * gems, low-poly rocks, an icosphere) and is far cheaper to construct than
+ * {@link MeshShape3D}, which tetrahedralises its interior.
+ *
+ * Contract:
+ *   - `support` is exact for any convex point set (deepest vertex along the
+ *     direction) — the precondition GJK relies on.
+ *   - `contains_point` is the convex half-space test (behind every face plane).
+ *   - `signed_distance` / `nearest_point_on_surface` scan the surface triangles
+ *     (O(F)); these are query-path helpers, not on the collision hot path.
+ *
+ * The input is assumed convex with outward-facing CCW winding — build it via
+ * {@link ConvexHullShape3D.from}. A genuine non-convex mesh belongs in
+ * {@link MeshShape3D} (and, once decomposition lands, will be represented as a
+ * set of these pieces).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ConvexHullShape3D extends AbstractShape3D {
+    /**
+     * Build from a convex triangle surface. Vertices must lie on the hull and
+     * faces must wind CCW when viewed from outside.
+     *
+     * @param {Float32Array} vertices flat `(x, y, z)` per vertex
+     * @param {Uint32Array}  indices  three uint32 per triangle, outward CCW
+     * @returns {ConvexHullShape3D}
+     */
+    static from(vertices: Float32Array, indices: Uint32Array): ConvexHullShape3D;
+    /**
+     * Hull vertex positions, flat `(x, y, z)` per vertex, in the body's
+     * local frame. Fed to {@link support}.
+     * @type {Float32Array}
+     */
+    vertices: Float32Array;
+    /**
+     * Surface triangle indices, three uint32 per face (outward CCW). Used by
+     * the surface-scan query helpers (signed distance / nearest point).
+     * @type {Uint32Array}
+     */
+    indices: Uint32Array;
+    /**
+     * Polygon-face representation for the contact clipper (CSR): face `f`'s
+     * vertex loop is `face_loops[face_offsets[f] .. face_offsets[f+1]]`,
+     * ordered CCW (outward). Currently one triangle per face; a coplanar-merge
+     * pass will collapse coplanar triangles into larger polygon faces.
+     * @type {Uint32Array}
+     */
+    face_offsets: Uint32Array;
+    /** @type {Uint32Array} */
+    face_loops: Uint32Array;
+    /**
+     * Face half-spaces, four doubles per face `(nx, ny, nz, d)` with unit
+     * outward normal and `d = n · v` — point is inside iff `n · p − d ≤ 0`
+     * for every face. Derived in {@link recompute}.
+     * @private
+     * @type {Float64Array}
+     */
+    private __planes;
+    /** @private @type {Float64Array} */
+    private __bbox;
+    /** @private @type {number} */
+    private __volume;
+    /** @private @type {number} */
+    private __surface_area;
+    /**
+     * Refresh the cached bbox / face planes / volume / surface area from the
+     * current `vertices` / `indices`.
+     */
+    recompute(): void;
+    compute_bounding_box(result: any): void;
+    /**
+     * GJK support: the hull vertex furthest along the direction. Exact for a
+     * convex point set. Linear scan over the vertices — fine for the modest
+     * vertex counts of authored hulls; a hill-climb over vertex adjacency is
+     * the acceleration for very large hulls.
+     */
+    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    /**
+     * Convex half-space test: inside iff the point is behind (or on) every face
+     * plane. Exact for a convex polytope.
+     */
+    contains_point(point: any): boolean;
+    /**
+     * Unsigned nearest-surface distance via a per-triangle scan, signed by
+     * {@link contains_point}. Same approach as {@link MeshShape3D}; O(F).
+     */
+    signed_distance_at_point(point: any): number;
+    signed_distance_gradient_at_point(result: any, point: any): number;
+    nearest_point_on_surface(result: any, reference: any): void;
+    sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
+    /**
+     * @param {ConvexHullShape3D} other
+     * @returns {boolean}
+     */
+    equals(other: ConvexHullShape3D): boolean;
+    /**
+     * Fast type-check marker.
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isConvexHullShape3D: boolean;
+}
+import { AbstractShape3D } from "./AbstractShape3D.js";
+//# sourceMappingURL=ConvexHullShape3D.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ConvexHullShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/ConvexHullShape3D.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA+CI;;;;;;;OAOG;IACH,sBAJW,YAAY,WACZ,WAAW,GACT,iBAAiB,CAQ7B;IAxDG;;;;OAIG;IACH,UAFU,YAAY,CAEa;IAEnC;;;;OAIG;IACH,SAFU,WAAW,CAEY;IAEjC;;;;;;OAMG;IACH,cAFU,WAAW,CAEiB;IACtC,0BAA0B;IAC1B,YADW,WAAW,CACc;IAEpC;;;;;;OAMG;IACH,iBAAmC;IAEnC,oCAAoC;IACpC,eAAiC;IACjC,8BAA8B;IAC9B,iBAAiB;IACjB,8BAA8B;IAC9B,uBAAuB;IAmB3B;;;OAGG;IACH,kBAmDC;IAKD,wCAIC;IAED;;;;;OAKG;IACH,qGAgBC;IAED;;;OAGG;IACH,oCAgBC;IAED;;;OAGG;IACH,6CAwBC;IAED,mEAEC;IAED,4DAwBC;IAED,kFAmBC;IAED;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAanB;IAcL;;;;OAIG;IACH,8BAFU,OAAO,CAE8B;CAP9C;gCAxT+B,sBAAsB"}

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

@@ -0,0 +1,325 @@
+import { computeHashFloat } from "../../../primitives/numbers/computeHashFloat.js";
+import { computeTriangleClosestPointToPointBarycentric } from "../triangle/computeTriangleClosestPointToPointBarycentric.js";
+import { AbstractShape3D } from "./AbstractShape3D.js";
+import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
+
+/**
+ * Convex polyhedron collider.
+ *
+ * Holds a convex triangle surface (`vertices` + outward-CCW `indices`) and the
+ * derived face half-spaces. Because it is convex (`is_convex === true`, the
+ * default), it routes straight through the narrowphase's GJK + EPA path via
+ * {@link support} — no tetrahedralisation, no per-triangle decomposition, no
+ * BVH. This is the right shape for authored convex geometry (props, crates,
+ * gems, low-poly rocks, an icosphere) and is far cheaper to construct than
+ * {@link MeshShape3D}, which tetrahedralises its interior.
+ *
+ * Contract:
+ *   - `support` is exact for any convex point set (deepest vertex along the
+ *     direction) — the precondition GJK relies on.
+ *   - `contains_point` is the convex half-space test (behind every face plane).
+ *   - `signed_distance` / `nearest_point_on_surface` scan the surface triangles
+ *     (O(F)); these are query-path helpers, not on the collision hot path.
+ *
+ * The input is assumed convex with outward-facing CCW winding — build it via
+ * {@link ConvexHullShape3D.from}. A genuine non-convex mesh belongs in
+ * {@link MeshShape3D} (and, once decomposition lands, will be represented as a
+ * set of these pieces).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ConvexHullShape3D extends AbstractShape3D {
+
+    constructor() {
+        super();
+
+        /**
+         * Hull vertex positions, flat `(x, y, z)` per vertex, in the body's
+         * local frame. Fed to {@link support}.
+         * @type {Float32Array}
+         */
+        this.vertices = new Float32Array(0);
+
+        /**
+         * Surface triangle indices, three uint32 per face (outward CCW). Used by
+         * the surface-scan query helpers (signed distance / nearest point).
+         * @type {Uint32Array}
+         */
+        this.indices = new Uint32Array(0);
+
+        /**
+         * Polygon-face representation for the contact clipper (CSR): face `f`'s
+         * vertex loop is `face_loops[face_offsets[f] .. face_offsets[f+1]]`,
+         * ordered CCW (outward). Currently one triangle per face; a coplanar-merge
+         * pass will collapse coplanar triangles into larger polygon faces.
+         * @type {Uint32Array}
+         */
+        this.face_offsets = new Uint32Array(0);
+        /** @type {Uint32Array} */
+        this.face_loops = new Uint32Array(0);
+
+        /**
+         * Face half-spaces, four doubles per face `(nx, ny, nz, d)` with unit
+         * outward normal and `d = n · v` — point is inside iff `n · p − d ≤ 0`
+         * for every face. Derived in {@link recompute}.
+         * @private
+         * @type {Float64Array}
+         */
+        this.__planes = new Float64Array(0);
+
+        /** @private @type {Float64Array} */
+        this.__bbox = new Float64Array(6);
+        /** @private @type {number} */
+        this.__volume = 0;
+        /** @private @type {number} */
+        this.__surface_area = 0;
+    }
+
+    /**
+     * Build from a convex triangle surface. Vertices must lie on the hull and
+     * faces must wind CCW when viewed from outside.
+     *
+     * @param {Float32Array} vertices flat `(x, y, z)` per vertex
+     * @param {Uint32Array}  indices  three uint32 per triangle, outward CCW
+     * @returns {ConvexHullShape3D}
+     */
+    static from(vertices, indices) {
+        const s = new ConvexHullShape3D();
+        s.vertices = vertices;
+        s.indices = indices;
+        s.recompute();
+        return s;
+    }
+
+    /**
+     * Refresh the cached bbox / face planes / volume / surface area from the
+     * current `vertices` / `indices`.
+     */
+    recompute() {
+        const v = this.vertices;
+        const idx = this.indices;
+
+        let mnx = Infinity, mny = Infinity, mnz = Infinity;
+        let mxx = -Infinity, mxy = -Infinity, mxz = -Infinity;
+        const vc = v.length / 3;
+        for (let i = 0; i < vc; i++) {
+            const x = v[i * 3], y = v[i * 3 + 1], z = v[i * 3 + 2];
+            if (x < mnx) mnx = x; if (x > mxx) mxx = x;
+            if (y < mny) mny = y; if (y > mxy) mxy = y;
+            if (z < mnz) mnz = z; if (z > mxz) mxz = z;
+        }
+        if (vc === 0) { mnx = mny = mnz = mxx = mxy = mxz = 0; }
+        const b = this.__bbox;
+        b[0] = mnx; b[1] = mny; b[2] = mnz; b[3] = mxx; b[4] = mxy; b[5] = mxz;
+
+        const tri = idx.length / 3;
+        const planes = new Float64Array(tri * 4);
+        let area = 0;
+        let vol6 = 0; // 6× the signed volume (Σ a·(b×c) over outward faces)
+        for (let f = 0; f < tri; f++) {
+            const ia = idx[f * 3] * 3, ib = idx[f * 3 + 1] * 3, ic = idx[f * 3 + 2] * 3;
+            const ax = v[ia], ay = v[ia + 1], az = v[ia + 2];
+            const bx = v[ib], by = v[ib + 1], bz = v[ib + 2];
+            const cx = v[ic], cy = v[ic + 1], cz = v[ic + 2];
+
+            const e1x = bx - ax, e1y = by - ay, e1z = bz - az;
+            const e2x = cx - ax, e2y = cy - ay, e2z = cz - az;
+            let nx = e1y * e2z - e1z * e2y;
+            let ny = e1z * e2x - e1x * e2z;
+            let nz = e1x * e2y - e1y * e2x;
+            const len = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+            area += 0.5 * len;
+            vol6 += ax * (by * cz - bz * cy) + ay * (bz * cx - bx * cz) + az * (bx * cy - by * cx);
+
+            nx /= len; ny /= len; nz /= len;
+            const o = f * 4;
+            planes[o] = nx; planes[o + 1] = ny; planes[o + 2] = nz;
+            planes[o + 3] = nx * ax + ny * ay + nz * az;
+        }
+        this.__planes = planes;
+        this.__surface_area = area;
+        this.__volume = Math.abs(vol6) / 6;
+
+        // Polygon faces for the clipper. v1: one triangle per face (the contact
+        // clipper consumes polygon loops; a tetrahedral piece is exactly this).
+        const fo = new Uint32Array(tri + 1);
+        for (let f = 0; f <= tri; f++) fo[f] = f * 3;
+        this.face_offsets = fo;
+        this.face_loops = idx;
+    }
+
+    get volume() { return this.__volume; }
+    get surface_area() { return this.__surface_area; }
+
+    compute_bounding_box(result) {
+        const b = this.__bbox;
+        result[0] = b[0]; result[1] = b[1]; result[2] = b[2];
+        result[3] = b[3]; result[4] = b[4]; result[5] = b[5];
+    }
+
+    /**
+     * GJK support: the hull vertex furthest along the direction. Exact for a
+     * convex point set. Linear scan over the vertices — fine for the modest
+     * vertex counts of authored hulls; a hill-climb over vertex adjacency is
+     * the acceleration for very large hulls.
+     */
+    support(result, result_offset, direction_x, direction_y, direction_z) {
+        const v = this.vertices;
+        const vc = v.length / 3;
+        if (vc === 0) {
+            result[result_offset] = 0; result[result_offset + 1] = 0; result[result_offset + 2] = 0;
+            return;
+        }
+        let best = -Infinity;
+        let bi = 0;
+        for (let i = 0; i < vc; i++) {
+            const d = direction_x * v[i * 3] + direction_y * v[i * 3 + 1] + direction_z * v[i * 3 + 2];
+            if (d > best) { best = d; bi = i; }
+        }
+        result[result_offset] = v[bi * 3];
+        result[result_offset + 1] = v[bi * 3 + 1];
+        result[result_offset + 2] = v[bi * 3 + 2];
+    }
+
+    /**
+     * Convex half-space test: inside iff the point is behind (or on) every face
+     * plane. Exact for a convex polytope.
+     */
+    contains_point(point) {
+        const px = point[0], py = point[1], pz = point[2];
+        const b = this.__bbox;
+        if (px < b[0] || py < b[1] || pz < b[2] || px > b[3] || py > b[4] || pz > b[5]) {
+            return false;
+        }
+        const planes = this.__planes;
+        const f = planes.length / 4;
+        const EPS = 1e-6;
+        for (let i = 0; i < f; i++) {
+            const o = i * 4;
+            if (planes[o] * px + planes[o + 1] * py + planes[o + 2] * pz - planes[o + 3] > EPS) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /**
+     * Unsigned nearest-surface distance via a per-triangle scan, signed by
+     * {@link contains_point}. Same approach as {@link MeshShape3D}; O(F).
+     */
+    signed_distance_at_point(point) {
+        const v = this.vertices;
+        const idx = this.indices;
+        const tri = idx.length / 3;
+        const px = point[0], py = point[1], pz = point[2];
+
+        let best_d2 = Infinity;
+        const baryc = scratch_barycentric;
+        for (let i = 0; i < tri; i++) {
+            const ia = idx[i * 3] * 3, ib = idx[i * 3 + 1] * 3, ic = idx[i * 3 + 2] * 3;
+            const ax = v[ia], ay = v[ia + 1], az = v[ia + 2];
+            const bx = v[ib], by = v[ib + 1], bz = v[ib + 2];
+            const cx = v[ic], cy = v[ic + 1], cz = v[ic + 2];
+            computeTriangleClosestPointToPointBarycentric(baryc, 0, px, py, pz, ax, ay, az, bx, by, bz, cx, cy, cz);
+            const u = baryc[0], w = baryc[1], t = 1 - u - w;
+            const qx = u * ax + w * bx + t * cx;
+            const qy = u * ay + w * by + t * cy;
+            const qz = u * az + w * bz + t * cz;
+            const dx = qx - px, dy = qy - py, dz = qz - pz;
+            const d2 = dx * dx + dy * dy + dz * dz;
+            if (d2 < best_d2) best_d2 = d2;
+        }
+        const dist = Math.sqrt(best_d2);
+        return this.contains_point(point) ? -dist : dist;
+    }
+
+    signed_distance_gradient_at_point(result, point) {
+        return compute_signed_distance_gradient_by_sampling(result, this, point);
+    }
+
+    nearest_point_on_surface(result, reference) {
+        const v = this.vertices;
+        const idx = this.indices;
+        const tri = idx.length / 3;
+        const px = reference[0], py = reference[1], pz = reference[2];
+
+        let best_d2 = Infinity;
+        let bx_ = 0, by_ = 0, bz_ = 0;
+        const baryc = scratch_barycentric;
+        for (let i = 0; i < tri; i++) {
+            const ia = idx[i * 3] * 3, ib = idx[i * 3 + 1] * 3, ic = idx[i * 3 + 2] * 3;
+            const ax = v[ia], ay = v[ia + 1], az = v[ia + 2];
+            const bx = v[ib], by = v[ib + 1], bz = v[ib + 2];
+            const cx = v[ic], cy = v[ic + 1], cz = v[ic + 2];
+            computeTriangleClosestPointToPointBarycentric(baryc, 0, px, py, pz, ax, ay, az, bx, by, bz, cx, cy, cz);
+            const u = baryc[0], w = baryc[1], t = 1 - u - w;
+            const qx = u * ax + w * bx + t * cx;
+            const qy = u * ay + w * by + t * cy;
+            const qz = u * az + w * bz + t * cz;
+            const dx = qx - px, dy = qy - py, dz = qz - pz;
+            const d2 = dx * dx + dy * dy + dz * dz;
+            if (d2 < best_d2) { best_d2 = d2; bx_ = qx; by_ = qy; bz_ = qz; }
+        }
+        result[0] = bx_; result[1] = by_; result[2] = bz_;
+    }
+
+    sample_random_point_in_volume(result, result_offset, random) {
+        const b = this.__bbox;
+        const lx = b[0], ly = b[1], lz = b[2];
+        const sx = b[3] - b[0], sy = b[4] - b[1], sz = b[5] - b[2];
+        const probe = scratch_point;
+        for (let attempt = 0; attempt < 256; attempt++) {
+            probe[0] = lx + random() * sx;
+            probe[1] = ly + random() * sy;
+            probe[2] = lz + random() * sz;
+            if (this.contains_point(probe)) {
+                result[result_offset] = probe[0];
+                result[result_offset + 1] = probe[1];
+                result[result_offset + 2] = probe[2];
+                return;
+            }
+        }
+        result[result_offset] = lx + sx * 0.5;
+        result[result_offset + 1] = ly + sy * 0.5;
+        result[result_offset + 2] = lz + sz * 0.5;
+    }
+
+    /**
+     * @param {ConvexHullShape3D} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (!super.equals(other)) return false;
+        if (this.vertices.length !== other.vertices.length) return false;
+        if (this.indices.length !== other.indices.length) return false;
+        for (let i = 0; i < this.vertices.length; i++) {
+            if (this.vertices[i] !== other.vertices[i]) return false;
+        }
+        for (let i = 0; i < this.indices.length; i++) {
+            if (this.indices[i] !== other.indices[i]) return false;
+        }
+        return true;
+    }
+
+    hash() {
+        const v_count = this.vertices.length / 3 | 0;
+        const t_count = this.indices.length / 3 | 0;
+        let h = (v_count * 31 + t_count) | 0;
+        if (this.vertices.length >= 3) {
+            h = (h * 31 + (computeHashFloat(this.vertices[0]))) | 0;
+            h = (h * 31 + (computeHashFloat(this.vertices[this.vertices.length - 1]))) | 0;
+        }
+        return h | 0;
+    }
+}
+
+/**
+ * Fast type-check marker.
+ * @readonly
+ * @type {boolean}
+ */
+ConvexHullShape3D.prototype.isConvexHullShape3D = true;
+
+const scratch_barycentric = new Float64Array(2);
+const scratch_point = new Float64Array(3);

package/src/core/geom/vec3/v3_array_copy.d.ts

@@ -1,9 +1,9 @@
 /**
  *
- * @param {number[]|Float32Array|Uint32Array|Int32Array} target
+ * @param {number[]|Float32Array|Float64Array|Uint32Array|Int32Array} target
  * @param {number} target_offset
- * @param {number[]|Float32Array|Uint32Array|Int32Array} source
+ * @param {number[]|Float32Array|Float64Array|Uint32Array|Int32Array} source
  * @param {number} source_offset
  */
-export function v3_array_copy(target: number[] | Float32Array | Uint32Array | Int32Array, target_offset: number, source: number[] | Float32Array | Uint32Array | Int32Array, source_offset: number): void;
+export function v3_array_copy(target: number[] | Float32Array | Float64Array | Uint32Array | Int32Array, target_offset: number, source: number[] | Float32Array | Float64Array | Uint32Array | Int32Array, source_offset: number): void;
 //# sourceMappingURL=v3_array_copy.d.ts.map

package/src/core/geom/vec3/v3_array_copy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_array_copy.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_array_copy.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,sCALW,MAAM,EAAE,GAAC,YAAY,GAAC,WAAW,GAAC,UAAU,iBAC5C,MAAM,UACN,MAAM,EAAE,GAAC,YAAY,GAAC,WAAW,GAAC,UAAU,iBAC5C,MAAM,QAWhB"}
+{"version":3,"file":"v3_array_copy.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_array_copy.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,sCALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAAC,WAAW,GAAC,UAAU,iBACzD,MAAM,UACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAAC,WAAW,GAAC,UAAU,iBACzD,MAAM,QAWhB"}

package/src/core/geom/vec3/v3_array_copy.js

@@ -1,8 +1,8 @@
 /**
  *
- * @param {number[]|Float32Array|Uint32Array|Int32Array} target
+ * @param {number[]|Float32Array|Float64Array|Uint32Array|Int32Array} target
  * @param {number} target_offset
- * @param {number[]|Float32Array|Uint32Array|Int32Array} source
+ * @param {number[]|Float32Array|Float64Array|Uint32Array|Int32Array} source
  * @param {number} source_offset
  */
 export function v3_array_copy(target, target_offset, source, source_offset) {

package/src/core/geom/vec3/v3_cross.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cross product `a × b`, written to `result[result_offset .. result_offset+2]`.
+ *
+ * Scalar-argument companion to {@link v3_cross_array} (which takes both operands
+ * at array offsets): use this when the operands are already in registers/locals,
+ * to avoid staging them into a buffer just to cross them. Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} result destination
+ * @param {number} result_offset offset into `result`
+ * @param {number} ax @param {number} ay @param {number} az  first vector
+ * @param {number} bx @param {number} by @param {number} bz  second vector
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v3_cross(result: number[] | Float32Array | Float64Array, result_offset: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number): void;
+//# sourceMappingURL=v3_cross.d.ts.map

package/src/core/geom/vec3/v3_cross.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_cross.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_cross.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,iCARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,MACN,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAStD"}

package/src/core/geom/vec3/v3_cross.js

@@ -0,0 +1,20 @@
+/**
+ * Cross product `a × b`, written to `result[result_offset .. result_offset+2]`.
+ *
+ * Scalar-argument companion to {@link v3_cross_array} (which takes both operands
+ * at array offsets): use this when the operands are already in registers/locals,
+ * to avoid staging them into a buffer just to cross them. Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} result destination
+ * @param {number} result_offset offset into `result`
+ * @param {number} ax @param {number} ay @param {number} az  first vector
+ * @param {number} bx @param {number} by @param {number} bz  second vector
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v3_cross(result, result_offset, ax, ay, az, bx, by, bz) {
+    result[result_offset] = ay * bz - az * by;
+    result[result_offset + 1] = az * bx - ax * bz;
+    result[result_offset + 2] = ax * by - ay * bx;
+}

package/src/core/geom/vec3/v3_subtract.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Vector difference `a − b`, written to `result[result_offset .. result_offset+2]`.
+ *
+ * Scalar-argument, out-parameter form: lets callers compute an edge/offset vector
+ * straight into a scratch buffer without allocating a temporary. Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} result destination
+ * @param {number} result_offset offset into `result`
+ * @param {number} ax @param {number} ay @param {number} az  minuend
+ * @param {number} bx @param {number} by @param {number} bz  subtrahend
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v3_subtract(result: number[] | Float32Array | Float64Array, result_offset: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number): void;
+//# sourceMappingURL=v3_subtract.d.ts.map

package/src/core/geom/vec3/v3_subtract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_subtract.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_subtract.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,oCARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,MACN,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAStD"}

package/src/core/geom/vec3/v3_subtract.js

@@ -0,0 +1,19 @@
+/**
+ * Vector difference `a − b`, written to `result[result_offset .. result_offset+2]`.
+ *
+ * Scalar-argument, out-parameter form: lets callers compute an edge/offset vector
+ * straight into a scratch buffer without allocating a temporary. Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} result destination
+ * @param {number} result_offset offset into `result`
+ * @param {number} ax @param {number} ay @param {number} az  minuend
+ * @param {number} bx @param {number} by @param {number} bz  subtrahend
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v3_subtract(result, result_offset, ax, ay, az, bx, by, bz) {
+    result[result_offset] = ax - bx;
+    result[result_offset + 1] = ay - by;
+    result[result_offset + 2] = az - bz;
+}

package/src/engine/graphics/ecs/decal/v2/FPDecalSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FPDecalSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/decal/v2/FPDecalSystem.js"],"names":[],"mappings":"AAoOA;;GAEG;AACH;IAGI;;;OAGG;IACH,4BA0CC;IAhDD,SAAgB;IASZ,kDAAsC;IAEtC;;;;OAIG;IACH,wBAUE;IAEF;;;;OAIG;IACH,iBAAmC;IAEnC;;;;OAIG;IACH,iBAAsB;IAEtB;;;;OAIG;IACH,oBAAiC;IAGrC,gCAEC;IAED,iCAEC;IAED;;;;;;OAMG;IACH,4BALW,MAAM,EAAE,iBACR,MAAM,UACN,MAAM,EAAE,GACN,MAAM,CA2DlB;IAED;;;;;;;;;;;OAWG;IACH,kBAVW,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,uEAGJ;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,SAAS,EAAC,KAAK,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAC,EAAE,CAkGtE;CACJ;sCA1bqC,iDAAiD;oBArBnE,sCAAsC;0BAuBhC,wCAAwC;sBAM5C,YAAY;2BArBP,4CAA4C;8BASzC,8CAA8C"}
+{"version":3,"file":"FPDecalSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/decal/v2/FPDecalSystem.js"],"names":[],"mappings":"AAqOA;;GAEG;AACH;IAGI;;;OAGG;IACH,4BA0CC;IAhDD,SAAgB;IASZ,kDAAsC;IAEtC;;;;OAIG;IACH,wBAUE;IAEF;;;;OAIG;IACH,iBAAmC;IAEnC;;;;OAIG;IACH,iBAAsB;IAEtB;;;;OAIG;IACH,oBAAiC;IAGrC,gCASC;IAED,iCAEC;IAED;;;;;;OAMG;IACH,4BALW,MAAM,EAAE,iBACR,MAAM,UACN,MAAM,EAAE,GACN,MAAM,CA2DlB;IAED;;;;;;;;;;;OAWG;IACH,kBAVW,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,uEAGJ;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,SAAS,EAAC,KAAK,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAC,EAAE,CAkGtE;CACJ;sCAjcqC,iDAAiD;oBAtBnE,sCAAsC;0BAwBhC,wCAAwC;sBAM5C,YAAY;2BAtBP,4CAA4C;8BASzC,8CAA8C"}

package/src/engine/graphics/ecs/decal/v2/FPDecalSystem.js

@@ -21,6 +21,7 @@ import { SurfacePoint3 } from "../../../../../core/geom/3d/SurfacePoint3.js";
 import { computeStringHash } from "../../../../../core/primitives/strings/computeStringHash.js";
 import { AssetManager } from "../../../../asset/AssetManager.js";
 import { GameAssetType } from "../../../../asset/GameAssetType.js";
+import { ImageRGBADataLoader } from "../../../../asset/loaders/image/ImageRGBADataLoader.js";
 import { AbstractContextSystem } from "../../../../ecs/system/AbstractContextSystem.js";
 import { SystemEntityContext } from "../../../../ecs/system/SystemEntityContext.js";
 import { Transform } from "../../../../ecs/transform/Transform.js";
@@ -282,6 +283,13 @@ export class FPDecalSystem extends AbstractContextSystem {
 
     async startup(em) {
         this.__fp_plugin = await this.__engine.plugins.acquire(ForwardPlusRenderingPlugin);
+
+        const am = this.__engine.assetManager;
+        if (!am.hasLoaderForType(GameAssetType.Image)) {
+            await am.registerLoader(GameAssetType.Image, new ImageRGBADataLoader());
+        }
+
+
     }
 
     async shutdown(em) {

package/src/engine/graphics/ecs/trail2d/Trail2D.d.ts

@@ -90,6 +90,10 @@ declare class Trail2D {
      */
     build(segment_count: number): void;
     mesh: import("three").Mesh<import("three").BufferGeometry, import("three").Material | import("three").Material[]>;
+    /**
+     * Clear the trail's geometry and reset its state.
+     */
+    clear(): void;
     fromJSON({ maxAge, width, textureURL, offset, color }: {
         maxAge?: number;
         width?: number;

package/src/engine/graphics/ecs/trail2d/Trail2D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Trail2D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail2d/Trail2D.js"],"names":[],"mappings":";AAmBA;IAkJI,oCAMC;IAtJD;;;OAGG;IACH,QAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,QAFU,OAAO,GAAC,IAAI,CAER;IAEd;;;OAGG;IACH,UAFU,mBAAmB,CAEQ;IAErC;;;OAGG;IACH,cAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,cAAsB;IAEtB,gBAQC;IAMD,4BAEC;IAND,yBAEC;IAMD;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,SACnB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,OAAO,CAInB;IAED;;;OAGG;IACH,qBAFW,MAAM,QAehB;IADG,kHAAgB;IAWpB;;;;;;;;;;;aAcC;IAGD;;;;;;;;;;;;;;;MAQC;IAED;;;OAGG;IACH,cAFW,OAAO,WASjB;IAED;;;;;;;OAOG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CA2CnB;CAEJ;;;;;;sBAvQqB,iCAAiC;oBACnC,kCAAkC;wBAI9B,0BAA0B;oCACd,sCAAsC;0BAPhD,yCAAyC;6BAStC,mBAAmB;kCADd,wBAAwB"}
+{"version":3,"file":"Trail2D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail2d/Trail2D.js"],"names":[],"mappings":";AAoBA;IAsKI,oCAMC;IA1KD;;;OAGG;IACH,QAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,QAFU,OAAO,GAAC,IAAI,CAER;IAEd;;;OAGG;IACH,UAFU,mBAAmB,CAEQ;IAErC;;;OAGG;IACH,cAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,cAAsB;IAEtB,gBAQC;IAMD,4BAEC;IAND,yBAEC;IAMD;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,YAAY,SACnB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,OAAO,CAInB;IAED;;;OAGG;IACH,qBAFW,MAAM,QAehB;IADG,kHAAgB;IAGpB;;OAEG;IACH,cAeC;IAUD;;;;;;;;;;;aAcC;IAGD;;;;;;;;;;;;;;;MAQC;IAED;;;OAGG;IACH,cAFW,OAAO,WASjB;IAED;;;;;;;OAOG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CA2CnB;CAEJ;;;;;;sBA3RqB,iCAAiC;oBACnC,kCAAkC;wBAI9B,0BAA0B;oCACd,sCAAsC;0BAPhD,yCAAyC;6BAStC,mBAAmB;kCADd,wBAAwB"}

package/src/engine/graphics/ecs/trail2d/Trail2D.js

@@ -1,3 +1,4 @@
+import { FLOAT32_MAX } from "../../../../core/binary/FLOAT32_MAX.js";
 import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
 import { Color } from "../../../../core/color/Color.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
@@ -163,6 +164,26 @@ class Trail2D {
         this.mesh = mesh;
     }
 
+    /**
+     * Clear the trail's geometry and reset its state.
+     */
+    clear() {
+        const ribbon = this.ribbon;
+
+        if (ribbon === null) {
+            // nothing to clear
+            return;
+        }
+
+        const n = ribbon.getCount();
+
+        for (let i = 0; i < n; i++) {
+            ribbon.setPointAttribute_Scalar(i, RIBBON_ATTRIBUTE_ADDRESS_AGE, FLOAT32_MAX);
+            ribbon.setPointAlpha(i, 0);
+        }
+
+    }
+
     static fromJSON(json) {
         const r = new Trail2D();
 

package/src/engine/physics/PLAN.md

@@ -117,10 +117,10 @@ Architectural references for design choices:
   call. A 100-block stack hit at the base wakes top-down in one frame
   rather than over 100 frames of broadphase propagation.
 - `DisableSleep` on any island member exempts the whole island.
-- ContactBegin / Stay / End buffer + dispatch through both
-  `PhysicsSystem.onContactBegin/Stay/End` Signals and the per-entity
-  `entity.sendEvent(PhysicsEvents.ContactBegin, ...)` channel (when a
-  dataset is attached).
+- ContactBegin / Stay / End buffer + dispatch through the per-entity
+  `dataset.sendEvent(entity, PhysicsEvents.ContactBegin, ...)` channel — the
+  sole contact-event path, delivered to each entity of the pair when a
+  dataset is attached.
 
 ### Islands
 - **Union-find** with path halving + union by min-index over the awake-body