ugly-game 0.5.8 → 0.5.10

package/dist/assets/gpuProps.d.ts

@@ -0,0 +1,29 @@
+export interface PropMesh {
+    positions: Float32Array;
+    normals: Float32Array;
+    colors: Float32Array;
+    indices: Uint32Array;
+}
+export interface PropInstance {
+    model: number;
+    mat: Float32Array;
+}
+export declare class GpuPropsRenderer {
+    private device;
+    private pipe;
+    private occPipe;
+    private uBuf;
+    private lightBuf;
+    private models;
+    private instBufs;
+    private bgs;
+    private occBGs;
+    private counts;
+    constructor(device: GPUDevice, format: GPUTextureFormat);
+    setModels(meshes: PropMesh[]): void;
+    /** Group instances by model and upload per-model transform buffers. */
+    setInstances(instances: PropInstance[]): void;
+    /** Occluder pass: draw all instanced props' depth into the shared shadow map from the sun's ortho view. */
+    shadowPass(pass: GPURenderPassEncoder, lightVP: Float32Array): void;
+    frame(enc: GPUCommandEncoder, colorView: GPUTextureView, depthView: GPUTextureView, camVP: Float32Array, sunDir: [number, number, number], sunCol: [number, number, number], amb: [number, number, number], camPos: [number, number, number], fog: [number, number, number], fogDensity: number): void;
+}

package/dist/assets/gpuProps.js

