ugly-game 0.2.0 → 0.4.0

package/dist/assets/ugm.d.ts

@@ -0,0 +1,53 @@
+export declare enum ChunkKind {
+    VTX = 1,
+    IDX = 2,
+    CLUSTER = 3,
+    MIP = 4,
+    MAT = 5,
+    SKEL = 6,
+    ANIM = 7,
+    MORPH = 8,
+    UV = 9,
+    KTX2 = 10
+}
+export interface ChunkIn {
+    kind: ChunkKind;
+    detailLevel: number;
+    targetId: number;
+    base: boolean;
+    bytes: Uint8Array;
+}
+export interface UgmMeta {
+    formatVersion: number;
+    renderIRVersion: number;
+    flags: number;
+    bounds: [number, number, number, number];
+}
+export declare const MAGIC = 843925333;
+export declare const HEADER_BYTES = 64;
+export declare const TOC_ENTRY_BYTES = 24;
+/** fnv1a-32 over raw bytes → u32 content hash (deterministic; enables chunk dedup).
+ *  Byte-wise (no String.fromCharCode spread — that overflows the stack on large chunks). */
+export declare function hashBytes(b: Uint8Array): number;
+export declare function packUgm(chunks: ChunkIn[], meta: UgmMeta): Uint8Array;
+export interface TocEntry {
+    kind: ChunkKind;
+    detailLevel: number;
+    targetId: number;
+    offset: number;
+    length: number;
+    hash: number;
+}
+export interface UgmHeader {
+    formatVersion: number;
+    renderIRVersion: number;
+    flags: number;
+    bounds: [number, number, number, number];
+    chunkCount: number;
+    tocOffset: number;
+    basePayloadLen: number;
+    totalLen: number;
+}
+export declare function readHeader(buf: Uint8Array): UgmHeader;
+export declare function readToc(buf: Uint8Array, h: UgmHeader): TocEntry[];
+export declare function readChunk(buf: Uint8Array, e: TocEntry): Uint8Array;

package/dist/assets/ugm.js

