@woosh/meep-engine 3.38.0 → 3.40.0

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

@@ -1,75 +1,58 @@
 /**
- * Draws the level's water under Shade.
- *
- * Water is a shared AVBOIT side channel. The extension is debug presentation only; normal frames
- * composite water exactly once alongside particles, meshlets and trails in AVBOIT's resolve.
- *
- * Registration does not wait for a device. `GraphicsEngine` holds extensions and applies them
- * to the renderer when one exists and again after a restart (E9, §4.8).
+ * 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.
  */
 export class WaterSystem extends System<any> {
-    /**
-     * @param {GraphicsEngine} graphics
-     */
-    constructor(graphics: GraphicsEngine);
-    dependencies: (typeof Water)[];
+    constructor(graphics: any, scene: any);
+    dependencies: (typeof Transform64 | typeof MeshletGeometry | typeof Water)[];
+    components_used: ResourceAccessSpecification<typeof WaterWaves>[];
     get settings(): {
         enabled: boolean;
         max_distance: number;
         distance_tolerance: number;
         max_updates: number;
         fallback_steps: number;
-        mode: number; /**
-         * @type {GPUWaterRenderer}
-         */
+        mode: number;
         reflections: number;
         debug_view: number;
+        inscatter_segments: number;
+        tessellation_pixels: number;
     };
-    /** The registered channel, for diagnostics such as testing registration order. */
+    get waves(): GPUWaterWaveSimulation;
     get transparency_channel(): GPUWaterRenderer;
+    get scene(): any;
     request_probe(uv: any): Promise<any>;
     set time(seconds: number);
     get time(): number;
-    /**
-     * What the pass draws. Read-only — the surfaces follow the entities, and a harness that wants
-     * one gone takes its component off.
-     *
-     * @returns {WaterSurface[]}
-     */
-    get surfaces(): WaterSurface[];
     startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame: FrameContext): void;
-    /**
-     * @param {Water} water
-     * @param {number} entity
-     */
-    link(water: Water, entity: number): void;
-    /**
-     * @param {Water} water
-     * @param {number} entity
-     */
-    unlink(water: Water, entity: number): void;
-    update(timeDelta: any): void;
+    shutdown(): Promise<void>;
+    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. */
+    splash(entity: any, position: any, radius: any, strength: any): void;
+    record_surface(frame: any): void;
+    record(frame: any): void;
     #private;
 }
-/**
- * Opt-in water inspection after temporal processing. Kept under the exported name
- * for compatibility; this never records a water color overlay in normal rendering.
- */
 export class WaterExtension extends RenderExtension {
-    /**
-     * @param {WaterSystem} system
-     */
-    constructor(system: WaterSystem);
+    constructor(system: any);
+    system: any;
+    record(frame: any): void;
+}
+export class WaterSurfaceExtension extends RenderExtension {
+    constructor(system: any);
+    system: any;
     record(frame: any): void;
-    #private;
 }
 import { System } from "../ecs/System.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