@@ -0,0 +1,147 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// GPU PROPS — instanced static-mesh renderer for scattered nature props (PLATFORM). Draws each cooked
+// model (tree/rock/bush/…) many times at per-instance world transforms, lit + fogged to match the
+// terrain. Runs in a load pass after the terrain so props depth-test against the surface.
+// ─────────────────────────────────────────────────────────────────────────────
+const SHADER = /* wgsl */ `
+struct U { mvp: mat4x4<f32>, sun: vec4<f32>, sunCol: vec4<f32>, amb: vec4<f32>, cam: vec4<f32>, fog: vec4<f32> };
+@group(0) @binding(0) var<uniform> u: U;
+@group(0) @binding(1) var<storage,read> models: array<mat4x4<f32>>;
+struct VO { @builtin(position) pos: vec4<f32>, @location(0) world: vec3<f32>, @location(1) n: vec3<f32>, @location(2) c: vec3<f32> };
+@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;
+}
+@fragment fn fs(i: VO) -> @location(0) vec4<f32> {
+  let d = clamp(dot(normalize(i.n), -normalize(u.sun.xyz)), 0.0, 1.0);
+  let lit = i.c * (u.amb.xyz + d * u.sunCol.xyz);
+  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).
+const OCCLUDER = /* wgsl */ `
+@group(0) @binding(0) var<uniform> lightVP: mat4x4<f32>;
+@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));
+}`;
+export class GpuPropsRenderer {
+    device;
+    pipe;
+    occPipe;
+    uBuf;
+    lightBuf;
+    models = [];
+    instBufs = [];
+    bgs = [];
+    occBGs = [];
+    counts = [];
+    constructor(device, format) {
+        this.device = device;
+        const sm = device.createShaderModule({ code: SHADER });
+        this.pipe = device.createRenderPipeline({
+            layout: 'auto',
+            vertex: { module: sm, entryPoint: 'vs', buffers: [
+                    { arrayStride: 12, attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }] },
+                    { arrayStride: 12, attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x3' }] },
+                    { arrayStride: 12, attributes: [{ shaderLocation: 2, offset: 0, format: 'float32x3' }] }
+                ] },
+            fragment: { module: sm, entryPoint: 'fs', targets: [{ format }] },
+            primitive: { topology: 'triangle-list', cullMode: 'none' },
+            depthStencil: { format: 'depth24plus', depthWriteEnabled: true, depthCompare: 'less' },
+        });
+        const om = device.createShaderModule({ code: OCCLUDER });
+        this.occPipe = device.createRenderPipeline({
+            layout: 'auto',
+            vertex: { module: om, entryPoint: 'vs', buffers: [{ arrayStride: 12, attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }] }] },
+            primitive: { topology: 'triangle-list', cullMode: 'none' },
+            depthStencil: { format: 'depth32float', depthWriteEnabled: true, depthCompare: 'less' },
+        });
+        this.uBuf = device.createBuffer({ size: 96 + 16 * 5, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.lightBuf = device.createBuffer({ size: 64, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    }
+    setModels(meshes) {
+        const dev = this.device, U = GPUBufferUsage;
+        for (const p of this.models) {
+            p.posB.destroy();
+            p.nrmB.destroy();
+            p.colB.destroy();
+            p.idxB.destroy();
+        }
+        const mk = (d, u) => { const b = dev.createBuffer({ size: d.byteLength, usage: u }); dev.queue.writeBuffer(b, 0, d); return b; };
+        this.models = meshes.map((m) => ({ posB: mk(m.positions, U.VERTEX | U.COPY_DST), nrmB: mk(m.normals, U.VERTEX | U.COPY_DST), colB: mk(m.colors, U.VERTEX | U.COPY_DST), idxB: mk(m.indices, U.INDEX | U.COPY_DST), idxCount: m.indices.length }));
+        this.instBufs = meshes.map(() => null);
+        this.bgs = meshes.map(() => null);
+        this.occBGs = meshes.map(() => null);
+        this.counts = meshes.map(() => 0);
+    }
+    /** Group instances by model and upload per-model transform buffers. */
+    setInstances(instances) {
+        const dev = this.device;
+        const byModel = this.models.map(() => []);
+        const data = this.models.map(() => []);
+        for (const it of instances) {
+            if (it.model < 0 || it.model >= this.models.length)
+                continue;
+            byModel[it.model].push(0);
+            for (let i = 0; i < 16; i++)
+                data[it.model].push(it.mat[i]);
+        }
+        for (let m = 0; m < this.models.length; m++) {
+            this.instBufs[m]?.destroy();
+            const arr = new Float32Array(data[m]);
+            this.counts[m] = byModel[m].length;
+            if (arr.length === 0) {
+                this.instBufs[m] = null;
+                this.bgs[m] = null;
+                this.occBGs[m] = null;
+                continue;
+            }
+            const b = dev.createBuffer({ size: arr.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+            dev.queue.writeBuffer(b, 0, arr);
+            this.instBufs[m] = b;
+            this.bgs[m] = dev.createBindGroup({ layout: this.pipe.getBindGroupLayout(0), entries: [{ binding: 0, resource: { buffer: this.uBuf } }, { binding: 1, resource: { buffer: b } }] });
+            this.occBGs[m] = dev.createBindGroup({ layout: this.occPipe.getBindGroupLayout(0), entries: [{ binding: 0, resource: { buffer: this.lightBuf } }, { binding: 1, resource: { buffer: b } }] });
+        }
+    }
+    /** 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);
+        pass.setPipeline(this.occPipe);
+        for (let m = 0; m < this.models.length; m++) {
+            const bg = this.occBGs[m], mdl = this.models[m];
+            if (!bg || this.counts[m] === 0)
+                continue;
+            pass.setBindGroup(0, bg);
+            pass.setVertexBuffer(0, mdl.posB);
+            pass.setIndexBuffer(mdl.idxB, 'uint32');
+            pass.drawIndexed(mdl.idxCount, this.counts[m]);
+        }
+    }
+    frame(enc, colorView, depthView, camVP, sunDir, sunCol, amb, camPos, fog, fogDensity) {
+        const u = new Float32Array(24 + 20);
+        u.set(camVP, 0);
+        u.set([sunDir[0], sunDir[1], sunDir[2], 0], 16);
+        u.set([sunCol[0], sunCol[1], sunCol[2], 0], 20);
+        u.set([amb[0], amb[1], amb[2], 0], 24);
+        u.set([camPos[0], camPos[1], camPos[2], 0], 28);
+        u.set([fog[0], fog[1], fog[2], fogDensity], 32);
+        this.device.queue.writeBuffer(this.uBuf, 0, u);
+        const rp = enc.beginRenderPass({ colorAttachments: [{ view: colorView, loadOp: 'load', storeOp: 'store' }], depthStencilAttachment: { view: depthView, depthLoadOp: 'load', depthStoreOp: 'store' } });
+        rp.setPipeline(this.pipe);
+        for (let m = 0; m < this.models.length; m++) {
+            const bg = this.bgs[m], mdl = this.models[m];
+            if (!bg || this.counts[m] === 0)
+                continue;
+            rp.setBindGroup(0, bg);
+            rp.setVertexBuffer(0, mdl.posB);
+            rp.setVertexBuffer(1, mdl.nrmB);
+            rp.setVertexBuffer(2, mdl.colB);
+            rp.setIndexBuffer(mdl.idxB, 'uint32');
+            rp.drawIndexed(mdl.idxCount, this.counts[m]);
+        }
+        rp.end();
+    }
+}

package/dist/gpuShadow.d.ts

@@ -8,6 +8,19 @@ export interface CubeInstance {
     hue: number;
     emissive?: number;
     rot?: [number, number, number, number];
+    tile?: number;
+    up?: number;
+}
+/** Atlas layout: which grid tiles a material's top/side/bottom faces sample. Grid indices into a cols×rows atlas. */
+export interface AtlasLayout {
+    tileSize: number;
+    cols: number;
+    rows: number;
+    tiles: Record<number, {
+        top: number;
+        side: number;
+        bottom: number;
+    }>;
 }
 /** The 36-vertex cube as WGSL array-literal bodies (pos + per-face normal). Shared by shadow modules. */
 export declare const CUBE: {
@@ -29,6 +42,10 @@ export declare class GpuShadowRenderer {
     private shadowSampler;
     private count;
     private cam;
+    private atlasView;
+    private atlasSampler;
+    private tileRectBuf;
+    private useAtlas;
     private alphaPipe;
     private overlayBuf;
     private overlayBG;
@@ -52,12 +69,28 @@ export declare class GpuShadowRenderer {
         camVisible: number;
         lightVisible: number;
     };
+    private hizPipe;
+    private hizBGL;
+    private hizTex;
+    private hizView;
+    private hizParam;
+    private hizW;
+    private hizH;
+    private hizReady;
+    private occView;
     constructor(device: GPUDevice, format: GPUTextureFormat);
     private makeCullBuf;
+    private cullBG;
     private makeCullResources;
+    /** (Re)create the coarse Hi-Z for a `w×h` depth target and rebind the cull groups to it. Idempotent per size. */
+    private ensureHiZ;
     private scratch;
     private fill;
     private makeBindGroups;
+    /** Bind a block-texture atlas + its material→tile layout. Each material's top/side/bottom faces sample distinct
+     *  atlas tiles; a `CubeInstance.tile` of that material id + its `up`-face code selects the right tile in-shader.
+     *  Call once after the atlas texture is uploaded; instances with `tile < 0` still use the flat hue path. */
+    setAtlas(tex: GPUTexture, layout: AtlasLayout): void;
     /** Static scene: sizes the buffer to exactly these instances. */
     setScene(instances: CubeInstance[]): void;
     /** Dynamic scene: pre-allocate for `cap` instances; call updateInstances() each frame. */
@@ -65,10 +98,16 @@ export declare class GpuShadowRenderer {
     updateInstances(instances: CubeInstance[]): void;
     /** Translucent overlay cubes drawn over the opaque scene each frame; `emissive` carries per-cube alpha. */
     updateOverlay(instances: CubeInstance[]): void;
-    /** Write a frustum's cull uniform: 6 Gribb-Hartmann planes from `vp` + the live instance count. */
+    /** Write a frustum's cull uniform: 6 planes + count + this frustum's VP + occlusion params (occ on the camera pass). */
     private writeCull;
-    /** camVP/lightVP: column-major Float32Array(16). sunDir: travel direction. */
-    frame(enc: GPUCommandEncoder, colorView: GPUTextureView, sceneDepth: GPUTextureView, camVP: Float32Array, lightVP: Float32Array, sunDir: [number, number, number], sunCol: [number, number, number], ambient: number, load?: boolean): void;
+    /** camVP/lightVP: column-major Float32Array(16). sunDir: travel direction. Pass `occlusion` (the depth target +
+     *  its size) to enable Hi-Z occlusion culling on the camera pass — the renderer rebuilds a coarse Hi-Z from that
+     *  depth each frame and the NEXT frame's cull uses it (hole-free: the first frame + any resize skip occlusion). */
+    frame(enc: GPUCommandEncoder, colorView: GPUTextureView, sceneDepth: GPUTextureView, camVP: Float32Array, lightVP: Float32Array, sunDir: [number, number, number], sunCol: [number, number, number], ambient: number, load?: boolean, occlusion?: {
+        depth: GPUTextureView;
+        w: number;
+        h: number;
+    }, tint?: [number, number, number, number], extraShadow?: (sp: GPURenderPassEncoder, lightVP: Float32Array) => void): void;
     /** Read back the last frame's GPU cull result (camera-visible, light-visible). Does its OWN copy+submit so it's
      *  safe to call from a live render loop (no per-frame readback cost, no race with the ongoing frames). IR/tests. */
     readCullStats(): Promise<{

package/dist/gpuShadow.js

@@ -14,6 +14,7 @@
 import { frustumPlanes } from './mat4';
 const SHADOW_SIZE = 2048;
 const CULL_WG = 64; // compute-cull workgroup size
+const INST_F = 16; // floats per instance: pos.xyz+hue, scl.xyz+emissive, rot quat, aux (tile,up,_,_)
 const OVERLAY_CAP = 512; // max translucent overlay cubes per frame (the place ghost + headroom)
 // Build the 36-vertex cube (6 faces × 2 tris) in JS and inject as WGSL const arrays —
 // bulletproof + readable vs. bit-twiddling from vertex_index. cullMode is 'none', so winding
@@ -48,8 +49,10 @@ struct Cam {
   lightVP: mat4x4<f32>,
   sun: vec4<f32>,      // xyz = direction light travels, w = ambient
   sunCol: vec4<f32>,   // xyz = sun colour, w = shadow map size (texels)
+  tint: vec4<f32>,     // rgb = per-planet tint · w = tint strength (0 = none)
+  atlas: vec4<f32>,    // x = useAtlas (1/0)
 };
-struct Inst { pos: vec4<f32>, scl: vec4<f32>, rot: vec4<f32> };  // pos.w = hue (<0 ⇒ ground) · scl.w = emissive/alpha · rot = quaternion
+struct Inst { pos: vec4<f32>, scl: vec4<f32>, rot: vec4<f32>, aux: vec4<f32> };  // pos.w = hue (<0 ⇒ ground) · scl.w = emissive/alpha · rot = quaternion · aux.x = atlas tile (<0 ⇒ hue) · aux.y = up-face code
 @group(0) @binding(0) var<uniform> cam: Cam;
 @group(0) @binding(1) var<storage, read> insts: array<Inst>;
 
@@ -77,14 +80,25 @@ fn hsv(hh: f32) -> vec3<f32> {
 // instance quaternion). This is exact for any size/aspect/rotation — critical because a bounding SPHERE from the
 // centre wrongly culls a big flat cube (a ground plane whose centre sits far behind the camera while the ground
 // underfoot is plainly in view). Mirrors gpuDriven.ts; validated against a CPU box-vs-plane oracle.
+// 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.
 const CULL_WGSL = /* wgsl */ `
