ugly-game 0.1.0

package/dist/dmath.d.ts

@@ -0,0 +1,14 @@
+/** Deterministic sine. Quadrant reduction (round + subtract) → polynomial. Bit-identical
+ *  across engines because it uses only +,-,*,/,Math.round (all IEEE/spec-exact). */
+export declare function dsin(x: number): number;
+/** Deterministic cosine. */
+export declare function dcos(x: number): number;
+/** Deterministic tangent. */
+export declare function dtan(x: number): number;
+/** Deterministic 2D length. Math.sqrt IS IEEE-correctly-rounded (identical everywhere),
+ *  unlike Math.hypot whose overflow-avoidance algorithm varies by engine. For engine
+ *  magnitudes (no overflow risk) sqrt(a²+b²) is exact and portable. */
+export declare function dhypot(a: number, b: number): number;
+export declare function dhypot3(a: number, b: number, c: number): number;
+/** Deterministic atan2. Reduces to |ratio| ≤ 1 then a polynomial + quadrant fixup. */
+export declare function datan2(y: number, x: number): number;

package/dist/dmath.js

@@ -0,0 +1,57 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Deterministic math — the ONLY trig/hypot the engine sim may use.
+//
+// WHY: JS `Math.sin/cos/tan/atan2/hypot/exp/log/pow` are NOT bit-identical across JS
+// engines (V8 vs SpiderMonkey vs JavaScriptCore) — they are not required by IEEE-754 to
+// be correctly rounded, so each engine's approximation differs in the low bits. Proven
+// live on /determinism: the pure-JS ECS diverged on Firefox-Android and Safari-iOS.
+// That silently breaks cross-device replay + lockstep — the moat.
+//
+// FIX: implement the transcendentals from ONLY the operations IEEE-754 *does* mandate to
+// be correctly rounded and therefore identical everywhere — `+ - * /`, `Math.sqrt`,
+// `Math.round/floor/abs` (exact, spec-defined). The result is bit-identical on every
+// engine. Enforced by the lint rule + `mathguard.test.mts` (no raw Math.* trig in engine
+// source). See design/engine-build-plan.md, GAME.md §5.1.
+// ─────────────────────────────────────────────────────────────────────────────
+const PI = Math.PI, HALF_PI = PI / 2, INV_HALF_PI = 2 / PI;
+// sin/cos on the reduced range [-π/4, π/4] via Taylor series (error < ~2e-9 there).
+function sinPoly(r) { const r2 = r * r; return r * (1 + r2 * (-1 / 6 + r2 * (1 / 120 + r2 * (-1 / 5040 + r2 * (1 / 362880))))); }
+function cosPoly(r) { const r2 = r * r; return 1 + r2 * (-1 / 2 + r2 * (1 / 24 + r2 * (-1 / 720 + r2 * (1 / 40320)))); }
+/** Deterministic sine. Quadrant reduction (round + subtract) → polynomial. Bit-identical
+ *  across engines because it uses only +,-,*,/,Math.round (all IEEE/spec-exact). */
+export function dsin(x) {
+    const k = Math.round(x * INV_HALF_PI); // nearest π/2 quadrant (Math.round is spec-exact)
+    const r = x - k * HALF_PI; // r ∈ [-π/4, π/4]
+    const q = k & 3; // quadrant 0..3 (correct for negative k too)
+    return q === 0 ? sinPoly(r) : q === 1 ? cosPoly(r) : q === 2 ? -sinPoly(r) : -cosPoly(r);
+}
+/** Deterministic cosine. */
+export function dcos(x) {
+    const k = Math.round(x * INV_HALF_PI);
+    const r = x - k * HALF_PI;
+    const q = k & 3;
+    return q === 0 ? cosPoly(r) : q === 1 ? -sinPoly(r) : q === 2 ? -cosPoly(r) : sinPoly(r);
+}
+/** Deterministic tangent. */
+export function dtan(x) { return dsin(x) / dcos(x); }
+/** Deterministic 2D length. Math.sqrt IS IEEE-correctly-rounded (identical everywhere),
+ *  unlike Math.hypot whose overflow-avoidance algorithm varies by engine. For engine
+ *  magnitudes (no overflow risk) sqrt(a²+b²) is exact and portable. */
+export function dhypot(a, b) { return Math.sqrt(a * a + b * b); }
+export function dhypot3(a, b, c) { return Math.sqrt(a * a + b * b + c * c); }
+// atan on [-1,1] via a minimax polynomial (error < ~2e-6) — only +,-,*,/.
+function atanUnit(z) { const z2 = z * z; return z * (0.9998660 + z2 * (-0.3302995 + z2 * (0.1801410 + z2 * (-0.0851330 + z2 * 0.0208351)))); }
+/** Deterministic atan2. Reduces to |ratio| ≤ 1 then a polynomial + quadrant fixup. */
+export function datan2(y, x) {
+    if (x === 0)
+        return y > 0 ? HALF_PI : y < 0 ? -HALF_PI : 0;
+    const ax = x < 0 ? -x : x, ay = y < 0 ? -y : y;
+    let a; // atan(min/max) ∈ [0, π/4]
+    if (ay <= ax)
+        a = atanUnit(ay / ax);
+    else
+        a = HALF_PI - atanUnit(ax / ay);
+    if (x < 0)
+        a = PI - a;
+    return y < 0 ? -a : a;
+}

