ugly-game 0.5.5 → 0.5.7

package/dist/gpuShadow.d.ts

@@ -1,6 +1,3 @@
-/** One cube instance: world position, per-axis scale, a hue (< 0 ⇒ neutral ground), and an optional
- *  emissive flag (> 0 ⇒ the cube self-glows at full brightness, bypassing sun/shadow/AO — used for the
- *  place ghost, destroy marker, projectiles, and sparkles so effect cubes read as distinct from terrain). */
 export interface CubeInstance {
     x: number;
     y: number;
@@ -37,7 +34,27 @@ export declare class GpuShadowRenderer {
     private overlayBG;
     private overlayScratch;
     private overlayCount;
+    private cullPipe;
+    private cullBGL;
+    private cap;
+    private camArgs;
+    private camVis;
+    private camCull;
+    private camCullBG;
+    private lightArgs;
+    private lightVis;
+    private lightCull;
+    private lightCullBG;
+    private statsBuf;
+    /** Last frame's visible counts (main-pass camera cull, shadow-pass light cull) + total — for IR/telemetry. */
+    lastCull: {
+        total: number;
+        camVisible: number;
+        lightVisible: number;
+    };
     constructor(device: GPUDevice, format: GPUTextureFormat);
+    private makeCullBuf;
+    private makeCullResources;
     private scratch;
     private fill;
     private makeBindGroups;
@@ -48,6 +65,15 @@ export declare class GpuShadowRenderer {
     updateInstances(instances: CubeInstance[]): void;
     /** Translucent overlay cubes drawn over the opaque scene each frame; `emissive` carries per-cube alpha. */
     updateOverlay(instances: CubeInstance[]): void;
+    /** Write a frustum's cull uniform: 6 Gribb-Hartmann planes from `vp` + the live instance count. */
+    private writeCull;
     /** camVP/lightVP: column-major Float32Array(16). sunDir: travel direction. */
     frame(enc: GPUCommandEncoder, colorView: GPUTextureView, sceneDepth: GPUTextureView, camVP: Float32Array, lightVP: Float32Array, sunDir: [number, number, number], sunCol: [number, number, number], ambient: number, load?: boolean): void;
+    /** 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<{
+        total: number;
+        camVisible: number;
+        lightVisible: number;
+    }>;
 }

package/dist/gpuShadow.js

@@ -8,7 +8,12 @@
 // Everything is a cube instance — including the ground (a big flat cube) — so one geometry
 // and one vertex path serve both passes. Per-instance non-uniform scale (vec3) lets the
 // ground be flat while props are boxy.
+/** One cube instance: world position, per-axis scale, a hue (< 0 ⇒ neutral ground), and an optional
+ *  emissive flag (> 0 ⇒ the cube self-glows at full brightness, bypassing sun/shadow/AO — used for the
+ *  place ghost, destroy marker, projectiles, and sparkles so effect cubes read as distinct from terrain). */
+import { frustumPlanes } from './mat4';
 const SHADOW_SIZE = 2048;
+const CULL_WG = 64; // compute-cull workgroup size
 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
@@ -61,19 +66,60 @@ fn hsv(hh: f32) -> vec3<f32> {
   if (h < 5.0) { return vec3(x, 0.0, 1.0); } return vec3(1.0, 0.0, x);
 }
 `;
+// GPU-DRIVEN CULLING. The whole instance buffer stays resident; a compute pass frustum-culls it and compacts the
+// survivors' indices into a `visible` list + an indirect draw's instanceCount. The draw passes then index
+// insts[visible[ii]] and drawIndirect the compacted count — so the vertex shader + rasterizer only ever touch
+// in-frustum cubes. Two culls per frame: the MAIN pass against the CAMERA frustum, the SHADOW pass against the
+// LIGHT (ortho) frustum, so shadows from off-screen occluders stay correct while both passes shrink.
+//
+// The test is an ORIENTED-BOX vs plane separating test (NOT a bounding sphere). Each cube's world extent along a
+// plane normal n is |n·bx|+|n·by|+|n·bz|, where bx/by/bz are the box's rotated semi-axes (0.5·scl rotated by the
+// instance quaternion). This is exact for any size/aspect/rotation — critical because a bounding SPHERE from the
+// centre wrongly culls a big flat cube (a ground plane whose centre sits far behind the camera while the ground
+// underfoot is plainly in view). Mirrors gpuDriven.ts; validated against a CPU box-vs-plane oracle.
+const CULL_WGSL = /* wgsl */ `
+struct Inst { pos: vec4<f32>, scl: vec4<f32>, rot: 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
+@group(0) @binding(0) var<storage, read> insts: array<Inst>;
+@group(0) @binding(1) var<storage, read_write> args: Args;
+@group(0) @binding(2) var<storage, read_write> visible: array<u32>;
+@group(0) @binding(3) var<uniform> cc: CullCam;
+fn qr(q: vec4<f32>, v: vec3<f32>) -> vec3<f32> { let t = 2.0 * cross(q.xyz, v); return v + q.w * t + cross(q.xyz, t); }
+@compute @workgroup_size(${CULL_WG})
+fn cull(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let i = gid.x;
+  if (i >= u32(cc.cnt.x)) { return; }
+  let inst = insts[i];
+  let c = inst.pos.xyz;
+  let h = 0.5 * inst.scl.xyz;
+  let bx = qr(inst.rot, vec3<f32>(h.x, 0.0, 0.0));   // rotated box semi-axes
+  let by = qr(inst.rot, vec3<f32>(0.0, h.y, 0.0));
+  let bz = qr(inst.rot, vec3<f32>(0.0, 0.0, h.z));
+  for (var p = 0u; p < 6u; p++) {
+    let pl = cc.planes[p];
+    let e = abs(dot(pl.xyz, bx)) + abs(dot(pl.xyz, by)) + abs(dot(pl.xyz, bz));   // box half-width along the normal
+    if (dot(pl.xyz, c) + pl.w < -e) { return; }
+  }
+  let slot = atomicAdd(&args.ic, 1u);
+  visible[slot] = i;
+}
+`;
 const SHADOW_WGSL = COMMON_WGSL + /* wgsl */ `
+@group(0) @binding(2) var<storage, read> vis: array<u32>;
 @vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> @builtin(position) vec4<f32> {
-  return cam.lightVP * vec4(worldOf(insts[ii], vi), 1.0);
+  return cam.lightVP * vec4(worldOf(insts[vis[ii]], vi), 1.0);
 }
 `;
 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>;
 
 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> };
 
 @vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VOut {
-  let inst = insts[ii];
+  let inst = insts[vis[ii]];
   let world = worldOf(inst, vi);
   var o: VOut;
   o.clip = cam.camVP * vec4(world, 1.0);
@@ -171,6 +217,21 @@ export class GpuShadowRenderer {
     overlayBG;
     overlayScratch = new Float32Array(OVERLAY_CAP * 12);
     overlayCount = 0;
+    // GPU-driven culling: one compute pipeline; per-frustum (camera + light) indirect args + compacted visible lists.
+    cullPipe;
+    cullBGL;
+    cap = 0;
+    camArgs;
+    camVis;
+    camCull;
+    camCullBG;
+    lightArgs;
+    lightVis;
+    lightCull;
+    lightCullBG;
+    statsBuf; // readback: [camVisible, lightVisible] for the IR/tests
+    /** Last frame's visible counts (main-pass camera cull, shadow-pass light cull) + total — for IR/telemetry. */
+    lastCull = { total: 0, camVisible: 0, lightVisible: 0 };
     constructor(device, format) {
         this.device = device;
         this.camBuf = device.createBuffer({ size: this.cam.byteLength, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
@@ -181,6 +242,7 @@ export class GpuShadowRenderer {
         const shadowBGL = device.createBindGroupLayout({ entries: [
                 { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: 'uniform' } },
                 { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } },
+                { binding: 2, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } }, // light-visible list
             ] });
         this.shadowPipe = device.createRenderPipeline({
             layout: device.createPipelineLayout({ bindGroupLayouts: [shadowBGL] }),
@@ -193,6 +255,7 @@ export class GpuShadowRenderer {
                 { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } },
                 { 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
             ] });
         this.mainPipe = device.createRenderPipeline({
             layout: device.createPipelineLayout({ bindGroupLayouts: [mainBGL] }),
@@ -224,6 +287,44 @@ export class GpuShadowRenderer {
         this.overlayBG = device.createBindGroup({ layout: alphaBGL, entries: [
                 { binding: 0, resource: { buffer: this.camBuf } }, { binding: 1, resource: { buffer: this.overlayBuf } }
             ] });
+        // GPU-driven cull: compute pipeline shared by the camera + light dispatches (each with its own args/vis/uniform).
+        const cullMod = device.createShaderModule({ code: CULL_WGSL });
+        this.cullBGL = device.createBindGroupLayout({ entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'read-only-storage' } }, // insts
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } }, // args (atomic ic)
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } }, // visible list
+                { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'uniform' } }, // planes + count
+            ] });
+        this.cullPipe = device.createComputePipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.cullBGL] }),
+            compute: { module: cullMod, entryPoint: 'cull' },
+        });
+    }
+    // One frustum's cull resources: indirect args (drawIndirect), a compacted visible-index list sized to the
+    // instance capacity, and a small uniform holding the 6 planes + the live instance count.
+    makeCullBuf() {
+        const d = this.device;
+        const args = d.createBuffer({ size: 4 * 4, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC });
+        const vis = d.createBuffer({ size: Math.max(1, this.cap) * 4, usage: GPUBufferUsage.STORAGE });
+        const cull = d.createBuffer({ size: 6 * 16 + 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        const bg = d.createBindGroup({ layout: this.cullBGL, entries: [
+                { binding: 0, resource: { buffer: this.instBuf } }, { binding: 1, resource: { buffer: args } },
+                { binding: 2, resource: { buffer: vis } }, { binding: 3, resource: { buffer: cull } }
+            ] });
+        return { args, vis, cull, bg };
+    }
+    makeCullResources() {
+        const cam = this.makeCullBuf();
+        this.camArgs = cam.args;
+        this.camVis = cam.vis;
+        this.camCull = cam.cull;
+        this.camCullBG = cam.bg;
+        const lit = this.makeCullBuf();
+        this.lightArgs = lit.args;
+        this.lightVis = lit.vis;
+        this.lightCull = lit.cull;
+        this.lightCullBG = lit.bg;
+        this.statsBuf = this.device.createBuffer({ size: 4 * 4 * 2, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
     }
     scratch = new Float32Array(0);
     fill(scratch, instances, n) {
@@ -244,17 +345,21 @@ export class GpuShadowRenderer {
         }
     }
     makeBindGroups() {
+        this.makeCullResources(); // (re)create the cull buffers against the fresh instBuf/cap first — the draw passes bind their visible lists
         this.shadowBG = this.device.createBindGroup({ layout: this.shadowBGL, entries: [
                 { binding: 0, resource: { buffer: this.camBuf } }, { binding: 1, resource: { buffer: this.instBuf } },
+                { binding: 2, resource: { buffer: this.lightVis } },
             ] });
         this.mainBG = this.device.createBindGroup({ layout: this.mainBGL, entries: [
                 { 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 } },
             ] });
     }
     /** 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.fill(this.scratch, instances, this.count);
         this.instBuf = this.device.createBuffer({ size: this.scratch.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
@@ -263,6 +368,7 @@ 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.instBuf = this.device.createBuffer({ size: this.scratch.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
         this.count = 0;
@@ -282,6 +388,19 @@ export class GpuShadowRenderer {
             this.device.queue.writeBuffer(this.overlayBuf, 0, this.overlayScratch, 0, n * 12);
         this.overlayCount = n;
     }
+    /** Write a frustum's cull uniform: 6 Gribb-Hartmann planes from `vp` + the live instance count. */
+    writeCull(buf, vp) {
+        const planes = frustumPlanes(vp);
+        const u = new Float32Array(6 * 4 + 4);
+        for (let p = 0; p < 6; p++) {
+            u[p * 4] = planes[p][0];
+            u[p * 4 + 1] = planes[p][1];
+            u[p * 4 + 2] = planes[p][2];
+            u[p * 4 + 3] = planes[p][3];
+        }
+        u[24] = this.count;
+        this.device.queue.writeBuffer(buf, 0, u);
+    }
     /** camVP/lightVP: column-major Float32Array(16). sunDir: travel direction. */
     frame(enc, colorView, sceneDepth, camVP, lightVP, sunDir, sunCol, ambient, load = false) {
         this.cam.set(camVP, 0);
@@ -295,27 +414,58 @@ export class GpuShadowRenderer {
         this.cam[38] = sunCol[2];
         this.cam[39] = SHADOW_SIZE;
         this.device.queue.writeBuffer(this.camBuf, 0, this.cam);
-        // Pass 1: occluder depth from the sun.
+        // GPU-DRIVEN CULL: reset each frustum's indirect args ([vertexCount=36, instanceCount=0, 0, 0]), then compute-cull
+        // — main pass vs the camera frustum, shadow pass vs the light frustum. Each dispatch atomically compacts its
+        // survivors into a visible list + counts them in instanceCount, which the matching drawIndirect then consumes.
+        const resetArgs = new Uint32Array([36, 0, 0, 0]);
+        this.device.queue.writeBuffer(this.camArgs, 0, resetArgs);
+        this.device.queue.writeBuffer(this.lightArgs, 0, resetArgs);
+        this.writeCull(this.camCull, camVP);
+        this.writeCull(this.lightCull, lightVP);
+        if (this.count > 0) {
+            const cp = enc.beginComputePass();
+            cp.setPipeline(this.cullPipe);
+            cp.setBindGroup(0, this.camCullBG);
+            cp.dispatchWorkgroups(Math.ceil(this.count / CULL_WG));
+            cp.setBindGroup(0, this.lightCullBG);
+            cp.dispatchWorkgroups(Math.ceil(this.count / CULL_WG));
+            cp.end();
+        }
+        // Pass 1: occluder depth from the sun (light-frustum-culled).
         const sp = enc.beginRenderPass({ colorAttachments: [], depthStencilAttachment: {
                 view: this.shadowView, depthClearValue: 1.0, depthLoadOp: 'clear', depthStoreOp: 'store'
             } });
         sp.setPipeline(this.shadowPipe);
         sp.setBindGroup(0, this.shadowBG);
-        sp.draw(36, this.count);
+        sp.drawIndirect(this.lightArgs, 0);
         sp.end();
-        // Pass 2: camera, shadow-sampled.
+        // Pass 2: camera, shadow-sampled (camera-frustum-culled).
         const mp = enc.beginRenderPass({
             colorAttachments: [{ view: colorView, ...(load ? { loadOp: 'load' } : { clearValue: { r: 0.04, g: 0.05, b: 0.07, a: 1 }, loadOp: 'clear' }), storeOp: 'store' }],
             depthStencilAttachment: { view: sceneDepth, ...(load ? { depthLoadOp: 'load' } : { depthClearValue: 1.0, depthLoadOp: 'clear' }), depthStoreOp: 'store' }
         });
         mp.setPipeline(this.mainPipe);
         mp.setBindGroup(0, this.mainBG);
-        mp.draw(36, this.count);
+        mp.drawIndirect(this.camArgs, 0);
         if (this.overlayCount > 0) {
             mp.setPipeline(this.alphaPipe);
             mp.setBindGroup(0, this.overlayBG);
             mp.draw(36, this.overlayCount);
-        } // translucent overlay last
+        } // translucent overlay last (uncapped, no cull)
         mp.end();
+        this.lastCull.total = this.count;
+    }
+    /** Read back the last frame's GPU cull result (camera-visible, light-visible). Does its OWN copy+submit so it's
+     *  safe to call from a live render loop (no per-frame readback cost, no race with the ongoing frames). IR/tests. */
+    async readCullStats() {
+        const enc = this.device.createCommandEncoder();
+        enc.copyBufferToBuffer(this.camArgs, 0, this.statsBuf, 0, 16); // args[1] = instanceCount (the visible count)
+        enc.copyBufferToBuffer(this.lightArgs, 0, this.statsBuf, 16, 16);
+        this.device.queue.submit([enc.finish()]);
+        await this.statsBuf.mapAsync(GPUMapMode.READ);
+        const a = new Uint32Array(this.statsBuf.getMappedRange().slice(0));
+        this.statsBuf.unmap();
+        this.lastCull = { total: this.count, camVisible: a[1], lightVisible: a[5] };
+        return this.lastCull;
     }
 }

package/dist/mat4.d.ts

@@ -12,6 +12,6 @@ export declare function ortho(l: number, r: number, b: number, t: number, n: num
 export declare function lightViewProjection(dir: Vec3, center: Vec3, extent: number, depth: number): Mat4;
 export type Plane = readonly [number, number, number, number];
 /** Extract + normalize the 6 frustum planes from a column-major view-proj (Gribb-Hartmann). */
-export declare function frustumPlanes(m: Mat4): Plane[];
+export declare function frustumPlanes(m: ArrayLike<number>): Plane[];
 /** Sphere vs frustum: false only if the sphere is fully outside any plane. */
 export declare function sphereVisible(planes: Plane[], x: number, y: number, z: number, radius: number): boolean;

package/dist/net/sharedClock.d.ts

@@ -7,8 +7,10 @@ export declare class SharedClock {
     private pinned;
     constructor(tickMs: number, // ms per tick (e.g. 1000/60)
     now: () => number);
-    /** From the server `hello`. */
-    setEpoch(epoch: number): void;
+    /** From the server `hello`. Pass the server's `now` to seed a PROVISIONAL offset so `targetTick()` is roughly
+     *  right immediately — the window between joining and the first ping/pong returning is exactly when lockstep
+     *  clients stamp their first commands, and an offset of 0 there desyncs them. A real ping sample overrides it. */
+    setEpoch(epoch: number, serverNow?: number): void;
     get hasEpoch(): boolean;
     get epochMs(): number;
     /** Feed a ping round-trip: `sentAt` = local ms we sent, `serverNow` = server ms in the pong. Keeps the sample

package/dist/net/sharedClock.js

@@ -17,10 +17,14 @@ export class SharedClock {
         this.tickMs = tickMs;
         this.now = now;
     }
-    /** From the server `hello`. */
-    setEpoch(epoch) {
+    /** From the server `hello`. Pass the server's `now` to seed a PROVISIONAL offset so `targetTick()` is roughly
+     *  right immediately — the window between joining and the first ping/pong returning is exactly when lockstep
+     *  clients stamp their first commands, and an offset of 0 there desyncs them. A real ping sample overrides it. */
+    setEpoch(epoch, serverNow) {
         this.epoch = epoch;
         this.pinned = true;
+        if (serverNow !== undefined && this.bestRtt === Infinity)
+            this.offset = serverNow - this.now();
     }
     get hasEpoch() {
         return this.pinned;

package/package.json

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