@woosh/meep-engine 2.169.2 → 2.169.3

package/src/engine/graphics/ecs/mesh-v2/DeferredBoundsQueue.js

@@ -0,0 +1,88 @@
+/**
+ * Collects {@link ShadedGeometry} components whose bounding box has gone stale under
+ * {@link ShadedGeometryFlags.DeferredBoundsUpdate}, until the owner of the BVH is ready
+ * to take the updates.
+ *
+ * WHY THIS EXISTS
+ *
+ * A {@link Transform} signals `position`, `rotation` and `scale` separately, so one
+ * logical move produces several change notifications: two when a caller sets position
+ * and rotation, three when the transform is written as a matrix (which is what
+ * {@link TransformAttachmentSystem} does for every entity in a hierarchy, and what
+ * `Transform.copy` does). Updating bounds on each of those recomputes the same box and
+ * walks the same path to the BVH root several times over. Parking the component here
+ * instead collapses the batch into one update per component per flush.
+ *
+ * Entries are appended without a membership test; {@link ShadedGeometry} carries the
+ * "already queued" bit so enqueueing stays O(1) and a component appears at most once.
+ */
+export class DeferredBoundsQueue {
+    /**
+     * Retained between flushes and overwritten in place rather than re-allocated.
+     * Only the first {@link #size} entries are live.
+     * @type {ShadedGeometry[]}
+     */
+    #items = [];
+
+    /**
+     * @type {number}
+     */
+    #size = 0;
+
+    /**
+     * Number of components waiting for their bounds to be applied.
+     * @returns {number}
+     */
+    get size() {
+        return this.#size;
+    }
+
+    /**
+     * Park a component whose bounds have gone stale.
+     *
+     * The caller must not add a component that is already queued — see
+     * {@link ShadedGeometry.updateTransform}, which owns that bit.
+     * @param {ShadedGeometry} sg
+     * @returns {void}
+     */
+    add(sg) {
+        this.#items[this.#size++] = sg;
+    }
+
+    /**
+     * Apply every parked update, leaving the BVH consistent with the current transforms.
+     *
+     * Components that were unlinked while queued, or whose bounds were already settled by
+     * a read, are skipped.
+     *
+     * Must not be re-entered: nothing reached from here writes to a {@link Transform},
+     * so no component can go dirty while the batch is being applied.
+     * @returns {number} how many components actually had an update applied, which is a
+     * useful profiling signal — it is the number of BVH refits the batch cost
+     */
+    flush() {
+        const items = this.#items;
+        const size = this.#size;
+
+        let applied = 0;
+
+        for (let i = 0; i < size; i++) {
+            if (items[i].applyDeferredBoundsUpdate()) {
+                applied++;
+            }
+        }
+
+        // Drop the references so components unlinked while queued are not held alive
+        // until their slot happens to be overwritten — after a teardown the slots may
+        // never be reused, and each entry retains a geometry and a material.
+        //
+        // Done in one sweep rather than per entry inside the loop above: clearing each
+        // slot as it was consumed measured ~25% slower per tick on a 2000-mover scene,
+        // the store into the object array carrying a GC write barrier each time.
+        items.fill(null, 0, size);
+
+        this.#size = 0;
+
+        return applied;
+    }
+}

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometry.d.ts

