@woosh/meep-engine 3.41.0 → 3.43.0

package/src/engine/graphics/ecs/water/Water.d.ts

@@ -28,6 +28,15 @@ declare class Water {
      * @type {Vector1}
      */
     roughness: Vector1;
+    /**
+     * Whether the body's surface keeps moving while no view sees it. Off (the default), a hidden body is paused:
+     * its wave particles stand still and its wind turn holds until it comes back into view, and it costs one
+     * culling test a frame. On, it is simulated every frame wherever the camera looks, at the cost of a visible
+     * body's simulation — for water whose ripples must have travelled on when the camera turns back.
+     * Ambient waves follow time, not state: they are current either way.
+     * @type {ObservedBoolean}
+     */
+    simulateWhenHidden: ObservedBoolean;
     /** Optical edits queue a scene row update. */
     onChanged: Signal;
     /** @param {ParticipatingMedium} value */
@@ -42,6 +51,7 @@ declare class Water {
     toJSON(): {
         ior: number;
         roughness: number;
+        simulateWhenHidden: boolean;
         medium: any;
     };
     #private;
@@ -50,6 +60,7 @@ declare namespace Water {
     let typeName: string;
 }
 import Vector1 from "../../../../core/geom/Vector1.js";
+import ObservedBoolean from "../../../../core/model/ObservedBoolean.js";
 import Signal from "../../../../core/events/signal/Signal.js";
 import { ParticipatingMedium } from "../../../../shade/renderer/medium/ParticipatingMedium.js";
 //# sourceMappingURL=Water.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Water.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/Water.js"],"names":[],"mappings":";AASA;;;;;;;;;;;;;;;GAeG;AACH;IAmCI,0BAQC;IA1CD;;;OAGG;IACH,KAFU,OAAO,CAEQ;IAEzB;;;;OAIG;IACH,WAFU,OAAO,CAEa;IAE9B,8CAA8C;IAC9C,kBAAyB;IAWzB,yCAAyC;IACzC,uCAMC;IAbD;;;;OAIG;IACH,kCAAqC;IAoBrC,0BAgBC;IAED;;;;MAMC;;CACJ;;;;oBA9FmB,kCAAkC;mBADnC,0CAA0C;oCAEzB,0DAA0D"}
+{"version":3,"file":"Water.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/Water.js"],"names":[],"mappings":";AAUA;;;;;;;;;;;;;;;GAeG;AACH;IA6CI,0BASC;IArDD;;;OAGG;IACH,KAFU,OAAO,CAEQ;IAEzB;;;;OAIG;IACH,WAFU,OAAO,CAEa;IAE9B;;;;;;;OAOG;IACH,oBAFU,eAAe,CAEuB;IAEhD,8CAA8C;IAC9C,kBAAyB;IAWzB,yCAAyC;IACzC,uCAMC;IAbD;;;;OAIG;IACH,kCAAqC;IAqBrC,0BAoBC;IAED;;;;;MAOC;;CACJ;;;;oBA/GmB,kCAAkC;4BAC1B,2CAA2C;mBAFpD,0CAA0C;oCAGzB,0DAA0D"}

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

@@ -1,5 +1,6 @@
 import Signal from "../../../../core/events/signal/Signal.js";
 import Vector1 from "../../../../core/geom/Vector1.js";
+import ObservedBoolean from "../../../../core/model/ObservedBoolean.js";
 import { ParticipatingMedium } from "../../../../shade/renderer/medium/ParticipatingMedium.js";
 import {
     participating_medium_from_json,
@@ -37,6 +38,16 @@ class Water {
      */
     roughness = new Vector1(0.02);
 
+    /**
+     * Whether the body's surface keeps moving while no view sees it. Off (the default), a hidden body is paused:
+     * its wave particles stand still and its wind turn holds until it comes back into view, and it costs one
+     * culling test a frame. On, it is simulated every frame wherever the camera looks, at the cost of a visible
+     * body's simulation — for water whose ripples must have travelled on when the camera turns back.
+     * Ambient waves follow time, not state: they are current either way.
+     * @type {ObservedBoolean}
+     */
+    simulateWhenHidden = new ObservedBoolean(false);
+
     /** Optical edits queue a scene row update. */
     onChanged = new Signal();
     /** @type {ParticipatingMedium|null} */
@@ -61,6 +72,7 @@ class Water {
     constructor(options) {
         this.ior.onChanged.add(this.#changed);
         this.roughness.onChanged.add(this.#changed);
+        this.simulateWhenHidden.onChanged.add(this.#changed);
         this.medium = water_medium_default();
         if (options !== undefined) {
             console.error('Constructor options are deprecated');
@@ -81,6 +93,10 @@ class Water {
             this.roughness.fromJSON(json.roughness);
         }
 
+        if (typeof json.simulateWhenHidden === 'boolean') {
+            this.simulateWhenHidden.fromJSON(json.simulateWhenHidden);
+        }
+
         if (json.medium !== null && typeof json.medium === 'object') {
             participating_medium_from_json(this.medium, json.medium);
         }
@@ -90,6 +106,7 @@ class Water {
         return {
             ior: this.ior.toJSON(),
             roughness: this.roughness.toJSON(),
+            simulateWhenHidden: this.simulateWhenHidden.toJSON(),
             medium: participating_medium_to_json(this.medium),
         };
     }

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

@@ -1 +1 @@
-{"version":3,"file":"WaterSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterSerializationAdapter.js"],"names":[],"mappings":"AAOA;;IAEI,oBAAc;IAGd;;;;OAIG;IACH,uCAFW,KAAK,QAOf;IAED;;;;OAIG;IACH,yCAFW,KAAK,QAOf;CACJ;gDAnC+C,gEAAgE;kBAK9F,YAAY"}
+{"version":3,"file":"WaterSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterSerializationAdapter.js"],"names":[],"mappings":"AAOA;;IAEI,oBAAc;IAGd;;;;OAIG;IACH,uCAFW,KAAK,QAQf;IAED;;;;OAIG;IACH,yCAFW,KAAK,QAQf;CACJ;gDArC+C,gEAAgE;kBAK9F,YAAY"}

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

@@ -8,7 +8,7 @@ import Water from "./Water.js";
 export class WaterSerializationAdapter extends BinaryClassSerializationAdapter {
 
     klass = Water;
-    version = 4;
+    version = 5;
 
     /**
      *
@@ -20,6 +20,7 @@ export class WaterSerializationAdapter extends BinaryClassSerializationAdapter {
         buffer.writeFloat32(value.roughness.getValue());
 
         serialize_participating_medium(buffer, value.medium);
+        value.simulateWhenHidden.toBinaryBuffer(buffer);
     }
 
     /**
@@ -32,5 +33,6 @@ export class WaterSerializationAdapter extends BinaryClassSerializationAdapter {
         value.roughness.set(buffer.readFloat32());
 
         deserialize_participating_medium(buffer, value.medium);
+        value.simulateWhenHidden.fromBinaryBuffer(buffer);
     }
 }

package/src/engine/graphics/ecs/water/WaterSerializationUpgrader_4_5.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Keep version 4's optics and append `simulateWhenHidden` as version 5 introduced it: off, so a body saved before
+ * pauses while hidden, like every body by default.
+ */
+export class WaterSerializationUpgrader_4_5 extends BinaryClassUpgrader {
+    upgrade(source: any, target: any): void;
+}
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+//# sourceMappingURL=WaterSerializationUpgrader_4_5.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WaterSerializationUpgrader_4_5.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterSerializationUpgrader_4_5.js"],"names":[],"mappings":"AAOA;;;GAGG;AACH;IAII,wCAOC;CACJ;oCAvBmC,oDAAoD"}

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

@@ -0,0 +1,24 @@
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+import {
+    deserialize_participating_medium,
+    serialize_participating_medium
+} from "../../../../shade/renderer/medium/participating_medium_serialization.js";
+import { water_medium_default } from "../../../../shade/renderer/medium/water/water_presets.js";
+
+/**
+ * Keep version 4's optics and append `simulateWhenHidden` as version 5 introduced it: off, so a body saved before
+ * pauses while hidden, like every body by default.
+ */
+export class WaterSerializationUpgrader_4_5 extends BinaryClassUpgrader {
+    __startVersion = 4;
+    __targetVersion = 5;
+
+    upgrade(source, target) {
+        target.writeFloat32(source.readFloat32());
+        target.writeFloat32(source.readFloat32());
+        const medium = water_medium_default();
+        deserialize_participating_medium(source, medium);
+        serialize_participating_medium(target, medium);
+        target.writeUint8(0);
+    }
+}

package/src/engine/graphics/ecs/water/WaterWaves.d.ts

@@ -1,29 +1,50 @@
+/** Amplitude reflection coefficient of a water body's outline when nothing says otherwise. */
+export const WATER_WAVES_SHORE_REFLECTION_DEFAULT: 0.5;
 export default WaterWaves;
 /**
- * What drives the waves of the {@link Water} on the same entity, for the primitive wave
- * simulation.
+ * The waves of the {@link Water} on the same entity: the wind that raises them and how the body's outline
+ * treats them (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1).
  *
- * Kept apart from `Water` on purpose: `Water` describes the body and its optics, and says nothing
- * about how the surface moves. The production surface simulation replaces this component, its
- * system and its producer together, and `Water` stays as it is. A body without this component
- * tessellates its authored rest surface and allocates no wave grid until a splash is queued.
+ * Kept apart from `Water`, which describes the body and its optics and says nothing about how the surface
+ * moves. A body without this component is calm, and its outline reflects wave particles (from
+ * `WaterSystem.splash`) at the default coefficient.
+ *
+ * The wind's waves follow from physics: a fetch-limited JONSWAP sea of this wind speed over the water upwind
+ * — the body's own extent along the wind plus {@link upwindFetch} — so the same wind raises centimetre ripples
+ * on a puddle and swell on an open sea.
  */
 declare class WaterWaves {
     /**
-     * Wind speed at 10 m, m/s. Sets the forcing, which grows as its square, and the slope variance
-     * of the waves the simulation's grid does not resolve (Cox-Munk).
+     * Wind speed at 10 m, m/s.
      * @type {Vector1}
      */
     windSpeed: Vector1;
     /**
-     * Direction the wind blows towards, radians in the mesh's local xz plane, measured from +x towards +z.
+     * Direction the wind blows towards, radians in the body's local xz plane, measured from +x towards +z.
+     * The angle turns with the body's rotation and is not skewed by its scale. A change turns the waves over
+     * a few seconds.
      * @type {Vector1}
      */
     windDirection: Vector1;
+    /**
+     * Open water upwind of the mesh, metres, added to the mesh's own extent along the wind. Zero for a body
+     * that is all the water there is (a pool, a lake); an open sea states the distance to its far shore
+     * (a fully developed sea at 10 m/s needs about 170 km).
+     * @type {Vector1}
+     */
+    upwindFetch: Vector1;
+    /**
+     * Amplitude reflection coefficient of the mesh's outline for wave particles: 0 a beach that absorbs
+     * them, 1 a wall that returns them whole.
+     * @type {Vector1}
+     */
+    shoreReflection: Vector1;
     fromJSON(json: any): void;
     toJSON(): {
         windSpeed: number;
         windDirection: number;
+        upwindFetch: number;
+        shoreReflection: number;
     };
 }
 declare namespace WaterWaves {

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

@@ -1 +1 @@
-{"version":3,"file":"WaterWaves.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterWaves.js"],"names":[],"mappings":";AAEA;;;;;;;;GAQG;AACH;IACI;;;;OAIG;IACH,WAFU,OAAO,CAEU;IAE3B;;;OAGG;IACH,eAFU,OAAO,CAEc;IAE/B,0BAQC;IAED;;;MAKC;CACJ;;;;oBAzCmB,kCAAkC"}
+{"version":3,"file":"WaterWaves.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterWaves.js"],"names":[],"mappings":"AAEA,8FAA8F;AAC9F,uDAAwD;;AAExD;;;;;;;;;;;GAWG;AACH;IACI;;;OAGG;IACH,WAFU,OAAO,CAEU;IAE3B;;;;;OAKG;IACH,eAFU,OAAO,CAEc;IAE/B;;;;;OAKG;IACH,aAFU,OAAO,CAEY;IAE7B;;;;OAIG;IACH,iBAFU,OAAO,CAEmD;IAEpE,0BAgBC;IAED;;;;;MAOC;CACJ;;;;oBAzEmB,kCAAkC"}

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

@@ -1,28 +1,50 @@
 import Vector1 from "../../../../core/geom/Vector1.js";
 
+/** Amplitude reflection coefficient of a water body's outline when nothing says otherwise. */
+export const WATER_WAVES_SHORE_REFLECTION_DEFAULT = 0.5;
+
 /**
- * What drives the waves of the {@link Water} on the same entity, for the primitive wave
- * simulation.
+ * The waves of the {@link Water} on the same entity: the wind that raises them and how the body's outline
+ * treats them (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1).
+ *
+ * Kept apart from `Water`, which describes the body and its optics and says nothing about how the surface
+ * moves. A body without this component is calm, and its outline reflects wave particles (from
+ * `WaterSystem.splash`) at the default coefficient.
  *
- * Kept apart from `Water` on purpose: `Water` describes the body and its optics, and says nothing
- * about how the surface moves. The production surface simulation replaces this component, its
- * system and its producer together, and `Water` stays as it is. A body without this component
- * tessellates its authored rest surface and allocates no wave grid until a splash is queued.
+ * The wind's waves follow from physics: a fetch-limited JONSWAP sea of this wind speed over the water upwind
+ * — the body's own extent along the wind plus {@link upwindFetch} — so the same wind raises centimetre ripples
+ * on a puddle and swell on an open sea.
  */
 class WaterWaves {
     /**
-     * Wind speed at 10 m, m/s. Sets the forcing, which grows as its square, and the slope variance
-     * of the waves the simulation's grid does not resolve (Cox-Munk).
+     * Wind speed at 10 m, m/s.
      * @type {Vector1}
      */
     windSpeed = new Vector1(3);
 
     /**
-     * Direction the wind blows towards, radians in the mesh's local xz plane, measured from +x towards +z.
+     * Direction the wind blows towards, radians in the body's local xz plane, measured from +x towards +z.
+     * The angle turns with the body's rotation and is not skewed by its scale. A change turns the waves over
+     * a few seconds.
      * @type {Vector1}
      */
     windDirection = new Vector1(0);
 
+    /**
+     * Open water upwind of the mesh, metres, added to the mesh's own extent along the wind. Zero for a body
+     * that is all the water there is (a pool, a lake); an open sea states the distance to its far shore
+     * (a fully developed sea at 10 m/s needs about 170 km).
+     * @type {Vector1}
+     */
+    upwindFetch = new Vector1(0);
+
+    /**
+     * Amplitude reflection coefficient of the mesh's outline for wave particles: 0 a beach that absorbs
+     * them, 1 a wall that returns them whole.
+     * @type {Vector1}
+     */
+    shoreReflection = new Vector1(WATER_WAVES_SHORE_REFLECTION_DEFAULT);
+
     fromJSON(json) {
         if (typeof json.windSpeed === 'number') {
             this.windSpeed.fromJSON(json.windSpeed);
@@ -31,12 +53,22 @@ class WaterWaves {
         if (typeof json.windDirection === 'number') {
             this.windDirection.fromJSON(json.windDirection);
         }
+
+        if (typeof json.upwindFetch === 'number') {
+            this.upwindFetch.fromJSON(json.upwindFetch);
+        }
+
+        if (typeof json.shoreReflection === 'number') {
+            this.shoreReflection.fromJSON(json.shoreReflection);
+        }
     }
 
     toJSON() {
         return {
             windSpeed: this.windSpeed.toJSON(),
             windDirection: this.windDirection.toJSON(),
+            upwindFetch: this.upwindFetch.toJSON(),
+            shoreReflection: this.shoreReflection.toJSON(),
         };
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"WaterWavesSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterWavesSerializationAdapter.js"],"names":[],"mappings":"AAGA;;IAEI,yBAAmB;IAGnB;;;OAGG;IACH,uCAFW,UAAU,QAKpB;IAED;;;OAGG;IACH,yCAFW,UAAU,QAKpB;CACJ;gDAzB+C,gEAAgE;uBACzF,iBAAiB"}
+{"version":3,"file":"WaterWavesSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/WaterWavesSerializationAdapter.js"],"names":[],"mappings":"AAGA;;IAEI,yBAAmB;IAGnB;;;OAGG;IACH,uCAFW,UAAU,QAOpB;IAED;;;OAGG;IACH,yCAFW,UAAU,QAOpB;CACJ;gDA7B+C,gEAAgE;uBACzF,iBAAiB"}

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

@@ -1,26 +1,30 @@
-import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
-import WaterWaves from "./WaterWaves.js";
-
-export class WaterWavesSerializationAdapter extends BinaryClassSerializationAdapter {
-
-    klass = WaterWaves;
-    version = 0;
-
-    /**
-     * @param {BinaryBuffer} buffer
-     * @param {WaterWaves} value
-     */
-    serialize(buffer, value) {
-        buffer.writeFloat32(value.windSpeed.getValue());
-        buffer.writeFloat32(value.windDirection.getValue());
-    }
-
-    /**
-     * @param {BinaryBuffer} buffer
-     * @param {WaterWaves} value
-     */
-    deserialize(buffer, value) {
-        value.windSpeed.set(buffer.readFloat32());
-        value.windDirection.set(buffer.readFloat32());
-    }
-}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import WaterWaves from "./WaterWaves.js";
+
+export class WaterWavesSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = WaterWaves;
+    version = 1;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {WaterWaves} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat32(value.windSpeed.getValue());
+        buffer.writeFloat32(value.windDirection.getValue());
+        buffer.writeFloat32(value.upwindFetch.getValue());
+        buffer.writeFloat32(value.shoreReflection.getValue());
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {WaterWaves} value
+     */
+    deserialize(buffer, value) {
+        value.windSpeed.set(buffer.readFloat32());
+        value.windDirection.set(buffer.readFloat32());
+        value.upwindFetch.set(buffer.readFloat32());
+        value.shoreReflection.set(buffer.readFloat32());
+    }
+}

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

@@ -0,0 +1,6 @@
+/** Keep version 0's wind and append the version-1 defaults. */
+export class WaterWavesSerializationUpgrader_0_1 extends BinaryClassUpgrader {
+    upgrade(source: any, target: any): void;
+}
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+//# sourceMappingURL=WaterWavesSerializationUpgrader_0_1.d.ts.map

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"}