+import { MeshletGeometry } from "../../shade/renderer/geometry/MeshletGeometry.js";
 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 { 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":"AAWA;;;;;;;;GAQG;AACH;IA6DI;;OAEG;IACH,sCAMC;IArED,+BAAuB;IA6BvB;;;;;;sBAtBA;;WAEG;;;MAoB+C;IAElD,kFAAkF;IAClF,6CAAqD;IAErD,qCAA8D;IAG9D,0BAIC;IALD,mBAAiC;IAcjC;;;;;OAKG;IACH,+BAEC;IAaD,2CAMC;IAED,4CAWC;IAED;;OAEG;IACH,kCAGC;IAED;;;OAGG;IACH,YAHW,KAAK,UACL,MAAM,QA+BhB;IAED;;;OAGG;IACH,cAHW,KAAK,UACL,MAAM,QAgBhB;IAED,6BAgBC;;CA4FJ;AAED;;;GAGG;AACH;IAWI;;OAEG;IACH,oBAFW,WAAW,EAMrB;IAED,yBAEC;;CACJ;uBArTsB,kBAAkB;kBAHvB,gCAAgC;iCAIjB,gDAAgD;gCAGjD,mDAAmD"}
+{"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"}

package/src/engine/graphics3/WaterSystem.js

@@ -1,314 +1,230 @@
 import { assert } from "../../core/assert.js";
 import Water from "../graphics/ecs/water/Water.js";
-import { WATER_SIZE } from "../graphics/ecs/water/WATER_SIZE.js";
-import { obtainTerrain } from "../ecs/terrain/util/obtainTerrain.js";
+import WaterWaves 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";
+import { TransformAttachment } from "../ecs/transform-attachment/TransformAttachment.js";
+import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
+import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
+import { MeshletGeometry } from "../../shade/renderer/geometry/MeshletGeometry.js";
+import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
 import { GPUWaterRenderer } from "../../shade/renderer/water/GPUWaterRenderer.js";
-import { water_height_texture_from_sampler } from "../../shade/renderer/water/water_height_texture_from_sampler.js";
+import { GPUWaterBodies } from "../../shade/renderer/water/medium/GPUWaterBodies.js";
+import { GPUWaterWaveSimulation } from "../../shade/renderer/water/surface/GPUWaterWaveSimulation.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";
+
+const WIND_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['forcing', 'unresolved_variance']);
+const IMPULSE_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['impulses', 'impulse_count']);
 
 /**
- * Draws the level's water under Shade.
- *
- * Water is a shared AVBOIT side channel. The extension is debug presentation only; normal frames
- * composite water exactly once alongside particles, meshlets and trails in AVBOIT's resolve.
- *
- * Registration does not wait for a device. `GraphicsEngine` holds extensions and applies them
- * to the renderer when one exists and again after a restart (E9, §4.8).
+ * 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.
  */
 export class WaterSystem extends System {
-    dependencies = [Water];
-
-    /**
-     * @type {GraphicsEngine}
-     */
+    dependencies = [Water, MeshletGeometry, Transform64];
+    components_used = [ResourceAccessSpecification.from(WaterWaves, ResourceAccessKind.Read)];
     #graphics;
-
-    /**
-     * @type {GPUWaterRenderer}
-     */
+    #scene;
+    #context = null;
     #renderer = new GPUWaterRenderer();
-
-    /**
-     * What the pass draws, in link order.
-     *
-     * @type {WaterSurface[]}
-     */
-    #surfaces = [];
-
-    /**
-     * @type {Map<number, WaterSurface>}
-     */
+    #waves = new GPUWaterWaveSimulation();
+    #bodies = new GPUWaterBodies();
     #entries = new Map();
-
-    /**
-     * @type {RenderExtension|null}
-     */
-    #extension = null;
-
+    #dirty = new Set();
+    #impulses = new Set();
+    #extensions = [];
+    #time = 0;
     get settings() { return this.#renderer.settings; }
-
-    /** The registered channel, for diagnostics such as testing registration order. */
+    get waves() { return this.#waves; }
     get transparency_channel() { return this.#renderer; }
-
+    get scene() { return this.#scene; }
     request_probe(uv) { return this.#renderer.request_probe(uv); }
-
     get time() { return this.#time; }
     set time(seconds) {
         assert.ok(Number.isFinite(seconds) && seconds >= 0, 'water time must be finite and non-negative');
         this.#time = seconds;
-        this.update(0);
     }
 
-    /**
-     * Seconds since startup. Waves are a function of it and nothing else advances it.
-     *
-     * @type {number}
-     */
-    #time = 0;
-
-    /**
-     * What the pass draws. Read-only — the surfaces follow the entities, and a harness that wants
-     * one gone takes its component off.
-     *
-     * @returns {WaterSurface[]}
-     */
-    get surfaces() {
-        return this.#surfaces;
-    }
-
-    /**
-     * @param {GraphicsEngine} graphics
-     */
-    constructor(graphics) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-
-        this.#graphics = graphics;
+    constructor(graphics, scene) {
+        super(); assert.defined(graphics, 'graphics'); assert.defined(scene, 'scene');
+        this.#graphics = graphics; this.#scene = scene;
+        this.#renderer.scene = scene;
+        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); }
+            }
+        });
+        this.#renderer.bodies = this.#bodies;
+        this.#renderer.waves = this.#waves;
     }
 
     async startup(entityManager) {
         this.entityManager = entityManager;
-
-        this.#renderer.surfaces = this.#surfaces;
+        assert.ok(this.#scene.dataset == null || this.#scene.dataset === entityManager.dataset, 'scene belongs to another dataset');
+        this.#scene.dataset = entityManager.dataset;
         this.#graphics.add_transparency_channel(this.#renderer);
-        this.#extension = this.#graphics.add_extension(new WaterExtension(this));
+        this.#extensions = [this.#graphics.add_extension(new WaterExtension(this)),
+            this.#graphics.add_extension(new WaterSurfaceExtension(this))];
     }
 
-    async shutdown(entityManager) {
+    async shutdown() {
+        for (const entry of Array.from(this.#entries.values())) { this.unlink(entry.water, entry.geometry, entry.transform, entry.entity); }
         this.#graphics.remove_transparency_channel(this.#renderer);
-        this.#renderer.dispose();
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-
-            this.#extension = null;
-        }
-
-        this.#surfaces.length = 0;
-        this.#entries.clear();
-    }
-
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame) {
-        const inspection = this.#renderer.inspect(frame.graph, frame.view, frame.resolution);
-        if (inspection !== undefined) { frame.get(SceneColor).color = inspection; }
+        for (const extension of this.#extensions) { this.#graphics.remove_extension(extension); }
+        this.#extensions.length = 0;
+        this.#renderer.dispose(); this.#waves.dispose(); this.#context = null;
     }
 
-    /**
-     * @param {Water} water
-     * @param {number} entity
-     */
-    link(water, entity) {
-        const surface = {
-            entity,
-            visible: true,
-            level: water.level.getValue(),
-            time: this.#time,
-            extent: new Float32Array(4),
-            height_uv: new Float32Array([0, 0, 1, 1]),
-            color_deep: new Float32Array(3),
-            color_shore: new Float32Array(3),
-            wave_amplitude: water.waveAmplitude.getValue(),
-            wave_speed: water.waveSpeed.getValue(),
-            wave_frequency: water.waveFrequency.getValue(),
-            scattering: water.scattering.getValue(),
-            shore_transition: new Float32Array(2),
-            extinction: new Float32Array(3),
-            height_texture: null,
-            height_data: null,
-            height_version: -1,
-            component: water
+    link(water, geometry, transform, entity) {
+        const entry = { water, geometry, transform, entity, context: null, row: -1, wave: -1, waves: null,
+            impulses: [], staged: [], wave_record: null };
+        const dataset = this.entityManager.dataset;
+        entry.changed = () => this.#dirty.add(entry);
+        entry.world = () => entry.context?.rows.mark_world(entity);
+        entry.local = () => entry.context?.rows.mark_local(entity);
+        entry.components = ({ klass }) => {
+            if (klass === WaterWaves) { this.#watch_waves(entry); entry.changed(); }
+            if (klass === TransformAttachment) { entry.local(); }
         };
-
-        this.#entries.set(entity, surface);
-
-        this.#refresh(surface, water);
-
-        if (surface.height_texture !== null) {
-            this.#surfaces.push(surface);
-        }
+        water.onChanged.add(entry.changed);
+        dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.world);
+        dataset.addEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, entry.local);
+        dataset.addEntityEventListener(entity, EventType.ComponentAdded, entry.components);
+        dataset.addEntityEventListener(entity, EventType.ComponentRemoved, entry.components);
+        this.#entries.set(entity, entry);
+        this.#watch_waves(entry);
+        this.#dirty.add(entry);
+        this.#renderer.body_count++;
     }
 
-    /**
-     * @param {Water} water
-     * @param {number} entity
-     */
-    unlink(water, entity) {
-        const surface = this.#entries.get(entity);
-
-        if (surface === undefined) {
-            return;
-        }
-
-        const index = this.#surfaces.indexOf(surface);
+    #watch_waves(entry) {
+        entry.waves?.windSpeed.onChanged.remove(entry.changed);
+        entry.waves?.windDirection.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 (index !== -1) {
-            this.#surfaces.splice(index, 1);
+    unlink(water, geometry, transform, entity) {
+        const entry = this.#entries.get(entity);
+        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);
+        dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.world);
+        dataset.removeEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, entry.local);
+        dataset.removeEntityEventListener(entity, EventType.ComponentAdded, entry.components);
+        dataset.removeEntityEventListener(entity, EventType.ComponentRemoved, entry.components);
+        if (entry.context !== null && entry.context === this.#graphics.scene_context(this.#scene)) {
+            entry.context.scene_database.get('water_bodies').remove(entry.row);
+            entry.context.rows.release(entity);
         }
-
-        this.#entries.delete(entity);
+        this.#entries.delete(entity); this.#dirty.delete(entry); this.#impulses.delete(entry);
+        this.#renderer.body_count--;
+        if (entry.context !== null) { this.#renderer.meshlet_capacity -= entry.geometry.meshlets.count; }
     }
 
-    update(timeDelta) {
-        this.#time += timeDelta;
-
-        for (const surface of this.#entries.values()) {
-            surface.time = this.#time;
-
-            this.#refresh(surface, surface.component);
-
-            if (surface.height_texture !== null && this.#surfaces.indexOf(surface) === -1) {
-                // the terrain arrived after the water did, which is ordinary at level-load rates
-                this.#surfaces.push(surface);
-            } else if (surface.height_texture === null) {
-                const index = this.#surfaces.indexOf(surface);
-                if (index !== -1) { this.#surfaces.splice(index, 1); }
+    update(dt) {
+        this.#time += dt; this.#renderer.time = this.#time; this.#waves.advance(dt);
+        const context = this.#graphics.scene_context(this.#scene);
+        if (context === null) { return; }
+        if (context !== this.#context) {
+            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;
+                this.#dirty.add(entry);
             }
+            this.#renderer.meshlet_capacity = 0;
         }
+        for (const entry of this.#dirty) { this.#write(entry, context); }
+        this.#dirty.clear();
     }
 
-    /**
-     * Copy the component's authored values across, and work out where the surface sits over the
-     * terrain it is flooding.
-     *
-     * @param {WaterSurface} surface
-     * @param {Water} water
-     */
-    #refresh(surface, water) {
-        surface.level = water.level.getValue();
-        surface.wave_amplitude = water.waveAmplitude.getValue();
-        surface.wave_speed = water.waveSpeed.getValue();
-        surface.wave_frequency = water.waveFrequency.getValue();
-        surface.scattering = water.scattering.getValue();
-        surface.ior = Math.max(1, water.ior.getValue());
-        surface.normal_strength = Math.max(0, water.opticalNormalStrength.getValue());
-        surface.normal_scale = Math.max(0.01, water.opticalNormalScale.getValue());
-        surface.roughness = Math.min(1, Math.max(0, water.reflectionRoughness.getValue()));
-        surface.extinction.set([water.extinction.x, water.extinction.y, water.extinction.z]);
-
-        surface.color_deep[0] = water.color.r;
-        surface.color_deep[1] = water.color.g;
-        surface.color_deep[2] = water.color.b;
-
-        surface.color_shore[0] = water.shoreColor.r;
-        surface.color_shore[1] = water.shoreColor.g;
-        surface.color_shore[2] = water.shoreColor.b;
-
-        surface.shore_transition[0] = water.shoreDepthTransition.min;
-        surface.shore_transition[1] = water.shoreDepthTransition.max;
-
-        const terrain = obtainTerrain(this.entityManager.dataset);
-
-        if (terrain === null || terrain === undefined) {
-            // no terrain to flood; the shore line has nothing to read and the surface stays out of
-            // the pass until one exists
-            surface.height_texture = null;
-            surface.height_data = null;
-            surface.height_version = -1;
-            return;
+    #write(entry, context) {
+        const bodies = context.scene_database.get('water_bodies');
+        const waves = context.scene_database.get('water_waves');
+        if (entry.context === null) {
+            context.rows.acquire(entry.entity);
+            context.geometries.add(entry.geometry);
+            entry.context = context;
+            this.#renderer.meshlet_capacity += entry.geometry.meshlets.count;
         }
-
-        const width = terrain.size.x * terrain.gridScale;
-        const height = terrain.size.y * terrain.gridScale;
-        if (!(width > 0 && height > 0)) {
-            surface.height_texture = null; surface.height_data = null; surface.height_version = -1;
-            return;
-        }
-
-        /*
-         The legacy placement, read off it rather than derived: an 800-unit plane centred at
-         `WATER_SIZE / 4` on both axes, so it spans [-200, 600] regardless of how big the terrain is.
-         The map is an island in an ocean, not a lake fitted to the map, and where the surface hangs
-         past the terrain the height map clamps — which is what lets the shore line continue instead
-         of stopping at the boundary.
-
-         The three path stated the same thing as a UV transform,
-         `(uv - 0.25) * (WATER_SIZE / terrain_size)`, and the two agree by construction: world
-         position is `(u - 0.25) * WATER_SIZE`, and terrain uv is that over the terrain's own size.
-        */
-        const x0 = -WATER_SIZE * 0.25;
-        const z0 = -WATER_SIZE * 0.25;
-
-        surface.extent[0] = x0;
-        surface.extent[1] = z0;
-        surface.extent[2] = x0 + WATER_SIZE;
-        surface.extent[3] = z0 + WATER_SIZE;
-
-        surface.height_uv[0] = x0 / width;
-        surface.height_uv[1] = z0 / height;
-        surface.height_uv[2] = WATER_SIZE / width;
-        surface.height_uv[3] = WATER_SIZE / height;
-
-        const height_field = terrain.samplerHeight;
-
-        /*
-         The height field a water surface links against is not the one it will read. A `Terrain`
-         carries a 512² placeholder from the moment its entity exists, and the level's own field
-         arrives later — while Shade uploads a texture once and has no notion of one changing. So a
-         surface linked at load time would read a flat sea floor for the rest of the session.
-
-         Watched on the data array rather than on the sampler: `Sampler2D.fromJSON` replaces `data`
-         and leaves `version` alone, so deserialization is invisible to the counter. The version is
-         watched too, for the edits that do bump it and keep the array.
-        */
-        if (surface.height_data !== height_field.data || surface.height_version !== height_field.version) {
-            surface.height_texture = water_height_texture_from_sampler(height_field);
-            surface.height_data = height_field.data;
-            surface.height_version = height_field.version;
+        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 water = entry.water;
+        const record = { geometry: context.geometries.getAddress(entry.geometry), node: entry.entity + 1,
+            dirty: 1,
+            wave: entry.wave === -1 ? 0xffffffff : 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); }
     }
-}
-
-/**
- * Opt-in water inspection after temporal processing. Kept under the exported name
- * for compatibility; this never records a water color overlay in normal rendering.
- */
-export class WaterExtension extends RenderExtension {
-    name = "water";
-
-    // Diagnostics must show this frame's measurements, not temporally accumulated colors.
-    phase = FramePhase.BeforePresent;
-
-    /**
-     * @type {WaterSystem}
-     */
-    #system;
 
-    /**
-     * @param {WaterSystem} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
+    /** World-space radius and velocity kick; position is interpreted in the CPU-owned pose. */
+    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);
+        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);
     }
 
+    record_surface(frame) {
+        const scene = frame.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 });
+    }
     record(frame) {
-        this.#system.record(frame);
+        const inspection = this.#renderer.inspect(frame.graph, frame.view, frame.resolution);
+        if (inspection !== undefined) { frame.get(SceneColor).color = inspection; }
     }
 }
+
+export class WaterExtension extends RenderExtension {
+    name = 'water'; phase = FramePhase.BeforePresent;
+    constructor(system) { super(); this.system = system; }
+    record(frame) { this.system.record(frame); }
+}
+export class WaterSurfaceExtension extends RenderExtension {
+    name = 'water surface'; phase = FramePhase.FrameStart;
+    constructor(system) { super(); this.system = system; }
+    record(frame) { this.system.record_surface(frame); }
+}

package/src/engine/interpolation/BinaryInterpolationAdapter.d.ts

@@ -22,7 +22,7 @@ export const InterpolationKind: Readonly<{
 }>;
 /**
  * Per-component-type interpolator: reads two encoded snapshots of one
- * component from `source`, blends by `t`, writes the result to
+ * component from `source`, blends them, writes the result to
  * `out_buffer` in the SAME wire format so the receiver can deserialize
  * directly via the corresponding `BinaryClassSerializationAdapter`.
  *
@@ -45,14 +45,20 @@ export class BinaryInterpolationAdapter {
      *
      * `first_offset === second_offset` is the degenerate "snap to single
      * snapshot" case — implementations don't need to special-case it; the
-     * blend at any `t` reduces to the input.
+     * blend at any fraction reduces to the input.
+     *
+     * The blend fraction arrives in an array, `blend[blend_offset]`, not as a
+     * number: a caller blends every entity of a frame at the same fraction, and
+     * a number handed to a call V8 does not inline is boxed into a new heap
+     * object on every call, where an array is handed over as it is.
      *
      * @param {BinaryBuffer} out_buffer
      * @param {BinaryBuffer} source
      * @param {number} first_offset byte position of snapshot A
      * @param {number} second_offset byte position of snapshot B
-     * @param {number} t blend fraction in [0, 1]; 0 ⇒ A, 1 ⇒ B
+     * @param {Float64Array} blend holds the blend fraction, in [0, 1]; 0 ⇒ A, 1 ⇒ B
+     * @param {number} blend_offset index of the fraction in `blend`
      */
-    interpolate(out_buffer: BinaryBuffer, source: BinaryBuffer, first_offset: number, second_offset: number, t: number): void;
+    interpolate(out_buffer: BinaryBuffer, source: BinaryBuffer, first_offset: number, second_offset: number, blend: Float64Array, blend_offset: number): void;
 }
 //# sourceMappingURL=BinaryInterpolationAdapter.d.ts.map

package/src/engine/interpolation/BinaryInterpolationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BinaryInterpolationAdapter.d.ts","sourceRoot":"","sources":["../../../../src/engine/interpolation/BinaryInterpolationAdapter.js"],"names":[],"mappings":";;;;;gCAMU,MAAM;AANhB;;;;;;;GAOG;AACH;IACI,gEAAgE;;IAEhE,qEAAqE;;IAErE,+DAA+D;;GAEhE;AAEH;;;;;;;;;;;;;;;GAeG;AACH;IAEI,sDAAsD;IACtD,MADW,MAAM,CACe;IAEhC;;;;;;;;;;;;;OAaG;IACH,0EAJW,MAAM,iBACN,MAAM,KACN,MAAM,QAIhB;CACJ"}
+{"version":3,"file":"BinaryInterpolationAdapter.d.ts","sourceRoot":"","sources":["../../../../src/engine/interpolation/BinaryInterpolationAdapter.js"],"names":[],"mappings":";;;;;gCAMU,MAAM;AANhB;;;;;;;GAOG;AACH;IACI,gEAAgE;;IAEhE,qEAAqE;;IAErE,+DAA+D;;GAEhE;AAEH;;;;;;;;;;;;;;;GAeG;AACH;IAEI,sDAAsD;IACtD,MADW,MAAM,CACe;IAEhC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,0EALW,MAAM,iBACN,MAAM,SACN,YAAY,gBACZ,MAAM,QAIhB;CACJ"}