@woosh/meep-engine 3.39.0 → 3.40.0

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

@@ -21,15 +21,21 @@ 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. The surface is a real mesh: a primitive wave simulation on a
-512² grid over the body, driven by the WaterWaves component (wind speed and direction), writes its
-its mesh behind the surface interface the production simulation will replace
-(WATER_OPTICS_PLAN_2026_10_02.md §7.2). Screen reflections can be disabled while retaining the
+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.
 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, single scattering for now, and In-scatter segments
+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.
 
@@ -62,7 +68,7 @@ Newton miss reason: 0 none/not attempted, 1 bounds/clip, 2 sky, 3 parallel/inval
 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,
@@ -72,7 +78,7 @@ 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.
 
@@ -82,8 +88,8 @@ Opaque receiver transport uses the immutable pre-transparency HDR scene. Water c
 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
@@ -153,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/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";
@@ -24,6 +25,11 @@ import { ParticipatingMediaVolume } from "../../renderer/volumetrics/Participati
 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";
 
@@ -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,7 +79,7 @@ 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.roughness.set(number("roughness"));
+        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"),
@@ -157,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_ibl,water_finalize_shader_brick4,...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}`));

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

@@ -4,6 +4,7 @@ export function build_world(dataset: any): Promise<{
     water: Water;
     waves: WaterWaves;
     water_entity: any;
+    water_transform: Transform64;
     card: {
         transform: Transform64;
         component: ShadedGeometry;

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":"AA4DA,+FAA+F;AAC/F;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EC;AA9GM,mEAAsE;oBAzBzD,4CAA4C;kBAI9C,6CAA6C;uBACxC,kDAAkD;4BAJ7C,8CAA8C;+BAE3C,wDAAwD;iCAetD,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

@@ -82,10 +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);
+    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));
+    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};
@@ -106,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,waves,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();
@@ -132,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.medium=water_medium_preset({preset:'turbid_river'});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

@@ -75,6 +75,25 @@ export class Renderer {
     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

@@ -78,6 +78,8 @@ 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";
@@ -271,6 +273,58 @@ export class Renderer {
         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;
 
@@ -2116,6 +2170,12 @@ export class Renderer {
         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;
 
@@ -2271,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,
@@ -2675,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":"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"}
+{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"AAgJA;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;;OAMG;IACH,8BAHW,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;6BA96DY,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"}

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.

package/src/shade/renderer/animation/skinning/GPUMeshSkinningContext.d.ts

@@ -65,6 +65,13 @@ export class GPUMeshSkinningContext {
      * @returns {GPUBuffer|null}
      */
     get bindings_buffer(): any;
+    /**
+     * Bound {@link SkinnedMesh}es — the records {@link bindings_buffer} holds once {@link update} has
+     * uploaded them, which it does on the frame they change.
+     *
+     * @returns {number}
+     */
+    get binding_count(): number;
     /**
      * Per-meshlet base offsets into {@link prev_positions_buffer},
      * indexed by absolute meshlet metadata row. Non-clone meshlets

package/src/shade/renderer/animation/skinning/GPUMeshSkinningContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshSkinningContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js"],"names":[],"mappings":"AAmFA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAgNI;;;;;;;OAOG;IACH,sEAPW;QACV,UAAgB,EAAE,kBAAkB,CAAC;QACrC,iBAAuB,EAAE,mBAAmB,CAAC;QAC7C,aAAmB,EAAE,eAAe,CAAC;QACrC,MAAY,YAAY;KACrB,EAcH;IAED;;;;;;OAMG;IACH,iCAEC;IAED;;;;;;;OAOG;IACH,yCAEC;IAED;;;;;;OAMG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,wCAEC;IAED;;;;;;;;;;;;OAYG;IACH,qBAJW,MAAM,YACN,eAAe,GACb,mBAAmB,CAqB/B;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,mBAAmB,GAAC,SAAS,CAMzC;IAED;;;;;;;;;;OAUG;IACH,aAHW,MAAM,WACN,MAAM,QAwBhB;IAED;;;;;;;OAOG;IACH,oBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;;;;OAUG;IACH,eAFW,MAAM,QAYhB;IAED;;;;;;;;OAQG;IACH,4BAFW,MAAM,QAUhB;IA4FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,sBAFW,MAAM,QAqBhB;IAuBD;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAJW,sBAAsB,GACpB,OAAO,CA0NnB;IAkXD;;;;;;;OAOG;IACH,gBA+BC;;CACJ;qCA/wCY,OAAO,2CAA2C,EAAE,sBAAsB;iCAC1E,OAAO,sCAAsC,EAAE,kBAAkB;8BACjE,OAAO,gCAAgC,EAAE,eAAe;8BACxD,OAAO,mCAAmC,EAAE,eAAe;kCAC3D,OAAO,uCAAuC,EAAE,mBAAmB;kCACnE,OAAO,2BAA2B,EAAE,mBAAmB"}
+{"version":3,"file":"GPUMeshSkinningContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js"],"names":[],"mappings":"AAmFA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAgNI;;;;;;;OAOG;IACH,sEAPW;QACV,UAAgB,EAAE,kBAAkB,CAAC;QACrC,iBAAuB,EAAE,mBAAmB,CAAC;QAC7C,aAAmB,EAAE,eAAe,CAAC;QACrC,MAAY,YAAY;KACrB,EAcH;IAED;;;;;;OAMG;IACH,iCAEC;IAED;;;;;;;OAOG;IACH,yCAEC;IAED;;;;;;OAMG;IACH,2BAEC;IAED;;;;;OAKG;IACH,4BAEC;IAED;;;;;;;OAOG;IACH,wCAEC;IAED;;;;;;;;;;;;OAYG;IACH,qBAJW,MAAM,YACN,eAAe,GACb,mBAAmB,CAqB/B;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,mBAAmB,GAAC,SAAS,CAMzC;IAED;;;;;;;;;;OAUG;IACH,aAHW,MAAM,WACN,MAAM,QAwBhB;IAED;;;;;;;OAOG;IACH,oBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;;;;OAUG;IACH,eAFW,MAAM,QAYhB;IAED;;;;;;;;OAQG;IACH,4BAFW,MAAM,QAUhB;IA4FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,sBAFW,MAAM,QAqBhB;IAuBD;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAJW,sBAAsB,GACpB,OAAO,CA0NnB;IAmXD;;;;;;;OAOG;IACH,gBA+BC;;CACJ;qCA1xCY,OAAO,2CAA2C,EAAE,sBAAsB;iCAC1E,OAAO,sCAAsC,EAAE,kBAAkB;8BACjE,OAAO,gCAAgC,EAAE,eAAe;8BACxD,OAAO,mCAAmC,EAAE,eAAe;kCAC3D,OAAO,uCAAuC,EAAE,mBAAmB;kCACnE,OAAO,2BAA2B,EAAE,mBAAmB"}

package/src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js

@@ -372,6 +372,16 @@ export class GPUMeshSkinningContext {
         return this.#bindings_buffer;
     }
 
+    /**
+     * Bound {@link SkinnedMesh}es — the records {@link bindings_buffer} holds once {@link update} has
+     * uploaded them, which it does on the frame they change.
+     *
+     * @returns {number}
+     */
+    get binding_count() {
+        return this.#bindings.length;
+    }
+
     /**
      * Per-meshlet base offsets into {@link prev_positions_buffer},
      * indexed by absolute meshlet metadata row. Non-clone meshlets
@@ -1233,6 +1243,7 @@ export class GPUMeshSkinningContext {
 
             write_gpu_typed_buffer({
                 skin_matrix_offset: this.#animation_manager.get_skin_matrix_offset(b.skin_id),
+                skin_matrix_count: this.#animation_manager.get_skin_joint_count(b.skin_id),
                 source_meshlet_metadata_offset: b.source_meshlet_metadata_offset,
                 clone_meshlet_metadata_offset: b.clone_meshlet_metadata_offset,
                 meshlet_count: b.meshlet_count,

package/src/shade/renderer/animation/skinning/SKINNING_BINDING_STRUCT.d.ts

@@ -9,7 +9,9 @@
  *  - `skin_matrix_offset` is the skin's first joint row, read from the
  *    animation manager's {@link GPUAnimationManager#get_skin_matrix_offset}
  *    — a joint's matrix sits at its row — so the shader can index
- *    `skin_matrices` directly without dereferencing the skin record.
+ *    `skin_matrices` directly without dereferencing the skin record;
+ *    `skin_matrix_count`, its number of joints, from
+ *    {@link GPUAnimationManager#get_skin_joint_count}.
  *  - The two `*_meshlet_metadata_offset` values are the starts of the
  *    source's and clone's meshlet ranges in the meshlet metadata
  *    buffer; combined with `meshlet_count`, they bound the per-binding

package/src/shade/renderer/animation/skinning/SKINNING_BINDING_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SKINNING_BINDING_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/SKINNING_BINDING_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,mDAwDsB;6BA3EO,mCAAmC"}
+{"version":3,"file":"SKINNING_BINDING_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/SKINNING_BINDING_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,mDA+DsB;6BApFO,mCAAmC"}

package/src/shade/renderer/animation/skinning/SKINNING_BINDING_STRUCT.js

@@ -12,7 +12,9 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
  *  - `skin_matrix_offset` is the skin's first joint row, read from the
  *    animation manager's {@link GPUAnimationManager#get_skin_matrix_offset}
  *    — a joint's matrix sits at its row — so the shader can index
- *    `skin_matrices` directly without dereferencing the skin record.
+ *    `skin_matrices` directly without dereferencing the skin record;
+ *    `skin_matrix_count`, its number of joints, from
+ *    {@link GPUAnimationManager#get_skin_joint_count}.
  *  - The two `*_meshlet_metadata_offset` values are the starts of the
  *    source's and clone's meshlet ranges in the meshlet metadata
  *    buffer; combined with `meshlet_count`, they bound the per-binding
@@ -26,6 +28,13 @@ export const SKINNING_BINDING_STRUCT = WebGPUStruct.from({
      */
     skin_matrix_offset: u32,
 
+    /**
+     * How many joints the skin has: its matrices are `skin_matrix_count` rows from
+     * `skin_matrix_offset`. The skinning shader needs no count — a vertex names its joints — but a
+     * pass over the skin's pose does, such as the virtual shadow map's test of whether it moved.
+     */
+    skin_matrix_count: u32,
+
     /**
      * First source meshlet record in the meshlet metadata buffer. The
      * skinning shader reads attributes (position / normal / tangent /

package/src/shade/renderer/buffer/table/serde/table_wgsl_gen_read_code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table_wgsl_gen_read_code.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/buffer/table/serde/table_wgsl_gen_read_code.js"],"names":[],"mappings":"AAyKA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,uEAZW,MAAM,eACN,MAAM,qBAEJ,IAAI,CA8BhB"}
+{"version":3,"file":"table_wgsl_gen_read_code.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/buffer/table/serde/table_wgsl_gen_read_code.js"],"names":[],"mappings":"AAqMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,uEAZW,MAAM,eACN,MAAM,qBAEJ,IAAI,CA8BhB"}

package/src/shade/renderer/buffer/table/serde/table_wgsl_gen_read_code.js

@@ -1,13 +1,17 @@
 import { assert } from "../../../../../core/assert.js";
 import {
     f32,
+    i32,
     mat4x4f,
     u32,
     vec2f,
+    vec2i,
     vec2u,
     vec3f,
+    vec3i,
     vec3u,
     vec4f,
+    vec4i,
     vec4u
 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 
@@ -50,6 +54,30 @@ function table_wgsl_gen_read_code_primitive(
         case f32:
             builder.extend(`bitcast<f32>(${buffer_name}[base_offset + ${offset}])`);
             return;
+        case i32:
+            builder.extend(`bitcast<i32>(${buffer_name}[base_offset + ${offset}])`);
+            return;
+        case vec2i:
+            builder.extend(`vec2<i32>(`);
+            builder.indent();
+            read_multiple(builder, offset, buffer_name, i32, 2);
+            builder.dedent();
+            builder.extend(')');
+            return;
+        case vec3i:
+            builder.extend(`vec3<i32>(`);
+            builder.indent();
+            read_multiple(builder, offset, buffer_name, i32, 3);
+            builder.dedent();
+            builder.extend(')');
+            return;
+        case vec4i:
+            builder.extend(`vec4<i32>(`);
+            builder.indent();
+            read_multiple(builder, offset, buffer_name, i32, 4);
+            builder.dedent();
+            builder.extend(')');
+            return;
         case vec2f:
             builder.extend(`vec2<f32>(`);
             builder.indent();

package/src/shade/renderer/buffer/table/serde/table_wgsl_gen_write_code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table_wgsl_gen_write_code.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/buffer/table/serde/table_wgsl_gen_write_code.js"],"names":[],"mappings":"AAoHA;;;;;;;;;;;;;;GAcG;AACH,wEANW,MAAM,eACN,MAAM,iCAEN,MAAM,GACJ,IAAI,CAyBhB"}
+{"version":3,"file":"table_wgsl_gen_write_code.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/buffer/table/serde/table_wgsl_gen_write_code.js"],"names":[],"mappings":"AAkJA;;;;;;;;;;;;;;GAcG;AACH,wEANW,MAAM,eACN,MAAM,iCAEN,MAAM,GACJ,IAAI,CAyBhB"}

package/src/shade/renderer/buffer/table/serde/table_wgsl_gen_write_code.js

@@ -1,5 +1,19 @@
 import { assert } from "../../../../../core/assert.js";
-import { f32, mat4x4f, u32, vec2f, vec2u, vec3f, vec3u, vec4f, vec4u } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import {
+    f32,
+    i32,
+    mat4x4f,
+    u32,
+    vec2f,
+    vec2i,
+    vec2u,
+    vec3f,
+    vec3i,
+    vec3u,
+    vec4f,
+    vec4i,
+    vec4u
+} from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 
 /**
  *
@@ -21,8 +35,24 @@ function table_wgsl_gen_write_code_primitive(
             builder.add(`${buffer_name}[base_offset + ${offset}] = ${value_expr};`);
             return;
         case f32:
+        case i32:
             builder.add(`${buffer_name}[base_offset + ${offset}] = bitcast<u32>(${value_expr});`);
             return;
+        case vec2i:
+            for (let i = 0; i < 2; i++) {
+                table_wgsl_gen_write_code_primitive(builder, offset + i, buffer_name, i32, `${value_expr}[${i}]`);
+            }
+            return;
+        case vec3i:
+            for (let i = 0; i < 3; i++) {
+                table_wgsl_gen_write_code_primitive(builder, offset + i, buffer_name, i32, `${value_expr}[${i}]`);
+            }
+            return;
+        case vec4i:
+            for (let i = 0; i < 4; i++) {
+                table_wgsl_gen_write_code_primitive(builder, offset + i, buffer_name, i32, `${value_expr}[${i}]`);
+            }
+            return;
         case vec2f:
             for (let i = 0; i < 2; i++) {
                 table_wgsl_gen_write_code_primitive(builder, offset + i, buffer_name, f32, `${value_expr}[${i}]`);