package/dist/gpuShadow.d.ts

@@ -0,0 +1,53 @@
+/** 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;
+    z: number;
+    sx: number;
+    sy: number;
+    sz: number;
+    hue: number;
+    emissive?: number;
+    rot?: [number, number, number, number];
+}
+/** The 36-vertex cube as WGSL array-literal bodies (pos + per-face normal). Shared by shadow modules. */
+export declare const CUBE: {
+    pos: string;
+    nrm: string;
+};
+export declare class GpuShadowRenderer {
+    private device;
+    private instBuf;
+    private camBuf;
+    private shadowTex;
+    private shadowView;
+    private shadowPipe;
+    private mainPipe;
+    private shadowBG;
+    private mainBG;
+    private shadowBGL;
+    private mainBGL;
+    private shadowSampler;
+    private count;
+    private cam;
+    private alphaPipe;
+    private overlayBuf;
+    private overlayBG;
+    private overlayScratch;
+    private overlayCount;
+    constructor(device: GPUDevice, format: GPUTextureFormat);
+    private scratch;
+    private fill;
+    private makeBindGroups;
+    /** Static scene: sizes the buffer to exactly these instances. */
+    setScene(instances: CubeInstance[]): void;
+    /** Dynamic scene: pre-allocate for `cap` instances; call updateInstances() each frame. */
+    setCapacity(cap: number): void;
+    updateInstances(instances: CubeInstance[]): void;
+    /** Translucent overlay cubes drawn over the opaque scene each frame; `emissive` carries per-cube alpha. */
+    updateOverlay(instances: CubeInstance[]): void;
+    /** 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;
+}

package/dist/gpuShadow.js

@@ -0,0 +1,315 @@
+// Render IR increment 5 — directional (sun) SHADOW MAPPING. The next rung of the
+// shading program: real cast shadows, the single biggest look upgrade after lighting.
+// Shadows need real depth from the light's POV, so geometry is instanced CUBES (impostors
+// are view-dependent and can't cast a correct shadow from a different view) on a ground
+// plane. Two passes: (1) render occluder depth from the sun's ortho view into a shadow
+// map; (2) main camera pass samples that map (PCF 3×3) to decide lit vs. shadowed.
+//
+// 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.
+const SHADOW_SIZE = 2048;
+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
+// doesn't matter. Positions in [-0.5, 0.5]; flat per-face normals.
+function buildCube() {
+    const faces = [
+        { n: [1, 0, 0], u: [0, 0, 1], v: [0, 1, 0] },
+        { n: [-1, 0, 0], u: [0, 0, 1], v: [0, 1, 0] },
+        { n: [0, 1, 0], u: [1, 0, 0], v: [0, 0, 1] },
+        { n: [0, -1, 0], u: [1, 0, 0], v: [0, 0, 1] },
+        { n: [0, 0, 1], u: [1, 0, 0], v: [0, 1, 0] },
+        { n: [0, 0, -1], u: [1, 0, 0], v: [0, 1, 0] },
+    ];
+    const corners = [[-0.5, -0.5], [0.5, -0.5], [0.5, 0.5], [-0.5, -0.5], [0.5, 0.5], [-0.5, 0.5]];
+    const P = [], Nn = [];
+    for (const f of faces)
+        for (const [cu, cv] of corners) {
+            const x = f.n[0] * 0.5 + f.u[0] * cu + f.v[0] * cv;
+            const y = f.n[1] * 0.5 + f.u[1] * cu + f.v[1] * cv;
+            const z = f.n[2] * 0.5 + f.u[2] * cu + f.v[2] * cv;
+            P.push(`vec3<f32>(${x},${y},${z})`);
+            Nn.push(`vec3<f32>(${f.n[0]},${f.n[1]},${f.n[2]})`);
+        }
+    return { pos: P.join(', '), nrm: Nn.join(', ') };
+}
+/** The 36-vertex cube as WGSL array-literal bodies (pos + per-face normal). Shared by shadow modules. */
+export const CUBE = buildCube();
+// Shared vertex helpers + cube data. cam.sunCol.w carries the shadow-map texel size.
+const COMMON_WGSL = /* wgsl */ `
+struct Cam {
+  camVP: mat4x4<f32>,
+  lightVP: mat4x4<f32>,
+  sun: vec4<f32>,      // xyz = direction light travels, w = ambient
+  sunCol: vec4<f32>,   // xyz = sun colour, w = shadow map size (texels)
+};
+struct Inst { pos: vec4<f32>, scl: vec4<f32>, rot: vec4<f32> };  // pos.w = hue (<0 ⇒ ground) · scl.w = emissive/alpha · rot = quaternion
+@group(0) @binding(0) var<uniform> cam: Cam;
+@group(0) @binding(1) var<storage, read> insts: array<Inst>;
+
+const CUBE_POS = array<vec3<f32>, 36>(${CUBE.pos});
+const CUBE_NRM = array<vec3<f32>, 36>(${CUBE.nrm});
+
+fn qrot(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); }
+fn worldOf(inst: Inst, vi: u32) -> vec3<f32> { return inst.pos.xyz + qrot(inst.rot, CUBE_POS[vi] * inst.scl.xyz); }
+fn hsv(hh: f32) -> vec3<f32> {
+  let h = fract(hh) * 6.0;
+  let x = 1.0 - abs((h % 2.0) - 1.0);
+  if (h < 1.0) { return vec3(1.0, x, 0.0); } if (h < 2.0) { return vec3(x, 1.0, 0.0); }
+  if (h < 3.0) { return vec3(0.0, 1.0, x); } if (h < 4.0) { return vec3(0.0, x, 1.0); }
+  if (h < 5.0) { return vec3(x, 0.0, 1.0); } return vec3(1.0, 0.0, x);
+}
+`;
+const SHADOW_WGSL = COMMON_WGSL + /* wgsl */ `
+@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);
+}
+`;
+const MAIN_WGSL = COMMON_WGSL + /* wgsl */ `
+@group(0) @binding(2) var shadowMap: texture_depth_2d;
+@group(0) @binding(3) var shadowSamp: sampler_comparison;
+
+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 };
+
+@vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VOut {
+  let inst = insts[ii];
+  let world = worldOf(inst, vi);
+  var o: VOut;
+  o.clip = cam.camVP * vec4(world, 1.0);
+  o.world = world;
+  o.nrm = normalize(qrot(inst.rot, CUBE_NRM[vi] / inst.scl.xyz));   // normal under non-uniform scale + rotation
+  o.hue = inst.pos.w;
+  o.emis = inst.scl.w;
+  return o;
+}
+
+// PCF 3×3 sun shadow. Returns 1 = fully lit, 0 = fully shadowed.
+fn shadowFactor(world: vec3<f32>, ndl: f32) -> f32 {
+  let lp = cam.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.0006 * (1.0 - ndl), 0.0004);   // slope-scaled, kills acne on grazing faces
+  let texel = 1.0 / cam.sunCol.w;
+  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;
+}
+
+// Per-block edge darkening (baked AO) — mirrors shared/voxelShade.ts blockShade so a flat face shows its
+// individual voxels instead of reading as one uniform slab. fx,fz ∈ [0,1) within the block face.
+fn blockShade(fx: f32, fz: f32) -> f32 {
+  let edge = min(min(fx, 1.0 - fx), min(fz, 1.0 - fz));
+  let t = clamp(edge / 0.17, 0.0, 1.0);
+  return 0.6 + 0.4 * (t * t * (3.0 - 2.0 * t));
+}
+@fragment fn fs(i: VOut) -> @location(0) vec4<f32> {
+  if (i.emis > 0.5) {                                  // self-glowing effect cube: full-bright, unlit
+    let g = mix(hsv(i.hue), vec3(1.0), 0.4);
+    return vec4(pow(clamp(g, vec3(0.0), vec3(1.0)), vec3(0.4545)), 1.0);
+  }
+  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 world axes not along the (axis-aligned) face normal
+  let an = abs(N);
+  var fx: f32; var fz: f32;
+  if (an.y >= an.x && an.y >= an.z) { fx = fract(i.world.x); fz = fract(i.world.z); }
+  else if (an.x >= an.z) { fx = fract(i.world.y); fz = fract(i.world.z); }
+  else { fx = fract(i.world.x); fz = fract(i.world.y); }
+  let ao = blockShade(fx, fz);
+  let lit = base * (cam.sun.w + cam.sunCol.xyz * ndl * sh) * ao;
+  return vec4(pow(clamp(lit, vec3(0.0), vec3(1.0)), vec3(0.4545)), 1.0);  // gamma
+}
+`;
+// Translucent OVERLAY pass — full-size, alpha-blended cubes drawn over the opaque scene with depth test but
+// no depth write (so they don't occlude each other or the world behind). scl.w carries the ALPHA (0..1).
+// Used for the place ghost: a full-size, low-opacity preview of the block that will materialize.
+const ALPHA_WGSL = COMMON_WGSL + /* wgsl */ `
+struct AOut { @builtin(position) clip: vec4<f32>, @location(0) hue: f32, @location(1) a: f32 };
+@vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> AOut {
+  let inst = insts[ii];
+  var o: AOut;
+  o.clip = cam.camVP * vec4(worldOf(inst, vi), 1.0);
+  o.hue = inst.pos.w; o.a = inst.scl.w;
+  return o;
+}
+@fragment fn fs(i: AOut) -> @location(0) vec4<f32> {
+  let g = mix(hsv(i.hue), vec3(1.0), 0.28);
+  return vec4(pow(clamp(g, vec3(0.0), vec3(1.0)), vec3(0.4545)), i.a);
+}
+`;
+export class GpuShadowRenderer {
+    device;
+    instBuf;
+    camBuf;
+    shadowTex;
+    shadowView;
+    shadowPipe;
+    mainPipe;
+    shadowBG;
+    mainBG;
+    shadowBGL;
+    mainBGL;
+    shadowSampler;
+    count = 0;
+    cam = new Float32Array(40); // 2×mat4 + 2×vec4
+    alphaPipe;
+    overlayBuf;
+    overlayBG;
+    overlayScratch = new Float32Array(OVERLAY_CAP * 12);
+    overlayCount = 0;
+    constructor(device, format) {
+        this.device = device;
+        this.camBuf = device.createBuffer({ size: this.cam.byteLength, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.shadowTex = device.createTexture({ size: [SHADOW_SIZE, SHADOW_SIZE], format: 'depth32float', usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING });
+        this.shadowView = this.shadowTex.createView();
+        const shadowMod = device.createShaderModule({ code: SHADOW_WGSL });
+        const mainMod = device.createShaderModule({ code: MAIN_WGSL });
+        const shadowBGL = device.createBindGroupLayout({ entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: 'uniform' } },
+                { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } },
+            ] });
+        this.shadowPipe = device.createRenderPipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [shadowBGL] }),
+            vertex: { module: shadowMod, entryPoint: 'vs' },
+            primitive: { topology: 'triangle-list', cullMode: 'none' },
+            depthStencil: { format: 'depth32float', depthWriteEnabled: true, depthCompare: 'less' },
+        });
+        const mainBGL = 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, texture: { sampleType: 'depth' } },
+                { binding: 3, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'comparison' } },
+            ] });
+        this.mainPipe = device.createRenderPipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [mainBGL] }),
+            vertex: { module: mainMod, entryPoint: 'vs' },
+            fragment: { module: mainMod, entryPoint: 'fs', targets: [{ format }] },
+            primitive: { topology: 'triangle-list', cullMode: 'none' }, // cube winding isn't per-face outward; depth test handles overdraw
+            depthStencil: { format: 'depth24plus', depthWriteEnabled: true, depthCompare: 'less' },
+        });
+        this.shadowBGL = shadowBGL;
+        this.mainBGL = mainBGL;
+        this.shadowSampler = device.createSampler({ compare: 'less', magFilter: 'linear', minFilter: 'linear' });
+        // translucent overlay: alpha-blended, depth-tested but not depth-writing (drawn after opaque)
+        const alphaMod = device.createShaderModule({ code: ALPHA_WGSL });
+        const alphaBGL = device.createBindGroupLayout({ entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: 'uniform' } },
+                { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } },
+            ] });
+        this.alphaPipe = device.createRenderPipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [alphaBGL] }),
+            vertex: { module: alphaMod, entryPoint: 'vs' },
+            fragment: { module: alphaMod, entryPoint: 'fs', targets: [{ format, blend: {
+                            color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' }
+                        } }] },
+            primitive: { topology: 'triangle-list', cullMode: 'none' },
+            depthStencil: { format: 'depth24plus', depthWriteEnabled: false, depthCompare: 'less' },
+        });
+        this.overlayBuf = device.createBuffer({ size: this.overlayScratch.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+        this.overlayBG = device.createBindGroup({ layout: alphaBGL, entries: [
+                { binding: 0, resource: { buffer: this.camBuf } }, { binding: 1, resource: { buffer: this.overlayBuf } }
+            ] });
+    }
+    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;
+            scratch[o] = c.x;
+            scratch[o + 1] = c.y;
+            scratch[o + 2] = c.z;
+            scratch[o + 3] = c.hue;
+            scratch[o + 4] = c.sx;
+            scratch[o + 5] = c.sy;
+            scratch[o + 6] = c.sz;
+            scratch[o + 7] = c.emissive ?? 0;
+            scratch[o + 8] = r ? r[0] : 0;
+            scratch[o + 9] = r ? r[1] : 0;
+            scratch[o + 10] = r ? r[2] : 0;
+            scratch[o + 11] = r ? r[3] : 1; // quaternion, default identity
+        }
+    }
+    makeBindGroups() {
+        this.shadowBG = this.device.createBindGroup({ layout: this.shadowBGL, entries: [
+                { binding: 0, resource: { buffer: this.camBuf } }, { binding: 1, resource: { buffer: this.instBuf } },
+            ] });
+        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 },
+            ] });
+    }
+    /** Static scene: sizes the buffer to exactly these instances. */
+    setScene(instances) {
+        this.count = instances.length;
+        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 });
+        this.device.queue.writeBuffer(this.instBuf, 0, this.scratch);
+        this.makeBindGroups();
+    }
+    /** Dynamic scene: pre-allocate for `cap` instances; call updateInstances() each frame. */
+    setCapacity(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;
+        this.makeBindGroups();
+    }
+    updateInstances(instances) {
+        const n = Math.min(instances.length, this.scratch.length / 12);
+        this.fill(this.scratch, instances, n);
+        this.device.queue.writeBuffer(this.instBuf, 0, this.scratch, 0, n * 12);
+        this.count = n;
+    }
+    /** Translucent overlay cubes drawn over the opaque scene each frame; `emissive` carries per-cube alpha. */
+    updateOverlay(instances) {
+        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.overlayCount = n;
+    }
+    /** 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);
+        this.cam.set(lightVP, 16);
+        this.cam[32] = sunDir[0];
+        this.cam[33] = sunDir[1];
+        this.cam[34] = sunDir[2];
+        this.cam[35] = ambient;
+        this.cam[36] = sunCol[0];
+        this.cam[37] = sunCol[1];
+        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.
+        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.end();
+        // Pass 2: camera, shadow-sampled.
+        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);
+        if (this.overlayCount > 0) {
+            mp.setPipeline(this.alphaPipe);
+            mp.setBindGroup(0, this.overlayBG);
+            mp.draw(36, this.overlayCount);
+        } // translucent overlay last
+        mp.end();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './dmath';
+export * from './mat4';
+export * from './noise';
+export * from './moat';
+export * from './gpuShadow';
+export * from './input/resolve';
+export * from './input/browserBackend';
+export * from './input/ControlHints';
+export * from './input/TouchControls';

package/dist/index.js

@@ -0,0 +1,11 @@
+// ugly-game — the reusable game platform (renderer, input system, math, noise, deterministic moat).
+// Games (all-mine-sky, the demo) depend on this package instead of copy-lifting these modules.
+export * from './dmath';
+export * from './mat4';
+export * from './noise';
+export * from './moat';
+export * from './gpuShadow';
+export * from './input/resolve';
+export * from './input/browserBackend';
+export * from './input/ControlHints';
+export * from './input/TouchControls';

package/dist/input/ControlHints.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import { type Device, type ControlDesc, type InputMode } from './resolve';
+export interface ControlHint {
+    keys: string[];
+    label: string;
+}
+export type HintCorner = 'bottom' | 'bottom-left' | 'top-left';
+/** Pretty label for a raw KeyboardEvent.code (KeyW→W, ArrowUp→↑, Space→Space, ShiftLeft→Shift, …). */
+export declare function prettyKey(code: string): string;
+/** Turn control descriptors into display hints for one device (drops fields with no binding on that device).
+ *  Fields that share a label are MERGED into one hint (e.g. mv+strafe both "move" → one "W A S D move"). */
+export declare function deviceHints(descs: ControlDesc[], device: Device): ControlHint[];
+/** The device the player is currently using — updates live on keydown/mouse (desktop), touchstart (touch),
+ *  or gamepad activity (gamepad). Last deliberate input wins, so the hints always match what's in hand. */
+export declare function useActiveDevice(): Device;
+type Props = {
+    corner?: HintCorner;
+    compact?: boolean;
+    showDevice?: boolean;
+} & ({
+    hints: ControlHint[];
+} | {
+    mode: InputMode<unknown>;
+    labels?: Record<string, string> | undefined;
+    order?: string[] | undefined;
+});
+/** The standardized overlay. Give it a `mode` (+labels) to derive device-aware hints, or an explicit list. */
+export declare function ControlHints(props: Props): React.JSX.Element;
+export {};

