@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/playground/water_refraction/README.md

@@ -21,11 +21,23 @@ one 1/60-second engine tick. Presets cover the shore, normal incidence, grazing
 screen edges, the emergent-object/shoreline discontinuity view, and the deliberately unsupported
 below-interface view. The grazing camera stays over the submerged floor.
 
-Water fields edit the actual component. Optical normals are independent of the legacy shoreline
-wave modulation. Screen reflections can be disabled while retaining the environment fallback.
+Water is an entity with `Water`, `MeshletGeometry` and `Transform64`. The mesh authors the outline
+and elevations, and the transform places it; Level edits the transform's height. This fixture
+has a curved, coarse authored outline. Optical controls edit Water. Optional WaterWaves supplies wind
+forcing to a persistent shared GPU displacement atlas, with 128² samples per active body. The existing
+geometry BLAS bakes the authored footprint into a simulation mask when a wave row is created;
+dry samples remain zero, including holes and gaps. Vertices sample the field in local xz and move
+along local y. This primitive simulation therefore expects a surface that can be represented as a
+height field in local xz; multiple stacked surfaces sharing that domain also share its displacement.
+Calm meshes allocate no grid. The simulation uses a one-metre reference depth and
+does not infer bathymetry from the mesh. Screen reflections can be disabled while retaining the
+fallback to the renderer's indirect lighting (IBL, or Brick4 when it is the active mode).
 The Newton, bounded HZB traversal, and undisplaced control modes all use the same AVBOIT path.
-An IOR of 1, zero RGB extinction and zero optical normal strength should leave opaque transport
-unchanged. Increase extinction to see independent color attenuation and the body-color source.
+The Medium select picks one of the water presets (`shade/renderer/medium/water/water_presets.js`):
+what fills the body as absorption and scattering in 1/m. The body's colour is not authored — it is the sun
+and sky scattered back up the refracted view ray, using the existing water column model. In-scatter segments
+sets how many steps that integral takes. Seen from above, light leaving the water crosses the surface
+by Fresnel and the n² law, so the floor reads about half as bright as it would dry.
 
 Move the card, alpha/additive particles and ribbon above/below the interface using Layer height.
 The box and five thin posts exercise opaque occlusion and discontinuities. Swap channel order
@@ -49,14 +61,14 @@ no readback. Arrays are `receiver=[u,v,path,status+updates/32]`,
 `transmission=[Tr,Tg,Tb,coverage]`, `radiance=[Wr,Wg,Wb,residual]`.
 The separate `confidence` field is the final weight after rejecting unsupported lookups; the
 confidence display reads this same weight rather than recomputing an approximation.
-Status 0 is a Newton-assisted, visibility-checked hit; codes 8–13 are validated HZB hits, 16–21 undisplaced opaque fallbacks,
+Status 0 is a converged Newton hit; codes 8–13 are validated HZB hits, 16–21 undisplaced opaque fallbacks,
 24–29 bounded sky fallbacks, and 31 the below-interface control. The low three bits preserve the
 Newton miss reason: 0 none/not attempted, 1 bounds/clip, 2 sky, 3 parallel/invalid, 4 ray interval,
 5 exhausted budget/residual. The probe decodes these names and the update count. Residual is capped
 at 65504 for half-float storage. The status display uses green/cyan/purple/orange/pink for those
 five final classes; red increases with update count.
 
-Compile check compiles all ten production water modules on the active device. Rendering exercises
+Compile check compiles the production water modules on the active device. Rendering exercises
 their real pipelines and bind groups; the first validation error stops rendering and remains visible
 in the status panel and console. Restart device resumes after correcting the error. Profile / T
 uses the existing GPU profiler and exports `.sgpt`. Compare water on/off at a fixed paused camera,
@@ -66,18 +78,18 @@ mode in its note. A device without timestamp-query records structure without tim
 
 Copy state writes versioned JSON into the text area and attempts clipboard copying. Apply state
 restores camera, displayed controls, water/fixture clock, terrain offset and channel order.
-GPU particle populations and temporal histories are not serialized: reload/reset them and warm up
+GPU wave fields, particle populations and temporal histories are not serialized: reload/reset them and warm up
 equally for image/performance comparisons. Probe values describe the captured frame; camera changes
 require a fresh probe.
 
 ## Integration boundaries and adversarial checks
 
 Opaque receiver transport uses the immutable pre-transparency HDR scene. Water contributes only its
-surface source and RGB extinction; shared resolve applies the transported opaque background once.
+reflection and in-scattered radiance and its RGB transmittance; shared resolve applies the transported opaque background once.
 Rear transparent surfaces/particles are attenuated at their original screen positions. Their radiance
 is not sampled through the bent ray. Missing/off-screen receivers get bounded, explicit fallbacks.
-Missing receivers use the local terrain column to estimate water thickness; the trace budget is only
-an upper bound. Final shading fades the receiver UV toward the control UV around emergent silhouettes,
+Missing receivers use the medium's extinction distance, bounded by the trace budget. Final shading
+fades the receiver UV toward the control UV around emergent silhouettes,
 shoreline visibility gaps and screen edges, then performs one geometry-aware color lookup. It derives
 water thickness from that lookup's local receiver plane and builds its complete optical event. It
 does not crossfade two displaced images. Three quarter-resolution passes form a conservative
@@ -86,14 +98,16 @@ that field, which would amplify them into large moving blotches. The raw receive
 still show classified misses; Refraction confidence shows the displacement fade actually used by
 the final image. Screen reflections also fade near the ray origin and frame
 edges to avoid self-hit speckles, reusing the existing SSR back-face/thickness/vignette validation.
