ugly-game 0.2.0 → 0.3.0

package/dist/gpuGraph.js

@@ -0,0 +1,128 @@
+// Renders each shader GRAPH as its own pipeline: compileGraph() emits a `material()` WGSL fn that
+// is spliced into a shared scene template (cube instances + Cook-Torrance PBR lighting). So the
+// LIGHTING is engine-owned and identical; only the artist-authored material() differs per graph —
+// exactly how a production shader-graph pipeline works. No hand-written per-material WGSL.
+import { CUBE } from './gpuShadow';
+import { compileGraph } from './shaderGraph';
+function sceneWGSL(materialFn) {
+    return /* wgsl */ `
+struct Inst { pos: vec4<f32>, scl: vec4<f32> };
+struct U { camVP: mat4x4<f32>, eye: vec4<f32>, sun: vec4<f32>, misc: vec4<f32> };  // misc.x = time
+@group(0) @binding(0) var<uniform> u: U;
+@group(0) @binding(1) var<storage, read> insts: array<Inst>;
+@group(0) @binding(2) var gsamp: sampler;
+@group(0) @binding(3) var gtex: texture_2d_array<f32>;
+const CUBE_POS = array<vec3<f32>, 36>(${CUBE.pos});
+const CUBE_NRM = array<vec3<f32>, 36>(${CUBE.nrm});
+
+struct Surface { albedo: vec3<f32>, rough: f32, metal: f32, emit: vec3<f32> };
+fn hash21(p: vec2<f32>) -> f32 { return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453); }
+fn gnoise(uv: vec2<f32>) -> f32 {
+  let i = floor(uv); let f = fract(uv); let w = f * f * (3.0 - 2.0 * f);
+  let a = hash21(i); let b = hash21(i + vec2(1.0, 0.0)); let c = hash21(i + vec2(0.0, 1.0)); let d = hash21(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, w.x), mix(c, d, w.x), w.y);
+}
+fn gchecker(uv: vec2<f32>) -> f32 { return f32((i32(floor(uv.x)) + i32(floor(uv.y))) & 1); }
+
+${materialFn}
+
+struct VOut { @builtin(position) clip: vec4<f32>, @location(0) world: vec3<f32>, @location(1) nrm: vec3<f32>, @location(2) uv: vec2<f32> };
+@vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VOut {
+  let it = insts[ii]; let lp = CUBE_POS[vi]; let n = CUBE_NRM[vi];
+  var uv = lp.xy; if (abs(n.x) > 0.5) { uv = lp.zy; } else if (abs(n.y) > 0.5) { uv = lp.xz; }
+  var o: VOut; let world = it.pos.xyz + lp * it.scl.xyz;
+  o.clip = u.camVP * vec4(world, 1.0); o.world = world; o.nrm = normalize(n / it.scl.xyz); o.uv = (uv + 0.5) * 2.0;
+  return o;
+}
+const PI = 3.14159265;
+fn ggx(nh: f32, r: f32) -> f32 { let a = r * r; let d = nh * nh * (a * a - 1.0) + 1.0; return a * a / max(PI * d * d, 1e-5); }
+fn gs(nv: f32, nl: f32, r: f32) -> f32 { let k = (r + 1.0) * (r + 1.0) / 8.0; return (nv / (nv * (1.0 - k) + k)) * (nl / (nl * (1.0 - k) + k)); }
+fn fres(ct: f32, f0: vec3<f32>) -> vec3<f32> { return f0 + (vec3(1.0) - f0) * pow(1.0 - ct, 5.0); }
+fn aces(x: vec3<f32>) -> vec3<f32> { return clamp((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14), vec3(0.0), vec3(1.0)); }
+
+@fragment fn fs(v: VOut) -> @location(0) vec4<f32> {
+  let N = normalize(v.nrm); let V = normalize(u.eye.xyz - v.world);
+  let s = material(v.uv, N, V, u.misc.x);        // ← artist-authored, compiled from the graph
+  let L = -normalize(u.sun.xyz); let H = normalize(V + L);
+  let nl = max(dot(N, L), 0.0); let nv = max(dot(N, V), 0.0);
+  let f0 = mix(vec3(0.04), s.albedo, s.metal);
+  let D = ggx(max(dot(N, H), 0.0), s.rough); let G = gs(nv, nl, s.rough); let F = fres(max(dot(H, V), 0.0), f0);
+  let spec = (D * G) * F / max(4.0 * nv * nl, 1e-4);
+  let kd = (vec3(1.0) - F) * (1.0 - s.metal);
+  let lit = (kd * s.albedo / PI + spec) * vec3(1.3, 1.2, 1.05) * nl + s.albedo * (0.11 + 0.06 * N.y) + s.emit;
+  return vec4(pow(aces(lit), vec3(0.4545)), 1.0);
+}`;
+}
+export class GpuGraphRenderer {
+    device;
+    uBuf;
+    u = new Float32Array(28);
+    samp;
+    texView;
+    bgl;
+    pipes = [];
+    groups = [];
+    /** Per-graph compiled WGSL — exposed so the demo can show it's generated, not hand-written. */
+    compiled;
+    constructor(device, format, graphs, tex) {
+        this.device = device;
+        this.uBuf = device.createBuffer({ size: this.u.byteLength, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.samp = device.createSampler({ magFilter: 'linear', minFilter: 'linear', mipmapFilter: 'linear', addressModeU: 'repeat', addressModeV: 'repeat' });
+        this.texView = tex.createView({ dimension: '2d-array' });
+        this.bgl = device.createBindGroupLayout({ entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: 'uniform' } },
+                { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } },
+                { binding: 2, visibility: GPUShaderStage.FRAGMENT, sampler: {} },
+                { binding: 3, visibility: GPUShaderStage.FRAGMENT, texture: { viewDimension: '2d-array' } }
+            ] });
+        const layout = device.createPipelineLayout({ bindGroupLayouts: [this.bgl] });
+        this.compiled = graphs.map((g) => compileGraph(g));
+        this.pipes = this.compiled.map((mat) => {
+            const mod = device.createShaderModule({ code: sceneWGSL(mat) });
+            return device.createRenderPipeline({ layout, vertex: { module: mod, entryPoint: 'vs' }, fragment: { module: mod, entryPoint: 'fs', targets: [{ format }] },
+                primitive: { topology: 'triangle-list', cullMode: 'none' }, depthStencil: { format: 'depth24plus', depthWriteEnabled: true, depthCompare: 'less' }, multisample: { count: 4 } });
+        });
+    }
+    /** groups: each is (which graph pipeline, the instances shaded by it). */
+    setGroups(groups) {
+        this.groups = groups.map((grp) => {
+            const data = new Float32Array(grp.instances.length * 8);
+            for (let i = 0; i < grp.instances.length; i++) {
+                const c = grp.instances[i], o = i * 8;
+                data[o] = c.x;
+                data[o + 1] = c.y;
+                data[o + 2] = c.z;
+                data[o + 4] = c.sx;
+                data[o + 5] = c.sy;
+                data[o + 6] = c.sz;
+            }
+            const buf = this.device.createBuffer({ size: data.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+            this.device.queue.writeBuffer(buf, 0, data);
+            const bg = this.device.createBindGroup({ layout: this.bgl, entries: [
+                    { binding: 0, resource: { buffer: this.uBuf } }, { binding: 1, resource: { buffer: buf } }, { binding: 2, resource: this.samp }, { binding: 3, resource: this.texView }
+                ] });
+            return { pipe: grp.graph, buf, bg, count: grp.instances.length };
+        });
+    }
+    frame(enc, msaaView, resolveView, depthView, camVP, eye, sunDir, time) {
+        this.u.set(camVP, 0);
+        this.u[16] = eye[0];
+        this.u[17] = eye[1];
+        this.u[18] = eye[2];
+        this.u[20] = sunDir[0];
+        this.u[21] = sunDir[1];
+        this.u[22] = sunDir[2];
+        this.u[24] = time;
+        this.device.queue.writeBuffer(this.uBuf, 0, this.u);
+        const rp = enc.beginRenderPass({
+            colorAttachments: [{ view: msaaView, resolveTarget: resolveView, clearValue: { r: 0.05, g: 0.07, b: 0.11, a: 1 }, loadOp: 'clear', storeOp: 'store' }],
+            depthStencilAttachment: { view: depthView, depthClearValue: 1.0, depthLoadOp: 'clear', depthStoreOp: 'store' }
+        });
+        for (const g of this.groups) {
+            rp.setPipeline(this.pipes[g.pipe]);
+            rp.setBindGroup(0, g.bg);
+            rp.draw(36, g.count);
+        }
+        rp.end();
+    }
+}

package/dist/gpuLit.d.ts

@@ -0,0 +1,40 @@
+export interface Instance {
+    x: number;
+    y: number;
+    z: number;
+    scale: number;
+    material: number;
+    bounds: number;
+}
+export interface Light {
+    x: number;
+    y: number;
+    z: number;
+    radius: number;
+    r: number;
+    g: number;
+    b: number;
+}
+export type Plane = readonly [number, number, number, number];
+export declare class GpuLitRenderer {
+    private device;
+    private format;
+    private instBuf;
+    private argsBuf;
+    private visBuf;
+    private camBuf;
+    private lightBuf;
+    private cullPipe;
+    private drawPipe;
+    private cullBG;
+    private drawBG;
+    private count;
+    private pipelines;
+    private capPerPipe;
+    private lightCount;
+    lastDrawCalls: number;
+    constructor(device: GPUDevice, format: GPUTextureFormat);
+    setScene(instances: Instance[], pipelines: number, capPerPipe: number, maxLights: number): void;
+    setLights(lights: Light[]): void;
+    frame(encoder: GPUCommandEncoder, view: GPUTextureView, depth: GPUTextureView, viewProj: Float32Array, right: number[], up: number[], fwd: number[], planes: Plane[], sun: number[], sunCol: number[], ambient: number): void;
+}

package/dist/gpuLit.js

@@ -0,0 +1,193 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// GPU-driven LIT renderer — the shading program begins here (GAME.md §3.6). Builds
+// on the proven cull backend (compute frustum-cull → per-pipeline indirect draw) and
+// adds real lighting: instances render as lit impostor SPHERES (a billboard quad whose
+// fragment reconstructs a sphere normal), shaded by a directional sun + a buffer of
+// MANY dynamic POINT LIGHTS. This is the many-dynamic-lights look the open-world axis
+// needs; a later increment adds tiled/clustered light culling to scale the light count.
+// See design/moonshot-open-world.md §5 (phase 4), design/engine-build-plan.md.
+// ─────────────────────────────────────────────────────────────────────────────
+const INSTANCE_F32 = 8, ARG_U32 = 4, LIGHT_F32 = 8, CAM_F32 = 64;
+const WGSL = /* wgsl */ `
+struct Inst { pos: vec4<f32>, attr: vec4<f32> };
+struct Args { vc: u32, ic: atomic<u32>, fv: u32, fi: u32 };
+struct Light { posr: vec4<f32>, color: vec4<f32> };       // xyz + radius; rgb
+struct Cam {
+  viewProj: mat4x4<f32>,
+  right: vec4<f32>, up: vec4<f32>, fwd: vec4<f32>,
+  planes: array<vec4<f32>, 6>,
+  counts: vec4<f32>,                                       // count, capPerPipe, pipelines, lightCount
+  sun: vec4<f32>,                                          // sun dir xyz
+  sunCol: vec4<f32>,                                       // rgb, ambient(a)
+};
+
+@group(0) @binding(0) var<storage, read> instances: array<Inst>;
+@group(0) @binding(1) var<storage, read_write> args: array<Args>;
+@group(0) @binding(2) var<storage, read_write> visible: array<u32>;
+@group(0) @binding(3) var<uniform> cam: Cam;
+
+@compute @workgroup_size(64)
+fn cull(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let i = gid.x;
+  if (i >= u32(cam.counts.x)) { return; }
+  let inst = instances[i];
+  let c = inst.pos.xyz; let r = inst.attr.y;
+  for (var p = 0u; p < 6u; p++) { let pl = cam.planes[p]; if (dot(pl.xyz, c) + pl.w < -r) { return; } }
+  let pipe = u32(inst.attr.x);
+  let slot = atomicAdd(&args[pipe].ic, 1u);
+  let cap = u32(cam.counts.y);
+  if (slot < cap) { visible[pipe * cap + slot] = i; }
+}
+
+// ── lit render: impostor spheres shaded by sun + point lights ──
+@group(0) @binding(0) var<storage, read> rinstances: array<Inst>;
+@group(0) @binding(1) var<storage, read> rvisible: array<u32>;
+@group(0) @binding(2) var<uniform> rcam: Cam;
+@group(0) @binding(3) var<storage, read> lights: array<Light>;
+
+struct VOut { @builtin(position) pos: vec4<f32>, @location(0) uv: vec2<f32>, @location(1) center: vec3<f32>, @location(2) scale: f32 };
+const QUAD = array<vec2<f32>, 6>(vec2(-1.,-1.), vec2(1.,-1.), vec2(1.,1.), vec2(-1.,-1.), vec2(1.,1.), vec2(-1.,1.));
+
+@vertex
+fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VOut {
+  let inst = rinstances[rvisible[ii]];
+  let q = QUAD[vi];
+  let world = inst.pos.xyz + (rcam.right.xyz * q.x + rcam.up.xyz * q.y) * inst.pos.w;
+  var o: VOut;
+  o.pos = rcam.viewProj * vec4(world, 1.0);
+  o.uv = q; o.center = inst.pos.xyz; o.scale = inst.pos.w;
+  return o;
+}
+@fragment
+fn fs(v: VOut) -> @location(0) vec4<f32> {
+  let r2 = dot(v.uv, v.uv);
+  if (r2 > 1.0) { discard; }
+  let nz = sqrt(1.0 - r2);
+  let N = normalize(rcam.right.xyz * v.uv.x + rcam.up.xyz * v.uv.y - rcam.fwd.xyz * nz); // sphere normal toward camera
+  let wp = v.center + N * v.scale;                        // approx surface point
+  let base = vec3<f32>(0.55, 0.57, 0.62);                 // neutral albedo so light colors show
+  var lit = base * rcam.sunCol.a;                         // ambient
+  lit += base * rcam.sunCol.rgb * max(dot(N, -rcam.sun.xyz), 0.0); // sun
+  let n = u32(rcam.counts.w);
+  for (var i = 0u; i < n; i++) {
+    let L = lights[i].posr.xyz - wp; let d = length(L); let rad = lights[i].posr.w;
+    if (d < rad) { let a = 1.0 - d / rad; lit += base * lights[i].color.rgb * max(dot(N, L / d), 0.0) * a * a; }
+  }
+  return vec4(lit, 1.0);
+}
+`;
+export class GpuLitRenderer {
+    device;
+    format;
+    instBuf;
+    argsBuf;
+    visBuf;
+    camBuf;
+    lightBuf;
+    cullPipe;
+    drawPipe;
+    cullBG;
+    drawBG;
+    count = 0;
+    pipelines = 1;
+    capPerPipe = 0;
+    lightCount = 0;
+    lastDrawCalls = 0;
+    constructor(device, format) {
+        this.device = device;
+        this.format = format;
+    }
+    setScene(instances, pipelines, capPerPipe, maxLights) {
+        const d = this.device;
+        this.count = instances.length;
+        this.pipelines = pipelines;
+        this.capPerPipe = capPerPipe;
+        const idata = new Float32Array(this.count * INSTANCE_F32);
+        for (let i = 0; i < this.count; i++) {
+            const o = i * INSTANCE_F32, it = instances[i];
+            idata[o] = it.x;
+            idata[o + 1] = it.y;
+            idata[o + 2] = it.z;
+            idata[o + 3] = it.scale;
+            idata[o + 4] = it.material;
+            idata[o + 5] = it.bounds;
+        }
+        this.instBuf = d.createBuffer({ size: idata.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+        d.queue.writeBuffer(this.instBuf, 0, idata);
+        this.argsBuf = d.createBuffer({ size: pipelines * ARG_U32 * 4, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST });
+        this.visBuf = d.createBuffer({ size: pipelines * capPerPipe * 4, usage: GPUBufferUsage.STORAGE });
+        this.camBuf = d.createBuffer({ size: CAM_F32 * 4, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.lightBuf = d.createBuffer({ size: maxLights * LIGHT_F32 * 4, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+        const mod = d.createShaderModule({ code: WGSL });
+        this.cullPipe = d.createComputePipeline({ layout: 'auto', compute: { module: mod, entryPoint: 'cull' } });
+        this.drawPipe = d.createRenderPipeline({ layout: 'auto', vertex: { module: mod, entryPoint: 'vs' }, fragment: { module: mod, entryPoint: 'fs', targets: [{ format: this.format }] }, primitive: { topology: 'triangle-list' }, depthStencil: { format: 'depth24plus', depthWriteEnabled: true, depthCompare: 'less' } });
+        this.cullBG = d.createBindGroup({ layout: this.cullPipe.getBindGroupLayout(0), entries: [{ binding: 0, resource: { buffer: this.instBuf } }, { binding: 1, resource: { buffer: this.argsBuf } }, { binding: 2, resource: { buffer: this.visBuf } }, { binding: 3, resource: { buffer: this.camBuf } }] });
+        this.drawBG = d.createBindGroup({ layout: this.drawPipe.getBindGroupLayout(0), entries: [{ binding: 0, resource: { buffer: this.instBuf } }, { binding: 1, resource: { buffer: this.visBuf } }, { binding: 2, resource: { buffer: this.camBuf } }, { binding: 3, resource: { buffer: this.lightBuf } }] });
+    }
+    setLights(lights) {
+        this.lightCount = lights.length;
+        const data = new Float32Array(lights.length * LIGHT_F32);
+        for (let i = 0; i < lights.length; i++) {
+            const o = i * LIGHT_F32, L = lights[i];
+            data[o] = L.x;
+            data[o + 1] = L.y;
+            data[o + 2] = L.z;
+            data[o + 3] = L.radius;
+            data[o + 4] = L.r;
+            data[o + 5] = L.g;
+            data[o + 6] = L.b;
+        }
+        this.device.queue.writeBuffer(this.lightBuf, 0, data);
+    }
+    frame(encoder, view, depth, viewProj, right, up, fwd, planes, sun, sunCol, ambient) {
+        const cam = new Float32Array(CAM_F32);
+        cam.set(viewProj, 0);
+        cam[16] = right[0];
+        cam[17] = right[1];
+        cam[18] = right[2];
+        cam[20] = up[0];
+        cam[21] = up[1];
+        cam[22] = up[2];
+        cam[24] = fwd[0];
+        cam[25] = fwd[1];
+        cam[26] = fwd[2];
+        for (let p = 0; p < 6; p++) {
+            cam[28 + p * 4] = planes[p][0];
+            cam[29 + p * 4] = planes[p][1];
+            cam[30 + p * 4] = planes[p][2];
+            cam[31 + p * 4] = planes[p][3];
+        }
+        cam[52] = this.count;
+        cam[53] = this.capPerPipe;
+        cam[54] = this.pipelines;
+        cam[55] = this.lightCount;
+        cam[56] = sun[0];
+        cam[57] = sun[1];
+        cam[58] = sun[2];
+        cam[60] = sunCol[0];
+        cam[61] = sunCol[1];
+        cam[62] = sunCol[2];
+        cam[63] = ambient;
+        this.device.queue.writeBuffer(this.camBuf, 0, cam);
+        const args = new Uint32Array(this.pipelines * ARG_U32);
+        for (let p = 0; p < this.pipelines; p++) {
+            args[p * 4] = 6;
+            args[p * 4 + 1] = 0;
+            args[p * 4 + 2] = 0;
+            args[p * 4 + 3] = p * this.capPerPipe;
+        }
+        this.device.queue.writeBuffer(this.argsBuf, 0, args);
+        const cp = encoder.beginComputePass();
+        cp.setPipeline(this.cullPipe);
+        cp.setBindGroup(0, this.cullBG);
+        cp.dispatchWorkgroups(Math.ceil(this.count / 64));
+        cp.end();
+        const rp = encoder.beginRenderPass({ colorAttachments: [{ view, clearValue: { r: 0.02, g: 0.03, b: 0.05, a: 1 }, loadOp: 'clear', storeOp: 'store' }], depthStencilAttachment: { view: depth, depthClearValue: 1, depthLoadOp: 'clear', depthStoreOp: 'store' } });
+        rp.setPipeline(this.drawPipe);
+        rp.setBindGroup(0, this.drawBG);
+        for (let p = 0; p < this.pipelines; p++)
+            rp.drawIndirect(this.argsBuf, p * ARG_U32 * 4);
+        rp.end();
+        this.lastDrawCalls = this.pipelines;
+    }
+}

package/dist/gpuPost.d.ts

@@ -0,0 +1,33 @@
+export declare class PostChain {
+    private device;
+    private w;
+    private h;
+    private hw;
+    private hh;
+    private uMain;
+    private uMainBuf;
+    private uBlurH;
+    private uBlurV;
+    private samp;
+    private brightPipe;
+    private blurPipe;
+    private compPipe;
+    private brightBGL;
+    private blurBGL;
+    private compBGL;
+    private brightTex?;
+    private blurTmp?;
+    private bloomTex?;
+    private brightView;
+    private blurTmpView;
+    private bloomView;
+    private brightBG;
+    private blurHBG;
+    private blurVBG;
+    private compBG;
+    constructor(device: GPUDevice, format: GPUTextureFormat);
+    resize(w: number, h: number): void;
+    /** Bind the scene's HDR texture (rebuild when it's (re)created, e.g. on resize). */
+    setInput(hdr: GPUTexture): void;
+    process(enc: GPUCommandEncoder, swapView: GPUTextureView, sunUV: [number, number], sunVis: number): void;
+}

package/dist/gpuPost.js

@@ -0,0 +1,162 @@
+// Stage 2 — a MULTI-STEP GPU POST-PROCESSING CHAIN over the HDR scene, the thing the earlier
+// "few draw calls, analytic shading" demos conspicuously lacked. Five fullscreen passes:
+//   1. BRIGHT extract (threshold the HDR → the bloom/flare source, at half res)
+//   2+3. separable GAUSSIAN BLUR (H then V) → BLOOM
+//   4. COMPOSITE: HDR + bloom + volumetric GOD-RAYS (radial march of the bright buffer toward the
+//      sun) + LENS-FLARE ghosts (offset samples of the bright buffer) → ACES tonemap → screen.
+// This is exactly the "multi-step GPU processing" AAA rendering needs; the same skeleton extends
+// to SSAO, SSR, motion blur, DOF, TAA, etc. Fed by gpuCinematic's textured-PBR HDR output.
+const HDR = 'rgba16float';
+const FS_VS = /* wgsl */ `@vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4<f32> {
+  var p = array<vec2<f32>, 3>(vec2(-1.0, -1.0), vec2(3.0, -1.0), vec2(-1.0, 3.0)); return vec4(p[vi], 0.0, 1.0); }`;
+const BRIGHT_WGSL = FS_VS + /* wgsl */ `
+struct U { a: vec4<f32>, b: vec4<f32>, c: vec4<f32> };  // a=texelFull.xy,texelHalf.xy  b=sunUV.xy,vis,exposure  c=thresh,bloomI,godrayI,flareI
+@group(0) @binding(0) var<uniform> u: U;
+@group(0) @binding(1) var samp: sampler;
+@group(0) @binding(2) var hdr: texture_2d<f32>;
+@fragment fn fs(@builtin(position) fc: vec4<f32>) -> @location(0) vec4<f32> {
+  let uv = fc.xy * u.a.zw;                        // half-res target
+  let col = textureSampleLevel(hdr, samp, uv, 0.0).rgb;
+  return vec4(max(col - vec3(u.c.x), vec3(0.0)), 1.0);
+}`;
+const BLUR_WGSL = FS_VS + /* wgsl */ `
+struct B { texel: vec4<f32> };  // xy = texel, zw = direction
+@group(0) @binding(0) var<uniform> b: B;
+@group(0) @binding(1) var samp: sampler;
+@group(0) @binding(2) var src: texture_2d<f32>;
+@fragment fn fs(@builtin(position) fc: vec4<f32>) -> @location(0) vec4<f32> {
+  let uv = fc.xy * b.texel.xy;
+  let d = b.texel.zw;
+  let w = array<f32, 5>(0.227, 0.194, 0.121, 0.054, 0.016);
+  var c = textureSampleLevel(src, samp, uv, 0.0).rgb * w[0];
+  for (var i = 1; i < 5; i = i + 1) {
+    let o = d * f32(i) * 1.4;
+    c = c + textureSampleLevel(src, samp, uv + o, 0.0).rgb * w[i];
+    c = c + textureSampleLevel(src, samp, uv - o, 0.0).rgb * w[i];
+  }
+  return vec4(c, 1.0);
+}`;
+const COMPOSITE_WGSL = FS_VS + /* wgsl */ `
+struct U { a: vec4<f32>, b: vec4<f32>, c: vec4<f32> };
+@group(0) @binding(0) var<uniform> u: U;
+@group(0) @binding(1) var samp: sampler;
+@group(0) @binding(2) var hdr: texture_2d<f32>;
+@group(0) @binding(3) var bloom: texture_2d<f32>;
+@group(0) @binding(4) var bright: texture_2d<f32>;
+fn aces(x: vec3<f32>) -> vec3<f32> { return clamp((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14), vec3(0.0), vec3(1.0)); }
+@fragment fn fs(@builtin(position) fc: vec4<f32>) -> @location(0) vec4<f32> {
+  let uv = fc.xy * u.a.xy;
+  var col = textureSampleLevel(hdr, samp, uv, 0.0).rgb;
+  col = col + textureSampleLevel(bloom, samp, uv, 0.0).rgb * u.c.y;
+  // volumetric god-rays: march the bright buffer toward the sun's screen position
+  let sunUV = u.b.xy; let vis = u.b.z;
+  if (vis > 0.5) {
+    var gr = vec3(0.0); let delta = (sunUV - uv) * (1.0 / 48.0); var p = uv; var dec = 1.0;
+    for (var i = 0; i < 48; i = i + 1) { p = p + delta; gr = gr + textureSampleLevel(bloom, samp, p, 0.0).rgb * dec; dec = dec * 0.96; }
+    col = col + gr * (u.c.z / 48.0);
+    // lens-flare ghosts: mirrored samples of the bright buffer through screen centre
+    let gv = (vec2(0.5) - sunUV) * 0.32;
+    var fl = vec3(0.0);
+    for (var i = 1; i < 6; i = i + 1) { fl = fl + textureSampleLevel(bloom, samp, uv + gv * f32(i), 0.0).rgb * (0.7 / f32(i)); }
+    let halo = textureSampleLevel(bloom, samp, uv + normalize(gv + vec2(1e-5)) * 0.28, 0.0).rgb;
+    col = col + (fl + halo * 0.4) * u.c.w * vec3(1.0, 0.9, 0.75);
+  }
+  return vec4(pow(aces(col * u.b.w), vec3(0.4545)), 1.0);
+}`;
+export class PostChain {
+    device;
+    w = 0;
+    h = 0;
+    hw = 0;
+    hh = 0;
+    uMain = new Float32Array(12);
+    uMainBuf;
+    uBlurH;
+    uBlurV;
+    samp;
+    brightPipe;
+    blurPipe;
+    compPipe;
+    brightBGL;
+    blurBGL;
+    compBGL;
+    brightTex;
+    blurTmp;
+    bloomTex;
+    brightView;
+    blurTmpView;
+    bloomView;
+    brightBG;
+    blurHBG;
+    blurVBG;
+    compBG;
+    constructor(device, format) {
+        this.device = device;
+        this.uMainBuf = device.createBuffer({ size: this.uMain.byteLength, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.uBlurH = device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.uBlurV = device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.samp = device.createSampler({ magFilter: 'linear', minFilter: 'linear', addressModeU: 'clamp-to-edge', addressModeV: 'clamp-to-edge' });
+        const bMod = device.createShaderModule({ code: BRIGHT_WGSL }), blMod = device.createShaderModule({ code: BLUR_WGSL }), cMod = device.createShaderModule({ code: COMPOSITE_WGSL });
+        this.brightBGL = device.createBindGroupLayout({ entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: 'uniform' } }, { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: {} }, { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: {} }
+            ] });
+        this.blurBGL = device.createBindGroupLayout({ entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: 'uniform' } }, { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: {} }, { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: {} }
+            ] });
+        this.compBGL = device.createBindGroupLayout({ entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: 'uniform' } }, { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: {} },
+                { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: {} }, { binding: 3, visibility: GPUShaderStage.FRAGMENT, texture: {} }, { binding: 4, visibility: GPUShaderStage.FRAGMENT, texture: {} }
+            ] });
+        const mk = (bgl, mod, fmt) => device.createRenderPipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [bgl] }), vertex: { module: mod, entryPoint: 'vs' }, fragment: { module: mod, entryPoint: 'fs', targets: [{ format: fmt }] }, primitive: { topology: 'triangle-list' }
+        });
+        this.brightPipe = mk(this.brightBGL, bMod, HDR);
+        this.blurPipe = mk(this.blurBGL, blMod, HDR);
+        this.compPipe = mk(this.compBGL, cMod, format);
+    }
+    resize(w, h) {
+        this.w = w;
+        this.h = h;
+        this.hw = Math.max(1, w >> 1);
+        this.hh = Math.max(1, h >> 1);
+        for (const t of [this.brightTex, this.blurTmp, this.bloomTex])
+            t?.destroy();
+        const mk = () => this.device.createTexture({ size: [this.hw, this.hh], format: HDR, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING });
+        this.brightTex = mk();
+        this.blurTmp = mk();
+        this.bloomTex = mk();
+        this.brightView = this.brightTex.createView();
+        this.blurTmpView = this.blurTmp.createView();
+        this.bloomView = this.bloomTex.createView();
+        this.device.queue.writeBuffer(this.uBlurH, 0, new Float32Array([1 / this.hw, 1 / this.hh, 1 / this.hw, 0]));
+        this.device.queue.writeBuffer(this.uBlurV, 0, new Float32Array([1 / this.hw, 1 / this.hh, 0, 1 / this.hh]));
+        this.blurHBG = this.device.createBindGroup({ layout: this.blurBGL, entries: [{ binding: 0, resource: { buffer: this.uBlurH } }, { binding: 1, resource: this.samp }, { binding: 2, resource: this.brightView }] });
+        this.blurVBG = this.device.createBindGroup({ layout: this.blurBGL, entries: [{ binding: 0, resource: { buffer: this.uBlurV } }, { binding: 1, resource: this.samp }, { binding: 2, resource: this.blurTmpView }] });
+    }
+    /** Bind the scene's HDR texture (rebuild when it's (re)created, e.g. on resize). */
+    setInput(hdr) {
+        const hv = hdr.createView();
+        this.brightBG = this.device.createBindGroup({ layout: this.brightBGL, entries: [{ binding: 0, resource: { buffer: this.uMainBuf } }, { binding: 1, resource: this.samp }, { binding: 2, resource: hv }] });
+        this.compBG = this.device.createBindGroup({ layout: this.compBGL, entries: [
+                { binding: 0, resource: { buffer: this.uMainBuf } }, { binding: 1, resource: this.samp },
+                { binding: 2, resource: hv }, { binding: 3, resource: this.bloomView }, { binding: 4, resource: this.brightView }
+            ] });
+    }
+    process(enc, swapView, sunUV, sunVis) {
+        this.uMain.set([1 / this.w, 1 / this.h, 1 / this.hw, 1 / this.hh], 0);
+        this.uMain.set([sunUV[0], sunUV[1], sunVis, 1.0], 4); // exposure 1.0
+        this.uMain.set([1.3, 0.85, 0.5, 0.22], 8); // threshold, bloomI, godrayI, flareI (softened)
+        this.device.queue.writeBuffer(this.uMainBuf, 0, this.uMain);
+        const pass = (view, pipe, bg) => {
+            const p = enc.beginRenderPass({ colorAttachments: [{ view, loadOp: 'clear', storeOp: 'store', clearValue: { r: 0, g: 0, b: 0, a: 1 } }] });
+            p.setPipeline(pipe);
+            p.setBindGroup(0, bg);
+            p.draw(3);
+            p.end();
+        };
+        pass(this.brightView, this.brightPipe, this.brightBG); // 1. bright extract
+        pass(this.blurTmpView, this.blurPipe, this.blurHBG); // 2. blur H
+        pass(this.bloomView, this.blurPipe, this.blurVBG); // 3. blur V → bloom
+        pass(swapView, this.compPipe, this.compBG); // 4. composite + godrays + flare + tonemap
+    }
+}