package/dist/input/ControlHints.js

@@ -0,0 +1,112 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { describeControls } from './resolve';
+/** Pretty label for a raw KeyboardEvent.code (KeyW→W, ArrowUp→↑, Space→Space, ShiftLeft→Shift, …). */
+export function prettyKey(code) {
+    if (code.startsWith('Key'))
+        return code.slice(3);
+    if (code.startsWith('Digit'))
+        return code.slice(5);
+    const map = {
+        ArrowUp: '↑', ArrowDown: '↓', ArrowLeft: '←', ArrowRight: '→',
+        Space: 'Space', ShiftLeft: 'Shift', ShiftRight: 'Shift', ControlLeft: 'Ctrl', ControlRight: 'Ctrl',
+        Enter: 'Enter', Escape: 'Esc', Tab: 'Tab',
+    };
+    return map[code] ?? code;
+}
+// W3C Standard Gamepad button/axis names.
+const GP_BTN = { 0: 'A', 1: 'B', 2: 'X', 3: 'Y', 4: 'LB', 5: 'RB', 6: 'LT', 7: 'RT', 8: 'Back', 9: 'Start', 10: 'L3', 11: 'R3', 12: '↑', 13: '↓', 14: '←', 15: '→' };
+const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+/** The label to show for one binding on a given device, or null if that binding isn't for this device. */
+function token(ref, device) {
+    if (device === 'desktop') {
+        if (ref.dev === 'key')
+            return prettyKey(ref.code);
+        if (ref.dev === 'pointer' || ref.dev === 'pointerButton')
+            return 'Mouse';
+        return null;
+    }
+    if (device === 'gamepad') {
+        if (ref.dev === 'gpButton')
+            return GP_BTN[ref.button] ?? `B${ref.button}`;
+        if (ref.dev === 'gpAxis')
+            return ref.axis < 2 ? 'L-Stick' : 'R-Stick';
+        return null;
+    }
+    if (ref.dev === 'touchButton')
+        return ref.id.toUpperCase();
+    if (ref.dev === 'touchAxis')
+        return cap(ref.id) + ' pad';
+    return null;
+}
+const uniq = (a) => [...new Set(a)];
+/** Turn control descriptors into display hints for one device (drops fields with no binding on that device).
+ *  Fields that share a label are MERGED into one hint (e.g. mv+strafe both "move" → one "W A S D move"). */
+export function deviceHints(descs, device) {
+    const byLabel = new Map();
+    const order = [];
+    for (const d of descs) {
+        if (!d.label)
+            continue;
+        const keys = uniq(d.bindings.map((b) => token(b, device)).filter((x) => x !== null));
+        if (keys.length === 0)
+            continue;
+        if (!byLabel.has(d.label)) {
+            byLabel.set(d.label, []);
+            order.push(d.label);
+        }
+        const arr = byLabel.get(d.label);
+        for (const k of keys)
+            if (!arr.includes(k))
+                arr.push(k);
+    }
+    return order.map((label) => ({ keys: byLabel.get(label), label }));
+}
+/** The device the player is currently using — updates live on keydown/mouse (desktop), touchstart (touch),
+ *  or gamepad activity (gamepad). Last deliberate input wins, so the hints always match what's in hand. */
+export function useActiveDevice() {
+    const [dev, setDev] = React.useState(() => {
+        if (typeof navigator !== 'undefined' && navigator.getGamepads().some((p) => p))
+            return 'gamepad'; // a pad is already plugged in → show its controls
+        if (typeof navigator !== 'undefined' && navigator.maxTouchPoints > 0 && !(typeof matchMedia !== 'undefined' && matchMedia('(pointer:fine)').matches))
+            return 'touch';
+        return 'desktop';
+    });
+    React.useEffect(() => {
+        const desktop = () => { setDev('desktop'); }, touch = () => { setDev('touch'); }, gamepad = () => { setDev('gamepad'); };
+        window.addEventListener('keydown', desktop);
+        window.addEventListener('mousedown', desktop);
+        window.addEventListener('touchstart', touch);
+        window.addEventListener('gamepadconnected', gamepad);
+        let raf = 0;
+        const poll = () => {
+            const pads = navigator.getGamepads();
+            for (const p of pads) {
+                if (p && (p.buttons.some((b) => b.pressed) || p.axes.some((a) => Math.abs(a) > 0.5))) {
+                    setDev('gamepad');
+                    break;
+                }
+            }
+            raf = requestAnimationFrame(poll);
+        };
+        raf = requestAnimationFrame(poll);
+        return () => { window.removeEventListener('keydown', desktop); window.removeEventListener('mousedown', desktop); window.removeEventListener('touchstart', touch); window.removeEventListener('gamepadconnected', gamepad); cancelAnimationFrame(raf); };
+    }, []);
+    return dev;
+}
+const POS = {
+    'bottom': { bottom: 14, left: '50%', transform: 'translateX(-50%)' },
+    'bottom-left': { bottom: 14, left: 14 },
+    'top-left': { top: 14, left: 14 },
+};
+const DEVICE_LABEL = { desktop: 'keyboard', gamepad: 'gamepad', touch: 'touch' };
+/** The standardized overlay. Give it a `mode` (+labels) to derive device-aware hints, or an explicit list. */
+export function ControlHints(props) {
+    const device = useActiveDevice();
+    const hints = 'hints' in props ? props.hints : deviceHints(describeControls(props.mode, props.labels ?? {}, props.order), device);
+    const { corner = 'bottom', compact = false, showDevice = false } = props;
+    return (_jsxs("div", { style: { position: 'absolute', zIndex: 5, ...POS[corner], display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: compact ? 8 : 12, justifyContent: 'center',
+            maxWidth: '92%', padding: '7px 12px', borderRadius: 10, background: 'rgba(6,12,20,0.55)', backdropFilter: 'blur(3px)',
+            fontFamily: 'ui-monospace, Menlo, monospace', fontSize: compact ? 11 : 12.5, color: '#e6edf5', pointerEvents: 'none', userSelect: 'none' }, children: [showDevice && !('hints' in props) && _jsx("span", { style: { fontSize: 10, opacity: 0.55, textTransform: 'uppercase', letterSpacing: 0.5 }, children: DEVICE_LABEL[device] }), hints.map((h) => (_jsxs("span", { style: { display: 'inline-flex', alignItems: 'center', gap: 5, whiteSpace: 'nowrap' }, children: [h.keys.map((k) => _jsx("kbd", { style: { display: 'inline-block', minWidth: k.length > 1 ? undefined : 18, padding: '1px 6px', borderRadius: 5,
+                            background: 'rgba(255,255,255,0.12)', border: '1px solid rgba(255,255,255,0.28)', boxShadow: '0 1px 0 rgba(0,0,0,0.4)', fontWeight: 700, textAlign: 'center' }, children: k }, k)), _jsx("span", { style: { opacity: 0.85 }, children: h.label })] }, h.label)))] }));
+}

package/dist/input/TouchControls.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import type { BrowserRawBackend } from './browserBackend';
+export interface StickCfg {
+    id: string;
+    side: 'left' | 'right';
+    label?: string;
+}
+export interface BtnCfg {
+    id: string;
+    label: string;
+}
+export declare function TouchControls({ backendRef, sticks, buttons }: {
+    backendRef: React.RefObject<BrowserRawBackend | null>;
+    sticks?: StickCfg[];
+    buttons?: BtnCfg[];
+}): React.JSX.Element;