@@ -110,6 +110,28 @@ export class ShadedGeometry {
      * @return {null|number[]}
      */
     get transform(): number[];
+    /**
+     * Attach this component to the queue that collects deferred bounds updates.
+     * Called by the system when the component enters the BVH.
+     * @param {DeferredBoundsQueue} queue
+     * @returns {void}
+     */
+    bindBoundsQueue(queue: DeferredBoundsQueue): void;
+    /**
+     * Called by the system when the component leaves the BVH. Any update parked in the
+     * queue is abandoned — the entry is left in place and becomes inert, so unlinking
+     * stays O(1).
+     * @returns {void}
+     */
+    unbindBoundsQueue(): void;
+    /**
+     * Recompute the bounding box and push it into the BVH, if a deferred update is pending.
+     *
+     * This is the single point where a parked update lands; it is driven both by
+     * {@link DeferredBoundsQueue.flush} and by any read of the bounding box.
+     * @returns {boolean} whether an update was actually pending
+     */
+    applyDeferredBoundsUpdate(): boolean;
     /**
      *
      * @param {AABB3} destination
@@ -122,6 +144,11 @@ export class ShadedGeometry {
      * @param {DrawMode} [draw_mode]
      */
     from(geometry: THREE.BufferGeometry, material: THREE.Material, draw_mode?: DrawMode): void;
+    /**
+     * Change handler subscribed to the entity's {@link Transform} while the component is
+     * linked; see {@link ShadedGeometrySystem.link}.
+     * @returns {void}
+     */
     updateTransform(): void;
     update_bounds(): void;
     /**
@@ -132,6 +159,7 @@ export class ShadedGeometry {
      * @returns {boolean}
      */
     query_raycast_nearest(contact: SurfacePoint3, ray: ArrayLike<number> | number[] | Float32Array, transform_matrix4: ArrayLike<number> | number[] | Float32Array): boolean;
+    #private;
 }
 export namespace ShadedGeometry {
     let typeName: string;

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadedGeometry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/mesh-v2/ShadedGeometry.js"],"names":[],"mappings":"AAuCA;;;GAGG;AACH;IA+LI;;;;;;OAMG;IACH,sBALW,MAAM,cAAc,YACpB,MAAM,QAAQ,cACd,QAAQ,GACP,cAAc,CAQzB;IA1MG;;;OAGG;IACH,UAFU,MAAM,cAAc,GAAC,IAAI,CAEf;IACpB;;;OAGG;IACH,UAFU,MAAM,QAAQ,GAAC,IAAI,CAET;IAEpB;;;OAGG;IACH,gBAFU,MAAM,QAAQ,GAAC,IAAI,CAEH;IAE1B,sBAAiC;IAEjC;;;;OAIG;IACH,iBAAkB;IAElB;;;;OAIG;IACH,sBAAyB;IAEzB;;;OAGG;IACH,MAFU,QAAQ,GAAC,MAAM,CAEK;IAE9B;;;OAGG;IACH,aAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,OAFU,MAAM,CAEU;IAG9B;;;;OAIG;IACH,cAHW,MAAM,GAAC,mBAAmB,GACxB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,mBAAmB,GACxB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,mBAAmB,SAC1B,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,mBAAmB,GACxB,OAAO,CAInB;IAED;;;OAGG;IACH,QAFY,MAAM,CASjB;IAED;;;;OAIG;IACH,cAHW,cAAc,GACZ,OAAO,CAUnB;IAED;;;OAGG;IACH,YAFW,cAAc,QASxB;IAED;;;OAGG;IACH,SAFa,cAAc,CAQ1B;IAED;;;OAGG;IACH,qBAEC;IAED;;;;OAIG;IACH,0BAEC;IAED;;;OAGG;IACH,4BAFW,KAAK,QAMf;IAED;;;;;OAKG;IACH,eAJW,MAAM,cAAc,YACpB,MAAM,QAAQ,cACd,QAAQ,QAWlB;IAiBD,wBAIC;IAED,sBAMC;IAED;;;;;;OAMG;IACH,mDAJW,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,qBACvC,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,GACrC,OAAO,CA4BnB;CACJ;;kBAIS,MAAM;sBAON,OAAO;;0BAnTS,yCAAyC;yBAM1C,eAAe;oCACJ,0BAA0B;sBANxC,wCAAwC"}
+{"version":3,"file":"ShadedGeometry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/mesh-v2/ShadedGeometry.js"],"names":[],"mappings":"AAwCA;;;GAGG;AACH;IA8PI;;;;;;OAMG;IACH,sBALW,MAAM,cAAc,YACpB,MAAM,QAAQ,cACd,QAAQ,GACP,cAAc,CAQzB;IAzPG;;;OAGG;IACH,UAFU,MAAM,cAAc,GAAC,IAAI,CAEf;IACpB;;;OAGG;IACH,UAFU,MAAM,QAAQ,GAAC,IAAI,CAET;IAEpB;;;OAGG;IACH,gBAFU,MAAM,QAAQ,GAAC,IAAI,CAEH;IAE1B,sBAAiC;IAEjC;;;;OAIG;IACH,iBAAkB;IAElB;;;;OAIG;IACH,sBAAyB;IAEzB;;;OAGG;IACH,MAFU,QAAQ,GAAC,MAAM,CAEK;IAE9B;;;OAGG;IACH,aAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,OAFU,MAAM,CAEU;IAG9B;;;;OAIG;IACH,cAHW,MAAM,GAAC,mBAAmB,GACxB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,mBAAmB,GACxB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,mBAAmB,SAC1B,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,mBAAmB,GACxB,OAAO,CAInB;IAED;;;OAGG;IACH,QAFY,MAAM,CASjB;IAED;;;;OAIG;IACH,cAHW,cAAc,GACZ,OAAO,CAUnB;IAED;;;OAGG;IACH,YAFW,cAAc,QASxB;IAED;;;OAGG;IACH,SAFa,cAAc,CAQ1B;IAED;;;OAGG;IACH,qBAEC;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;;OAKG;IACH,6CAFa,IAAI,CAMhB;IAED;;;;;OAKG;IACH,qBAFa,IAAI,CAKhB;IAED;;;;;;OAMG;IACH,6BAFa,OAAO,CAcnB;IAED;;;OAGG;IACH,4BAFW,KAAK,QASf;IAED;;;;;OAKG;IACH,eAJW,MAAM,cAAc,YACpB,MAAM,QAAQ,cACd,QAAQ,QAWlB;IAiBD;;;;OAIG;IACH,mBAFa,IAAI,CAgBhB;IAED,sBAMC;IAED;;;;;;OAMG;IACH,mDAJW,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,qBACvC,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,GACrC,OAAO,CA4BnB;;CACJ;;kBAIS,MAAM;sBAON,OAAO;;0BAjYS,yCAAyC;yBAM1C,eAAe;oCACJ,0BAA0B;sBANxC,wCAAwC"}

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometry.js