package/dist/gpuShadowMap.d.ts

@@ -0,0 +1,11 @@
+export declare const SHADOW_SIZE = 2048;
+export declare const SHADOW_WGSL = "\nfn shadowFactor(lightVP: mat4x4<f32>, world: vec3<f32>, ndl: f32, texel: f32,\n                shadowMap: texture_depth_2d, shadowSamp: sampler_comparison) -> f32 {\n  let lp = lightVP * vec4(world, 1.0);\n  let proj = lp.xyz / lp.w;\n  let uv = proj.xy * vec2(0.5, -0.5) + vec2(0.5, 0.5);\n  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0 || proj.z > 1.0 || proj.z < 0.0) { return 1.0; }\n  let bias = max(0.0025 * (1.0 - ndl), 0.0012);\n  var s = 0.0;\n  for (var dy = -1; dy <= 1; dy = dy + 1) {\n    for (var dx = -1; dx <= 1; dx = dx + 1) {\n      s = s + textureSampleCompareLevel(shadowMap, shadowSamp, uv + vec2(f32(dx), f32(dy)) * texel, proj.z - bias);\n    }\n  }\n  return s / 9.0;\n}";
+export declare class GpuShadowMap {
+    readonly view: GPUTextureView;
+    readonly sampler: GPUSampler;
+    readonly texel: number;
+    private tex;
+    constructor(device: GPUDevice);
+    /** Begin the occluder depth pass (clears the map). Renderers draw their depth-only geometry into it. */
+    begin(enc: GPUCommandEncoder): GPURenderPassEncoder;
+}

