@woosh/meep-engine 3.41.0 → 3.43.0

package/src/engine/graphics3/WaterSystem.js

@@ -1,6 +1,6 @@
 import { assert } from "../../core/assert.js";
 import Water from "../graphics/ecs/water/Water.js";
-import WaterWaves from "../graphics/ecs/water/WaterWaves.js";
+import WaterWaves, { WATER_WAVES_SHORE_REFLECTION_DEFAULT } from "../graphics/ecs/water/WaterWaves.js";
 import { System } from "../ecs/System.js";
 import { EventType } from "../ecs/EventType.js";
 import { Transform64 } from "../ecs/transform/Transform64.js";
@@ -12,21 +12,32 @@ import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
 import { GPUWaterRenderer } from "../../shade/renderer/water/GPUWaterRenderer.js";
 import { GPUWaterBodies } from "../../shade/renderer/water/medium/GPUWaterBodies.js";
-import { GPUWaterWaveSimulation } from "../../shade/renderer/water/surface/GPUWaterWaveSimulation.js";
+import { GPUWaterSurface } from "../../shade/renderer/water/surface/GPUWaterSurface.js";
 import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
 import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
 import { SceneColor } from "../../shade/renderer/extension/SceneColor.js";
 import { m4_invert } from "../../core/geom/3d/mat4/m4_invert.js";
 import { generate_record_writer } from "../../shade/renderer/buffer/table/serde/generate_record_writer.js";
 import { WATER_WAVE_IMPULSE_LIMIT, WATER_WAVE_RECORD_STRUCT } from "../../shade/renderer/water/surface/WATER_WAVE_RECORD_STRUCT.js";
+import { WATER_SPECTRUM_BAND_COUNT } from "../../shade/renderer/water/surface/spectrum/WATER_SPECTRUM.js";
 
-const WIND_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['forcing', 'unresolved_variance']);
+// Only the authored fields: a whole-record write would undo what the GPU derives into the row.
+const AUTHORED_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['wind', 'upwind_fetch', 'node', 'geometry', 'simulate_hidden']);
 const IMPULSE_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['impulses', 'impulse_count']);