@@ -0,0 +1,100 @@
+// The cooked .ugm v2 container — streamable by construction (design/asset-streaming.md §2).
+// Layout (little-endian): [64B header][TOC: chunkCount × 24B][chunk bytes …].
+// Chunks are sorted base-first then ascending detailLevel, so a leading byte range
+// (0 .. basePayloadLen) is a complete coarse-renderable asset.
+export var ChunkKind;
+(function (ChunkKind) {
+    ChunkKind[ChunkKind["VTX"] = 1] = "VTX";
+    ChunkKind[ChunkKind["IDX"] = 2] = "IDX";
+    ChunkKind[ChunkKind["CLUSTER"] = 3] = "CLUSTER";
+    ChunkKind[ChunkKind["MIP"] = 4] = "MIP";
+    ChunkKind[ChunkKind["MAT"] = 5] = "MAT";
+    ChunkKind[ChunkKind["SKEL"] = 6] = "SKEL";
+    ChunkKind[ChunkKind["ANIM"] = 7] = "ANIM";
+    ChunkKind[ChunkKind["MORPH"] = 8] = "MORPH";
+    ChunkKind[ChunkKind["UV"] = 9] = "UV";
+    ChunkKind[ChunkKind["KTX2"] = 10] = "KTX2";
+})(ChunkKind || (ChunkKind = {}));
+export const MAGIC = 0x324d4755; // "UGM2" little-endian
+export const HEADER_BYTES = 64;
+export const TOC_ENTRY_BYTES = 24; // kind1 detail1 targetId2 offset4 length4 hash4 depMask4 pad4
+/** fnv1a-32 over raw bytes → u32 content hash (deterministic; enables chunk dedup).
+ *  Byte-wise (no String.fromCharCode spread — that overflows the stack on large chunks). */
+export function hashBytes(b) {
+    let h = 0x811c9dc5;
+    for (const byte of b) {
+        h ^= byte;
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+export function packUgm(chunks, meta) {
+    // base-first, then ascending detail — this ordering IS the coarse→fine stream order.
+    const sorted = [...chunks].sort((a, b) => (Number(b.base) - Number(a.base)) || (a.detailLevel - b.detailLevel) || (a.kind - b.kind) || (a.targetId - b.targetId));
+    const tocBytes = sorted.length * TOC_ENTRY_BYTES;
+    const dataStart = HEADER_BYTES + tocBytes;
+    let cursor = dataStart, baseEnd = dataStart;
+    const offsets = [];
+    for (const c of sorted) {
+        offsets.push(cursor);
+        cursor += c.bytes.byteLength;
+        if (c.base)
+            baseEnd = cursor;
+    }
+    const total = cursor;
+    const out = new Uint8Array(total);
+    const dv = new DataView(out.buffer);
+    // header
+    dv.setUint32(0, MAGIC, true);
+    dv.setUint16(4, meta.formatVersion, true);
+    dv.setUint16(6, meta.renderIRVersion, true);
+    dv.setUint32(8, meta.flags, true);
+    dv.setFloat32(12, meta.bounds[0], true);
+    dv.setFloat32(16, meta.bounds[1], true);
+    dv.setUint32(20, sorted.length, true); // chunkCount
+    dv.setUint32(24, HEADER_BYTES, true); // tocOffset
+    dv.setUint32(28, baseEnd, true); // basePayloadLen
+    dv.setUint32(32, total, true); // totalLen
+    dv.setFloat32(36, meta.bounds[2], true);
+    dv.setFloat32(40, meta.bounds[3], true);
+    // TOC
+    let t = HEADER_BYTES;
+    for (let i = 0; i < sorted.length; i++) {
+        const c = sorted[i];
+        dv.setUint8(t, c.kind);
+        dv.setUint8(t + 1, c.detailLevel);
+        dv.setUint16(t + 2, c.targetId, true);
+        dv.setUint32(t + 4, offsets[i], true);
+        dv.setUint32(t + 8, c.bytes.byteLength, true);
+        dv.setUint32(t + 12, hashBytes(c.bytes), true);
+        dv.setUint32(t + 16, 0, true); // depMask reserved
+        t += TOC_ENTRY_BYTES;
+    }
+    // chunk bytes
+    for (let i = 0; i < sorted.length; i++)
+        out.set(sorted[i].bytes, offsets[i]);
+    return out;
+}
+function dvOf(buf) { return new DataView(buf.buffer, buf.byteOffset, buf.byteLength); }
+export function readHeader(buf) {
+    const dv = dvOf(buf);
+    if (dv.getUint32(0, true) !== MAGIC)
+        throw new Error('.ugm: bad magic');
+    return {
+        formatVersion: dv.getUint16(4, true), renderIRVersion: dv.getUint16(6, true), flags: dv.getUint32(8, true),
+        bounds: [dv.getFloat32(12, true), dv.getFloat32(16, true), dv.getFloat32(36, true), dv.getFloat32(40, true)],
+        chunkCount: dv.getUint32(20, true), tocOffset: dv.getUint32(24, true),
+        basePayloadLen: dv.getUint32(28, true), totalLen: dv.getUint32(32, true),
+    };
+}
+export function readToc(buf, h) {
+    const dv = dvOf(buf);
+    const out = [];
+    for (let i = 0; i < h.chunkCount; i++) {
+        const t = h.tocOffset + i * TOC_ENTRY_BYTES;
+        out.push({ kind: dv.getUint8(t), detailLevel: dv.getUint8(t + 1), targetId: dv.getUint16(t + 2, true),
+            offset: dv.getUint32(t + 4, true), length: dv.getUint32(t + 8, true), hash: dv.getUint32(t + 12, true) });
+    }
+    return out;
+}
+export function readChunk(buf, e) { return buf.subarray(e.offset, e.offset + e.length); }

package/dist/gpuDriven.d.ts

@@ -0,0 +1,39 @@
+export interface Instance {
+    x: number;
+    y: number;
+    z: number;
+    scale: number;
+    material: number;
+    bounds: number;
+    lod?: number;
+}
+export type Plane = readonly [number, number, number, number];
+export declare class GpuDrivenRenderer {
+    private device;
+    private format;
+    private instBuf;
+    private argsBuf;
+    private visBuf;
+    private camBuf;
+    private colorBuf;
+    private readBuf;
+    private cullPipe;
+    private drawPipe;
+    private cullBG;
+    private drawBG;
+    private count;
+    private pipelines;
+    private capPerPipe;
+    private lodCount;
+    private get buckets();
+    lastDrawCalls: number;
+    constructor(device: GPUDevice, format: GPUTextureFormat);
+    /** Upload a scene: instances + a color per pipeline (material). capPerPipe bounds the
+     *  visible-per-pipeline compaction region. */
+    setScene(instances: Instance[], colors: [number, number, number][], capPerPipe: number, lodCount?: number): void;
+    /** One frame: reset args, compute-cull, then one indirect draw per pipeline. */
+    frame(encoder: GPUCommandEncoder, view: GPUTextureView, depth: GPUTextureView, viewProj: Float32Array, right: [number, number, number], up: [number, number, number], planes: Plane[]): void;
+    raw: number[];
+    /** Read the GPU-computed visible instanceCount per pipeline (the compute cull's result). */
+    readVisibleCounts(): Promise<number[]>;
+}

package/dist/gpuDriven.js

@@ -0,0 +1,197 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// GPU-DRIVEN render backend (WebGPU) — executes the render IR's DrawPlan on the GPU.
+// The whole scene lives in a storage buffer; a COMPUTE shader frustum-culls every
+// instance and writes, per pipeline (material), an atomic instanceCount + a compacted
+// list of visible instance indices; then ONE indirect draw per pipeline renders all
+// its visible instances. CPU draw calls = O(pipelines), independent of instance count.
+//
+// This is the real backend for the render IR (shared/renderIR.ts is the CPU reference
+// oracle it's validated against). Instances are billboarded quads for now — the shape
+// is not the point; the draw-call model is. See design/moonshot-open-world.md §5.
+// ─────────────────────────────────────────────────────────────────────────────
+const INSTANCE_F32 = 8; // pos.xyz, scale | material, bounds, pad, pad
+const ARG_U32 = 4; // drawIndirect: vertexCount, instanceCount, firstVertex, firstInstance
+const WGSL = /* wgsl */ `
+struct Inst { pos: vec4<f32>, attr: vec4<f32> };            // pos.xyz + scale(w); attr.x=pipeline, attr.y=bounds, attr.z=lod
+struct Args { vc: u32, ic: atomic<u32>, fv: u32, fi: u32 };
+struct Cam {
+  viewProj: mat4x4<f32>,
+  right: vec4<f32>, up: vec4<f32>,
+  planes: array<vec4<f32>, 6>,
+  counts: vec4<f32>,                                        // x=count, y=capPerPipe, z=pipelines, w=lodCount
+};
+
+@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;
+  var vis = true;
+  for (var p = 0u; p < 6u; p++) { let pl = cam.planes[p]; if (dot(pl.xyz, c) + pl.w < -r) { vis = false; } }
+  if (!vis) { return; }
+  // compact into per-(pipeline × lod) buckets — O(materials×lods) draws, LOD selected per instance.
+  let bucket = u32(inst.attr.x) * u32(cam.counts.w) + u32(inst.attr.z);
+  let slot = atomicAdd(&args[bucket].ic, 1u);
+  let cap = u32(cam.counts.y);
+  if (slot < cap) { visible[bucket * cap + slot] = i; }
+}
+
+// ── render (billboarded quad per visible instance) ──
+struct RInst { pos: vec4<f32>, attr: vec4<f32> };
+@group(0) @binding(0) var<storage, read> rinstances: array<RInst>;
+@group(0) @binding(1) var<storage, read> rvisible: array<u32>;
+@group(0) @binding(2) var<uniform> rcam: Cam;
+@group(0) @binding(3) var<uniform> colors: array<vec4<f32>, 8>;
+
+struct VOut { @builtin(position) pos: vec4<f32>, @location(0) color: vec3<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 idx = rvisible[ii];
+  let inst = rinstances[idx];
+  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.color = colors[u32(inst.attr.x)].rgb;
+  return o;
+}
+@fragment
+fn fs(i: VOut) -> @location(0) vec4<f32> { return vec4(i.color, 1.0); }
+`;
+export class GpuDrivenRenderer {
+    device;
+    format;
+    instBuf;
+    argsBuf;
+    visBuf;
+    camBuf;
+    colorBuf;
+    readBuf;
+    cullPipe;
+    drawPipe;
+    cullBG;
+    drawBG;
+    count = 0;
+    pipelines = 1;
+    capPerPipe = 0;
+    lodCount = 1;
+    get buckets() { return this.pipelines * this.lodCount; } // per-(pipeline × lod) draw groups
+    lastDrawCalls = 0;
+    constructor(device, format) {
+        this.device = device;
+        this.format = format;
+    }
+    /** Upload a scene: instances + a color per pipeline (material). capPerPipe bounds the
+     *  visible-per-pipeline compaction region. */
+    setScene(instances, colors, capPerPipe, lodCount = 1) {
+        const d = this.device;
+        this.count = instances.length;
+        this.pipelines = colors.length;
+        this.capPerPipe = capPerPipe;
+        this.lodCount = lodCount;
+        // instance storage (attr.z carries the per-instance LOD; defaults to 0 when unused)
+        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;
+            idata[o + 6] = it.lod ?? 0;
+        }
+        this.instBuf = d.createBuffer({ size: idata.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+        d.queue.writeBuffer(this.instBuf, 0, idata);
+        // per-bucket (pipeline × lod) indirect args + visible compaction buffer
+        this.argsBuf = d.createBuffer({ size: this.buckets * ARG_U32 * 4, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC });
+        this.visBuf = d.createBuffer({ size: this.buckets * capPerPipe * 4, usage: GPUBufferUsage.STORAGE });
+        this.readBuf = d.createBuffer({ size: this.buckets * ARG_U32 * 4, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
+        // camera uniform (mat4 64 + right 16 + up 16 + planes 96 + counts 16 = 208)
+        this.camBuf = d.createBuffer({ size: 208, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        // colors uniform (8 × vec4)
+        const cdata = new Float32Array(8 * 4);
+        for (let p = 0; p < this.pipelines; p++) {
+            cdata[p * 4] = colors[p][0];
+            cdata[p * 4 + 1] = colors[p][1];
+            cdata[p * 4 + 2] = colors[p][2];
+            cdata[p * 4 + 3] = 1;
+        }
+        this.colorBuf = d.createBuffer({ size: cdata.byteLength, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        d.queue.writeBuffer(this.colorBuf, 0, cdata);
+        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.colorBuf } }] });
+    }
+    /** One frame: reset args, compute-cull, then one indirect draw per pipeline. */
+    frame(encoder, view, depth, viewProj, right, up, planes) {
+        // camera uniform
+        const cam = new Float32Array(52);
+        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];
+        for (let p = 0; p < 6; p++) {
+            cam[24 + p * 4] = planes[p][0];
+            cam[25 + p * 4] = planes[p][1];
+            cam[26 + p * 4] = planes[p][2];
+            cam[27 + p * 4] = planes[p][3];
+        }
+        cam[48] = this.count;
+        cam[49] = this.capPerPipe;
+        cam[50] = this.pipelines;
+        cam[51] = this.lodCount;
+        this.device.queue.writeBuffer(this.camBuf, 0, cam);
+        // reset indirect args per bucket: [vertexCount=6, instanceCount=0, firstVertex=0, firstInstance=bucket*cap]
+        const args = new Uint32Array(this.buckets * ARG_U32);
+        for (let b = 0; b < this.buckets; b++) {
+            args[b * 4] = 6;
+            args[b * 4 + 1] = 0;
+            args[b * 4 + 2] = 0;
+            args[b * 4 + 3] = b * this.capPerPipe;
+        }
+        this.device.queue.writeBuffer(this.argsBuf, 0, args);
+        // compute cull
+        const cp = encoder.beginComputePass();
+        cp.setPipeline(this.cullPipe);
+        cp.setBindGroup(0, this.cullBG);
+        cp.dispatchWorkgroups(Math.ceil(this.count / 64));
+        cp.end();
+        // render — ONE indirect draw per pipeline
+        const rp = encoder.beginRenderPass({ colorAttachments: [{ view, clearValue: { r: 0.043, g: 0.075, b: 0.114, 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 b = 0; b < this.buckets; b++)
+            rp.drawIndirect(this.argsBuf, b * ARG_U32 * 4);
+        rp.end();
+        this.lastDrawCalls = this.buckets;
+        // copy args → readback
+        encoder.copyBufferToBuffer(this.argsBuf, 0, this.readBuf, 0, this.buckets * ARG_U32 * 4);
+    }
+    raw = [];
+    /** Read the GPU-computed visible instanceCount per pipeline (the compute cull's result). */
+    async readVisibleCounts() {
+        await this.readBuf.mapAsync(GPUMapMode.READ);
+        const a = new Uint32Array(this.readBuf.getMappedRange().slice(0));
+        this.readBuf.unmap();
+        this.raw = Array.from(a);
+        const out = [];
+        for (let b = 0; b < this.buckets; b++)
+            out.push(a[b * ARG_U32 + 1]); // visible count per (pipeline×lod) bucket
+        return out;
+    }
+}

package/dist/gpuGI.d.ts

@@ -0,0 +1,39 @@
+export interface GIBox {
+    x: number;
+    y: number;
+    z: number;
+    sx: number;
+    sy: number;
+    sz: number;
+    r: number;
+    g: number;
+    b: number;
+}
+export interface Grid {
+    ox: number;
+    oy: number;
+    oz: number;
+    cell: number;
+    nx: number;
+    ny: number;
+    nz: number;
+}
+/** Bake the probe grid: for each probe, cast rays; a surface hit contributes the hit box's
+ *  sun-lit albedo (one bounce, colour bleed), a miss contributes sky. Project into 6 axes.
+ *  Returns a Float32Array of `nx*ny*nz*6` vec4 (rgb + pad), axis-major within each probe. */
+export declare function bakeProbes(boxes: GIBox[], g: Grid, rays?: number): Float32Array;
+export declare class GpuGIRenderer {
+    private device;
+    private uBuf;
+    private u;
+    private instBuf;
+    private probeBuf;
+    private count;
+    private grid;
+    private pipe;
+    private bgl;
+    private bg;
+    constructor(device: GPUDevice, format: GPUTextureFormat);
+    setScene(boxes: GIBox[], probes: Float32Array, grid: Grid): void;
+    frame(enc: GPUCommandEncoder, colorView: GPUTextureView, depthView: GPUTextureView, camVP: Float32Array, giOn: boolean, flatAmbient: number): void;
+}

package/dist/gpuGI.js

@@ -0,0 +1,253 @@
+// Render increment 8 — BAKED GLOBAL ILLUMINATION via an irradiance probe grid (DDGI-style).
+// The last of GAME.md §3.6's named look gaps. Real-time path tracing is out; the tractable form
+// is to PRECOMPUTE indirect light into a 3D grid of probes, then sample it per-pixel. Each probe
+// stores a 6-axis AMBIENT CUBE (irradiance arriving along ±X/±Y/±Z — the Half-Life 2 trick):
+// cheap to store, captures direction, so a red box bleeds red onto its neighbours and occluded
+// nooks that see little sky go dark (soft AO). One bounce, baked once on the CPU.
+//
+// bakeProbes() is the CPU bake (ray-cast the scene per probe → ambient cubes). GpuGIRenderer
+// renders the boxes with direct sun + the probe-sampled indirect term. `?gi=0` on the page swaps
+// the probe term for a flat ambient so the difference is unmistakable.
+import { CUBE } from './gpuShadow';
+const AXES = [[1, 0, 0], [-1, 0, 0], [0, 1, 0], [0, -1, 0], [0, 0, 1], [0, 0, -1]];
+const SUN = [-0.4, -0.85, -0.32]; // direction light travels
+const SUN_COL = [1.15, 1.05, 0.9];
+function norm3(x, y, z) { const l = Math.hypot(x, y, z) || 1; return [x / l, y / l, z / l]; }
+const SUN_N = norm3(SUN[0], SUN[1], SUN[2]);
+/** Deterministic near-uniform sphere directions (Fibonacci). */
+function sphereDirs(n) {
+    const out = [], ga = Math.PI * (3 - Math.sqrt(5));
+    for (let i = 0; i < n; i++) {
+        const y = 1 - ((i + 0.5) / n) * 2, r = Math.sqrt(Math.max(0, 1 - y * y)), th = ga * i;
+        out.push([Math.cos(th) * r, y, Math.sin(th) * r]);
+    }
+    return out;
+}
+/** Ray vs AABB (slab). Returns entry distance + entry-face normal, or null. */
+function rayBox(ox, oy, oz, dx, dy, dz, b) {
+    const o = [ox, oy, oz], d = [dx, dy, dz], mn = [b.x - b.sx / 2, b.y - b.sy / 2, b.z - b.sz / 2], mx = [b.x + b.sx / 2, b.y + b.sy / 2, b.z + b.sz / 2];
+    let tmin = -Infinity, tmax = Infinity, axis = 0, sign = 1;
+    for (let a = 0; a < 3; a++) {
+        if (Math.abs(d[a]) < 1e-9) {
+            if (o[a] < mn[a] || o[a] > mx[a])
+                return null;
+            continue;
+        }
+        const inv = 1 / d[a];
+        let t1 = (mn[a] - o[a]) * inv, t2 = (mx[a] - o[a]) * inv, s = -1;
+        if (t1 > t2) {
+            const tmp = t1;
+            t1 = t2;
+            t2 = tmp;
+            s = 1;
+        }
+        if (t1 > tmin) {
+            tmin = t1;
+            axis = a;
+            sign = s;
+        }
+        if (t2 < tmax)
+            tmax = t2;
+        if (tmin > tmax)
+            return null;
+    }
+    if (tmax < 0)
+        return null;
+    const t = tmin > 0 ? tmin : tmax;
+    if (t < 0)
+        return null;
+    const n = [0, 0, 0];
+    n[axis] = sign;
+    return { t, n };
+}
+function skyColor(dy) {
+    if (dy < 0)
+        return [0.03, 0.03, 0.04]; // below horizon → almost no light
+    const t = dy; // horizon → zenith. Kept DIM on purpose:
+    return [0.16 + 0.08 * t, 0.19 + 0.11 * t, 0.24 + 0.16 * t]; // a bright sky washes out the colour bounce
+}
+/** Bake the probe grid: for each probe, cast rays; a surface hit contributes the hit box's
+ *  sun-lit albedo (one bounce, colour bleed), a miss contributes sky. Project into 6 axes.
+ *  Returns a Float32Array of `nx*ny*nz*6` vec4 (rgb + pad), axis-major within each probe. */
+export function bakeProbes(boxes, g, rays = 32) {
+    const dirs = sphereDirs(rays);
+    const N = g.nx * g.ny * g.nz;
+    const out = new Float32Array(N * 6 * 4);
+    for (let iz = 0; iz < g.nz; iz++)
+        for (let iy = 0; iy < g.ny; iy++)
+            for (let ix = 0; ix < g.nx; ix++) {
+                const px = g.ox + ix * g.cell, py = g.oy + iy * g.cell, pz = g.oz + iz * g.cell;
+                const cube = new Float64Array(18), wsum = new Float64Array(6); // 6 axes × rgb
+                for (const [dx, dy, dz] of dirs) {
+                    let bestT = Infinity, hit = null;
+                    for (const b of boxes) {
+                        const r = rayBox(px, py, pz, dx, dy, dz, b);
+                        if (r && r.t > 0.02 && r.t < bestT) {
+                            bestT = r.t;
+                            hit = { b, n: r.n };
+                        }
+                    }
+                    let cr, cg, cb;
+                    if (hit) {
+                        const sl = Math.max(-(hit.n[0] * SUN_N[0] + hit.n[1] * SUN_N[1] + hit.n[2] * SUN_N[2]), 0); // face lit by sun?
+                        cr = hit.b.r * (0.16 + SUN_COL[0] * sl);
+                        cg = hit.b.g * (0.16 + SUN_COL[1] * sl);
+                        cb = hit.b.b * (0.16 + SUN_COL[2] * sl);
+                    }
+                    else {
+                        const s = skyColor(dy);
+                        cr = s[0];
+                        cg = s[1];
+                        cb = s[2];
+                    }
+                    for (let a = 0; a < 6; a++) {
+                        const ax = AXES[a];
+                        const w = Math.max(dx * ax[0] + dy * ax[1] + dz * ax[2], 0);
+                        if (w <= 0)
+                            continue;
+                        wsum[a] += w;
+                        cube[a * 3] += cr * w;
+                        cube[a * 3 + 1] += cg * w;
+                        cube[a * 3 + 2] += cb * w;
+                    }
+                }
+                const pi = (iz * g.ny + iy) * g.nx + ix;
+                for (let a = 0; a < 6; a++) {
+                    const wv = Math.max(wsum[a], 1e-4), o = (pi * 6 + a) * 4;
+                    out[o] = cube[a * 3] / wv;
+                    out[o + 1] = cube[a * 3 + 1] / wv;
+                    out[o + 2] = cube[a * 3 + 2] / wv;
+                }
+            }
+    return out;
+}
+const SCENE_WGSL = /* wgsl */ `
+struct Inst { pos: vec4<f32>, scl: vec4<f32>, col: vec4<f32> };
+struct GU {
+  camVP: mat4x4<f32>,
+  sun: vec4<f32>,          // xyz dir, w = giOn
+  originCell: vec4<f32>,   // xyz grid origin, w = cell size
+  dims: vec4<f32>,         // xyz grid dims, w = flat ambient (gi off)
+};
+@group(0) @binding(0) var<uniform> gu: GU;
+@group(0) @binding(1) var<storage, read> insts: array<Inst>;
+@group(0) @binding(2) var<storage, read> probes: array<vec4<f32>>;
+const CUBE_POS = array<vec3<f32>, 36>(${CUBE.pos});
+const CUBE_NRM = array<vec3<f32>, 36>(${CUBE.nrm});
+
+struct VOut { @builtin(position) clip: vec4<f32>, @location(0) world: vec3<f32>, @location(1) nrm: vec3<f32>, @location(2) col: vec3<f32> };
+@vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VOut {
+  let it = insts[ii];
+  let world = it.pos.xyz + CUBE_POS[vi] * it.scl.xyz;
+  var o: VOut;
+  o.clip = gu.camVP * vec4(world, 1.0);
+  o.world = world; o.nrm = normalize(CUBE_NRM[vi] / it.scl.xyz); o.col = it.col.rgb;
+  return o;
+}
+fn probeAxis(pi: u32, a: u32) -> vec3<f32> { return probes[pi * 6u + a].rgb; }
+// Trilinear-sample the probe grid, then reconstruct irradiance for normal N (ambient cube).
+fn giAt(world: vec3<f32>, N: vec3<f32>) -> vec3<f32> {
+  let dims = gu.dims.xyz;
+  let g = (world - gu.originCell.xyz) / gu.originCell.w;
+  let gc = clamp(floor(g), vec3(0.0), dims - 1.0);
+  let f = clamp(g - gc, vec3(0.0), vec3(1.0));
+  var c0 = vec3(0.0); var c1 = vec3(0.0); var c2 = vec3(0.0); var c3 = vec3(0.0); var c4 = vec3(0.0); var c5 = vec3(0.0);
+  for (var k = 0u; k < 8u; k = k + 1u) {
+    let ox = f32(k & 1u); let oy = f32((k >> 1u) & 1u); let oz = f32((k >> 2u) & 1u);
+    let ix = clamp(gc.x + ox, 0.0, dims.x - 1.0); let iy = clamp(gc.y + oy, 0.0, dims.y - 1.0); let iz = clamp(gc.z + oz, 0.0, dims.z - 1.0);
+    let w = mix(1.0 - f.x, f.x, ox) * mix(1.0 - f.y, f.y, oy) * mix(1.0 - f.z, f.z, oz);
+    let pi = u32((iz * dims.y + iy) * dims.x + ix);
+    c0 = c0 + w * probeAxis(pi, 0u); c1 = c1 + w * probeAxis(pi, 1u); c2 = c2 + w * probeAxis(pi, 2u);
+    c3 = c3 + w * probeAxis(pi, 3u); c4 = c4 + w * probeAxis(pi, 4u); c5 = c5 + w * probeAxis(pi, 5u);
+  }
+  let n2 = N * N;
+  let cx = select(c1, c0, N.x > 0.0); let cy = select(c3, c2, N.y > 0.0); let cz = select(c5, c4, N.z > 0.0);
+  return n2.x * cx + n2.y * cy + n2.z * cz;
+}
+@fragment fn fs(v: VOut) -> @location(0) vec4<f32> {
+  let N = normalize(v.nrm);
+  let sl = max(dot(N, -normalize(gu.sun.xyz)), 0.0);
+  let direct = v.col * (sl * vec3(0.85, 0.8, 0.7));               // dimmer direct so indirect bleed reads
+  var indirect = v.col * gu.dims.w;                                 // flat ambient (gi off)
+  if (gu.sun.w > 0.5) { indirect = v.col * giAt(v.world, N); }      // probe-baked indirect (gi on)
+  return vec4(pow(clamp(direct + indirect, vec3(0.0), vec3(1.0)), vec3(0.4545)), 1.0);
+}
+`;
+export class GpuGIRenderer {
+    device;
+    uBuf;
+    u = new Float32Array(28); // mat4 + 3 vec4
+    instBuf;
+    probeBuf;
+    count = 0;
+    grid;
+    pipe;
+    bgl;
+    bg;
+    constructor(device, format) {
+        this.device = device;
+        this.uBuf = device.createBuffer({ size: this.u.byteLength, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        const mod = device.createShaderModule({ code: SCENE_WGSL });
+        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, buffer: { type: 'read-only-storage' } }
+            ] });
+        this.pipe = device.createRenderPipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.bgl] }),
+            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' }
+        });
+    }
+    setScene(boxes, probes, grid) {
+        this.grid = grid;
+        this.count = boxes.length;
+        const data = new Float32Array(this.count * 12);
+        for (let i = 0; i < this.count; i++) {
+            const b = boxes[i], o = i * 12;
+            data[o] = b.x;
+            data[o + 1] = b.y;
+            data[o + 2] = b.z;
+            data[o + 4] = b.sx;
+            data[o + 5] = b.sy;
+            data[o + 6] = b.sz;
+            data[o + 8] = b.r;
+            data[o + 9] = b.g;
+            data[o + 10] = b.b;
+        }
+        this.instBuf = this.device.createBuffer({ size: data.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+        this.device.queue.writeBuffer(this.instBuf, 0, data);
+        this.probeBuf = this.device.createBuffer({ size: probes.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+        this.device.queue.writeBuffer(this.probeBuf, 0, new Float32Array(probes)); // ArrayBuffer-backed copy (one-time)
+        this.bg = this.device.createBindGroup({ layout: this.bgl, entries: [
+                { binding: 0, resource: { buffer: this.uBuf } }, { binding: 1, resource: { buffer: this.instBuf } }, { binding: 2, resource: { buffer: this.probeBuf } }
+            ] });
+    }
+    frame(enc, colorView, depthView, camVP, giOn, flatAmbient) {
+        const g = this.grid;
+        this.u.set(camVP, 0);
+        this.u[16] = SUN[0];
+        this.u[17] = SUN[1];
+        this.u[18] = SUN[2];
+        this.u[19] = giOn ? 1 : 0;
+        this.u[20] = g.ox;
+        this.u[21] = g.oy;
+        this.u[22] = g.oz;
+        this.u[23] = g.cell;
+        this.u[24] = g.nx;
+        this.u[25] = g.ny;
+        this.u[26] = g.nz;
+        this.u[27] = flatAmbient;
+        this.device.queue.writeBuffer(this.uBuf, 0, this.u);
+        const rp = enc.beginRenderPass({
+            colorAttachments: [{ view: colorView, clearValue: { r: 0.03, g: 0.04, b: 0.06, a: 1 }, loadOp: 'clear', storeOp: 'store' }],
+            depthStencilAttachment: { view: depthView, depthClearValue: 1.0, depthLoadOp: 'clear', depthStoreOp: 'store' }
+        });
+        rp.setPipeline(this.pipe);
+        rp.setBindGroup(0, this.bg);
+        rp.draw(36, this.count);
+        rp.end();
+    }
+}