package/dist/gpuShadowMap.js

@@ -0,0 +1,41 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// GPU SHADOW MAP (PLATFORM) — a shared directional-sun depth map + PCF sampling helper, so the outdoor
+// scene casts real shadows (the single biggest look upgrade after lighting; it also makes the sun's
+// DIRECTION legible — long shadows at dawn/dusk, short at noon). Occluders (terrain, props) render their
+// depth from the sun's ortho view into this one map; receivers (terrain) sample it with PCF. Reusable
+// across renderers: each contributes a depth-only pass into `begin()`, and samples via SHADOW_WGSL.
+// ─────────────────────────────────────────────────────────────────────────────
+export const SHADOW_SIZE = 2048;
+// Drop-in WGSL: paste into a receiver fragment shader. Expects `shadowMap` (binding 2) + `shadowSamp`
+// (binding 3) + a `lightVP` mat4 and texel size in scope. Returns 1 = lit, 0 = fully shadowed (PCF 3×3).
+export const SHADOW_WGSL = /* wgsl */ `
+fn shadowFactor(lightVP: mat4x4<f32>, world: vec3<f32>, ndl: f32, texel: f32,
+                shadowMap: texture_depth_2d, shadowSamp: sampler_comparison) -> f32 {
+  let lp = lightVP * vec4(world, 1.0);
+  let proj = lp.xyz / lp.w;
+  let uv = proj.xy * vec2(0.5, -0.5) + vec2(0.5, 0.5);
+  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0 || proj.z > 1.0 || proj.z < 0.0) { return 1.0; }
+  let bias = max(0.0025 * (1.0 - ndl), 0.0012);
+  var s = 0.0;
+  for (var dy = -1; dy <= 1; dy = dy + 1) {
+    for (var dx = -1; dx <= 1; dx = dx + 1) {
+      s = s + textureSampleCompareLevel(shadowMap, shadowSamp, uv + vec2(f32(dx), f32(dy)) * texel, proj.z - bias);
+    }
+  }
+  return s / 9.0;
+}`;
+export class GpuShadowMap {
+    view;
+    sampler;
+    texel = 1 / SHADOW_SIZE;
+    tex;
+    constructor(device) {
+        this.tex = device.createTexture({ size: [SHADOW_SIZE, SHADOW_SIZE], format: 'depth32float', usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING });
+        this.view = this.tex.createView();
+        this.sampler = device.createSampler({ compare: 'less', magFilter: 'linear', minFilter: 'linear' });
+    }
+    /** Begin the occluder depth pass (clears the map). Renderers draw their depth-only geometry into it. */
+    begin(enc) {
+        return enc.beginRenderPass({ colorAttachments: [], depthStencilAttachment: { view: this.view, depthClearValue: 1, depthLoadOp: 'clear', depthStoreOp: 'store' } });
+    }
+}