+/** The WaterWaves fields a body's row follows. */
+const WAVE_FIELDS = ['windSpeed', 'windDirection', 'upwindFetch', 'shoreReflection'];
+/** A splash's world-to-local matrix: rain can splash hundreds of times a second. */
+const SPLASH_INVERSE = new Float64Array(16);
 
 /**
  * Registers [Water, MeshletGeometry, Transform64] in the scene's existing GPU database. Authored
  * edits queue writes; idle frames never walk bodies. Transform rows follow the same change events
  * and GPU hierarchy as shaded geometry. Water does not enter the opaque mesh table or its TLAS.
+ *
+ * Every body has a surface row (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1): its wind from an
+ * optional {@link WaterWaves}, its queued splashes, and what the GPU derives from them each frame. The GPU culls
+ * every body against the frame's view before simulating; a hidden body is paused unless
+ * {@link Water#simulateWhenHidden} (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3).
  */
 export class WaterSystem extends System {
     dependencies = [Water, MeshletGeometry, Transform64];
@@ -35,11 +46,13 @@ export class WaterSystem extends System {
     #scene;
     #context = null;
     #renderer = new GPUWaterRenderer();
-    #waves = new GPUWaterWaveSimulation();
+    #waves = new GPUWaterSurface();
     #bodies = new GPUWaterBodies();
     #entries = new Map();
     #dirty = new Set();
     #impulses = new Set();
+    // bodies with wind: while there is none, the shared band tiles are not animated
+    #windy = new Set();
     #extensions = [];
     #time = 0;
     get settings() { return this.#renderer.settings; }
@@ -60,9 +73,8 @@ export class WaterSystem extends System {
         this.#waves.onInputsConsumed.add(context => {
             if (context !== this.#context) { return; }
             for (const entry of this.#impulses) {
-                entry.staged.length = 0;
-                if (entry.impulses.length !== 0) { this.#dirty.add(entry); }
-                else { this.#impulses.delete(entry); }
+                entry.staged.impulse_count = 0;
+                if (entry.queue.length === 0) { this.#impulses.delete(entry); }
             }
         });
         this.#renderer.bodies = this.#bodies;
@@ -87,8 +99,10 @@ export class WaterSystem extends System {
     }
 
     link(water, geometry, transform, entity) {
-        const entry = { water, geometry, transform, entity, context: null, row: -1, wave: -1, waves: null,
-            impulses: [], staged: [], wave_record: null };
+        // queue: splashes not yet staged, four numbers each (local x, z, radius, kick); staged: the batch on the
+        // GPU row until a submitted frame spends it
+        const entry = { water, geometry, transform, entity, context: null, row: -1, wave: -1, waves: null, queue: [],
+            staged: { impulses: Array.from({ length: WATER_WAVE_IMPULSE_LIMIT }, () => new Float64Array(4)), impulse_count: 0 } };
         const dataset = this.entityManager.dataset;
         entry.changed = () => this.#dirty.add(entry);
         entry.world = () => entry.context?.rows.mark_world(entity);
@@ -109,11 +123,9 @@ export class WaterSystem extends System {
     }
 
     #watch_waves(entry) {
-        entry.waves?.windSpeed.onChanged.remove(entry.changed);
-        entry.waves?.windDirection.onChanged.remove(entry.changed);
+        if (entry.waves != null) { for (const field of WAVE_FIELDS) { entry.waves[field].onChanged.remove(entry.changed); } }
         entry.waves = this.entityManager.dataset.getComponent(entry.entity, WaterWaves);
-        entry.waves?.windSpeed.onChanged.add(entry.changed);
-        entry.waves?.windDirection.onChanged.add(entry.changed);
+        if (entry.waves != null) { for (const field of WAVE_FIELDS) { entry.waves[field].onChanged.add(entry.changed); } }
     }
 
     unlink(water, geometry, transform, entity) {
@@ -121,8 +133,7 @@ export class WaterSystem extends System {
         if (entry === undefined) { return; }
         const dataset = this.entityManager.dataset;
         water.onChanged.remove(entry.changed);
-        entry.waves?.windSpeed.onChanged.remove(entry.changed);
-        entry.waves?.windDirection.onChanged.remove(entry.changed);
+        if (entry.waves != null) { for (const field of WAVE_FIELDS) { entry.waves[field].onChanged.remove(entry.changed); } }
         dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.world);
         dataset.removeEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, entry.local);
         dataset.removeEntityEventListener(entity, EventType.ComponentAdded, entry.components);
@@ -132,6 +143,7 @@ export class WaterSystem extends System {
             entry.context.rows.release(entity);
         }
         this.#entries.delete(entity); this.#dirty.delete(entry); this.#impulses.delete(entry);
+        this.#windy.delete(entry); this.#waves.windy = this.#windy.size > 0;
         this.#renderer.body_count--;
         if (entry.context !== null) { this.#renderer.meshlet_capacity -= entry.geometry.meshlets.count; }
     }
@@ -144,14 +156,34 @@ export class WaterSystem extends System {
             this.#context = context;
             // Device replacement is the only whole-scene rebuild; ordinary frames drain edits.
             for (const entry of this.#entries.values()) {
-                entry.context = null; entry.row = -1; entry.wave = -1; entry.wave_record = null;
-                entry.impulses.unshift(...entry.staged); entry.staged.length = 0;
+                entry.context = null; entry.row = -1; entry.wave = -1;
+                // a batch the old context never spent goes back to the front of the queue
+                const staged = [];
+                for (let i = 0; i < entry.staged.impulse_count; i++) { staged.push(...entry.staged.impulses[i]); }
+                entry.queue.unshift(...staged); entry.staged.impulse_count = 0;
                 this.#dirty.add(entry);
             }
             this.#renderer.meshlet_capacity = 0;
         }
         for (const entry of this.#dirty) { this.#write(entry, context); }
         this.#dirty.clear();
+        for (const entry of this.#impulses) { this.#stage(entry, context); }
+    }
+
+    /** Top up a body's batch on its surface row from its queue, up to the row's limit. */
+    #stage(entry, context) {
+        const staged = entry.staged, queue = entry.queue;
+        if (entry.wave === -1 || queue.length === 0 || staged.impulse_count === WATER_WAVE_IMPULSE_LIMIT) { return; }
+        const taken = Math.min(queue.length / 4, WATER_WAVE_IMPULSE_LIMIT - staged.impulse_count);
+        for (let i = 0; i < taken; i++) {
+            const impulse = staged.impulses[staged.impulse_count++];
+            for (let c = 0; c < 4; c++) { impulse[c] = queue[4 * i + c]; }
+        }
+        queue.copyWithin(0, 4 * taken);
+        queue.length -= 4 * taken;
+        this.#waves.splashed = true;
+        for (let i = staged.impulse_count; i < WATER_WAVE_IMPULSE_LIMIT; i++) { staged.impulses[i].fill(0); }
+        context.scene_database.get('water_waves').set_fields(entry.wave, staged, IMPULSE_WRITER);
     }
 
     #write(entry, context) {
@@ -163,54 +195,54 @@ export class WaterSystem extends System {
             entry.context = context;
             this.#renderer.meshlet_capacity += entry.geometry.meshlets.count;
         }
-        if (entry.wave !== -1 || entry.waves != null || entry.impulses.length !== 0) {
-            const bounds = entry.geometry.bounding_box;
-            if (entry.wave === -1) {
-                entry.wave_record = { extent: [bounds[0], bounds[2], bounds[3], bounds[5]],
-                    forcing: [1, 0, 0, 0], impulses: Array.from({ length: WATER_WAVE_IMPULSE_LIMIT }, () => [0, 0, 0, 0]),
-                    node: entry.entity + 1, geometry: context.geometries.getAddress(entry.geometry),
-                    unresolved_variance: 0, impulse_count: 0, first_write: 1, displacement_bounds: [0, 0] };
-                entry.wave = waves.add(entry.wave_record);
-            }
-            const wind = Math.max(0, entry.waves?.windSpeed.getValue() ?? 0);
-            const direction = entry.waves?.windDirection.getValue() ?? 0;
-            // Patch only authored fields: a full write would restore GPU-consumed impulses/reset flags.
-            waves.set_fields(entry.wave, { forcing: [Math.cos(direction), Math.sin(direction), 0.02 * wind * wind, 0.5 * wind],
-                unresolved_variance: wind > 0 ? 0.003 + 0.00512 * wind : 0 }, WIND_WRITER);
-            if (entry.impulses.length !== 0) {
-                entry.staged.push(...entry.impulses.splice(0, WATER_WAVE_IMPULSE_LIMIT - entry.staged.length));
-                const impulses = entry.staged.slice();
-                const count = impulses.length;
-                while (impulses.length < WATER_WAVE_IMPULSE_LIMIT) { impulses.push([0, 0, 0, 0]); }
-                waves.set_fields(entry.wave, { impulses, impulse_count: count }, IMPULSE_WRITER);
-            }
+        const geometry = context.geometries.getAddress(entry.geometry);
+        if (entry.wave === -1) {
+            entry.wave = waves.add({ wind: [1, 0, 0, WATER_WAVES_SHORE_REFLECTION_DEFAULT], upwind_fetch: 0,
+                impulses: Array.from({ length: WATER_WAVE_IMPULSE_LIMIT }, () => [0, 0, 0, 0]), impulse_count: 0,
+                node: entry.entity + 1, geometry, simulate_hidden: 0, derived_for: [-1, -1],
+                weights: new Array(WATER_SPECTRUM_BAND_COUNT).fill(0), slope_variance: 0,
+                wind_from: [0, 0], wind_to: [0, 0], wind_blend: 1, displacement_bounds: [0, 0, 0, 0], particle_levels: 0 });
         }
+        const waves_component = entry.waves;
+        const speed = Math.max(0, waves_component?.windSpeed.getValue() ?? 0);
+        const direction = waves_component?.windDirection.getValue() ?? 0;
+        const reflection = Math.min(1, Math.max(0, waves_component?.shoreReflection.getValue() ?? WATER_WAVES_SHORE_REFLECTION_DEFAULT));
+        waves.set_fields(entry.wave, { wind: [Math.cos(direction), Math.sin(direction), speed, reflection],
+            upwind_fetch: Math.max(0, waves_component?.upwindFetch.getValue() ?? 0), node: entry.entity + 1, geometry,
+            simulate_hidden: entry.water.simulateWhenHidden.getValue() ? 1 : 0 }, AUTHORED_WRITER);
+        if (speed > 0) { this.#windy.add(entry); } else { this.#windy.delete(entry); }
+        this.#waves.windy = this.#windy.size > 0;
         const water = entry.water;
-        const record = { geometry: context.geometries.getAddress(entry.geometry), node: entry.entity + 1,
+        const record = { geometry, node: entry.entity + 1,
             dirty: 1,
-            wave: entry.wave === -1 ? 0xffffffff : entry.wave, ior: Math.max(1, water.ior.getValue()),
+            wave: entry.wave, ior: Math.max(1, water.ior.getValue()),
             roughness: Math.min(1, Math.max(0, water.roughness.getValue())), medium: water.medium.to_gpu_record(),
             backscattering: [0, 0, 0, 0], extinction: [0, 0, 0, 0], diffuse_transmittance: 0 };
         if (entry.row === -1) { entry.row = bodies.add(record); } else { bodies.set(entry.row, record); }
     }
 
-    /** World-space radius and velocity kick; position is interpreted in the CPU-owned pose. */
+    /**
+     * A splash at a world position: rings of wave particles of the given world radius (half their wavelength)
+     * whose height is the given vertical velocity kick, m/s, over the time a crest takes to cross them. The
+     * position is interpreted in the CPU-owned pose; queued on the CPU and spent on the GPU, sixteen a body a frame.
+     */
     splash(entity, position, radius, strength) {
         const entry = this.#entries.get(entity); assert.defined(entry, 'water entity');
         assert.greaterThan(radius, 0, 'radius'); assert.isFinite(radius, 'radius'); assert.isFinite(strength, 'strength');
         for (let i = 0; i < 3; i++) { assert.isFinite(position[i], `position[${i}]`); }
-        const inverse = new Float64Array(16);
+        const inverse = SPLASH_INVERSE;
         assert.ok(m4_invert(inverse, entry.transform), 'water transform is singular');
         const x = inverse[0] * position[0] + inverse[4] * position[1] + inverse[8] * position[2] + inverse[12];
         const z = inverse[2] * position[0] + inverse[6] * position[1] + inverse[10] * position[2] + inverse[14];
-        entry.impulses.push([x, z, radius, strength]); this.#impulses.add(entry); this.#dirty.add(entry);
+        entry.queue.push(x, z, radius, strength); this.#impulses.add(entry);
     }
 
     record_surface(frame) {
-        const scene = frame.view.scene;
+        const view = frame.view, scene = view.scene;
         if (scene.scene !== this.#scene) { return; }
-        this.#waves.record({ graph: frame.graph, device: this.#graphics.renderer.graphics.device, scene });
-        this.#bodies.record({ graph: frame.graph, scene });
+        this.#waves.record({ graph: frame.graph, device: this.#graphics.renderer.graphics.device, scene, time: this.#time,
+            view: { camera: view.camera.gpu_buffer, projection: view.camera.camera.projection_matrix, height: view.resolution[1] },
+            pixels: this.#renderer.settings.tessellation_pixels });
     }
     record(frame) {
         const inspection = this.#renderer.inspect(frame.graph, frame.view, frame.resolution);

package/src/engine/input/devices/PointerDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PointerDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/PointerDevice.js"],"names":[],"mappings":"AA2NA;;;;;GAKG;AACH,mDAJW,OAAO,SACP,UAAU,GAAC,KAAK,WAChB,OAAO,QAejB;AAED;;;;;GAKG;AACH;IAuFI;;;;OAIG;IACH,wBAHW,WAAW,EA+BrB;IAtHD;;;;OAIG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;OAEG;IACH;;;QAGI;;;;;;WAMG;;;QAGH;;WAEG;;;;;;;;;MASL;IAeF;;;OAGG;IACH,kBAAkB;IAElB;;;;OAIG;IACH,kBAFU,iBAAiB,EAAE,CAEL;IAExB;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,0CAEC;IAED;;;OAGG;IACH,2CAEC;IAyID;;;OAGG;IACH,oBAFY,OAAO,CAIlB;IAED;;;OAGG;IACH,4BAsBC;IAED,0BAEC;IAED;;;;OAIG;IACH,qCAHW,OAAO,SACP,UAAU,GAAC,KAAK,QAI1B;IAED,cAiCC;IAED,aA4BC;;CACJ;oBAnkBmB,+BAA+B;mBADhC,uCAAuC;kCAOxB,wBAAwB"}
+{"version":3,"file":"PointerDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/PointerDevice.js"],"names":[],"mappings":"AAgPA;;;;;GAKG;AACH,mDAJW,OAAO,SACP,UAAU,GAAC,KAAK,WAChB,OAAO,QAejB;AAED;;;;;GAKG;AACH;IAyFI;;;;OAIG;IACH,wBAHW,WAAW,EA+BrB;IAtHD;;;;OAIG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;OAEG;IACH;;;QAGI;;;;;;WAMG;;;QAGH;;WAEG;;;;;;;;;MASL;IAeF;;;OAGG;IACH,kBAAkB;IAElB;;;;OAIG;IACH,kBAFU,iBAAiB,EAAE,CAEL;IAExB;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,0CAEC;IAED;;;OAGG;IACH,2CAEC;IA2ID;;;OAGG;IACH,oBAFY,OAAO,CAIlB;IAED;;;OAGG;IACH,4BAsBC;IAED,0BAEC;IAED;;;;OAIG;IACH,qCAHW,OAAO,SACP,UAAU,GAAC,KAAK,QAI1B;IAED,cAiCC;IAED,aA4BC;;CACJ;oBA5lBmB,+BAA+B;mBADhC,uCAAuC;kCAOxB,wBAAwB"}

package/src/engine/input/devices/PointerDevice.js

@@ -20,6 +20,7 @@ import { suppressContextMenu } from "./mouse/suppressContextMenu.js";
  * @param {number} [options.maxDistance] in pixels
  * @param {number} [options.maxDelay] Maximum delay between down and up events in seconds
  * @param {Signal} options.signal
+ * @returns {(id?:number)=>void} clears pending candidates without emitting a tap
  */
 function observeTap({
                         up,
@@ -139,6 +140,16 @@ function observeTap({
     }
 
     down.add(handleDown);
+
+    return id => {
+        if (id !== undefined) {
+            reset(id);
+            return;
+        }
+        active.clear();
+        up.remove(handleUp);
+        move.remove(handleMove);
+    };
 }
 
 /**
@@ -149,6 +160,7 @@ function observeTap({
  * @param {Signal} dragStart
  * @param {Signal} dragEnd
  * @param {Signal} drag
+ * @returns {()=>void} removes pending gesture observations without emitting a drag end
  */
 function observeDrag(up, down, move, dragStart, dragEnd, drag) {
     const origin = new Vector2();
@@ -188,7 +200,8 @@ function observeDrag(up, down, move, dragStart, dragEnd, drag) {
 
         lastDragPosition.copy(origin);
         dragStart.send2(origin, event);
-        handleDrag(position, event);
+        // A start consumer can stop the device and remove this gesture before motion is delivered.
+        if (up.contains(handleDragEnd)) handleDrag(position, event);
     }
 
     const lastDragPosition = new Vector2();
@@ -214,6 +227,14 @@ function observeDrag(up, down, move, dragStart, dragEnd, drag) {
     }
 
     down.add(handleDown);
+
+    return () => {
+        // Overlapping presses can register these owned observations more than once.
+        while (up.remove(noDrag)) {}
+        while (up.remove(handleDragEnd)) {}
+        while (move.remove(handleDragStart)) {}
+        while (move.remove(handleDrag)) {}
+    };
 }
 
 
@@ -245,6 +266,8 @@ export function readPositionFromMouseEvent(result, event, source = event.target)
  * @copyright Company Named Limited (c) 2026
  */
 export class PointerDevice {
+    #resetTap;
+    #resetDrag;
 
     /**
      * Current live position of the pointer
@@ -355,14 +378,14 @@ export class PointerDevice {
         // `globalUp`, not `up`, for the same reason observeDrag below uses it: `up` only fires for
         // a release over the element, so a press that lifted one pixel outside the canvas was
         // never resolved and never reset - the candidate simply sat in the map.
-        observeTap({
+        this.#resetTap = observeTap({
             up: this.on.globalUp,
             down: this.on.down,
             move: this.on.move,
             maxDistance: 10,
             signal: this.on.tap
         });
-        observeDrag(this.on.globalUp, this.on.down, this.on.move, this.on.dragStart, this.on.dragEnd, this.on.drag);
+        this.#resetDrag = observeDrag(this.on.globalUp, this.on.down, this.on.move, this.on.dragStart, this.on.dragEnd, this.on.drag);
 
     }
 
@@ -424,7 +447,9 @@ export class PointerDevice {
      * every button for the same reason. The pointer was the one device of the three that did not,
      * with `PointerEvents.Cancel` sitting unused in the event table as the tell.
      */
-    #releaseAllButtons = () => {
+    #releaseAllButtons = event => {
+        this.#resetTap(event?.type === PointerEvents.Cancel ? event.pointerId : undefined);
+        this.#resetDrag();
         const buttons = this.buttons;
 
         for (let i = 0; i < buttons.length; i++) {

package/src/engine/intelligence/behavior/selector/WeightedRandomBehavior.d.ts

@@ -2,6 +2,7 @@
  * Picks a random behavior to execute.
  * The selection is done during initialization, and that selected behavior will then run to completion.
  * NOTE: Weights are relative, so they don't need to add up to any specific value.
+ * If every weight is zero, no child runs and the selector fails.
  *
  * @example
  *  const behavior = WeightedRandomBehavior.from([

package/src/engine/intelligence/behavior/selector/WeightedRandomBehavior.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WeightedRandomBehavior.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/intelligence/behavior/selector/WeightedRandomBehavior.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH;IAkEI;;;;OAIG;IACH,sBAHW,8BAAyB,EAAE,GACzB,sBAAsB,CAUlC;;IA7ED;;;;OAIG;IACH,mBAAgB;IAEhB;;;;OAIG;IACH,iBAA+B;IAE/B;;;;OAIG;IACH,mBAAuB;IAEvB;;;OAGG;IACH,iBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,sBAFW,8BAAyB,EAAE,QAcrC;IAED;;;OAGG;IACH,cAFW,8BAAyB,QAanC;IAiBD,iBAYC;IAkBD,6BAEC;CACJ;yBAnIwB,gBAAgB;gCACT,sBAAsB"}
+{"version":3,"file":"WeightedRandomBehavior.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/intelligence/behavior/selector/WeightedRandomBehavior.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;GAcG;AACH;IAkEI;;;;OAIG;IACH,sBAHW,8BAAyB,EAAE,GACzB,sBAAsB,CAUlC;;IA7ED;;;;OAIG;IACH,mBAAgB;IAEhB;;;;OAIG;IACH,iBAA+B;IAE/B;;;;OAIG;IACH,mBAAuB;IAEvB;;;OAGG;IACH,iBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,sBAFW,8BAAyB,EAAE,QAcrC;IAED;;;OAGG;IACH,cAFW,8BAAyB,QAanC;IAiBD,iBAiBC;IAsBD,6BAEC;CACJ;yBA9IwB,gBAAgB;gCAET,sBAAsB"}

package/src/engine/intelligence/behavior/selector/WeightedRandomBehavior.js

@@ -2,12 +2,14 @@ import { assert } from "../../../../core/assert.js";
 import { weightedRandomFromArray } from "../../../../core/collection/array/weightedRandomFromArray.js";
 import { seededRandom } from "../../../../core/math/random/seededRandom.js";
 import { Behavior } from "../Behavior.js";
+import { BehaviorStatus } from "../BehaviorStatus.js";
 import { WeightedElement } from "./WeightedElement.js";
 
 /**
  * Picks a random behavior to execute.
  * The selection is done during initialization, and that selected behavior will then run to completion.
  * NOTE: Weights are relative, so they don't need to add up to any specific value.
+ * If every weight is zero, no child runs and the selector fails.
  *
  * @example
  *  const behavior = WeightedRandomBehavior.from([
@@ -106,6 +108,11 @@ export class WeightedRandomBehavior extends Behavior {
          */
         const weightedElement = weightedRandomFromArray(this.__elements, this.__random, WeightedElement.getWeight);
 
+        if (weightedElement === undefined) {
+            this.__selected = undefined;
+            return;
+        }
+
         const selected = weightedElement.data;
 
         assert.equal(selected.isBehavior, true, 'selected.isBehavior !== true');
@@ -118,18 +125,22 @@ export class WeightedRandomBehavior extends Behavior {
 
         this.__select();
 
-        this.__selected.initialize(context);
+        if (this.__selected !== undefined) {
+            this.__selected.initialize(context);
+        }
     }
 
     finalize() {
         super.finalize();
 
-        this.__selected.finalize();
+        if (this.__selected !== undefined) {
+            this.__selected.finalize();
+        }
 
         this.__selected = undefined;
     }
 
     tick(timeDelta) {
-        return this.__selected.tick(timeDelta);
+        return this.__selected === undefined ? BehaviorStatus.Failed : this.__selected.tick(timeDelta);
     }
 }

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

@@ -66,11 +66,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#426@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#430@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#426@#clear_field"(fluid: FluidComponent): void;
+    static "__#430@#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
@@ -82,7 +82,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#426@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#430@#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
@@ -102,7 +102,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#426@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#430@#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 Transform64> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/engine/physics/fluid/solver/v3_grid_advect_maccormack_velocity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_advect_maccormack_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_maccormack_velocity.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,4DAbW,YAAY,EAAE,WACd,YAAY,EAAE,aACd,YAAY,aACZ,YAAY,aACZ,YAAY,mBACZ,YAAY,EAAE,SAEd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QAgHpB"}
+{"version":3,"file":"v3_grid_advect_maccormack_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_maccormack_velocity.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,4DAbW,YAAY,EAAE,WACd,YAAY,EAAE,aACd,YAAY,aACZ,YAAY,aACZ,YAAY,mBACZ,YAAY,EAAE,SAEd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QAuHpB"}

package/src/engine/physics/fluid/solver/v3_grid_advect_maccormack_velocity.js

@@ -1,7 +1,7 @@
 import { v3_grid_limit8_at_indices } from "./v3_grid_limit8_at_indices.js";
 import { assert } from "../../../../core/assert.js";
 import { clamp } from "../../../../core/math/clamp.js";
-import { scs3d_sample_linear3 } from "../../../graphics/texture/3d/scs3d_sample_linear3.js";
+import { scs3d_sample_linear3_array } from "../../../graphics/texture/3d/scs3d_sample_linear3.js";
 
 /*
  * COLLOCATED VARIANT. FluidSimulator transports through the MAC (staggered-grid) kernels in the sibling
@@ -76,6 +76,7 @@ export function v3_grid_advect_maccormack_velocity(outputs, sources, carrier_x,
     const last_y = res_y - 1;
     const last_z = res_z - 1;
     const sample = scratch_sample;
+    const position = scratch_position;
 
     // ─── pass 1: forward SL step into the scratch trio ──────────────────────
     for (let z = 0; z < res_z; z++) {
@@ -93,7 +94,10 @@ export function v3_grid_advect_maccormack_velocity(outputs, sources, carrier_x,
                 const s_x = x - carrier_x[c] * time_delta;
                 const s_y = y - carrier_y[c] * time_delta;
                 const s_z = z - carrier_z[c] * time_delta;
-                scs3d_sample_linear3(sample, src_x, src_y, src_z, res_x, res_y, res_z, s_x, s_y, s_z);
+                position[0] = s_x;
+                position[1] = s_y;
+                position[2] = s_z;
+                scs3d_sample_linear3_array(sample, src_x, src_y, src_z, res_x, res_y, res_z, position, 0);
                 fwd_x[c] = sample[0];
                 fwd_y[c] = sample[1];
                 fwd_z[c] = sample[2];
@@ -119,7 +123,10 @@ export function v3_grid_advect_maccormack_velocity(outputs, sources, carrier_x,
                 const vy = carrier_y[c] * time_delta;
                 const vz = carrier_z[c] * time_delta;
 
-                scs3d_sample_linear3(sample, fwd_x, fwd_y, fwd_z, res_x, res_y, res_z, x + vx, y + vy, z + vz);
+                position[0] = x + vx;
+                position[1] = y + vy;
+                position[2] = z + vz;
+                scs3d_sample_linear3_array(sample, fwd_x, fwd_y, fwd_z, res_x, res_y, res_z, position, 0);
                 const corr_x = fwd_x[c] + 0.5 * (src_x[c] - sample[0]);
                 const corr_y = fwd_y[c] + 0.5 * (src_y[c] - sample[1]);
                 const corr_z = fwd_z[c] + 0.5 * (src_z[c] - sample[2]);
@@ -160,3 +167,5 @@ export function v3_grid_advect_maccormack_velocity(outputs, sources, carrier_x,
 
 /** Module-static sample destination — avoids per-cell allocation. */
 const scratch_sample = new Float32Array(3);
+/** Continuous coordinates passed to the sampler during this synchronous typed-array sweep. */
+const scratch_position = new Float64Array(3);

package/src/engine/physics/fluid/solver/v3_grid_advect_sl_velocity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_advect_sl_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_sl_velocity.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,oDAdW,YAAY,EAAE,WACd,YAAY,EAAE,aAEd,YAAY,aACZ,YAAY,aACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA+DpB"}
+{"version":3,"file":"v3_grid_advect_sl_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_sl_velocity.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,oDAdW,YAAY,EAAE,WACd,YAAY,EAAE,aAEd,YAAY,aACZ,YAAY,aACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QAmEpB"}

package/src/engine/physics/fluid/solver/v3_grid_advect_sl_velocity.js

@@ -1,5 +1,5 @@
 import { assert } from "../../../../core/assert.js";
-import { scs3d_sample_linear3 } from "../../../graphics/texture/3d/scs3d_sample_linear3.js";
+import { scs3d_sample_linear3_array } from "../../../graphics/texture/3d/scs3d_sample_linear3.js";
 
 /*
  * COLLOCATED VARIANT. FluidSimulator transports through the MAC (staggered-grid) kernels in the sibling
@@ -72,6 +72,7 @@ export function v3_grid_advect_sl_velocity(outputs, sources, carrier_x, carrier_
 
     const slice_size = res_x * res_y;
     const sample = scratch_sample;
+    const position = scratch_position;
 
     for (let z = 0; z < res_z; z++) {
         const z_off = z * slice_size;
@@ -94,7 +95,10 @@ export function v3_grid_advect_sl_velocity(outputs, sources, carrier_x, carrier_
                 const s_y = y - carrier_y[c] * time_delta;
                 const s_z = z - carrier_z[c] * time_delta;
 
-                scs3d_sample_linear3(sample, src_x, src_y, src_z, res_x, res_y, res_z, s_x, s_y, s_z);
+                position[0] = s_x;
+                position[1] = s_y;
+                position[2] = s_z;
+                scs3d_sample_linear3_array(sample, src_x, src_y, src_z, res_x, res_y, res_z, position, 0);
                 out_x[c] = sample[0];
                 out_y[c] = sample[1];
                 out_z[c] = sample[2];
@@ -105,3 +109,5 @@ export function v3_grid_advect_sl_velocity(outputs, sources, carrier_x, carrier_
 
 /** Module-static sample destination — avoids per-cell allocation. */
 const scratch_sample = new Float32Array(3);
+/** Continuous coordinates passed to the sampler during this synchronous typed-array sweep. */
+const scratch_position = new Float64Array(3);

package/src/engine/physics/fluid/solver/v3_grid_sample_scalar_masked.d.ts

@@ -27,4 +27,23 @@
  * @return {number}
  */
 export function v3_grid_sample_scalar_masked(data: Float32Array, solid: Uint8Array, res_x: number, res_y: number, res_z: number, x: number, y: number, z: number, fallback: number): number;
+/**
+ * {@link v3_grid_sample_scalar_masked} with `[x, y, z, fallback]` read from a reusable operand record
+ * and the sample written into `out`. No continuous number crosses the call boundary, including the
+ * result, so a per-cell caller does not need this sampler to be inlined to avoid numeric boxes.
+ *
+ * The operands are read before any output write; `out` may overlap `operands` or `data`. Float64
+ * operands preserve the scalar form's coordinate and fallback precision.
+ *
+ * @param {Float32Array|Float64Array|number[]} out
+ * @param {number} out_offset
+ * @param {Float32Array} data
+ * @param {Uint8Array} solid
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Float64Array} operands `[x, y, z, fallback]`
+ * @param {number} operands_offset
+ */
+export function v3_grid_sample_scalar_masked_array(out: Float32Array | Float64Array | number[], out_offset: number, data: Float32Array, solid: Uint8Array, res_x: number, res_y: number, res_z: number, operands: Float64Array, operands_offset: number): void;
 //# sourceMappingURL=v3_grid_sample_scalar_masked.d.ts.map

package/src/engine/physics/fluid/solver/v3_grid_sample_scalar_masked.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_sample_scalar_masked.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_sample_scalar_masked.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,mDAXW,YAAY,SACZ,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACL,MAAM,CA+DjB"}
+{"version":3,"file":"v3_grid_sample_scalar_masked.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_sample_scalar_masked.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,mDAXW,YAAY,SACZ,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACL,MAAM,CAYjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wDAVW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,QACN,YAAY,SACZ,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,YACN,YAAY,mBACZ,MAAM,QAqEhB"}

package/src/engine/physics/fluid/solver/v3_grid_sample_scalar_masked.js

@@ -1,5 +1,8 @@
 import { clamp } from "../../../../core/math/clamp.js";
 
+const scratch_operands = new Float64Array(4);
+const scratch_sample = new Float64Array(1);
+
 /**
  * Trilinearly sample a cell-centered scalar at a fractional position,
  * EXCLUDING solid cells from the interpolation: solid taps contribute zero
@@ -29,6 +32,41 @@ import { clamp } from "../../../../core/math/clamp.js";
  * @return {number}
  */
 export function v3_grid_sample_scalar_masked(data, solid, res_x, res_y, res_z, x, y, z, fallback) {
+    const operands = scratch_operands;
+    operands[0] = x;
+    operands[1] = y;
+    operands[2] = z;
+    operands[3] = fallback;
+
+    v3_grid_sample_scalar_masked_array(scratch_sample, 0, data, solid, res_x, res_y, res_z, operands, 0);
+
+    return scratch_sample[0];
+}
+
+/**
+ * {@link v3_grid_sample_scalar_masked} with `[x, y, z, fallback]` read from a reusable operand record
+ * and the sample written into `out`. No continuous number crosses the call boundary, including the
+ * result, so a per-cell caller does not need this sampler to be inlined to avoid numeric boxes.
+ *
+ * The operands are read before any output write; `out` may overlap `operands` or `data`. Float64
+ * operands preserve the scalar form's coordinate and fallback precision.
+ *
+ * @param {Float32Array|Float64Array|number[]} out
+ * @param {number} out_offset
+ * @param {Float32Array} data
+ * @param {Uint8Array} solid
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Float64Array} operands `[x, y, z, fallback]`
+ * @param {number} operands_offset
+ */
+export function v3_grid_sample_scalar_masked_array(out, out_offset, data, solid, res_x, res_y, res_z, operands, operands_offset) {
+    const x = operands[operands_offset];
+    const y = operands[operands_offset + 1];
+    const z = operands[operands_offset + 2];
+    const fallback = operands[operands_offset + 3];
+
     const x_max = res_x - 1;
     const y_max = res_y - 1;
     const z_max = res_z - 1;
@@ -80,7 +118,8 @@ export function v3_grid_sample_scalar_masked(data, solid, res_x, res_y, res_z, x
 
     const total = w000 + w100 + w010 + w110 + w001 + w101 + w011 + w111;
     if (total <= 0) {
-        return fallback;
+        out[out_offset] = fallback;
+        return;
     }
 
     const sum = w000 * data[c000] + w100 * data[c100]
@@ -88,5 +127,5 @@ export function v3_grid_sample_scalar_masked(data, solid, res_x, res_y, res_z, x
         + w001 * data[c001] + w101 * data[c101]
         + w011 * data[c011] + w111 * data[c111];
 
-    return sum / total;
+    out[out_offset] = sum / total;
 }

package/src/engine/physics/fluid/solver/v3_mac_advect_scalar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_mac_advect_scalar.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_advect_scalar.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,gDAXW,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA4CpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wDAZW,YAAY,SACZ,YAAY,mBACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA8GpB"}
+{"version":3,"file":"v3_mac_advect_scalar.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_advect_scalar.js"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,gDAXW,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QAgDpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wDAZW,YAAY,SACZ,YAAY,mBACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA8GpB"}