@woosh/meep-engine 3.37.0 → 3.39.0

package/src/engine/graphics3/WaterSystem.js

@@ -1,293 +1,423 @@
-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 { System } from "../ecs/System.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 { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { SceneColor } from "../../shade/renderer/extension/SceneColor.js";
-import { ViewTextures } from "../../shade/renderer/extension/ViewTextures.js";
-
-/**
- * Draws the level's water under Shade.
- *
- * **Water is a transparent pass on top of opaque**, so this system owns an extension rather than putting
- * anything in the scene: it registers once at startup against {@link FramePhase.AfterLighting} —
- * opaque lit and composited, transparency not yet run — and keeps a list of surfaces the pass draws.
- *
- * 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).
- */
-export class WaterSystem extends System {
-    dependencies = [Water];
-
-    /**
-     * @type {GraphicsEngine}
-     */
-    #graphics;
-
-    /**
-     * @type {GPUWaterRenderer}
-     */
-    #renderer = new GPUWaterRenderer();
-
-    /**
-     * What the pass draws, in link order.
-     *
-     * @type {WaterSurface[]}
-     */
-    #surfaces = [];
-
-    /**
-     * @type {Map<number, WaterSurface>}
-     */
-    #entries = new Map();
-
-    /**
-     * @type {RenderExtension|null}
-     */
-    #extension = null;
-
-    /**
-     * 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;
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.#extension = this.#graphics.add_extension(new WaterExtension(this));
-    }
-
-    async shutdown(entityManager) {
-        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) {
-        if (this.#surfaces.length === 0) {
-            // nothing to draw, and the frame's colour is left exactly as it was
-            return;
-        }
-
-        const scene = frame.get(SceneColor);
-
-        scene.color = this.#renderer.graph_draw({
-            graph: frame.graph,
-            surfaces: this.#surfaces,
-            color: scene.color,
-            depth: frame.get(ViewTextures).depth,
-            camera: frame.view.camera.buffer
-        });
-    }
-
-    /**
-     * @param {Water} water
-     * @param {number} entity
-     */
-    link(water, entity) {
-        const surface = {
-            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),
-            height_texture: null,
-            height_data: null,
-            height_version: -1,
-            component: water
-        };
-
-        this.#entries.set(entity, surface);
-
-        this.#refresh(surface, water);
-
-        if (surface.height_texture !== null) {
-            this.#surfaces.push(surface);
-        }
-    }
-
-    /**
-     * @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);
-
-        if (index !== -1) {
-            this.#surfaces.splice(index, 1);
-        }
-
-        this.#entries.delete(entity);
-    }
-
-    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);
-            }
-        }
-    }
-
-    /**
-     * 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.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
-            return;
-        }
-
-        const width = terrain.size.x * terrain.gridScale;
-        const height = terrain.size.y * terrain.gridScale;
-
-        /*
-         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;
-        }
-    }
-}
-
-/**
- * Water is a transparent surface over the lit opaque scene, so it draws at
- * {@link FramePhase.AfterLighting} — opaque lit and composited, transparency not yet run, so what
- * transparency draws afterwards blends over the water rather than under it.
- */
-export class WaterExtension extends RenderExtension {
-    name = "water";
-
-    phase = FramePhase.AfterLighting;
-
-    /**
-     * @type {WaterSystem}
-     */
-    #system;
-
-    /**
-     * @param {WaterSystem} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+import { assert } from "../../core/assert.js";
+import Water from "../graphics/ecs/water/Water.js";
+import WaterWaves from "../graphics/ecs/water/WaterWaves.js";
+import { WATER_SIZE } from "../graphics/ecs/water/WATER_SIZE.js";
+import { obtainTerrain } from "../ecs/terrain/util/obtainTerrain.js";
+import { System } from "../ecs/System.js";
+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 { WATER_WAVE_IMPULSE_LIMIT } from "../../shade/renderer/water/surface/WATER_WAVE_PARAMETERS_STRUCT.js";
+import { water_height_texture_from_sampler } from "../../shade/renderer/water/water_height_texture_from_sampler.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";
+
+/**
+ * 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).
+ */
+export class WaterSystem extends System {
+    dependencies = [Water];
+
+    components_used = [
+        // optional: drives the surface producer when present, calm water when not
+        ResourceAccessSpecification.from(WaterWaves, ResourceAccessKind.Read),
+    ];
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {GPUWaterRenderer}
+     */
+    #renderer = new GPUWaterRenderer();
+
+    /**
+     * The surface producer: the primitive wave simulation, behind the surface interface the water
+     * draws read (WATER_OPTICS_PLAN_2026_10_02.md §7.2).
+     *
+     * @type {GPUWaterWaveSimulation}
+     */
+    #waves = new GPUWaterWaveSimulation();
+
+    /**
+     * The frame's water bodies on the GPU: each one's medium and surface optics, read by every pass
+     * that lights water.
+     *
+     * @type {GPUWaterBodies}
+     */
+    #bodies = new GPUWaterBodies();
+
+    /**
+     * What the pass draws, in link order.
+     *
+     * @type {WaterSurface[]}
+     */
+    #surfaces = [];
+
+    /**
+     * @type {Map<number, WaterSurface>}
+     */
+    #entries = new Map();
+
+    /**
+     * @type {RenderExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * Records the surface producer at the head of each frame.
+     *
+     * @type {RenderExtension|null}
+     */
+    #surface_extension = null;
+
+    get settings() { return this.#renderer.settings; }
+
+    /** The surface producer, for settings such as its grid resolution. */
+    get waves() { return this.#waves; }
+
+    /** The registered channel, for diagnostics such as testing registration order. */
+    get transparency_channel() { return this.#renderer; }
+
+    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;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#renderer.surfaces = this.#surfaces;
+        this.#renderer.bodies = this.#bodies;
+        this.#graphics.add_transparency_channel(this.#renderer);
+        this.#extension = this.#graphics.add_extension(new WaterExtension(this));
+        this.#surface_extension = this.#graphics.add_extension(new WaterSurfaceExtension(this));
+    }
+
+    async shutdown(entityManager) {
+        this.#graphics.remove_transparency_channel(this.#renderer);
+        this.#renderer.dispose();
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+
+            this.#extension = null;
+        }
+        if (this.#surface_extension !== null) {
+            this.#graphics.remove_extension(this.#surface_extension);
+
+            this.#surface_extension = null;
+        }
+        this.#waves.dispose();
+        this.#bodies.dispose();
+
+        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; }
+    }
+
+    /**
+     * Record the surface producer: this frame's wave steps and the surface interface every water
+     * pass reads. At the head of the frame, so everything that reads it is recorded after.
+     *
+     * @param {FrameContext} frame
+     */
+    record_surface(frame) {
+        const renderer = this.#graphics.renderer;
+
+        if (renderer === null || renderer === undefined) {
+            return;
+        }
+
+        const device = renderer.graphics.device;
+
+        this.#waves.record({ graph: frame.graph, device, surfaces: this.#surfaces });
+        this.#bodies.record({ graph: frame.graph, device, surfaces: this.#surfaces });
+    }
+
+    /**
+     * Kick the surface of an entity's water, as a boat or a splash would: a vertical velocity
+     * `strength` m/s at `position`, falling off over `radius` m. Applied on the next frame that
+     * steps; at most {@link WATER_WAVE_IMPULSE_LIMIT} a frame per body, the rest wait for the
+     * following frames.
+     *
+     * @param {number} entity the entity carrying the {@link Water}
+     * @param {number[]} position world x, y, z; y is ignored
+     * @param {number} radius m
+     * @param {number} strength m/s, positive upwards
+     */
+    splash(entity, position, radius, strength) {
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.isArrayLike(position, 'position');
+        assert.isFinite(position[0], 'position[0]');
+        assert.isFinite(position[2], 'position[2]');
+        assert.isFinite(radius, 'radius');
+        assert.greaterThan(radius, 0, 'radius');
+        assert.isFinite(strength, 'strength');
+
+        const surface = this.#entries.get(entity);
+
+        assert.defined(surface, 'surface');
+
+        surface.impulses.push([position[0], position[2], radius, strength]);
+    }
+
+    /**
+     * @param {Water} water
+     * @param {number} entity
+     */
+    link(water, entity) {
+        const surface = {
+            entity,
+            visible: true,
+            level: water.level.getValue(),
+            ior: 1,
+            roughness: 0,
+            medium: water.medium,
+            body_index: 0,
+            time: this.#time,
+            extent: new Float32Array(4),
+            height_uv: new Float32Array([0, 0, 1, 1]),
+            height_texture: null,
+            height_data: null,
+            height_version: -1,
+            wind_speed: 0,
+            wind_direction: 0,
+            impulses: [],
+            gpu_surface: undefined,
+            component: water
+        };
+
+        this.#entries.set(entity, surface);
+
+        this.#refresh(surface, water);
+
+        if (surface.height_texture !== null) {
+            this.#surfaces.push(surface);
+        }
+    }
+
+    /**
+     * @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);
+
+        if (index !== -1) {
+            this.#surfaces.splice(index, 1);
+        }
+
+        this.#entries.delete(entity);
+    }
+
+    update(timeDelta) {
+        this.#time += timeDelta;
+        this.#waves.advance(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); }
+            }
+        }
+    }
+
+    /**
+     * 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.ior = Math.max(1, water.ior.getValue());
+        surface.roughness = Math.min(1, Math.max(0, water.roughness.getValue()));
+        surface.medium = water.medium;
+
+        const waves = this.entityManager.dataset.getComponent(surface.entity, WaterWaves);
+
+        surface.wind_speed = waves === undefined ? 0 : Math.max(0, waves.windSpeed.getValue());
+        surface.wind_direction = waves === undefined ? 0 : waves.windDirection.getValue();
+
+        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;
+        }
+
+        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;
+        }
+    }
+}
+
+/**
+ * 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;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}
+
+/**
+ * Records the water surface producer at {@link FramePhase.FrameStart}, so the surface exists before
+ * anything in the frame reads it.
+ */
+export class WaterSurfaceExtension extends RenderExtension {
+    name = "water surface";
+
+    phase = FramePhase.FrameStart;
+
+    /**
+     * @type {WaterSystem}
+     */
+    #system;
+
+    /**
+     * @param {WaterSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record_surface(frame);
+    }
+}