package/dist/gpuSpot.d.ts

@@ -0,0 +1,39 @@
+import type { CubeInstance } from './gpuShadow';
+export type { CubeInstance } from './gpuShadow';
+export interface Spot {
+    px: number;
+    py: number;
+    pz: number;
+    dx: number;
+    dy: number;
+    dz: number;
+    r: number;
+    g: number;
+    b: number;
+    range: number;
+    cosInner: number;
+    cosOuter: number;
+}
+export declare const NUM_SPOTS = 6;
+export declare class GpuSpotRenderer {
+    private device;
+    private instBuf;
+    private uBuf;
+    private lightVPBufs;
+    private shadowTex;
+    private layerViews;
+    private shadowPipe;
+    private mainPipe;
+    private shadowBGL;
+    private mainBGL;
+    private shadowSampler;
+    private shadowBGs;
+    private mainBG;
+    private count;
+    private u;
+    private vpScratch;
+    constructor(device: GPUDevice, format: GPUTextureFormat);
+    setScene(instances: CubeInstance[]): void;
+    /** camVP: Float32Array(16). spotVPs: NUM_SPOTS × Float32Array(16) (perspective light views). */
+    frame(enc: GPUCommandEncoder, colorView: GPUTextureView, sceneDepth: GPUTextureView, camVP: Float32Array, spots: Spot[], spotVPs: Float32Array[], ambient: number): void;
+}