ugly-game 0.7.7 → 0.7.9

package/dist/assets/gpuProps.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Per-world surface + motion parameters.
+ *
+ * `windAmp` should come from the world's AIR DENSITY: an airless world's flora is perfectly, eerily
+ * still, which is both physically correct and an instant read on where you are. `hueShift` and
+ * `saturation` carry the star-spectrum grade, so one planet's forest is waxy blue-green and the
+ * next is dry and rust-coloured from identical meshes.
+ */
+export interface PropWorld {
+    windDir: [number, number];
+    /** 0 disables sway entirely (and the vertex path early-outs). */
+    windAmp: number;
+    /** 0 disables the procedural grain. Larger = finer detail. */
+    grainScale: number;
+    grainDepth: number;
+    roughness: number;
+    /** bioluminescence — flat emissive added on dark worlds */
+    emissive: number;
+    hueShift: number;
+    saturation: number;
+    valueLift: number;
+}
 export interface PropMesh {
     positions: Float32Array;
     normals: Float32Array;
@@ -24,6 +46,17 @@ export declare class GpuPropsRenderer {
     private shadowBG;
     private lastSV;
     private lastSS;
+    /** Per-world look + motion. Defaults are inert: no sway, no grain, no grade. */
+    private world;
+    private phase;
+    /**
+     * Set the per-world look and motion. This is the whole point of the procedural surface: the same
+     * geometry and the same shader render a different planet's flora by moving a handful of numbers —
+     * no per-model textures to author, download, or keep coherent.
+     */
+    setWorld(w: Partial<PropWorld>): void;
+    /** Advance the wind phase. Pass the frame delta; sway is skipped entirely when windAmp is 0. */
+    tick(dt: number): void;
     constructor(device: GPUDevice, format: GPUTextureFormat);
     setModels(meshes: PropMesh[]): void;
     /** Group instances by model and upload per-model transform buffers. */

package/dist/assets/gpuProps.js

@@ -4,16 +4,37 @@
 // terrain. Runs in a load pass after the terrain so props depth-test against the surface.
 // ─────────────────────────────────────────────────────────────────────────────
 const SHADER = /* wgsl */ `
-struct U { mvp: mat4x4<f32>, lightVP: mat4x4<f32>, sun: vec4<f32>, sunCol: vec4<f32>, amb: vec4<f32>, cam: vec4<f32>, fog: vec4<f32>, up: vec4<f32> };
+// wind  = (dirX, dirZ, amplitude, phase)      — sway, amplitude scaled by the world's air density
+// surf  = (grainScale, grainDepth, roughness, emissive)
+// grade = (hueShift, saturation, valueLift, unused)
+struct U { mvp: mat4x4<f32>, lightVP: mat4x4<f32>, sun: vec4<f32>, sunCol: vec4<f32>, amb: vec4<f32>, cam: vec4<f32>, fog: vec4<f32>, up: vec4<f32>, wind: vec4<f32>, surf: vec4<f32>, grade: vec4<f32> };
 @group(0) @binding(0) var<uniform> u: U;
 @group(0) @binding(1) var<storage,read> models: array<mat4x4<f32>>;
 @group(1) @binding(0) var shadowMap: texture_depth_2d;      // the SAME sun shadow map the terrain cubes sample
 @group(1) @binding(1) var shadowSamp: sampler_comparison;
-struct VO { @builtin(position) pos: vec4<f32>, @location(0) world: vec3<f32>, @location(1) n: vec3<f32>, @location(2) c: vec3<f32> };
+struct VO { @builtin(position) pos: vec4<f32>, @location(0) world: vec3<f32>, @location(1) n: vec3<f32>, @location(2) c: vec3<f32>, @location(3) l: vec3<f32> };
+// WIND SWAY. Displacement is weighted by height above the instance's own anchor, so a trunk stays
+// planted while the canopy moves, and the phase is offset by world position so a grove never sways
+// in unison. Amplitude comes from the world's air density: an airless world is perfectly, eerily
+// still — physically right, and a strong signal of where you are.
+fn sway(local: vec3<f32>, world: vec3<f32>, up: vec3<f32>, scale: f32) -> vec3<f32> {
+  if (u.wind.z <= 0.0001) { return world; }
+  let h = max(dot(local, vec3(0.0, 1.0, 0.0)), 0.0);       // model +Y is local up (see placeMat)
+  let stiff = pow(min(h * 0.22, 1.0), 1.6);                 // stiff at the base, loose at the tip
+  let ph = u.wind.w + dot(world.xz, vec2(0.13, 0.17));
+  let a = u.wind.z * stiff * scale;
+  let d = a * (sin(ph) + 0.35 * sin(ph * 2.7 + h));
+  var wd = vec3(u.wind.x, 0.0, u.wind.y);
+  wd = normalize(wd - up * dot(wd, up));                    // project into the local tangent plane
+  return world + wd * d;
+}
 @vertex fn vs(@location(0) p: vec3<f32>, @location(1) nrm: vec3<f32>, @location(2) col: vec3<f32>, @builtin(instance_index) ii: u32) -> VO {
   let m = models[ii];
-  let world = (m * vec4(p, 1.0)).xyz;
-  var o: VO; o.pos = u.mvp * vec4(world, 1.0); o.world = world; o.n = (m * vec4(nrm, 0.0)).xyz; o.c = col; return o;
+  var world = (m * vec4(p, 1.0)).xyz;
+  let upv = normalize((m * vec4(0.0, 1.0, 0.0, 0.0)).xyz);
+  let sc = length(m[0].xyz);
+  world = sway(p, world, upv, sc);
+  var o: VO; o.pos = u.mvp * vec4(world, 1.0); o.world = world; o.n = (m * vec4(nrm, 0.0)).xyz; o.c = col; o.l = p; return o;
 }
 // same fixed directional FILL as the terrain cubes (gpuShadow.fixedFill) so plants/rocks read the same 3D shape,
 // day or night, under one shared light. up.w > 0.5 signals a valid local-up was supplied (else fall back to flat).
@@ -40,22 +61,84 @@ fn shadowFactor(world: vec3<f32>, ndl: f32) -> f32 {
   }
   return s / 9.0;
 }
+// ── PROCEDURAL SURFACE ───────────────────────────────────────────────────────
+// Detail is generated in the shader rather than sampled from a texture. Three reasons, all of them
+// load-bearing for a procedurally-populated universe: generated meshes have unreliable UVs (so
+// tri-planar, which needs none); there are no maps to download (the asset budget is already tight);
+// and the SAME code yields a different surface per planet by shifting a handful of parameters, which
+// is exactly what an infinite universe needs. Cohesion survives because every organism resolves
+// through one shared parameter set, not a per-model texture.
+fn hash3(p: vec3<f32>) -> f32 {
+  return fract(sin(dot(p, vec3(127.1, 311.7, 74.7))) * 43758.5453);
+}
+fn vnoise(p: vec3<f32>) -> f32 {
+  let i = floor(p); let f = fract(p);
+  let w = f * f * (3.0 - 2.0 * f);
+  let n000 = hash3(i); let n100 = hash3(i + vec3(1.0, 0.0, 0.0));
+  let n010 = hash3(i + vec3(0.0, 1.0, 0.0)); let n110 = hash3(i + vec3(1.0, 1.0, 0.0));
+  let n001 = hash3(i + vec3(0.0, 0.0, 1.0)); let n101 = hash3(i + vec3(1.0, 0.0, 1.0));
+  let n011 = hash3(i + vec3(0.0, 1.0, 1.0)); let n111 = hash3(i + vec3(1.0, 1.0, 1.0));
+  return mix(mix(mix(n000, n100, w.x), mix(n010, n110, w.x), w.y),
+             mix(mix(n001, n101, w.x), mix(n011, n111, w.x), w.y), w.z);
+}
+/** Tri-planar fbm — no UVs required, which matters because generated meshes rarely have usable ones. */
+fn triplanar(p: vec3<f32>, n: vec3<f32>, scale: f32) -> f32 {
+  let q = p * scale;
+  let w = abs(normalize(n));
+  let wn = w / max(w.x + w.y + w.z, 0.0001);
+  var v = vnoise(vec3(q.y, q.z, 0.0)) * wn.x
+        + vnoise(vec3(q.x, q.z, 1.7)) * wn.y
+        + vnoise(vec3(q.x, q.y, 3.3)) * wn.z;
+  v = v * 0.65 + 0.35 * vnoise(q * 2.7 + 11.0);   // a second octave for fine break-up
+  return v;
+}
+fn hsvShift(c: vec3<f32>, hue: f32, sat: f32, val: f32) -> vec3<f32> {
+  let k = vec3(0.57735, 0.57735, 0.57735);        // rotate about the grey axis
+  let cosA = cos(hue); let sinA = sin(hue);
+  let rot = c * cosA + cross(k, c) * sinA + k * dot(k, c) * (1.0 - cosA);
+  let g = dot(rot, vec3(0.299, 0.587, 0.114));
+  return clamp(mix(vec3(g, g, g), rot, sat) * val, vec3(0.0), vec3(4.0));
+}
 @fragment fn fs(i: VO) -> @location(0) vec4<f32> {
   let N = normalize(i.n);
   let ff = select(1.0, 0.5 + 0.85 * fixedFill(N, u.up.xyz), u.up.w > 0.5);   // fixed fill (fall back to flat amb if no up)
   let d = clamp(dot(N, -normalize(u.sun.xyz)), 0.0, 1.0);
   let sh = mix(1.0, shadowFactor(i.world, d), u.sun.w);   // u.sun.w = shadow-receive enable (0 ⇒ off, byte-identical for demo)
-  let lit = i.c * (u.amb.xyz * ff + d * u.sunCol.xyz * sh);
+  // procedural grain modulates the role colour; the per-world grade then re-tints the whole planet
+  var base = i.c;
+  if (u.surf.x > 0.0) {
+    let grain = triplanar(i.l, N, u.surf.x);
+    base = base * (1.0 - u.surf.y * 0.5 + u.surf.y * grain);
+  }
+  base = hsvShift(base, u.grade.x, max(u.grade.y, 0.0), max(u.grade.z, 0.0));
+  let spec = u.surf.z;
+  let lit = base * (u.amb.xyz * ff + d * u.sunCol.xyz * sh * (1.0 + spec * 0.6))
+          + base * u.surf.w;   // emissive — bioluminescence on dark worlds
   let dist = length(i.world - u.cam.xyz);
   let f = clamp(1.0 - exp(-dist * u.fog.w), 0.0, 1.0);
   return vec4(mix(lit, u.fog.xyz, f), 1.0);
 }`;
 // Depth-only occluder pass: instanced prop depth from the sun's ortho view (so trees/rocks cast shadows).
+// Depth-only occluder. It MUST apply the identical sway, or the shadows stay put while the leaves
+// move — a very visible detachment.
 const OCCLUDER = /* wgsl */ `
-@group(0) @binding(0) var<uniform> lightVP: mat4x4<f32>;
+struct OU { lightVP: mat4x4<f32>, wind: vec4<f32> };
+@group(0) @binding(0) var<uniform> o: OU;
 @group(0) @binding(1) var<storage,read> models: array<mat4x4<f32>>;
 @vertex fn vs(@location(0) p: vec3<f32>, @builtin(instance_index) ii: u32) -> @builtin(position) vec4<f32> {
-  return lightVP * (models[ii] * vec4(p, 1.0));
+  let m = models[ii];
+  var world = (m * vec4(p, 1.0)).xyz;
+  if (o.wind.z > 0.0001) {
+    let upv = normalize((m * vec4(0.0, 1.0, 0.0, 0.0)).xyz);
+    let h = max(p.y, 0.0);
+    let stiff = pow(min(h * 0.22, 1.0), 1.6);
+    let ph = o.wind.w + dot(world.xz, vec2(0.13, 0.17));
+    let a = o.wind.z * stiff * length(m[0].xyz);
+    var wd = vec3(o.wind.x, 0.0, o.wind.y);
+    wd = normalize(wd - upv * dot(wd, upv));
+    world = world + wd * (a * (sin(ph) + 0.35 * sin(ph * 2.7 + h)));
+  }
+  return o.lightVP * vec4(world, 1.0);
 }`;
 export class GpuPropsRenderer {
     device;
@@ -75,6 +158,32 @@ export class GpuPropsRenderer {
     shadowBG = null;
     lastSV = null;
     lastSS = null;
+    /** Per-world look + motion. Defaults are inert: no sway, no grain, no grade. */
+    world = {
+        windDir: [1, 0],
+        windAmp: 0,
+        grainScale: 0,
+        grainDepth: 0,
+        roughness: 0,
+        emissive: 0,
+        hueShift: 0,
+        saturation: 1,
+        valueLift: 1,
+    };
+    phase = 0;
+    /**
+     * Set the per-world look and motion. This is the whole point of the procedural surface: the same
+     * geometry and the same shader render a different planet's flora by moving a handful of numbers —
+     * no per-model textures to author, download, or keep coherent.
+     */
+    setWorld(w) {
+        this.world = { ...this.world, ...w };
+    }
+    /** Advance the wind phase. Pass the frame delta; sway is skipped entirely when windAmp is 0. */
+    tick(dt) {
+        if (this.world.windAmp > 0)
+            this.phase += dt * (0.8 + this.world.windAmp * 2.4);
+    }
     constructor(device, format) {
         this.device = device;
         const sm = device.createShaderModule({ code: SHADER });
@@ -127,11 +236,11 @@ export class GpuPropsRenderer {
             },
         });
         this.uBuf = device.createBuffer({
-            size: 128 + 16 * 6, // 2× mat4 (mvp + lightVP) + 6× vec4
+            size: 128 + 16 * 9, // 2× mat4 (mvp + lightVP) + 9× vec4 (…, wind, surf, grade)
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
         });
         this.lightBuf = device.createBuffer({
-            size: 64,
+            size: 64 + 16, // lightVP + wind (the occluder sways identically or shadows detach)
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
         });
         const dummy = device.createTexture({
@@ -213,7 +322,15 @@ export class GpuPropsRenderer {
     }
     /** Occluder pass: draw all instanced props' depth into the shared shadow map from the sun's ortho view. */
     shadowPass(pass, lightVP) {
-        this.device.queue.writeBuffer(this.lightBuf, 0, lightVP);
+        const ob = new Float32Array(20);
+        ob.set(lightVP, 0);
+        ob.set([
+            this.world.windDir[0],
+            this.world.windDir[1],
+            this.world.windAmp,
+            this.phase,
+        ], 16);
+        this.device.queue.writeBuffer(this.lightBuf, 0, ob);
         pass.setPipeline(this.occPipe);
         for (let m = 0; m < this.models.length; m++) {
             const bg = this.occBGs[m], mdl = this.models[m];
@@ -230,7 +347,7 @@ export class GpuPropsRenderer {
     // in the same shadow. Omit all three (the demo path) → no shadowing, byte-identical to before.
     lightVP, shadowView, shadowSamp) {
         const receive = !!(lightVP && shadowView && shadowSamp);
-        const u = new Float32Array(56);
+        const u = new Float32Array(68);
         u.set(camVP, 0);
         u.set(lightVP ?? IDENTITY4, 16); // lightVP (identity when not receiving — result is gated off by sun.w)
         u.set([sunDir[0], sunDir[1], sunDir[2], receive ? 1 : 0], 32); // sun.w = shadow-receive enable
@@ -240,6 +357,12 @@ export class GpuPropsRenderer {
         u.set([fog[0], fog[1], fog[2], fogDensity], 48);
         if (up)
             u.set([up[0], up[1], up[2], 1], 52); // up.w=1 → enable the fixed directional fill (matches the terrain)
+        // wind / surface / grade — all default to OFF, so a caller that never calls setWorld() renders
+        // byte-identically to before this feature existed.
+        const w = this.world;
+        u.set([w.windDir[0], w.windDir[1], w.windAmp, this.phase], 56);
+        u.set([w.grainScale, w.grainDepth, w.roughness, w.emissive], 60);
+        u.set([w.hueShift, w.saturation, w.valueLift, 0], 64);
         this.device.queue.writeBuffer(this.uBuf, 0, u);
         // group 1: the shadow map + comparison sampler (dummy when not receiving). Rebuild only when the view changes.
         const sv = shadowView ?? this.dummyShadowView, ss = shadowSamp ?? this.dummyShadowSamp;

package/dist/gpuShadow.d.ts

@@ -47,10 +47,13 @@ export declare class GpuShadowRenderer {
     private tileRectBuf;
     private useAtlas;
     private alphaPipe;
+    private alphaBGL;
     private overlayBuf;
     private overlayBG;
+    private overlayCap;
     private overlayScratch;
     private overlayCount;
+    private overlayDeferred;
     private cullPipe;
     private cullBGL;
     private cap;
@@ -96,8 +99,19 @@ export declare class GpuShadowRenderer {
     /** Dynamic scene: pre-allocate for `cap` instances; call updateInstances() each frame. */
     setCapacity(cap: number): void;
     updateInstances(instances: CubeInstance[]): void;
-    /** Translucent overlay cubes drawn over the opaque scene each frame; `emissive` carries per-cube alpha. */
-    updateOverlay(instances: CubeInstance[]): void;
+    /** Translucent overlay cubes drawn over the opaque scene; `emissive` carries per-cube alpha (0..1). The buffer
+     *  GROWS to fit (no hard cap). Pass `eye` to SORT the cubes back-to-front (farthest first) so overlapping
+     *  translucent cubes blend in the correct order — required for anything denser than the place ghost. By default
+     *  the cubes draw at the end of frame(); call deferOverlay(true) + overlayPass() to draw them after your own
+     *  transparent passes (e.g. water) so those don't paint over them. */
+    updateOverlay(instances: CubeInstance[], eye?: [number, number, number]): void;
+    /** Defer the translucent overlay out of frame() so the caller draws it via overlayPass() AFTER its own
+     *  transparent geometry (e.g. water). Otherwise those later passes paint over the overlay. */
+    deferOverlay(on: boolean): void;
+    /** Draw the translucent overlay in its own pass over `colorView`, depth-tested (read-only) against `depthView`
+     *  — same pipeline as the in-frame draw, just callable after other transparent passes. Pairs with
+     *  deferOverlay(true). No-op if the overlay is empty. */
+    overlayPass(enc: GPUCommandEncoder, colorView: GPUTextureView, depthView: GPUTextureView): void;
     /** Write a frustum's cull uniform: 6 planes + count + this frustum's VP + occlusion params (occ on the camera pass). */
     private writeCull;
     /** The sun shadow-map depth view + its comparison sampler + texel size. Feed these into GpuPropsRenderer/

package/dist/gpuShadow.js

@@ -91,10 +91,12 @@ fn hsv(hh: f32) -> vec3<f32> {
 // OCCLUSION CULLING (Hi-Z). After the frustum test, an in-frustum cube is ALSO dropped if it's fully hidden behind
 // nearer geometry. `hiz` is a coarse MAX-depth buffer (each texel = the farthest visible NDC depth over its block)
 // built from the PREVIOUS frame's depth. A cube is occluded iff its nearest corner is behind the farthest occluder
-// across its whole screen footprint. Using last frame's depth + a coarse buffer makes this HOLE-FREE by
-// construction: a newly-disoccluded area has far/cleared depth so nothing there is culled — the worst case is
-// under-culling for one frame, never a false cull. occ.x toggles it (camera pass only; the shadow pass never
-// occludes — an off-screen occluder still casts a shadow into view). occ.yz = hiz dims, occ.w = pixels/texel.
+// across its whole screen footprint. Because the depth is one frame STALE, a cube reprojects a few pixels under
+// camera motion and can be tested against near depth from where an occluder used to be — a false cull that blinks
+// the cube out for a frame. To absorb that, the footprint query is DILATED by 2 Hi-Z texels (see below); MAX over
+// the larger region only ever raises the occluder distance, so it strictly keeps more cubes and never hides real
+// geometry. occ.x toggles it (camera pass only; the shadow pass never occludes — an off-screen occluder still
+// casts a shadow into view). occ.yz = hiz dims, occ.w = pixels/texel.
 const CULL_WGSL = /* wgsl */ `
 struct Inst { pos: vec4<f32>, scl: vec4<f32>, rot: vec4<f32>, aux: vec4<f32> };
 struct Args { vc: u32, ic: atomic<u32>, fv: u32, fi: u32 };
@@ -145,9 +147,18 @@ fn cull(@builtin(global_invocation_id) gid: vec3<u32>) {
       let t1 = vec2<i32>(floor(clamp(mx, vec2<f32>(0.0), vec2<f32>(1.0)) * dim));
       // only query a bounded footprint; a huge on-screen box just isn't occlusion-tested (kept)
       if (t1.x - t0.x <= 8 && t1.y - t0.y <= 8) {
+        // DILATE the query by 2 Hi-Z texels. hiz is LAST frame's depth; under camera motion a cube reprojects by
+        // a few source pixels between frames, so a cube sitting at an occluder's silhouette gets tested against
+        // stale NEAR depth from where the occluder used to be and is wrongly culled — it blinks out for a frame
+        // (worst on thin/sparse geometry, but a one-frame hole in dense terrain too). Taking MAX over a dilated
+        // footprint is strictly MORE conservative (it can only raise farOccluder ⇒ only ever KEEP more cubes), so it
+        // never hides real geometry; it just leaves a couple of deeply-hidden cubes unculled. 2×8px of slack.
+        let lim = vec2<i32>(i32(cc.occ.y) - 1, i32(cc.occ.z) - 1);
+        let q0 = max(t0 - vec2<i32>(2, 2), vec2<i32>(0, 0));
+        let q1 = min(t1 + vec2<i32>(2, 2), lim);
         var farOccluder = 0.0;                          // MAX over the footprint of the coarse max-depth
-        for (var y = t0.y; y <= t1.y; y++) {
-          for (var x = t0.x; x <= t1.x; x++) {
+        for (var y = q0.y; y <= q1.y; y++) {
+          for (var x = q0.x; x <= q1.x; x++) {
             farOccluder = max(farOccluder, textureLoad(hiz, vec2<i32>(x, y), 0).r);
           }
         }
@@ -341,10 +352,13 @@ export class GpuShadowRenderer {
     tileRectBuf;
     useAtlas = 0;
     alphaPipe;
+    alphaBGL; // kept so the overlay buffer can grow and rebind on demand
     overlayBuf;
     overlayBG;
+    overlayCap = OVERLAY_CAP; // grows to fit — the overlay is no longer hard-capped
     overlayScratch = new Float32Array(OVERLAY_CAP * INST_F);
     overlayCount = 0;
+    overlayDeferred = false; // when true, frame() does NOT draw the overlay — the caller draws it via overlayPass()
     // GPU-driven culling: one compute pipeline; per-frustum (camera + light) indirect args + compacted visible lists.
     cullPipe;
     cullBGL;
@@ -473,7 +487,7 @@ export class GpuShadowRenderer {
         });
         // translucent overlay: alpha-blended, depth-tested but not depth-writing (drawn after opaque)
         const alphaMod = device.createShaderModule({ code: ALPHA_WGSL });
-        const alphaBGL = device.createBindGroupLayout({
+        const alphaBGL = (this.alphaBGL = device.createBindGroupLayout({
             entries: [
                 {
                     binding: 0,
@@ -486,7 +500,7 @@ export class GpuShadowRenderer {
                     buffer: { type: 'read-only-storage' },
                 },
             ],
-        });
+        }));
         this.alphaPipe = device.createRenderPipeline({
             layout: device.createPipelineLayout({ bindGroupLayouts: [alphaBGL] }),
             vertex: { module: alphaMod, entryPoint: 'vs' },
@@ -791,14 +805,67 @@ export class GpuShadowRenderer {
         this.device.queue.writeBuffer(this.instBuf, 0, this.scratch, 0, n * INST_F);
         this.count = n;
     }
-    /** Translucent overlay cubes drawn over the opaque scene each frame; `emissive` carries per-cube alpha. */
-    updateOverlay(instances) {
-        const n = Math.min(instances.length, OVERLAY_CAP);
-        this.fill(this.overlayScratch, instances, n);
+    /** Translucent overlay cubes drawn over the opaque scene; `emissive` carries per-cube alpha (0..1). The buffer
+     *  GROWS to fit (no hard cap). Pass `eye` to SORT the cubes back-to-front (farthest first) so overlapping
+     *  translucent cubes blend in the correct order — required for anything denser than the place ghost. By default
+     *  the cubes draw at the end of frame(); call deferOverlay(true) + overlayPass() to draw them after your own
+     *  transparent passes (e.g. water) so those don't paint over them. */
+    updateOverlay(instances, eye) {
+        let list = instances;
+        if (eye && instances.length > 1) {
+            // back-to-front: a nearer translucent cube must blend OVER a farther one, so draw the farthest first
+            list = instances
+                .map((c) => ({
+                c,
+                d: (c.x - eye[0]) * (c.x - eye[0]) +
+                    (c.y - eye[1]) * (c.y - eye[1]) +
+                    (c.z - eye[2]) * (c.z - eye[2]),
+            }))
+                .sort((a, b) => b.d - a.d)
+                .map((o) => o.c);
+        }
+        const n = list.length;
+        if (n > this.overlayCap) {
+            this.overlayCap = Math.ceil(n * 1.5);
+            this.overlayScratch = new Float32Array(this.overlayCap * INST_F);
+            this.overlayBuf.destroy();
+            this.overlayBuf = this.device.createBuffer({
+                size: this.overlayScratch.byteLength,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+            this.overlayBG = this.device.createBindGroup({
+                layout: this.alphaBGL,
+                entries: [
+                    { binding: 0, resource: { buffer: this.camBuf } },
+                    { binding: 1, resource: { buffer: this.overlayBuf } },
+                ],
+            });
+        }
+        this.fill(this.overlayScratch, list, n);
         if (n > 0)
             this.device.queue.writeBuffer(this.overlayBuf, 0, this.overlayScratch, 0, n * INST_F);
         this.overlayCount = n;
     }
+    /** Defer the translucent overlay out of frame() so the caller draws it via overlayPass() AFTER its own
+     *  transparent geometry (e.g. water). Otherwise those later passes paint over the overlay. */
+    deferOverlay(on) {
+        this.overlayDeferred = on;
+    }
+    /** Draw the translucent overlay in its own pass over `colorView`, depth-tested (read-only) against `depthView`
+     *  — same pipeline as the in-frame draw, just callable after other transparent passes. Pairs with
+     *  deferOverlay(true). No-op if the overlay is empty. */
+    overlayPass(enc, colorView, depthView) {
+        if (this.overlayCount === 0)
+            return;
+        const mp = enc.beginRenderPass({
+            colorAttachments: [{ view: colorView, loadOp: 'load', storeOp: 'store' }],
+            depthStencilAttachment: { view: depthView, depthReadOnly: true },
+        });
+        mp.setPipeline(this.alphaPipe);
+        mp.setBindGroup(0, this.overlayBG);
+        mp.draw(36, this.overlayCount);
+        mp.end();
+    }
     /** Write a frustum's cull uniform: 6 planes + count + this frustum's VP + occlusion params (occ on the camera pass). */
     writeCull(buf, vp, occlude) {
         const planes = frustumPlanes(vp);
@@ -914,11 +981,11 @@ export class GpuShadowRenderer {
         mp.setPipeline(this.mainPipe);
         mp.setBindGroup(0, this.mainBG);
         mp.drawIndirect(this.camArgs, 0);
-        if (this.overlayCount > 0) {
+        if (!this.overlayDeferred && this.overlayCount > 0) {
             mp.setPipeline(this.alphaPipe);
             mp.setBindGroup(0, this.overlayBG);
             mp.draw(36, this.overlayCount);
-        } // translucent overlay last (uncapped, no cull)
+        } // translucent overlay last (no cull) — unless deferred to overlayPass() (drawn after the caller's water etc.)
         mp.end();
         // Rebuild the coarse Hi-Z from the depth just written → next frame's cull uses it.
         if (occlusion) {

package/dist/input/browserBackend.js

@@ -12,6 +12,17 @@
 //   • touch: one finger = cursor (tap = place edge); two fingers = pan + pinch-zoom + twist.
 // ─────────────────────────────────────────────────────────────────────────────
 import { emptyFrame } from './resolve';
+// setPointerCapture throws InvalidStateError when a pointer-lock request is still in-flight or the pointerId is no
+// longer active. A failed capture only means an off-canvas drag won't keep tracking — never fatal — so swallow it
+// rather than let it bubble as an "Uncaught InvalidStateError".
+function safeCapture(el, pointerId) {
+    try {
+        el.setPointerCapture(pointerId);
+    }
+    catch {
+        /* pointer inactive or lock pending — capture simply doesn't apply this gesture */
+    }
+}
 export class BrowserRawBackend {
     keysDown = new Set();
     edges = new Set();
@@ -121,7 +132,7 @@ export class BrowserRawBackend {
                 this.touches.set(e.pointerId, { x: e.clientX, y: e.clientY, moved: 0 });
                 this.gPrev = this.touches.size === 2 ? this.gesture() : null;
                 if (!document.pointerLockElement)
-                    el.setPointerCapture(e.pointerId); // track gestures that leave the canvas
+                    safeCapture(el, e.pointerId); // track gestures that leave the canvas
             }
             else {
                 if (!this.pointerButtons.has(e.button))
@@ -130,8 +141,11 @@ export class BrowserRawBackend {
                 // Pointer LOCK and pointer CAPTURE are mutually-exclusive ways to route pointer input. Calling capture
                 // while lock is engaged/pending throws InvalidStateError (Firefox then never locks → no mouselook;
                 // Chrome logs it on every click while locked). So when the game wants mouselook use ONLY pointer lock;
-                // otherwise capture so a drag keeps tracking off-canvas. `document.pointerLockElement` is the guard that
-                // makes capture valid by construction — no try/catch needed.
+                // otherwise capture so a drag keeps tracking off-canvas. `document.pointerLockElement` narrows the window,
+                // but it's NOT sufficient: a click landing while a requestPointerLock() is still PENDING (lockElement is
+                // null but the browser has a lock in-flight), or on a pointerId the UA no longer considers active, still
+                // throws InvalidStateError — which surfaced as an "Uncaught InvalidStateError" in prod. `safeCapture`
+                // swallows it (a failed capture just means a drag won't track past the canvas edge — harmless).
                 if (this.pointerLock) {
                     if (!document.pointerLockElement)
                         void Promise.resolve(el.requestPointerLock()).catch(() => {
@@ -139,7 +153,7 @@ export class BrowserRawBackend {
                         });
                 }
                 else if (!document.pointerLockElement) {
-                    el.setPointerCapture(e.pointerId);
+                    safeCapture(el, e.pointerId);
                 }
             }
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-game",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "type": "module",
   "exports": {
     ".": {