@woosh/meep-engine 3.41.0 → 3.42.0

package/src/engine/graphics/ecs/water/WaterWavesSerializationUpgrader_0_1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WaterWavesSerializationUpgrader_0_1.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterWavesSerializationUpgrader_0_1.js"],"names":[],"mappings":"AAWA,+DAA+D;AAC/D;IAII,wCAIC;CACJ;oCArBmC,oDAAoD"}

package/src/engine/graphics/ecs/water/WaterWavesSerializationUpgrader_0_1.js

@@ -0,0 +1,22 @@
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+
+/**
+ * The fields version 1 appended, with the defaults they had at that version: constants, not read off the
+ * current `WaterWaves`, since an upgrader writes the format of its target version.
+ */
+const VERSION_1_DEFAULTS = [
+    0, // upwind fetch, metres
+    0.5, // shore reflection
+];
+
+/** Keep version 0's wind and append the version-1 defaults. */
+export class WaterWavesSerializationUpgrader_0_1 extends BinaryClassUpgrader {
+    __startVersion = 0;
+    __targetVersion = 1;
+
+    upgrade(source, target) {
+        target.writeFloat32(source.readFloat32());
+        target.writeFloat32(source.readFloat32());
+        for (const value of VERSION_1_DEFAULTS) { target.writeFloat32(value); }
+    }
+}

package/src/engine/graphics/geometry/buffered/query/bvh32_geometry_raycast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bvh32_geometry_raycast.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/geometry/buffered/query/bvh32_geometry_raycast.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;GAiBG;AACH,+CAhBW,aAAa,kCAEb,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,iBAC1B,MAAM,iBACN,MAAM,0BACN,OAAO,WACP,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,SAAS,YACpC,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,gBACN,MAAM,GACJ,OAAO,CA+DnB;8BA5F6B,8CAA8C"}
+{"version":3,"file":"bvh32_geometry_raycast.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/geometry/buffered/query/bvh32_geometry_raycast.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;GAiBG;AACH,+CAhBW,aAAa,kCAEb,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,iBAC1B,MAAM,iBACN,MAAM,0BACN,OAAO,WACP,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,SAAS,YACpC,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,gBACN,MAAM,GACJ,OAAO,CA6DnB;8BA1F6B,8CAA8C"}

package/src/engine/graphics/geometry/buffered/query/bvh32_geometry_raycast.js

@@ -1,7 +1,7 @@
 import { assert } from "../../../../../core/assert.js";
 import { bvh32_query_user_data_ray } from "../../../../../core/bvh2/binary/2/bvh32_query_user_data_ray.js";
 import { SurfacePoint3 } from "../../../../../core/geom/3d/SurfacePoint3.js";
-import { tri3_ray_intersection } from "../../../../../core/geom/3d/triangle/tri3_ray_intersection.js";
+import { tri3_ray_intersection_triangle_array } from "../../../../../core/geom/3d/triangle/tri3_ray_intersection.js";
 import { read_triangle_vertices } from "../read_triangle_vertices.js";
 
 const scratch_array = []
@@ -68,13 +68,11 @@ export function bvh32_geometry_raycast(
             triangle_index
         );
 