@@ -1,4 +1,5 @@
 import { m4_invert } from "../../../../core/geom/3d/mat4/m4_invert.js";
+import { assert } from "../../../../core/assert.js";
 import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
 import { AABB3 } from "../../../../core/geom/3d/aabb/AABB3.js";
 import { aabb3_from_three_geometry } from "../../../../core/geom/3d/aabb/aabb3_from_three_geometry.js";
@@ -42,6 +43,22 @@ const scratch_ray_0 = new Float32Array(6);
  * This is roughly equivalent to single draw call, note that his is not a hierarchical data structure, if you want that - you will need to combine multiple entities, each with a `ShadedGeometry` component
  */
 export class ShadedGeometry {
+    /**
+     * Set when a transform change has been observed but the bounding box and the BVH have
+     * not been brought up to date yet. Only ever set under
+     * {@link ShadedGeometryFlags.DeferredBoundsUpdate}, and doubles as the "already queued"
+     * bit for {@link #bounds_queue}.
+     * @type {boolean}
+     */
+    #bounds_dirty = false;
+
+    /**
+     * Transient, assigned in the system. Where this component parks itself when its bounds
+     * go stale under {@link ShadedGeometryFlags.DeferredBoundsUpdate}.
+     * @type {DeferredBoundsQueue|null}
+     */
+    #bounds_queue = null;
+
     constructor() {
         /**
          *
@@ -205,11 +222,58 @@ export class ShadedGeometry {
         return this.__c_transform.matrix;
     }
 
+    /**
+     * Attach this component to the queue that collects deferred bounds updates.
+     * Called by the system when the component enters the BVH.
+     * @param {DeferredBoundsQueue} queue
+     * @returns {void}
+     */
+    bindBoundsQueue(queue) {
+        assert.defined(queue, 'queue');
+
+        this.#bounds_queue = queue;
+    }
+
+    /**
+     * Called by the system when the component leaves the BVH. Any update parked in the
+     * queue is abandoned — the entry is left in place and becomes inert, so unlinking
+     * stays O(1).
+     * @returns {void}
+     */
+    unbindBoundsQueue() {
+        this.#bounds_dirty = false;
+        this.#bounds_queue = null;
+    }
+
+    /**
+     * Recompute the bounding box and push it into the BVH, if a deferred update is pending.
+     *
+     * This is the single point where a parked update lands; it is driven both by
+     * {@link DeferredBoundsQueue.flush} and by any read of the bounding box.
+     * @returns {boolean} whether an update was actually pending
+     */
+    applyDeferredBoundsUpdate() {
+        if (!this.#bounds_dirty) {
+            return false;
+        }
+
+        this.#bounds_dirty = false;
+
+        this.update_bounds();
+
+        this.__bvh_leaf.write_bounds();
+
+        return true;
+    }
+
     /**
      *
      * @param {AABB3} destination
      */
     getBoundingBox(destination) {
+        // settle a pending deferred update, so a read never observes a stale box
+        this.applyDeferredBoundsUpdate();
+
         const aabb = this.__bvh_leaf.bounds;
 
         destination.readFromArray(aabb);
@@ -247,7 +311,22 @@ export class ShadedGeometry {
         return r;
     }
 
+    /**
+     * Change handler subscribed to the entity's {@link Transform} while the component is
+     * linked; see {@link ShadedGeometrySystem.link}.
+     * @returns {void}
+     */
     updateTransform() {
+        if (this.getFlag(ShadedGeometryFlags.DeferredBoundsUpdate)) {
+            if (!this.#bounds_dirty) {
+                this.#bounds_dirty = true;
+
+                this.#bounds_queue.add(this);
+            }
+
+            return;
+        }
+
         this.update_bounds();
 
         this.__bvh_leaf.write_bounds();

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometryFlags.js

@@ -19,9 +19,27 @@ export const ShadedGeometryFlags = {
     Visible: 16,
 
     /**
-     * Bounds are updated whenever transforms change, we can defer this until next frame render request
-     * This lets us back updated and do less work overall
-     * TODO implement, currently it's ignored
+     * Bounds are updated whenever transforms change; with this set that work is deferred
+     * until the tree is next read (a render request, a query, or a read of the bounding
+     * box), and every change observed in between collapses into a single update.
+     *
+     * This is a trade, not a free win, and which way it goes depends entirely on how many
+     * times the transform is written between reads:
+     *
+     *   - Set it on anything whose transform is written more than once per frame. A
+     *     {@link Transform} signals `position`, `rotation` and `scale` separately, so a
+     *     mover that changes all three pays three bounds recomputations and three walks to
+     *     the BVH root, and everything driven through a transform hierarchy writes all
+     *     three every time (the hierarchy hands its children a matrix, and decomposing it
+     *     touches each). Measured on a 20k-mesh scene with 2k movers: 3x fewer updates,
+     *     ~20-25% off the frame.
+     *   - Leave it off for a mesh whose transform is written exactly once. There is
+     *     nothing to collapse, and the same work now spans two passes over the components
+     *     instead of one — measured ~10-20% worse on the same scene.
+     *   - Costs nothing on a mesh that does not move; an empty flush is one length test.
+     *
+     * @see ShadedGeometrySystem.flushBoundsUpdates
+     * @see ShadedGeometryDeferredBounds.bench.spec.js
      */
     DeferredBoundsUpdate: 32,
 };

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometrySystem.d.ts

@@ -44,10 +44,22 @@ export class ShadedGeometrySystem extends System<any> {
     __optimization_task: Task;
     __maintenance_task: Task;
     /**
-     *
+     * NOTE: components carrying {@link ShadedGeometryFlags.DeferredBoundsUpdate} only reach
+     * the tree at a {@link flushBoundsUpdates}, so a caller reaching for the tree directly
+     * must flush first. Every query on this system already does.
      * @returns {BVH}
      */
     get bvh(): BVH;
+    /**
+     * Apply every bounds update parked by components carrying
+     * {@link ShadedGeometryFlags.DeferredBoundsUpdate}, bringing {@link bvh} in line with
+     * the current transforms.
+     *
+     * Cheap when nothing is pending, which is why every query calls it unconditionally.
+     * @returns {number} how many meshes had their bounds applied, i.e. how many BVH
+     * refits this flush cost
+     */
+    flushBoundsUpdates(): number;
     /**
      * NOTE: DO NOT MODIFY RESULTS
      * @returns {Map<number,number>}

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometrySystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadedGeometrySystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/mesh-v2/ShadedGeometrySystem.js"],"names":[],"mappings":"AA8DA;IASI;;;OAGG;IACH,4BAmEC;IAjEG,2DAA+C;IAE/C;;;;OAIG;IACH,iBAAsB;IAEtB;;;;OAIG;IACH,uBAA0B;IAE1B;;;;OAIG;IACH,wBAAgC;IAEhC;;;;OAIG;IACH,4BAAoC;IAEpC;;;;OAIG;IACH,kCAA0C;IAE1C;;;;OAIG;IACH,qBAA6B;IAI7B,0BAYE;IAEF,yBAIC;IAIL;;;OAGG;IACH,eAEC;IAED;;;OAGG;IACH,4BAFa,IAAI,MAAM,EAAC,MAAM,CAAC,CAI9B;IAED;;;;OAIG;IACH,+BAHW,MAAM,+CAsBhB;IAED;;;;OAIG;IACH,iCAHW,MAAM,GACL,OAAO,CAmBlB;IAED;;;;OAIG;IACH,4BASC;IAED;;;;OAIG;IACH,8BAMC;IAED,2CAkCC;IAED,4CAmBC;IAED;;;;;OAKG;IACH,SAJW,cAAc,KACd,SAAS,UACT,MAAM,QA2ChB;IAED;;;;;OAKG;IACH,WAJW,cAAc,KACd,SAAS,UACT,MAAM,QA4BhB;IAED;;;;;;OAMG;IACH,4BALW,MAAM,EAAE,iBACR,MAAM,UACN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GACxB,MAAM,CAQlB;IAED;;;;;;;;;;;OAWG;IACH,kBAVW,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,6BACG,MAAM,QAAQ,cAAc,KAAK,OAAO,kCAE/C;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,IAAI,EAAC,cAAc,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAC,EAAE,CA8D1E;IAGD;;;;;;;;;;;;OAYG;IACH,wBAXW,aAAa,YACb,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,6BACG,MAAM,QAAQ,cAAc,KAAK,OAAO,kCAE/C;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,IAAI,EAAC,cAAc,CAAA;KAAC,GAAC,SAAS,CAmF1D;;CACJ;uBApiBsB,wBAAwB;0BACrB,qCAAqC;+BAIhC,qBAAqB;iBATnC,uCAAuC;oBAZpC,mCAAmC;8BAUzB,2CAA2C"}
+{"version":3,"file":"ShadedGeometrySystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/mesh-v2/ShadedGeometrySystem.js"],"names":[],"mappings":"AA8DA;IAiBI;;;OAGG;IACH,4BAmEC;IAjEG,2DAA+C;IAE/C;;;;OAIG;IACH,iBAAsB;IAEtB;;;;OAIG;IACH,uBAA0B;IAE1B;;;;OAIG;IACH,wBAAgC;IAEhC;;;;OAIG;IACH,4BAAoC;IAEpC;;;;OAIG;IACH,kCAA0C;IAE1C;;;;OAIG;IACH,qBAA6B;IAI7B,0BAYE;IAEF,yBAIC;IAIL;;;;;OAKG;IACH,eAEC;IAED;;;;;;;;OAQG;IACH,sBAHa,MAAM,CAKlB;IAED;;;OAGG;IACH,4BAFa,IAAI,MAAM,EAAC,MAAM,CAAC,CAI9B;IAED;;;;OAIG;IACH,+BAHW,MAAM,+CAsBhB;IAED;;;;OAIG;IACH,iCAHW,MAAM,GACL,OAAO,CAmBlB;IAED;;;;OAIG;IACH,4BASC;IAED;;;;OAIG;IACH,8BAMC;IAED,2CA0CC;IAED,4CAmBC;IAED;;;;;OAKG;IACH,SAJW,cAAc,KACd,SAAS,UACT,MAAM,QAuChB;IAED;;;;;OAKG;IACH,WAJW,cAAc,KACd,SAAS,UACT,MAAM,QAgChB;IAED;;;;;;OAMG;IACH,4BALW,MAAM,EAAE,iBACR,MAAM,UACN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GACxB,MAAM,CAUlB;IAED;;;;;;;;;;;OAWG;IACH,kBAVW,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,6BACG,MAAM,QAAQ,cAAc,KAAK,OAAO,kCAE/C;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,IAAI,EAAC,cAAc,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAC,EAAE,CAgE1E;IAGD;;;;;;;;;;;;OAYG;IACH,wBAXW,aAAa,YACb,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,6BACG,MAAM,QAAQ,cAAc,KAAK,OAAO,kCAE/C;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,IAAI,EAAC,cAAc,CAAA;KAAC,GAAC,SAAS,CAqF1D;;CACJ;uBA1kBsB,wBAAwB;0BACrB,qCAAqC;+BAKhC,qBAAqB;iBAVnC,uCAAuC;oBAXpC,mCAAmC;8BASzB,2CAA2C"}

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometrySystem.js

@@ -1,6 +1,5 @@
 import { assert } from "../../../../core/assert.js";
 import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
-import { make_bvh_depth_range_computer } from "../make_bvh_depth_range_computer.js";
 import { bvh_query_leaves_generic } from "../../../../core/bvh2/bvh3/query/bvh_query_leaves_generic.js";
 import {
     bvh_query_user_data_intersects_frustum
@@ -17,7 +16,8 @@ import TaskState from "../../../../core/process/task/TaskState.js";
 import { iteratorTask } from "../../../../core/process/task/util/iteratorTask.js";
 import { System } from "../../../ecs/System.js";
 import { Transform } from "../../../ecs/transform/Transform.js";
-import { isForwardPlusLightingSkipped } from "../../render/forward_plus/plugin/isForwardPlusLightingSkipped.js";
+import { make_bvh_depth_range_computer } from "../make_bvh_depth_range_computer.js";
+import { DeferredBoundsQueue } from "./DeferredBoundsQueue.js";
 import { RuntimeDrawMethodOptimizer } from "./render/optimization/RuntimeDrawMethodOptimizer.js";
 import { ShadedGeometryRendererContext } from "./render/ShadedGeometryRendererContext.js";
 import { ShadedGeometry } from "./ShadedGeometry.js";
@@ -69,6 +69,14 @@ export class ShadedGeometrySystem extends System {
      */
     #material_references = new Map();
 
+    /**
+     * Bounds updates parked by components carrying
+     * {@link ShadedGeometryFlags.DeferredBoundsUpdate}, drained by
+     * {@link flushBoundsUpdates} before anything reads {@link bvh}.
+     * @type {DeferredBoundsQueue}
+     */
+    #deferred_bounds = new DeferredBoundsQueue();
+
     /**
      *
      * @param {Engine} engine
@@ -144,13 +152,28 @@ export class ShadedGeometrySystem extends System {
 
 
     /**
-     *
+     * NOTE: components carrying {@link ShadedGeometryFlags.DeferredBoundsUpdate} only reach
+     * the tree at a {@link flushBoundsUpdates}, so a caller reaching for the tree directly
+     * must flush first. Every query on this system already does.
      * @returns {BVH}
      */
     get bvh() {
         return this.__bvh_binary;
     }
 
+    /**
+     * Apply every bounds update parked by components carrying
+     * {@link ShadedGeometryFlags.DeferredBoundsUpdate}, bringing {@link bvh} in line with
+     * the current transforms.
+     *
+     * Cheap when nothing is pending, which is why every query calls it unconditionally.
+     * @returns {number} how many meshes had their bounds applied, i.e. how many BVH
+     * refits this flush cost
+     */
+    flushBoundsUpdates() {
+        return this.#deferred_bounds.flush();
+    }
+
     /**
      * NOTE: DO NOT MODIFY RESULTS
      * @returns {Map<number,number>}
@@ -262,10 +285,18 @@ export class ShadedGeometrySystem extends System {
                 return 0;
             }
 
+            this.flushBoundsUpdates();
+
             return ctx.collect(destination, destination_offset, graphics.renderer, view, this.__bvh_binary, ecd);
         });
 
-        this.__render_layer.compute_depth_range = make_bvh_depth_range_computer(this.__bvh_binary);
+        const compute_depth_range = make_bvh_depth_range_computer(this.__bvh_binary);
+
+        this.__render_layer.compute_depth_range = (result, frustum, nx, ny, nz, plane_constant) => {
+            this.flushBoundsUpdates();
+
+            compute_depth_range(result, frustum, nx, ny, nz, plane_constant);
+        };
 
         this.__optimization_task.state.set(TaskState.INITIAL);
         engine.executor.run(this.__optimization_task);
@@ -318,16 +349,12 @@ export class ShadedGeometrySystem extends System {
         // exists we simply overwrite it rather than guarding a can't-happen case
         this.#material_references.set(entity, material_reference);
 
-        assert.ok(
-            !isForwardPlusLightingSkipped(material_manager, sg.material),
-            'lit material was not transformed for Forward+ clustered lighting,'
-            + ' ensure the Forward+ plugin is registered before entities are linked'
-        );
-
         sg.__c_transform = t;
 
         sg.update_bounds();
 
+        sg.bindBoundsQueue(this.#deferred_bounds);
+
         t.subscribe(sg.updateTransform, sg);
 
         // remember entity for lookups
@@ -353,6 +380,10 @@ export class ShadedGeometrySystem extends System {
     unlink(sg, t, entity) {
         t.unsubscribe(sg.updateTransform, sg);
 
+        // abandon any deferred update still parked in the queue, it would otherwise be
+        // applied to a leaf that no longer belongs to this tree
+        sg.unbindBoundsQueue();
+
         // disconnect BVH
         sg.__bvh_leaf.unlink();
 
@@ -390,6 +421,8 @@ export class ShadedGeometrySystem extends System {
         result_offset,
         planes
     ) {
+        this.flushBoundsUpdates();
+
         return bvh_query_user_data_intersects_frustum(result, result_offset, this.__bvh_binary, planes);
     }
 
@@ -414,6 +447,8 @@ export class ShadedGeometrySystem extends System {
 
         const hits = [];
 
+        this.flushBoundsUpdates();
+
         const bvh = this.__bvh_binary;
 
         const hit_count = bvh_query_leaves_generic(hits, 0, bvh, bvh.root, BVHQueryIntersectsRay.from([origin_x, origin_y, origin_z, direction_x, direction_y, direction_z]));
@@ -494,6 +529,8 @@ export class ShadedGeometrySystem extends System {
 
         const hits = [];
 
+        this.flushBoundsUpdates();
+
         const bvh = this.__bvh_binary;
 
         const hit_count = bvh_query_leaves_generic(hits, 0, bvh, bvh.root, BVHQueryIntersectsRay.from([origin_x, origin_y, origin_z, direction_x, direction_y, direction_z]));

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#189@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#191@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#189@#clear_field"(fluid: FluidComponent): void;
+    static "__#191@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#189@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#191@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#189@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#191@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/engine/physics/fluid/ecs/FluidSystem.d.ts

@@ -38,7 +38,7 @@ export class FluidSystem extends System<any> {
      * @param {FluidEffectorsComponent} effectors_component
      * @param {Transform} transform
      */
-    static "__#188@#sync_effectors_from_transform"(effectors_component: FluidEffectorsComponent, transform: Transform): void;
+    static "__#190@#sync_effectors_from_transform"(effectors_component: FluidEffectorsComponent, transform: Transform): void;
     /**
      * Visitor for the (FluidComponent, Transform) traversal — keeps the field's
      * grid origin locked to a cell-aligned position near the transform.
@@ -61,7 +61,7 @@ export class FluidSystem extends System<any> {
      * @param {FluidComponent} component
      * @param {Transform} transform
      */
-    static "__#188@#reanchor_field"(component: FluidComponent, transform: Transform): void;
+    static "__#190@#reanchor_field"(component: FluidComponent, transform: Transform): void;
     /**
      * Write the world-to-grid affine for a FluidComponent into `out`. Axis-aligned,
      * uniform-scale, so the matrix is sparse:
@@ -76,7 +76,7 @@ export class FluidSystem extends System<any> {
      * @param {Float32Array} out  length-16
      * @param {FluidComponent} component
      */
-    static "__#188@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
+    static "__#190@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
     constructor();
     dependencies: (typeof FluidComponent)[];
     /**

package/src/view/minimap/gl/MinimapMarkersGL.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MinimapMarkersGL.d.ts","sourceRoot":"","sources":["../../../../../src/view/minimap/gl/MinimapMarkersGL.js"],"names":[],"mappings":"AAoBA;;;;;;;GAOG;AACH;IACI;;;;OAIG;IACH,oFAwGC;IApGG;;;OAGG;IACH,sCAAkC;IAElC;;;OAGG;IACH,gCAAgC;IAEhC,2BAAkD;IAIlD,yCAA+B;IAMf,SAFN,IAAI,MAAM,EAAE,QAAQ,CAAC,CAES;IActB,WAFR,aAAa,CAEoD;IAE3E,+BAA+F;IAgD/F,qBAAuB;IAGvB,oDAA2E;IAM3E;;;OAGG;IACH,cAFU,OAAO,CAEQ;IAG7B,uBAyDC;IAED,sCAKC;IAGD;;;;OAIG;IACH,0BAEC;IAED,0BAMC;IAED,sBAuBC;CA0EJ;kCAzTiC,wBAAwB;6BAP7B,uCAAuC;6BACvC,+DAA+D;yBAInE,eAAe;8BAYV,sEAAsE;+BAfrE,uCAAuC;uBAHlC,OAAO"}
+{"version":3,"file":"MinimapMarkersGL.d.ts","sourceRoot":"","sources":["../../../../../src/view/minimap/gl/MinimapMarkersGL.js"],"names":[],"mappings":"AAoBA;;;;;;;GAOG;AACH;IACI;;;;OAIG;IACH,oFAwGC;IApGG;;;OAGG;IACH,sCAAkC;IAElC;;;OAGG;IACH,gCAAgC;IAEhC,2BAAkD;IAIlD,yCAA+B;IAMf,SAFN,IAAI,MAAM,EAAE,QAAQ,CAAC,CAES;IActB,WAFR,aAAa,CAEoD;IAE3E,+BAA+F;IAgD/F,qBAAuB;IAGvB,oDAA2E;IAM3E;;;OAGG;IACH,cAFU,OAAO,CAEQ;IAG7B,uBAyDC;IAED,sCAKC;IAGD;;;;OAIG;IACH,0BAEC;IAED,0BAMC;IAED,sBAuBC;CA4EJ;kCA3TiC,wBAAwB;6BAP7B,uCAAuC;6BACvC,+DAA+D;yBAInE,eAAe;8BAYV,sEAAsE;+BAfrE,uCAAuC;uBAHlC,OAAO"}

package/src/view/minimap/gl/MinimapMarkersGL.js

@@ -272,7 +272,9 @@ export class MinimapMarkersGL extends MinimapWorldLayer {
 
         atlas.on.painted.add(this.handleAtlasUpdate, this);
         this.shutdownHooks.push(() => {
-            atlas.on.painted.remove(this.handleAtlasUpdate);
+            // the context has to be passed here too, Signal.remove matches on the handle
+            // *and* the context, so a remove without one never matches this handler
+            atlas.on.painted.remove(this.handleAtlasUpdate, this);
         });