-Displaced Newton roots also require first-intersection evidence from a water adapter using the
-existing FFX cell intersection/depth-loading chunks. The adapter traverses the HZB's actual integer
+As in the paper, a converged Newton root is final: screen bounds plus the one-pixel and distance
+residuals accept it, with no further visibility proof. Like the paper's method it can converge past
+a thin occluder between the interface and the receiver; that is the accepted cost of a few G-buffer
+reads per pixel. Pixels Newton fails fall back to a water adapter using the existing FFX cell
+intersection/depth-loading chunks. The adapter traverses the HZB's actual integer
 mip dimensions, including odd viewport sizes; it does not assume a floating halving of the source
 grid. It starts in the source pixel, since water is absent from opaque depth. HZB slab crossings
 are intersected once with the selected receiver plane and validated again before shading. A second
-Newton search here could jump to a farther root and falsely certify it as the first hit. Analytic ray distance sets the visibility
-interval instead of the biased texel-center projection. An exhausted traversal uses the control
-event. Color filtering accepts only taps on the validated
+Newton search here could jump past the first footprint to a root the traversal has ruled out.
+An exhausted traversal uses the control event. Color filtering accepts only taps on the validated
 receiver's local plane, with geometric-normal and interface-side checks. Receiver selection retains
 full-precision UV/path/control-path data. Final shading reads the same selected interface and
 deterministic surface owner before shared occupancy/extinction/draw consume its optical result.
@@ -112,13 +126,14 @@ statistics nor its timing results apply directly to this implementation.
 Acceptance reconstructs the receiver at its subpixel UV on the sampled face plane before measuring
 ray proximity. Using the texel-center position instead can reject exact planar intersections at
 grazing angles and introduce striped hit/control transitions. This is independent of adaptive mip
-filtering. First-hit traversal still has a finite budget: inspect trace status when increasing the
-fallback steps, since an exhausted visibility check deliberately selects the control event.
+filtering. Each Newton lookup reads depth and face normal once: the plane that rejects one lookup
+is the tangent plane for the next update, so N updates read N+1 texels. Fallback steps bound only
+the traversal for failed pixels and screen reflections.
 
 The main risks to check on target hardware are moving-wave temporal ghosts (water keeps the opaque
 depth/motion contract), coarse 8×8 volume attenuation near thin/partial edges, tangent-plane hits at
 depth discontinuities, and first activation of AVBOIT in otherwise opaque scenes. No paper performance
-claim is adopted; visibility checks and geometry-aware filtering add work to water rendering.
+claim is adopted; disocclusion fades and geometry-aware filtering add work to water rendering.
 Water transient targets cost approximately 68 bytes per internal pixel before allocator lifetime
 reuse, plus up to 0.375 bytes per pixel for the three quarter-resolution visibility fields:
 32 bytes for receiver/trace metadata, 4 for interface depth, and 32 for final optics/background. The tiny-loss
@@ -133,7 +148,7 @@ They also cover the actual shared WGSL contribution/resolve, count conservation,
 normal-incidence acceptance, analytic plane/sphere intersections, invalid rays, bounded fallback thickness,
 geometry-only visibility seeds, single-lookup transport, subpixel receiver thickness,
 grazing visibility intervals, odd-dimension traversal crossings, receiver ownership at silhouettes,
-first-receiver selection, source/receiver frame-edge fades and old/new serialization.
+converged roots kept without a traversal budget, source/receiver frame-edge fades and old/new serialization.
 Software-device orchestration verifies water precedes shared warp/integration/resolve without adding
 another one. Visual checks are complementary: inspect TAA/fog, mixed sources, below-interface fallback,
 overlap, no-water/MBOIT suppression, terrain replacement and device restart on a real GPU.
@@ -144,6 +159,48 @@ the real GPU; the CPU test does not claim to prove that contract.
 Blast radius: water lifecycle/shaders/data plus AVBOIT preparation/background plumbing and its
 tiny-loss resolve guard; existing particle, mesh and ribbon APIs remain intact.
 
