ugly-game 0.5.9 → 0.5.11

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;
@@ -70,6 +87,10 @@ export declare class GpuShadowRenderer {
     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. */
@@ -86,7 +107,7 @@ export declare class GpuShadowRenderer {
         depth: GPUTextureView;
         w: number;
         h: number;
-    }): void;
+    }, 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>;
 
@@ -85,7 +88,7 @@ fn hsv(hh: f32) -> vec3<f32> {
 // 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
@@ -181,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]];
@@ -198,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;
 }
 
@@ -232,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.
@@ -241,7 +254,19 @@ 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); }
-  let ao = blockShade(fx, fz);
+  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
+  }
+  // per-block edge AO makes each voxel visible on FLAT-hue cubes, but reads as a hard GRID over textures — so the
+  // atlas path uses a soft, mostly-flat AO (texture already supplies surface detail) instead of the strong grid.
+  let ao = select(blockShade(fx, fz), mix(blockShade(fx, fz), 1.0, 0.8), cam.atlas.x > 0.5 && i.tile >= 0.0);
   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
 }
@@ -277,11 +302,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;
@@ -332,6 +361,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] }),
@@ -390,6 +422,12 @@ export class GpuShadowRenderer {
         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 uniform holding the 6 planes + instance count + camVP + occlusion params.
@@ -437,7 +475,7 @@ export class GpuShadowRenderer {
     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;
@@ -450,6 +488,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() {
@@ -462,13 +504,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);
@@ -477,15 +543,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. */
@@ -493,7 +559,7 @@ 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 planes + count + this frustum's VP + occlusion params (occ on the camera pass). */
@@ -517,7 +583,7 @@ export class GpuShadowRenderer {
     /** 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) {
+    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];
@@ -528,6 +594,11 @@ 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);
@@ -556,6 +627,8 @@ 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 + Hi-Z-occlusion-culled).
         const mp = enc.beginRenderPass({

package/package.json

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