-        const triangle_hit_found = tri3_ray_intersection(
+        const triangle_hit_found = tri3_ray_intersection_triangle_array(
             scratch_hit,
             origin_x, origin_y, origin_z,
             direction_x, direction_y, direction_z,
-            triangle_scratch[0], triangle_scratch[1], triangle_scratch[2],
-            triangle_scratch[3], triangle_scratch[4], triangle_scratch[5],
-            triangle_scratch[6], triangle_scratch[7], triangle_scratch[8]
+            triangle_scratch, 0
         )
 
         if (!triangle_hit_found) {

package/src/engine/graphics/texture/3d/scs3d_sample_linear3.d.ts

@@ -24,4 +24,24 @@
  * @return {Float32Array|number[]} `out`, for chaining.
  */
 export function scs3d_sample_linear3(out: Float32Array | number[], data_0: Float32Array, data_1: Float32Array, data_2: Float32Array, res_x: number, res_y: number, res_z: number, x: number, y: number, z: number): Float32Array | number[];
+/**
+ * {@link scs3d_sample_linear3} with the position read from `position[position_offset ..+2]`.
+ * For per-cell callers, passing fractional coordinates in a reusable array avoids numeric argument
+ * boxes when the sampler is not inlined. Float64 coordinates preserve the scalar form's precision.
+ *
+ * The three coordinates are read before any output store, so `position` may overlap `out` and a
+ * reentrant output setter cannot change the coordinates used by the scalar facade's sample.
+ *
+ * @param {Float32Array|Float64Array|number[]} out length >= 3
+ * @param {Float32Array} data_0
+ * @param {Float32Array} data_1
+ * @param {Float32Array} data_2
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Float64Array} position `[x, y, z]`, in grid index space
+ * @param {number} position_offset
+ * @return {Float32Array|Float64Array|number[]} `out`, for chaining.
+ */
+export function scs3d_sample_linear3_array(out: Float32Array | Float64Array | number[], data_0: Float32Array, data_1: Float32Array, data_2: Float32Array, res_x: number, res_y: number, res_z: number, position: Float64Array, position_offset: number): Float32Array | Float64Array | number[];
 //# sourceMappingURL=scs3d_sample_linear3.d.ts.map

package/src/engine/graphics/texture/3d/scs3d_sample_linear3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scs3d_sample_linear3.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/3d/scs3d_sample_linear3.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,0CAZW,YAAY,GAAC,MAAM,EAAE,UACrB,YAAY,UACZ,YAAY,UACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAsDhC"}
+{"version":3,"file":"scs3d_sample_linear3.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/3d/scs3d_sample_linear3.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,0CAZW,YAAY,GAAC,MAAM,EAAE,UACrB,YAAY,UACZ,YAAY,UACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAWhC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,gDAXW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,UAClC,YAAY,UACZ,YAAY,UACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,YACN,YAAY,mBACZ,MAAM,GACL,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,CA0D7C"}

package/src/engine/graphics/texture/3d/scs3d_sample_linear3.js

@@ -1,6 +1,8 @@
 import { clamp } from "../../../../core/math/clamp.js";
 import { lerp } from "../../../../core/math/lerp.js";
 
+const scratch_position = new Float64Array(3);
+
 /**
  * Trilinearly sample THREE single-channel 3D grids at the same fractional
  * position, sharing one set of corner indices and interpolation weights.
@@ -27,6 +29,40 @@ import { lerp } from "../../../../core/math/lerp.js";
  * @return {Float32Array|number[]} `out`, for chaining.
  */
 export function scs3d_sample_linear3(out, data_0, data_1, data_2, res_x, res_y, res_z, x, y, z) {
+    const position = scratch_position;
+    position[0] = x;
+    position[1] = y;
+    position[2] = z;
+
+    scs3d_sample_linear3_array(out, data_0, data_1, data_2, res_x, res_y, res_z, position, 0);
+
+    return out;
+}
+
+/**
+ * {@link scs3d_sample_linear3} with the position read from `position[position_offset ..+2]`.
+ * For per-cell callers, passing fractional coordinates in a reusable array avoids numeric argument
+ * boxes when the sampler is not inlined. Float64 coordinates preserve the scalar form's precision.
+ *
+ * The three coordinates are read before any output store, so `position` may overlap `out` and a
+ * reentrant output setter cannot change the coordinates used by the scalar facade's sample.
+ *
+ * @param {Float32Array|Float64Array|number[]} out length >= 3
+ * @param {Float32Array} data_0
+ * @param {Float32Array} data_1
+ * @param {Float32Array} data_2
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Float64Array} position `[x, y, z]`, in grid index space
+ * @param {number} position_offset
+ * @return {Float32Array|Float64Array|number[]} `out`, for chaining.
+ */
+export function scs3d_sample_linear3_array(out, data_0, data_1, data_2, res_x, res_y, res_z, position, position_offset) {
+    const x = position[position_offset];
+    const y = position[position_offset + 1];
+    const z = position[position_offset + 2];
+
     const x_max = res_x - 1;
     const y_max = res_y - 1;
     const z_max = res_z - 1;

package/src/engine/graphics3/WaterSystem.d.ts

@@ -2,6 +2,11 @@
  * 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<any> {
     constructor(graphics: any, scene: any);
@@ -19,7 +24,7 @@ export class WaterSystem extends System<any> {
         inscatter_segments: number;
         tessellation_pixels: number;
     };
-    get waves(): GPUWaterWaveSimulation;
+    get waves(): GPUWaterSurface;
     get transparency_channel(): GPUWaterRenderer;
     get scene(): any;
     request_probe(uv: any): Promise<any>;
@@ -30,7 +35,11 @@ export class WaterSystem extends System<any> {
     link(water: any, geometry: any, transform: any, entity: any): void;
     unlink(water: any, geometry: any, transform: any, entity: any): void;
     update(dt: any): void;
-    /** 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: any, position: any, radius: any, strength: any): void;
     record_surface(frame: any): void;
     record(frame: any): void;
@@ -52,7 +61,7 @@ import { MeshletGeometry } from "../../shade/renderer/geometry/MeshletGeometry.j
 import Water from "../graphics/ecs/water/Water.js";
 import WaterWaves from "../graphics/ecs/water/WaterWaves.js";
 import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
-import { GPUWaterWaveSimulation } from "../../shade/renderer/water/surface/GPUWaterWaveSimulation.js";
+import { GPUWaterSurface } from "../../shade/renderer/water/surface/GPUWaterSurface.js";
 import { GPUWaterRenderer } from "../../shade/renderer/water/GPUWaterRenderer.js";
 import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
 //# sourceMappingURL=WaterSystem.d.ts.map

package/src/engine/graphics3/WaterSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WaterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/WaterSystem.js"],"names":[],"mappings":"AAyBA;;;;GAIG;AACH;IAyBI,uCAcC;IAtCD,6EAAqD;IACrD,kEAA0F;IAY1F;;;;;;;;;;;MAAkD;IAClD,oCAAmC;IACnC,6CAAqD;IACrD,iBAAmC;IACnC,qCAA8D;IAE9D,0BAGC;IAJD,mBAAiC;IAsBjC,2CAOC;IAED,0BAMC;IAED,mEAoBC;IAUD,qEAkBC;IAED,sBAgBC;IA0CD,2FAA2F;IAC3F,qEASC;IAED,iCAKC;IACD,yBAGC;;CACJ;AAED;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAA4C;CAC/C;AACD;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAAoD;CACvD;uBAlOsB,kBAAkB;4BAEb,iCAAiC;gCAI7B,kDAAkD;kBARhE,gCAAgC;uBAC3B,qCAAqC;4CAShB,iDAAiD;uCAGtD,8DAA8D;iCAFpE,gDAAgD;gCAIjD,mDAAmD"}
+{"version":3,"file":"WaterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/WaterSystem.js"],"names":[],"mappings":"AA+BA;;;;;;;;;GASG;AACH;IA2BI,uCAaC;IAvCD,6EAAqD;IACrD,kEAA0F;IAc1F;;;;;;;;;;;MAAkD;IAClD,6BAAmC;IACnC,6CAAqD;IACrD,iBAAmC;IACnC,qCAA8D;IAE9D,0BAGC;IAJD,mBAAiC;IAqBjC,2CAOC;IAED,0BAMC;IAED,mEAsBC;IAQD,qEAkBC;IAED,sBAoBC;IAqDD;;;;OAIG;IACH,qEASC;IAED,iCAMC;IACD,yBAGC;;CACJ;AAED;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAA4C;CAC/C;AACD;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAAoD;CACvD;uBAlQsB,kBAAkB;4BAEb,iCAAiC;gCAI7B,kDAAkD;kBARhE,gCAAgC;uBACe,qCAAqC;4CAS1D,iDAAiD;gCAG7D,uDAAuD;iCAFtD,gDAAgD;gCAIjD,mDAAmD"}

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 "__#429@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#426@#clear_field"(fluid: FluidComponent): void;
+    static "__#429@#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 "__#429@#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 "__#429@#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"}