+Water bodies occupy persistent rows in the existing scene database. Optical and component edits
+queue CPU writes; idle updates do not enumerate bodies. GPU page iteration, the existing prefix
+scan, ordered meshlet expansion and indirect draws cover the scene. A GPU reduction supplies signed
+local-y displacement bounds after each simulation update. Body frustum culling expands the authored
+bounds by those extrema before applying the GPU world transform.
+
+Following Far Cry 5's view-tile approach, each candidate triangle classifies its swept footprint into
+view tiles. A tile contains 16×16 cells; `settings.tessellation_pixels` sets their reference-view spacing
+(4 pixels by default). GPU prefix sums drive one indirect patch draw in each surface pass. Patch
+vertices reconstruct the authored triangle in homogeneous barycentric coordinates, clip each cell
+to its boundary, then sample displacement and transform it into the render view. The mesh supplies
+outline and rest elevations; it does not need wave-scale subdivisions. Holes and disconnected
+surfaces remain separate. Triangle identity survives classification, including overlapping bodies;
+only displaced raster depth selects the nearest interface. Storage scales with source triangles,
+without allocating a triangle×tile list or reading tile counts back to the CPU.
+
+Simulated bodies use a shared local-xz reference plane at the displaced authored bound farther
+from the near plane. Classification sweeps rest elevations and both signed displacement endpoints
+against the view planes. Calm bodies project the authored triangles directly. Reference tiles can lie outside the viewport
+when displacement can bring them into view. Opaque depth is tested after displacement, so an
+undisplaced depth rejection cannot hide a crest. Both surface passes share the same patch counts
+and reconstruction inputs. Simulation is independent of camera position and render resolution;
+wave dispatch count depends on fixed steps, not the number of bodies. Device buffer and indirect
+draw limits still bound scene complexity. If the reference is coplanar with the camera, it moves
+farther beyond the displacement envelope to retain a projectable surface. The body's conservative
+swept span sets one shared grid spacing, at least the requested pixel spacing. This bounds each
+triangle's patches to a viewport-sized cell budget per axis, including near-plane displacement,
+and keeps adjacent triangles' edge subdivisions identical. Large envelopes near the camera can
+therefore reduce tessellation detail. Receiver attenuation and column scattering
+use the displaced surface's world normal and local tangent plane, so placement can rotate the body.
+
+Reference: Branislav Grujic, *Water Rendering in Far Cry 5*, GDC 2018,
+[presentation](https://media.gdcvault.com/gdc2018/presentations/Grujic_Branislav_WaterRenderingFarCry5.pdf),
+slides 49–56. This implementation reconstructs each retained triangle directly rather than keeping
+only the nearest rest-depth sample, to preserve overlap candidates and exact authored boundaries.
+
+Water binary version 4 stores optics only. Version 3 and earlier, and JSON with level or size,
+require asset migration before loading: generate the old footprint as MeshletGeometry and place
+it with Transform64. A component-only upgrader cannot create sibling components or split water
+from an entity whose transform places terrain or another object; it reports that requirement
+instead of silently losing placement. MeshletGeometry uses its existing binary adapter as an ECS component.
+
 Reference: Mayer, Assarsson and Sintorn, *Ultrafast Screen-Space Refractions and Caustics via Newton's
 Method*, JCGT 15(1), 2026, [paper](https://jcgt.org/published/0015/01/03/paper-lowres.pdf).
 See [the integration plan](../../../../WATER_MAYER2026_INTEGRATION_PLAN.md) for the transport contract.

package/src/shade/playground/water_refraction/index.html

@@ -16,19 +16,17 @@ input[type=range]{width:135px}input[type=number]{width:84px}input,select,button,
 <h2>Water</h2><label>Enabled<input id="enabled" type="checkbox" checked></label>
 <label>Level<input id="level" type="range" min="-1.5" max="2" step=".05" value="0"></label>
 <label>IOR<input id="ior" type="range" min="1" max="1.6" step=".01" value="1.33"></label>
-<label>Optical normal<input id="normal" type="range" min="0" max=".5" step=".01" value=".08"></label>
-<label>Normal scale<input id="scale" type="range" min=".2" max="8" step=".1" value="3"></label>
-<label>Roughness<input id="roughness" type="range" min="0" max="1" step=".01" value=".08"></label>
-<label>Extinction R<input id="extinction_r" type="number" min="0" max="2" step=".01" value=".12"></label>
-<label>Extinction G<input id="extinction_g" type="number" min="0" max="2" step=".01" value=".035"></label>
-<label>Extinction B<input id="extinction_b" type="number" min="0" max="2" step=".01" value=".02"></label>
-<label>Body color<input id="color" type="color" value="#004d80"></label><label>Shore color<input id="shore_color" type="color" value="#95cad9"></label>
+<label>Wind m/s<input id="wind" type="range" min="0" max="12" step=".1" value="3"></label>
+<label>Wind direction °<input id="wind_direction" type="range" min="0" max="360" step="1" value="30"></label>
+<label>Roughness<input id="roughness" type="range" min="0" max="1" step=".01" value=".02"></label>
+<label>Medium<select id="medium"><option value="swimming_pool">Swimming pool</option><option value="clear_ocean">Clear ocean</option><option value="tropical_lagoon">Tropical lagoon</option><option value="open_ocean" selected>Open ocean</option><option value="coastal">Coastal</option><option value="green_lake">Green lake</option><option value="turbid_river">Turbid river</option></select></label>
+<label>In-scatter segments<input id="segments" type="range" min="1" max="16" step="1" value="4"></label>
 <label>Screen reflections<input id="reflection" type="checkbox" checked></label>
 <h2>Mixed transparency</h2><label>Layer height<input id="layer_height" type="range" min="-2" max="3" step=".05" value="0"></label>
 <label>Card opacity<input id="opacity" type="range" min=".02" max=".98" step=".02" value=".5"></label>
 <label>Alpha + additive particles<input id="particles" type="checkbox" checked></label>
 <label>Ribbon<input id="ribbon" type="checkbox" checked></label><label>Move submerged object<input id="animate" type="checkbox"></label>
-<label>Overlap water<input id="overlap" type="checkbox"></label><div class="row"><button id="order">Swap channel order</button><button id="terrain">Replace terrain</button><button id="restart">Restart device</button></div>
+<label>Overlap water<input id="overlap" type="checkbox"></label><label>Warp steps (4 per octave)<input id="warp_steps" type="checkbox" checked></label><div class="row"><button id="order">Swap channel order</button><button id="terrain">Replace terrain</button><button id="restart">Restart device</button></div>
 <h2>Tracing / frame</h2><label>Trace<select id="mode"><option value="0">Newton + fallback</option><option value="1">Bounded traversal</option><option value="2">Undisplaced control</option></select></label>
 <label>Newton updates<input id="iterations" type="number" min="0" max="16" value="4"></label><label>Fallback steps<input id="fallback" type="number" min="0" max="128" value="48"></label>
 <label>Temporal<select id="temporal"><option value="off">Off</option><option value="taa">TAA</option><option value="nss">NSS (requires weights)</option></select></label>

package/src/shade/playground/water_refraction/main.js

@@ -8,6 +8,7 @@ import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDatas
 import { EntityManager } from "../../../engine/ecs/EntityManager.js";
 import { Entity } from "../../../engine/ecs/Entity.js";
 import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { t64_announce_change } from "../../../engine/ecs/transform/t64_announce_change.js";
 import { Light } from "../../../engine/graphics/ecs/light/Light.js";
 import { GPUParticleEmitterSystem } from "../../../engine/graphics3/GPUParticleEmitterSystem.js";
 import { GraphicsEngine } from "../../../engine/graphics3/GraphicsEngine.js";
@@ -21,8 +22,14 @@ import { Scene } from "../../renderer/scene/Scene.js";
 import { ShadeTransparencyMode } from "../../renderer/ShadeTransparencyMode.js";
 import { ShadeUpscalerType } from "../../renderer/ShadeUpscalerType.js";
 import { ParticipatingMediaVolume } from "../../renderer/volumetrics/ParticipatingMediaVolume.js";
-import { water_shader, water_finalize_shader } from "../../renderer/water/shader_water.js";
+import { water_medium_preset } from "../../renderer/medium/water/water_presets.js";
+import { water_finalize_shader_brick4, water_finalize_shader_ibl, water_shader } from "../../renderer/water/shader_water.js";
 import * as water_shaders from "../../renderer/water/shader_water_avboit.js";
+import { shader_water_bodies_derive } from "../../renderer/water/medium/shader_water_bodies_derive.js";
+import { shader_water_meshlet_counts, shader_water_meshlets_expand } from "../../renderer/water/medium/shader_water_meshlets.js";
+import { shader_water_wave_batch, shader_water_wave_batch_finish } from "../../renderer/water/surface/shader_water_wave_batch.js";
+import { shader_water_wave_domain, shader_water_wave_bounds } from "../../renderer/water/surface/shader_water_wave_domain.js";
+import { shader_water_tiles } from "../../renderer/water/surface/shader_water_tiles.js";
 import { install_profile_hotkey } from "../profile_hotkey.js";
 import { build_world } from "./world.js";
 
@@ -33,13 +40,12 @@ const presets = {
     edge: [[22,5,18],[23,0,11]], underwater: [[19,-0.8,18],[12,-1,12]],
     discontinuities: [[18.946,7.002,6.28],[15.4,2.439,10.562]],
 };
-const input_ids = ["preset","enabled","level","ior","normal","scale","roughness","extinction_r","extinction_g",
-    "extinction_b","color","shore_color","reflection","layer_height","opacity","particles","ribbon","animate",
-    "overlap","mode","iterations","fallback","temporal","resolution","ssr","fog","transparency","debug"];
+const input_ids = ["preset","enabled","level","ior","wind","wind_direction","roughness","medium","segments",
+    "reflection","layer_height","opacity","particles","ribbon","animate",
+    "overlap","warp_steps","mode","iterations","fallback","temporal","resolution","ssr","fog","transparency","debug"];
 const initial_inputs = Object.fromEntries(input_ids.map(id => [id,element(id).type === "checkbox" ? element(id).checked : element(id).value]));
 const number = id => Number(element(id).value);
 const checked = id => element(id).checked;
-const color = (target, hex) => target.setRGB(...[1,3,5].map(i => parseInt(hex.slice(i,i+2),16)/255));
 
 async function main() {
     const viewport = element("viewport"), graphics = new GraphicsEngine(), scene = new Scene();
@@ -47,7 +53,7 @@ async function main() {
     const assets = new AssetManager({context:{},executor:new ConcurrentExecutor()});
     await assets.registerLoader(GameAssetType.Image,new ImageRGBADataLoader()); assets.startup();
     const dataset = new EntityComponentDataset(), entities = new EntityManager();
-    const water_system = new WaterSystem(graphics);
+    const water_system = new WaterSystem(graphics,scene);
     entities.addSystem(new ShadedGeometrySystem(graphics,scene)); entities.addSystem(new LightSystem(graphics,scene));
     entities.addSystem(new GPUParticleEmitterSystem(graphics,scene,assets)); entities.addSystem(water_system);
     entities.attachDataset(dataset);
@@ -73,11 +79,11 @@ async function main() {
     function configure() {
         revision++;
         const w=world.water,s=water_system.settings,r=graphics.renderer;
-        w.level.set(number("level"));w.ior.set(number("ior"));w.opticalNormalStrength.set(number("normal"));
-        w.opticalNormalScale.set(number("scale"));w.reflectionRoughness.set(number("roughness"));
-        w.extinction.set(number("extinction_r"),number("extinction_g"),number("extinction_b"));
-        color(w.color,element("color").value);color(w.shoreColor,element("shore_color").value);
+        world.water_transform.setTranslation(16,number("level"),16);t64_announce_change(dataset,world.water_entity);w.ior.set(number("ior"));w.roughness.set(number("roughness"));
+        world.waves.windSpeed.set(number("wind"));world.waves.windDirection.set(number("wind_direction")*Math.PI/180);
+        w.medium=water_medium_preset({preset:element("medium").value});
         Object.assign(s,{enabled:checked("enabled"),mode:number("mode"),max_updates:number("iterations"),
+            inscatter_segments:number("segments"),
             fallback_steps:number("fallback"),reflections:checked("reflection")?1:0,debug_view:number("debug")});
         world.card.component.material.diffuse_color.a=number("opacity");
         world.effects.forEach(effect=>effect.emitting=checked("particles"));world.ribbon.visible=checked("ribbon");
@@ -86,6 +92,7 @@ async function main() {
         if(!checked("fog")&&fog_added){scene.volumetrics.remove(fog);fog_added=false;}
         if(r!==null&&r!==undefined){
             r.transparency_mode=element("transparency").value==="avboit"?ShadeTransparencyMode.AVBOIT:ShadeTransparencyMode.MBOIT;
+            r.avboit.warp_steps_per_octave=checked("warp_steps")?4:1;
             r.feature_taa_enabled=element("temporal").value!=="off";
             r.upscale_type=element("temporal").value==="nss"?ShadeUpscalerType.NSS:ShadeUpscalerType.TAA;
             r.feature_ssr_enabled=checked("ssr");r.pixel_ratio=number("resolution");
@@ -156,7 +163,10 @@ async function main() {
     element("compile").onclick=async()=>{
         if(!ready)return;
         const device=graphics.renderer.graphics.device,errors=[];
-        for(const shader of [water_shader,water_finalize_shader,...Object.values(water_shaders).map(s=>s.descriptor)]){
+        for(const shader of [water_shader,water_finalize_shader_ibl,water_finalize_shader_brick4,
+            ...[shader_water_bodies_derive,shader_water_meshlet_counts,shader_water_meshlets_expand,
+                shader_water_wave_batch,shader_water_wave_batch_finish,shader_water_wave_domain,shader_water_wave_bounds,
+                shader_water_tiles,...Object.values(water_shaders)].map(s=>s.descriptor)]){
             if(typeof shader?.source!=="string")continue;
             const module=device.createShaderModule({code:shader.source});const info=await module.getCompilationInfo();
             errors.push(...info.messages.filter(m=>m.type==="error").map(m=>`${m.lineNum}: ${m.message}`));
@@ -172,7 +182,7 @@ async function main() {
         try{const result=await water_system.request_probe([(event.clientX-rect.left)/rect.width,(event.clientY-rect.top)/rect.height]);
             const packed=result.receiver[3],code=Math.floor(packed);
             const classification=result.transmission[3]<=0?"no water coverage":code===31?"below-interface control":
-                ["Newton-assisted hit","HZB hit","undisplaced fallback","bounded sky"][Math.floor(code/8)]??"invalid";
+                ["Newton hit","HZB hit","undisplaced fallback","bounded sky"][Math.floor(code/8)]??"invalid";
             const reason=["none / not attempted","bounds / clip","sky","parallel / invalid","ray interval","budget / residual"][code%8];
             element("probe").textContent=JSON.stringify({...result,
                 stale:revision!==probe_revision||JSON.stringify(state().camera)!==probe_camera,

package/src/shade/playground/water_refraction/world.d.ts

@@ -2,7 +2,9 @@
 export function build_world(dataset: any): Promise<{
     terrain: Terrain;
     water: Water;
+    waves: WaterWaves;
     water_entity: any;
+    water_transform: Transform64;
     card: {
         transform: Transform64;
         component: ShadedGeometry;
@@ -29,6 +31,7 @@ export function build_world(dataset: any): Promise<{
 export function height_at(x: any, z: any, offset?: number): number;
 import Terrain from "../../../engine/ecs/terrain/ecs/Terrain.js";
 import Water from "../../../engine/graphics/ecs/water/Water.js";
+import WaterWaves from "../../../engine/graphics/ecs/water/WaterWaves.js";
 import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
 import { DynamicMeshBatch } from "../../renderer/scene/DynamicMeshBatch.js";

package/src/shade/playground/water_refraction/world.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/water_refraction/world.js"],"names":[],"mappings":"AA0DA,+FAA+F;AAC/F;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EC;AA5GM,mEAAsE;oBAxBzD,4CAA4C;kBAI9C,6CAA6C;4BAHnC,8CAA8C;+BAE3C,wDAAwD;iCActD,0CAA0C;4BAD/C,qCAAqC;+BAXlC,0DAA0D"}
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/water_refraction/world.js"],"names":[],"mappings":"AA4DA,+FAA+F;AAC/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFC;AAxHM,mEAAsE;oBAzBzD,4CAA4C;kBAI9C,6CAA6C;uBACxC,kDAAkD;4BAJ7C,8CAA8C;+BAE3C,wDAAwD;iCAetD,0CAA0C;4BAD/C,qCAAqC;+BAXlC,0DAA0D"}

package/src/shade/playground/water_refraction/world.js

@@ -1,4 +1,5 @@
 import { Color } from "../../../core/color/Color.js";
+import { water_medium_preset } from "../../renderer/medium/water/water_presets.js";
 import Quaternion from "../../../core/geom/Quaternion.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { Entity } from "../../../engine/ecs/Entity.js";
@@ -7,6 +8,7 @@ import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 import { t64_announce_change } from "../../../engine/ecs/transform/t64_announce_change.js";
 import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
 import Water from "../../../engine/graphics/ecs/water/Water.js";
+import WaterWaves from "../../../engine/graphics/ecs/water/WaterWaves.js";
 import { ParticleEffect } from "../../../engine/graphics/ecs/particles/ParticleEffect.js";
 import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
 import { MeshoptClusterizer } from "../../renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
@@ -80,8 +82,20 @@ export async function build_world(dataset) {
     const floor_material=material([1,1,1]); floor_material.texture_albedo=checker();
     const floor_transform=pose(0,0,0);
     const floor_entity=build(new Entity().add(floor_transform).add(shaded(meshlets(floor_geo),floor_material)));
-    const water=new Water(); water.level.set(0); water.scattering.set(0.6);
-    const water_entity=build(new Entity().add(water));
+    const water=new Water();
+    const water_plane=make_plane_geometry(40,40,8,8);
+    const water_positions=water_plane.getAttribute(StandardAttributes.Position).data;
+    const water_normals=water_plane.getAttribute(StandardAttributes.Normal).data;
+    for(let i=0;i<water_positions.length;i+=3) {
+        water_positions[i+2]=-water_positions[i+1];water_positions[i+1]=0;
+        // An authored outline: the displacement grid never supplies the rendered boundary.
+        water_positions[i]*=0.75+0.2*Math.cos(water_positions[i+2]*Math.PI/20);
+        water_normals[i]=0;water_normals[i+1]=1;water_normals[i+2]=0;
+    }
+    const water_geometry=meshlets(water_plane),water_transform=pose(16,0,16);
+    // the primitive wave simulation's forcing; the overlapping second body below has none and stays calm
+    const waves=new WaterWaves();
+    const water_entity=build(new Entity().add(water).add(waves).add(water_geometry).add(water_transform));
     const add_mesh=(geo,m,x,y,z,rotation)=>{
         const t=pose(x,y,z,rotation);const component=shaded(meshlets(geo),m);
         const entity=build(new Entity().add(t).add(component)); return {transform:t,component,entity};
@@ -102,7 +116,7 @@ export async function build_world(dataset) {
     const batch=new DynamicMeshBatch(); batch.add(ribbon);
     let secondary=null;
     let last_update=null;
-    return {terrain,water,water_entity,card,submerged,batch,ribbon,effects:live_effects,entities,
+    return {terrain,water,waves,water_entity,water_transform,card,submerged,batch,ribbon,effects:live_effects,entities,
         reset_particles() {
             particle_transforms.forEach(({entity},i)=>{
                 const replacement=live_effects[i].clone();
@@ -128,8 +142,8 @@ export async function build_world(dataset) {
             terrain.samplerHeight=sampler(offset); floor_transform.setTranslation(0,offset,0);t64_announce_change(dataset,floor_entity);
         },
         overlap(enabled) {
-            if(enabled&&secondary===null) {const other=new Water();other.level.set(water.level.getValue()-0.4);
-                other.color.setRGB(0.65,0.1,0.25);secondary=build(new Entity().add(other));}
+            if(enabled&&secondary===null) {const other=new Water();const placement=pose(16,water_transform.translation_y-0.4,16);
+                other.medium=water_medium_preset({preset:'turbid_river'});secondary=build(new Entity().add(other).add(water_geometry).add(placement));}
             if(!enabled&&secondary!==null) {dataset.removeEntity(secondary);secondary=null;}
         },
         dispose() {entities.forEach(id=>{if(dataset.entityExists(id)) dataset.removeEntity(id);});batch.clear();},

package/src/shade/renderer/Renderer.d.ts

@@ -73,6 +73,27 @@ export class Renderer {
     feature_tetrahedron_point_shadows: boolean;
     set shadow_update_budget(v: number);
     get shadow_update_budget(): number;
+    set shadow_cascade_count(v: number);
+    get shadow_cascade_count(): number;
+    /**
+     * Give directional lights virtual shadow maps — a clipmap of pages rendered as the view asks for
+     * them and as moving casters make them stale — instead of cascades. Pushed to the scene's shadow
+     * context each frame; a flip rebuilds every directional map. See
+     * {@link GPUSceneShadowmapContext.use_virtual_shadow_maps}.
+     * @type {boolean}
+     */
+    feature_virtual_shadow_maps: boolean;
+    set shadow_virtual_page_budget(v: number);
+    get shadow_virtual_page_budget(): number;
+    /**
+     * Added to the clipmap level every point of a virtual shadow map selects; positive is coarser,
+     * fewer pages and softer shadows. Pushed each frame; see
+     * {@link GPUSceneShadowmapContext.virtual_lod_bias}.
+     * @type {number}
+     */
+    shadow_virtual_lod_bias: number;
+    set shadow_virtual_first_texel_size(v: number);
+    get shadow_virtual_first_texel_size(): number;
     feature_bloom_enabled: boolean;
     feature_automatic_exposure_enabled: boolean;
     set exposure_compensation(v: number);

package/src/shade/renderer/Renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/Renderer.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/Renderer.js"],"names":[],"mappings":"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"}

package/src/shade/renderer/Renderer.js

@@ -77,6 +77,9 @@ import { graph_import_buffer } from "./shader/graph/graph_import_buffer.js";
 import { graph_import_texture } from "./shader/graph/graph_import_texture.js";
 import { ShadeUpscalerType } from "./ShadeUpscalerType.js";
 import { DEFAULT_SHADOWMAP_UPDATE_BUDGET } from "./shadow/map/DEFAULT_SHADOWMAP_UPDATE_BUDGET.js";
+import { SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT } from "./shadow/map/csm/SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT.js";
+import { DEFAULT_VSM_FIRST_TEXEL_SIZE } from "./shadow/vsm/DEFAULT_VSM_FIRST_TEXEL_SIZE.js";
+import { DEFAULT_VSM_PAGE_BUDGET } from "./shadow/vsm/DEFAULT_VSM_PAGE_BUDGET.js";
 import { CascadedSceneSDF } from "./shadow/sdf/cascade/CascadedSceneSDF.js";
 import { STATIC_GRAPHICS_ENGINE_ASSETS } from "./STATIC_GRAPHICS_ENGINE_ASSETS.js";
 import { GPUTextureContext } from "./texture/GPUTextureContext.js";
@@ -250,6 +253,78 @@ export class Renderer {
         return this.#shadow_update_budget;
     }
 
+    /**
+     * How many cascades a directional light's shadow map is split into, pushed to the scene's
+     * shadow context each frame; see {@link GPUSceneShadowmapContext.cascade_count}. More cascades
+     * put more shadow texels near the camera at the cost of a rasterization pass each. A change
+     * rebuilds every directional map, and its near planes come back loose for the two frames its
+     * caster range takes to be measured again.
+     * @type {number}
+     */
+    #shadow_cascade_count = SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT;
+
+    set shadow_cascade_count(v) {
+        assert.isPositiveInteger(v, 'shadow_cascade_count');
+
+        this.#shadow_cascade_count = v;
+    }
+
+    get shadow_cascade_count() {
+        return this.#shadow_cascade_count;
+    }
+
+    /**
+     * Give directional lights virtual shadow maps — a clipmap of pages rendered as the view asks for
+     * them and as moving casters make them stale — instead of cascades. Pushed to the scene's shadow
+     * context each frame; a flip rebuilds every directional map. See
+     * {@link GPUSceneShadowmapContext.use_virtual_shadow_maps}.
+     * @type {boolean}
+     */
+    feature_virtual_shadow_maps = false;
+
+    /**
+     * Virtual shadow map pages a scene may render per frame, pushed to the scene's shadow context
+     * each frame; see {@link DEFAULT_VSM_PAGE_BUDGET} for what a page costs and what waits.
+     * @type {number}
+     */
+    #shadow_virtual_page_budget = DEFAULT_VSM_PAGE_BUDGET;
+
+    set shadow_virtual_page_budget(v) {
+        assert.isNonNegativeInteger(v, 'shadow_virtual_page_budget');
+
+        this.#shadow_virtual_page_budget = v;
+    }
+
+    get shadow_virtual_page_budget() {
+        return this.#shadow_virtual_page_budget;
+    }
+
+    /**
+     * Added to the clipmap level every point of a virtual shadow map selects; positive is coarser,
+     * fewer pages and softer shadows. Pushed each frame; see
+     * {@link GPUSceneShadowmapContext.virtual_lod_bias}.
+     * @type {number}
+     */
+    shadow_virtual_lod_bias = 0;
+
+    /**
+     * World size of a virtual shadow map's finest texel, in metres. Pushed each frame; a change
+     * rebuilds the maps. See {@link DEFAULT_VSM_FIRST_TEXEL_SIZE}.
+     * @type {number}
+     */
+    #shadow_virtual_first_texel_size = DEFAULT_VSM_FIRST_TEXEL_SIZE;
+
+    set shadow_virtual_first_texel_size(v) {
+        assert.isNumber(v, 'shadow_virtual_first_texel_size');
+        assert.greaterThan(v, 0, 'shadow_virtual_first_texel_size');
+
+        this.#shadow_virtual_first_texel_size = v;
+    }
+
+    get shadow_virtual_first_texel_size() {
+        return this.#shadow_virtual_first_texel_size;
+    }
+
     feature_bloom_enabled = true;
     feature_automatic_exposure_enabled = true;
 
@@ -2093,6 +2168,14 @@ export class Renderer {
         sm.use_tetrahedron_point_shadows = this.feature_tetrahedron_point_shadows;
         // How many views the refresh scheduler may spend on this scene this frame.
         sm.update_budget = this.#shadow_update_budget;
+        // How many cascades a directional map has; a change rebuilds the maps inside process_lights.
+        sm.cascade_count = this.#shadow_cascade_count;
+        // Virtual shadow maps for directional lights, and what they may spend; a flip of the flag or
+        // of the first texel rebuilds the maps inside process_lights.
+        sm.use_virtual_shadow_maps = this.feature_virtual_shadow_maps;
+        sm.virtual_page_budget = this.#shadow_virtual_page_budget;
+        sm.virtual_lod_bias = this.shadow_virtual_lod_bias;
+        sm.virtual_first_texel_size = this.#shadow_virtual_first_texel_size;
 
         const taa = this.#taa;
 
@@ -2248,6 +2331,17 @@ export class Renderer {
             });
         }
 
+        // Virtual shadow map feedback: the casters that moved, the pages they left stale, and the
+        // pages this view's depth asks for, read back for the maps' next frames. No-op unless a
+        // directional light has a virtual map.
+        if (this.#feature_shadows_enabled) {
+            sm.graph_virtual_feedback({
+                graph,
+                view: view_ctx,
+                depth: gr_raster_depth,
+            });
+        }
+
         // run materials
         const mat_g = graphics.materials.graph_viz_render({
             graph,
@@ -2652,7 +2746,7 @@ export class Renderer {
             for (let i = 0; i < transparency_channels.length; i++) {
                 const channel = transparency_channels[i];
 
-                if (channel.avboit_is_empty !== undefined && channel.avboit_is_empty()) {
+                if (channel.avboit_is_empty !== undefined && channel.avboit_is_empty(view_ctx)) {
                     continue;
                 }
 

package/src/shade/renderer/animation/GPUAnimationManager.d.ts

@@ -125,6 +125,14 @@ export class GPUAnimationManager {
      * @returns {number}
      */
     get_skin_matrix_offset(skin_id: number): number;
+    /**
+     * How many joints the skin has — rows of the `skin_matrices` scratch buffer from
+     * {@link get_skin_matrix_offset}. Fixed once the skin is registered.
+     *
+     * @param {number} skin_id
+     * @returns {number}
+     */
+    get_skin_joint_count(skin_id: number): number;
     /**
      * Add an animation curve. Its keyframes go into `animation_keyframes` as one run of rows, in
      * order, and the curve's header names the run.

package/src/shade/renderer/animation/GPUAnimationManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"AA+IA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAsPI;;;;OAIG;IACH,sCAHW,MAAM,iBACN,eAAe,EAezB;IAED;;OAEG;IACH,4BAEC;IAED;;;;;;;;;;;;OAYG;IACH,gCAEC;IAED;;;;;;;;;;OAUG;IACH,qCAEC;IAED;;;;;;;;OAQG;IACH,gCAEC;IAED;;;;;;;;;;OAUG;IACH,mCAEC;IAED;;;;;;;;;;;;OAYG;IACH,4CAFW,MAAM,QA6BhB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAKvD;IAED;;;;;;;;;;;;;OAaG;IACH,gCAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;;;;;OASG;IACH,iBAHW,cAAc,GACZ,MAAM,CAmBlB;IAED;;;;;;;;;;;;;;OAcG;IACH,oBAJW;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAEhD,MAAM,CA4BlB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eARW;QACV,IAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAc,CAAC,EAAE,MAAM,CAAC;QACxB,QAAc,EAAE,MAAM;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC1E,GACS,MAAM,CA0ClB;IA4BD;;;;;;;;;;;;;;;;;OAiBG;IACH,kBAHW,MAAM,QACN,MAAM,QAWhB;IAED;;;;;;;;OAQG;IACH,2BAHW,MAAM,QACN,MAAM,QAKhB;IAED;;;;;;;;;;;;;;OAcG;IACH,6BAHW,MAAM,UACN,MAAM,QAWhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,mBAHW,MAAM,SACN,MAAM,QAMhB;IAED;;;;;;;OAOG;IACH,qBAHW,MAAM,SACN,MAAM,QAMhB;IAED;;;;;;;;;;;OAWG;IACH,eAFW,MAAM,QAMhB;IAED;;;;;;;;;OASG;IACH,cAFW,MAAM,QAMhB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eALW;QACV,MAAY,EAAE,MAAM;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,YAAY,GAAG,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;KAC1E,GACS,MAAM,CAuBlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,oBAHW,IAAI,GACF,MAAM,CA4BlB;IAwGD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,oBAHW,kBAAkB,GAChB,MAAM,CA2DlB;IAoND;;;;;;;;;;;;;;OAcG;IACH,yBAFW,MAAM,QA4BhB;IAED;;;;;;;;;;;;;;;OAeG;IACH,yBAFW,MAAM,QA+BhB;IAuLD;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAFW,sBAAsB,QAMhC;IAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,mCAFW,sBAAsB,QAmChC;IAgED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,cALW,sBAAsB,cACtB,MAAM,GACJ,OAAO,CA0CnB;IA8FD,gBAoBC;;CACJ;6BA55DY,OAAO,mDAAmD,EAAE,cAAc;8BAC1E,OAAO,iDAAiD,EAAE,eAAe;qCACzE,OAAO,wCAAwC,EAAE,sBAAsB;8BACvE,OAAO,6BAA6B,EAAE,eAAe;iCACrD,OAAO,yBAAyB,EAAE,kBAAkB;mBACpD,OAAO,WAAW,EAAE,IAAI;4BA/CT,gCAAgC"}
+{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"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"}

package/src/shade/renderer/animation/GPUAnimationManager.js

@@ -100,6 +100,7 @@ const CLIP_FLAGS_WORD = ANIMATION_CLIP_STATE_STRUCT.get('flags').offset / 4;
  * Word of a skin record holding its first joint row — where its matrices start.
  */
 const SKIN_JOINTS_FIRST_WORD = ANIMATION_SKIN_STRUCT.get('joints_first').offset / 4;
+const SKIN_JOINT_COUNT_WORD = ANIMATION_SKIN_STRUCT.get('joint_count').offset / 4;
 
 /**
  * A joint's `node` alone — what naming a pending skin's nodes writes, and all it uploads.
@@ -580,6 +581,23 @@ export class GPUAnimationManager {
         return joints_first;
     }
 
+    /**
+     * How many joints the skin has — rows of the `skin_matrices` scratch buffer from
+     * {@link get_skin_matrix_offset}. Fixed once the skin is registered.
+     *
+     * @param {number} skin_id
+     * @returns {number}
+     */
+    get_skin_joint_count(skin_id) {
+        assert.isNonNegativeInteger(skin_id, 'skin_id');
+
+        const joint_count = this.#database.get('animation_skins').get_word(skin_id, SKIN_JOINT_COUNT_WORD);
+
+        assert.defined(joint_count, `unknown skin_id ${skin_id}`);
+
+        return joint_count;
+    }
+
     /**
      * Add an animation curve. Its keyframes go into `animation_keyframes` as one run of rows, in
      * order, and the curve's header names the run.