-struct Inst { pos: vec4<f32>, scl: vec4<f32>, rot: vec4<f32> };
+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 };
-struct CullCam { planes: array<vec4<f32>, 6>, cnt: vec4<f32> };   // cnt.x = instance count
+struct CullCam {
+  planes: array<vec4<f32>, 6>, cnt: vec4<f32>,   // cnt.x = instance count
+  camVP: mat4x4<f32>, occ: vec4<f32>,            // occ.x = occlusion on · occ.yz = hiz w,h · occ.w = downscale
+};
 @group(0) @binding(0) var<storage, read> insts: array<Inst>;
 @group(0) @binding(1) var<storage, read_write> args: Args;
 @group(0) @binding(2) var<storage, read_write> visible: array<u32>;
 @group(0) @binding(3) var<uniform> cc: CullCam;
+@group(0) @binding(4) var hiz: texture_2d<f32>;
 fn qr(q: vec4<f32>, v: vec3<f32>) -> vec3<f32> { let t = 2.0 * cross(q.xyz, v); return v + q.w * t + cross(q.xyz, t); }
 @compute @workgroup_size(${CULL_WG})
 fn cull(@builtin(global_invocation_id) gid: vec3<u32>) {
@@ -101,10 +115,65 @@ fn cull(@builtin(global_invocation_id) gid: vec3<u32>) {
     let e = abs(dot(pl.xyz, bx)) + abs(dot(pl.xyz, by)) + abs(dot(pl.xyz, bz));   // box half-width along the normal
     if (dot(pl.xyz, c) + pl.w < -e) { return; }
   }
+  // ── Hi-Z occlusion (camera pass only) ──
+  if (cc.occ.x > 0.5) {
+    var mn = vec2<f32>(1e9, 1e9);
+    var mx = vec2<f32>(-1e9, -1e9);
+    var nearZ = 1e9;
+    var ok = true;
+    for (var ci = 0u; ci < 8u; ci++) {
+      let s = vec3<f32>(select(-1.0, 1.0, (ci & 1u) != 0u), select(-1.0, 1.0, (ci & 2u) != 0u), select(-1.0, 1.0, (ci & 4u) != 0u));
+      let corner = c + bx * s.x + by * s.y + bz * s.z;
+      let clip = cc.camVP * vec4<f32>(corner, 1.0);
+      if (clip.w <= 0.0) { ok = false; break; }        // a corner at/behind the eye → don't occlusion-cull (keep)
+      let ndc = clip.xyz / clip.w;
+      let uv = ndc.xy * vec2<f32>(0.5, -0.5) + vec2<f32>(0.5, 0.5);
+      mn = min(mn, uv); mx = max(mx, uv);
+      nearZ = min(nearZ, ndc.z);
+    }
+    if (ok && nearZ >= 0.0) {
+      let dim = vec2<f32>(cc.occ.y, cc.occ.z);
+      let t0 = vec2<i32>(floor(clamp(mn, vec2<f32>(0.0), vec2<f32>(1.0)) * dim));
+      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) {
+        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++) {
+            farOccluder = max(farOccluder, textureLoad(hiz, vec2<i32>(x, y), 0).r);
+          }
+        }
+        if (nearZ > farOccluder) { return; }            // behind the farthest occluder everywhere → occluded
+      }
+    }
+  }
   let slot = atomicAdd(&args.ic, 1u);
   visible[slot] = i;
 }
 `;
+// Hi-Z BUILD: max-reduce the previous frame's depth (a sampleable depth texture) into a coarse R32float buffer —
+// each output texel = the FARTHEST (max) NDC depth over its `down`×`down` source block, so "cube behind this" is a
+// safe occlusion test. depth24plus reads as a depth texture; textureLoad returns the stored [0,1] depth.
+const HIZ_WGSL = /* wgsl */ `
+@group(0) @binding(0) var srcDepth: texture_depth_2d;
+@group(0) @binding(1) var dst: texture_storage_2d<r32float, write>;
+struct P { dim: vec4<u32> };   // dim.xy = dst size, dim.zw = src size
+@group(0) @binding(2) var<uniform> p: P;
+@compute @workgroup_size(8, 8)
+fn build(@builtin(global_invocation_id) gid: vec3<u32>) {
+  if (gid.x >= p.dim.x || gid.y >= p.dim.y) { return; }
+  let down = 8u;
+  var mx = 0.0;
+  for (var dy = 0u; dy < down; dy++) {
+    for (var dx = 0u; dx < down; dx++) {
+      let sx = gid.x * down + dx; let sy = gid.y * down + dy;
+      if (sx < p.dim.z && sy < p.dim.w) { mx = max(mx, textureLoad(srcDepth, vec2<i32>(i32(sx), i32(sy)), 0)); }
+    }
+  }
+  textureStore(dst, vec2<i32>(i32(gid.x), i32(gid.y)), vec4<f32>(mx, 0.0, 0.0, 1.0));
+}
+`;
+const HIZ_DOWN = 8; // source pixels per Hi-Z texel (coarse ⇒ conservative, cheap)
 const SHADOW_WGSL = COMMON_WGSL + /* wgsl */ `
 @group(0) @binding(2) var<storage, read> vis: array<u32>;
 @vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> @builtin(position) vec4<f32> {
@@ -115,8 +184,18 @@ const MAIN_WGSL = COMMON_WGSL + /* wgsl */ `
 @group(0) @binding(2) var shadowMap: texture_depth_2d;
 @group(0) @binding(3) var shadowSamp: sampler_comparison;
 @group(0) @binding(4) var<storage, read> vis: array<u32>;
+@group(0) @binding(5) var atlasTex: texture_2d<f32>;
+@group(0) @binding(6) var atlasSamp: sampler;
+@group(0) @binding(7) var<storage, read> tileRects: array<vec4<f32>>;   // [u0,v0,du,dv] per (material*3 + face-variant)
 
-struct VOut { @builtin(position) clip: vec4<f32>, @location(0) world: vec3<f32>, @location(1) nrm: vec3<f32>, @location(2) hue: f32, @location(3) emis: f32, @location(4) blk: vec3<f32>, @location(5) objN: vec3<f32> };
+struct VOut { @builtin(position) clip: vec4<f32>, @location(0) world: vec3<f32>, @location(1) nrm: vec3<f32>, @location(2) hue: f32, @location(3) emis: f32, @location(4) blk: vec3<f32>, @location(5) objN: vec3<f32>, @location(6) tile: f32, @location(7) upc: f32 };
+
+fn faceVec(code: f32) -> vec3<f32> {
+  let c = i32(code);
+  if (c == 0) { return vec3(1.,0.,0.); } if (c == 1) { return vec3(-1.,0.,0.); }
+  if (c == 2) { return vec3(0.,1.,0.); } if (c == 3) { return vec3(0.,-1.,0.); }
+  if (c == 4) { return vec3(0.,0.,1.); } return vec3(0.,0.,-1.);
+}
 
 @vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VOut {
   let inst = insts[vis[ii]];
@@ -132,6 +211,7 @@ struct VOut { @builtin(position) clip: vec4<f32>, @location(0) world: vec3<f32>,
   // by inst.scl so a merged LOD cube (scl>1) still shows its sub-blocks. objN = pre-rotation face normal.
   o.blk = (CUBE_POS[vi] + vec3(0.5, 0.5, 0.5)) * inst.scl.xyz;
   o.objN = CUBE_NRM[vi];
+  o.tile = inst.aux.x; o.upc = inst.aux.y;
   return o;
 }
 
@@ -166,7 +246,6 @@ fn blockShade(fx: f32, fz: f32) -> f32 {
   }
   let N = normalize(i.nrm);
   let ndl = max(dot(N, -normalize(cam.sun.xyz)), 0.0);
-  let base = select(mix(vec3(0.34), hsv(i.hue), 0.62), vec3(0.6, 0.62, 0.66), i.hue < 0.0);
   let sh = shadowFactor(i.world, ndl);
   // in-block coords = the two OBJECT axes not along the (object-space, axis-aligned) face normal — so the AO
   // pattern is anchored to the model's own block grid and translates/rotates with the instance.
@@ -175,6 +254,16 @@ fn blockShade(fx: f32, fz: f32) -> f32 {
   if (an.y >= an.x && an.y >= an.z) { fx = fract(i.blk.x); fz = fract(i.blk.z); }
   else if (an.x >= an.z) { fx = fract(i.blk.y); fz = fract(i.blk.z); }
   else { fx = fract(i.blk.x); fz = fract(i.blk.y); }
+  var base = select(mix(vec3(0.34), hsv(i.hue), 0.62), vec3(0.6, 0.62, 0.66), i.hue < 0.0);
+  if (cam.atlas.x > 0.5 && i.tile >= 0.0) {   // ATLAS: pick top/side/bottom tile from the face vs the up axis, tile the AO in-face coords
+    let d = dot(i.objN, faceVec(i.upc));
+    var variant = 1u;                          // side
+    if (d > 0.5) { variant = 0u; } else if (d < -0.5) { variant = 2u; }
+    let rect = tileRects[u32(i.tile) * 3u + variant];
+    let uv = rect.xy + fract(vec2(fx, fz)) * rect.zw;
+    let texc = textureSampleLevel(atlasTex, atlasSamp, uv, 0.0).rgb;   // explicit LOD (early-return above makes control flow non-uniform)
+    base = mix(texc, texc * cam.tint.rgb, cam.tint.w);                 // per-planet tint
+  }
   let ao = blockShade(fx, fz);
   let lit = base * (cam.sun.w + cam.sunCol.xyz * ndl * sh) * ao;
   return vec4(pow(clamp(lit, vec3(0.0), vec3(1.0)), vec3(0.4545)), 1.0);  // gamma
@@ -211,11 +300,15 @@ export class GpuShadowRenderer {
     mainBGL;
     shadowSampler;
     count = 0;
-    cam = new Float32Array(40); // 2×mat4 + 2×vec4
+    cam = new Float32Array(48); // 2×mat4 + sun + sunCol + tint + atlas
+    atlasView;
+    atlasSampler;
+    tileRectBuf;
+    useAtlas = 0;
     alphaPipe;
     overlayBuf;
     overlayBG;
-    overlayScratch = new Float32Array(OVERLAY_CAP * 12);
+    overlayScratch = new Float32Array(OVERLAY_CAP * INST_F);
     overlayCount = 0;
     // GPU-driven culling: one compute pipeline; per-frustum (camera + light) indirect args + compacted visible lists.
     cullPipe;
@@ -232,6 +325,16 @@ export class GpuShadowRenderer {
     statsBuf; // readback: [camVisible, lightVisible] for the IR/tests
     /** Last frame's visible counts (main-pass camera cull, shadow-pass light cull) + total — for IR/telemetry. */
     lastCull = { total: 0, camVisible: 0, lightVisible: 0 };
+    // Hi-Z OCCLUSION: a coarse max-depth buffer rebuilt from each frame's depth, sampled by next frame's camera cull.
+    hizPipe;
+    hizBGL;
+    hizTex;
+    hizView;
+    hizParam;
+    hizW = 0;
+    hizH = 0;
+    hizReady = false; // a Hi-Z from a prior frame exists → safe to occlusion-test (false on frame 1 + resize)
+    occView; // the texture bound at cull binding 4 (a 1×1 dummy until occlusion is used)
     constructor(device, format) {
         this.device = device;
         this.camBuf = device.createBuffer({ size: this.cam.byteLength, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
@@ -256,6 +359,9 @@ export class GpuShadowRenderer {
                 { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'depth' } },
                 { binding: 3, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'comparison' } },
                 { binding: 4, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } }, // camera-visible list
+                { binding: 5, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } }, // block atlas
+                { binding: 6, visibility: GPUShaderStage.FRAGMENT, sampler: {} }, // atlas sampler
+                { binding: 7, visibility: GPUShaderStage.FRAGMENT, buffer: { type: 'read-only-storage' } }, // per-tile UV rects
             ] });
         this.mainPipe = device.createRenderPipeline({
             layout: device.createPipelineLayout({ bindGroupLayouts: [mainBGL] }),
@@ -293,43 +399,81 @@ export class GpuShadowRenderer {
                 { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'read-only-storage' } }, // insts
                 { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } }, // args (atomic ic)
                 { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } }, // visible list
-                { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'uniform' } }, // planes + count
+                { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'uniform' } }, // planes + count + camVP + occ
+                { binding: 4, visibility: GPUShaderStage.COMPUTE, texture: { sampleType: 'unfilterable-float' } }, // Hi-Z (dummy until occlusion is used)
             ] });
         this.cullPipe = device.createComputePipeline({
             layout: device.createPipelineLayout({ bindGroupLayouts: [this.cullBGL] }),
             compute: { module: cullMod, entryPoint: 'cull' },
         });
+        // Hi-Z occlusion build pipeline + a 1×1 dummy Hi-Z (bound when occlusion is off, never sampled)
+        const hizMod = device.createShaderModule({ code: HIZ_WGSL });
+        this.hizBGL = device.createBindGroupLayout({ entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, texture: { sampleType: 'depth' } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, storageTexture: { access: 'write-only', format: 'r32float' } },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'uniform' } },
+            ] });
+        this.hizPipe = device.createComputePipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.hizBGL] }),
+            compute: { module: hizMod, entryPoint: 'build' },
+        });
+        this.hizParam = device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        const dummy = device.createTexture({ size: [1, 1], format: 'r32float', usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING });
+        this.occView = dummy.createView();
+        // atlas dummies (bound until setAtlas): a 1×1 white texture + a 1-entry rect buffer + a plain sampler
+        const white = device.createTexture({ size: [1, 1], format: 'rgba8unorm', usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST });
+        device.queue.writeTexture({ texture: white }, new Uint8Array([255, 255, 255, 255]), {}, [1, 1]);
+        this.atlasView = white.createView();
+        this.atlasSampler = device.createSampler({ magFilter: 'nearest', minFilter: 'linear', mipmapFilter: 'linear' });
+        this.tileRectBuf = device.createBuffer({ size: 16, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
     }
     // One frustum's cull resources: indirect args (drawIndirect), a compacted visible-index list sized to the
-    // instance capacity, and a small uniform holding the 6 planes + the live instance count.
+    // instance capacity, and a uniform holding the 6 planes + instance count + camVP + occlusion params.
     makeCullBuf() {
         const d = this.device;
         const args = d.createBuffer({ size: 4 * 4, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC });
         const vis = d.createBuffer({ size: Math.max(1, this.cap) * 4, usage: GPUBufferUsage.STORAGE });
-        const cull = d.createBuffer({ size: 6 * 16 + 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
-        const bg = d.createBindGroup({ layout: this.cullBGL, entries: [
+        const cull = d.createBuffer({ size: 6 * 16 + 16 + 64 + 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST }); // planes+cnt+camVP+occ = 192
+        return { args, vis, cull };
+    }
+    cullBG(args, vis, cull) {
+        return this.device.createBindGroup({ layout: this.cullBGL, entries: [
                 { binding: 0, resource: { buffer: this.instBuf } }, { binding: 1, resource: { buffer: args } },
-                { binding: 2, resource: { buffer: vis } }, { binding: 3, resource: { buffer: cull } }
+                { binding: 2, resource: { buffer: vis } }, { binding: 3, resource: { buffer: cull } },
+                { binding: 4, resource: this.occView }
             ] });
-        return { args, vis, cull, bg };
     }
     makeCullResources() {
         const cam = this.makeCullBuf();
         this.camArgs = cam.args;
         this.camVis = cam.vis;
         this.camCull = cam.cull;
-        this.camCullBG = cam.bg;
         const lit = this.makeCullBuf();
         this.lightArgs = lit.args;
         this.lightVis = lit.vis;
         this.lightCull = lit.cull;
-        this.lightCullBG = lit.bg;
+        this.camCullBG = this.cullBG(this.camArgs, this.camVis, this.camCull);
+        this.lightCullBG = this.cullBG(this.lightArgs, this.lightVis, this.lightCull);
         this.statsBuf = this.device.createBuffer({ size: 4 * 4 * 2, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
     }
+    /** (Re)create the coarse Hi-Z for a `w×h` depth target and rebind the cull groups to it. Idempotent per size. */
+    ensureHiZ(w, h) {
+        const hw = Math.max(1, Math.ceil(w / HIZ_DOWN)), hh = Math.max(1, Math.ceil(h / HIZ_DOWN));
+        if (this.hizTex && this.hizW === hw && this.hizH === hh)
+            return;
+        this.hizW = hw;
+        this.hizH = hh;
+        this.hizReady = false; // fresh texture is uninitialized → skip occlusion until it's built once
+        this.hizTex = this.device.createTexture({ size: [hw, hh], format: 'r32float', usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING });
+        this.hizView = this.hizTex.createView();
+        this.occView = this.hizView; // the cull now samples the real Hi-Z
+        this.camCullBG = this.cullBG(this.camArgs, this.camVis, this.camCull);
+        this.lightCullBG = this.cullBG(this.lightArgs, this.lightVis, this.lightCull);
+    }
     scratch = new Float32Array(0);
     fill(scratch, instances, n) {
         for (let i = 0; i < n; i++) {
-            const c = instances[i], o = i * 12, r = c.rot;
+            const c = instances[i], o = i * INST_F, r = c.rot;
             scratch[o] = c.x;
             scratch[o + 1] = c.y;
             scratch[o + 2] = c.z;
@@ -342,6 +486,10 @@ export class GpuShadowRenderer {
             scratch[o + 9] = r ? r[1] : 0;
             scratch[o + 10] = r ? r[2] : 0;
             scratch[o + 11] = r ? r[3] : 1; // quaternion, default identity
+            scratch[o + 12] = c.tile ?? -1;
+            scratch[o + 13] = c.up ?? 1;
+            scratch[o + 14] = 0;
+            scratch[o + 15] = 0; // aux: atlas tile id + up-face code
         }
     }
     makeBindGroups() {
@@ -354,13 +502,37 @@ export class GpuShadowRenderer {
                 { binding: 0, resource: { buffer: this.camBuf } }, { binding: 1, resource: { buffer: this.instBuf } },
                 { binding: 2, resource: this.shadowView }, { binding: 3, resource: this.shadowSampler },
                 { binding: 4, resource: { buffer: this.camVis } },
+                { binding: 5, resource: this.atlasView }, { binding: 6, resource: this.atlasSampler }, { binding: 7, resource: { buffer: this.tileRectBuf } },
             ] });
     }
+    /** Bind a block-texture atlas + its material→tile layout. Each material's top/side/bottom faces sample distinct
+     *  atlas tiles; a `CubeInstance.tile` of that material id + its `up`-face code selects the right tile in-shader.
+     *  Call once after the atlas texture is uploaded; instances with `tile < 0` still use the flat hue path. */
+    setAtlas(tex, layout) {
+        this.atlasView = tex.createView();
+        const ids = Object.keys(layout.tiles).map(Number);
+        const maxMat = (ids.length ? Math.max(...ids) : 0) + 1;
+        const rects = new Float32Array(maxMat * 3 * 4);
+        const rectOf = (g) => {
+            const cx = g % layout.cols, cy = Math.floor(g / layout.cols);
+            return [cx / layout.cols, cy / layout.rows, 1 / layout.cols, 1 / layout.rows];
+        };
+        for (const [mat, f] of Object.entries(layout.tiles)) {
+            const b = Number(mat) * 3 * 4;
+            rects.set(rectOf(f.top), b);
+            rects.set(rectOf(f.side), b + 4);
+            rects.set(rectOf(f.bottom), b + 8);
+        }
+        this.tileRectBuf = this.device.createBuffer({ size: Math.max(16, rects.byteLength), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+        this.device.queue.writeBuffer(this.tileRectBuf, 0, rects);
+        this.useAtlas = 1;
+        this.makeBindGroups(); // rebind the main pass with the real atlas + rects
+    }
     /** Static scene: sizes the buffer to exactly these instances. */
     setScene(instances) {
         this.count = instances.length;
         this.cap = this.count;
-        this.scratch = new Float32Array(this.count * 12);
+        this.scratch = new Float32Array(this.count * INST_F);
         this.fill(this.scratch, instances, this.count);
         this.instBuf = this.device.createBuffer({ size: this.scratch.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
         this.device.queue.writeBuffer(this.instBuf, 0, this.scratch);
@@ -369,15 +541,15 @@ export class GpuShadowRenderer {
     /** Dynamic scene: pre-allocate for `cap` instances; call updateInstances() each frame. */
     setCapacity(cap) {
         this.cap = cap;
-        this.scratch = new Float32Array(cap * 12);
+        this.scratch = new Float32Array(cap * INST_F);
         this.instBuf = this.device.createBuffer({ size: this.scratch.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
         this.count = 0;
         this.makeBindGroups();
     }
     updateInstances(instances) {
-        const n = Math.min(instances.length, this.scratch.length / 12);
+        const n = Math.min(instances.length, this.scratch.length / INST_F);
         this.fill(this.scratch, instances, n);
-        this.device.queue.writeBuffer(this.instBuf, 0, this.scratch, 0, n * 12);
+        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. */
@@ -385,13 +557,13 @@ export class GpuShadowRenderer {
         const n = Math.min(instances.length, OVERLAY_CAP);
         this.fill(this.overlayScratch, instances, n);
         if (n > 0)
-            this.device.queue.writeBuffer(this.overlayBuf, 0, this.overlayScratch, 0, n * 12);
+            this.device.queue.writeBuffer(this.overlayBuf, 0, this.overlayScratch, 0, n * INST_F);
         this.overlayCount = n;
     }
-    /** Write a frustum's cull uniform: 6 Gribb-Hartmann planes from `vp` + the live instance count. */
-    writeCull(buf, vp) {
+    /** 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);
-        const u = new Float32Array(6 * 4 + 4);
+        const u = new Float32Array(48); // planes[24] + cnt[4] + camVP[16] + occ[4]
         for (let p = 0; p < 6; p++) {
             u[p * 4] = planes[p][0];
             u[p * 4 + 1] = planes[p][1];
@@ -399,10 +571,17 @@ export class GpuShadowRenderer {
             u[p * 4 + 3] = planes[p][3];
         }
         u[24] = this.count;
+        u.set(vp, 28); // camVP
+        u[44] = occlude ? 1 : 0;
+        u[45] = this.hizW;
+        u[46] = this.hizH;
+        u[47] = HIZ_DOWN;
         this.device.queue.writeBuffer(buf, 0, u);
     }
-    /** camVP/lightVP: column-major Float32Array(16). sunDir: travel direction. */
-    frame(enc, colorView, sceneDepth, camVP, lightVP, sunDir, sunCol, ambient, load = false) {
+    /** camVP/lightVP: column-major Float32Array(16). sunDir: travel direction. Pass `occlusion` (the depth target +
+     *  its size) to enable Hi-Z occlusion culling on the camera pass — the renderer rebuilds a coarse Hi-Z from that
+     *  depth each frame and the NEXT frame's cull uses it (hole-free: the first frame + any resize skip occlusion). */
+    frame(enc, colorView, sceneDepth, camVP, lightVP, sunDir, sunCol, ambient, load = false, occlusion, tint = [1, 1, 1, 0], extraShadow) {
         this.cam.set(camVP, 0);
         this.cam.set(lightVP, 16);
         this.cam[32] = sunDir[0];
@@ -413,15 +592,23 @@ export class GpuShadowRenderer {
         this.cam[37] = sunCol[1];
         this.cam[38] = sunCol[2];
         this.cam[39] = SHADOW_SIZE;
+        this.cam[40] = tint[0];
+        this.cam[41] = tint[1];
+        this.cam[42] = tint[2];
+        this.cam[43] = tint[3];
+        this.cam[44] = this.useAtlas;
         this.device.queue.writeBuffer(this.camBuf, 0, this.cam);
+        if (occlusion)
+            this.ensureHiZ(occlusion.w, occlusion.h);
+        const occludeNow = !!occlusion && this.hizReady; // only once a Hi-Z from a prior frame exists (never on frame 1/resize)
         // GPU-DRIVEN CULL: reset each frustum's indirect args ([vertexCount=36, instanceCount=0, 0, 0]), then compute-cull
-        // — main pass vs the camera frustum, shadow pass vs the light frustum. Each dispatch atomically compacts its
-        // survivors into a visible list + counts them in instanceCount, which the matching drawIndirect then consumes.
+        // — main pass vs the camera frustum (+ Hi-Z occlusion), shadow pass vs the light frustum. Each dispatch atomically
+        // compacts its survivors into a visible list + counts them in instanceCount, which the matching drawIndirect consumes.
         const resetArgs = new Uint32Array([36, 0, 0, 0]);
         this.device.queue.writeBuffer(this.camArgs, 0, resetArgs);
         this.device.queue.writeBuffer(this.lightArgs, 0, resetArgs);
-        this.writeCull(this.camCull, camVP);
-        this.writeCull(this.lightCull, lightVP);
+        this.writeCull(this.camCull, camVP, occludeNow);
+        this.writeCull(this.lightCull, lightVP, false);
         if (this.count > 0) {
             const cp = enc.beginComputePass();
             cp.setPipeline(this.cullPipe);
@@ -438,8 +625,10 @@ export class GpuShadowRenderer {
         sp.setPipeline(this.shadowPipe);
         sp.setBindGroup(0, this.shadowBG);
         sp.drawIndirect(this.lightArgs, 0);
+        if (extraShadow)
+            extraShadow(sp, lightVP); // let the app cast extra occluders (mesh props/trees) into the same sun shadow map
         sp.end();
-        // Pass 2: camera, shadow-sampled (camera-frustum-culled).
+        // Pass 2: camera, shadow-sampled (camera-frustum + Hi-Z-occlusion-culled).
         const mp = enc.beginRenderPass({
             colorAttachments: [{ view: colorView, ...(load ? { loadOp: 'load' } : { clearValue: { r: 0.04, g: 0.05, b: 0.07, a: 1 }, loadOp: 'clear' }), storeOp: 'store' }],
             depthStencilAttachment: { view: sceneDepth, ...(load ? { depthLoadOp: 'load' } : { depthClearValue: 1.0, depthLoadOp: 'clear' }), depthStoreOp: 'store' }
@@ -453,6 +642,19 @@ export class GpuShadowRenderer {
             mp.draw(36, this.overlayCount);
         } // translucent overlay last (uncapped, no cull)
         mp.end();
+        // Rebuild the coarse Hi-Z from the depth just written → next frame's cull uses it.
+        if (occlusion) {
+            this.device.queue.writeBuffer(this.hizParam, 0, new Uint32Array([this.hizW, this.hizH, occlusion.w, occlusion.h]));
+            const bg = this.device.createBindGroup({ layout: this.hizBGL, entries: [
+                    { binding: 0, resource: occlusion.depth }, { binding: 1, resource: this.hizView }, { binding: 2, resource: { buffer: this.hizParam } }
+                ] });
+            const hp = enc.beginComputePass();
+            hp.setPipeline(this.hizPipe);
+            hp.setBindGroup(0, bg);
+            hp.dispatchWorkgroups(Math.ceil(this.hizW / 8), Math.ceil(this.hizH / 8));
+            hp.end();
+            this.hizReady = true;
+        }
         this.lastCull.total = this.count;
     }
     /** Read back the last frame's GPU cull result (camera-visible, light-visible). Does its OWN copy+submit so it's

package/package.json

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