ugly-game 0.3.0 → 0.4.0

package/dist/assets/geometry.js

@@ -0,0 +1,134 @@
+// Geometry wire codec (design/asset-streaming.md §0/§1): positions + UVs are QUANTIZED to 16-bit
+// within a per-mesh AABB, then run through the meshopt vertex codec. Quantizing first is the real
+// size lever — the meshopt delta-coder compresses integers far better than float32 mantissas (whose
+// low bits are high-entropy noise), and 16-bit across a model-scale AABB is sub-0.1mm, visually
+// exact. A small float32 AABB prepends each payload so the chunk self-describes; decode dequantizes
+// back to float32 so the GPU/render path is unchanged. Encode is offline, decode runs in-browser;
+// both live here because meshoptimizer's WASM runs in Node and the browser.
+import { MeshoptEncoder, MeshoptDecoder } from 'meshoptimizer';
+const POS_STRIDE = 8; // 4 × uint16 (x,y,z + pad) — meshopt requires stride % 4 == 0; the constant
+// pad channel costs ~nothing after encoding.
+const AABB_BYTES = 24; // 6 × float32: min.xyz, max.xyz, prepended to the vtx payload.
+const quant = (v, lo, hi) => hi > lo ? Math.max(0, Math.min(65535, Math.round((v - lo) / (hi - lo) * 65535))) : 0;
+function bounds3(p) {
+    let a = Infinity, b = Infinity, c = Infinity, d = -Infinity, e = -Infinity, f = -Infinity;
+    for (let i = 0; i < p.length; i += 3) {
+        const x = p[i], y = p[i + 1], z = p[i + 2];
+        if (x < a)
+            a = x;
+        if (y < b)
+            b = y;
+        if (z < c)
+            c = z;
+        if (x > d)
+            d = x;
+        if (y > e)
+            e = y;
+        if (z > f)
+            f = z;
+    }
+    return [a, b, c, d, e, f];
+}
+// Compact a mesh (+ optional parallel per-vertex UV) to only the vertices its index buffer
+// references, remapping indices to first-encounter order. A simplified LOD references a subset of
+// the source vertices; without this each LOD re-stores the FULL vertex buffer (design/asset-
+// streaming.md §3). Positions and UVs are remapped with the SAME table so they stay aligned. NOTE:
+// this REORDERS vertices, so it must NOT be applied to a mesh whose per-vertex skin (SKEL) is kept
+// separately — only compact LODs that carry no external per-vertex data (i.e. not the finest/skinned LOD).
+export function compactMesh(positions, indices, uvs) {
+    const remap = new Int32Array(positions.length / 3).fill(-1);
+    const outIdx = new Uint32Array(indices.length);
+    const posOut = [], uvOut = [];
+    for (let i = 0; i < indices.length; i++) {
+        const o = indices[i];
+        let n = remap[o];
+        if (n < 0) {
+            n = posOut.length / 3;
+            remap[o] = n;
+            posOut.push(positions[o * 3], positions[o * 3 + 1], positions[o * 3 + 2]);
+            if (uvs)
+                uvOut.push(uvs[o * 2], uvs[o * 2 + 1]);
+        }
+        outIdx[i] = n;
+    }
+    return uvs ? { positions: Float32Array.from(posOut), indices: outIdx, uvs: Float32Array.from(uvOut) } : { positions: Float32Array.from(posOut), indices: outIdx };
+}
+export async function encodeGeometry(m) {
+    await MeshoptEncoder.ready;
+    const vertexCount = m.positions.length / 3;
+    const [minx, miny, minz, maxx, maxy, maxz] = bounds3(m.positions);
+    const q = new Uint16Array(vertexCount * 4);
+    for (let i = 0; i < vertexCount; i++) {
+        q[i * 4] = quant(m.positions[i * 3], minx, maxx);
+        q[i * 4 + 1] = quant(m.positions[i * 3 + 1], miny, maxy);
+        q[i * 4 + 2] = quant(m.positions[i * 3 + 2], minz, maxz);
+    }
+    const enc = MeshoptEncoder.encodeVertexBuffer(new Uint8Array(q.buffer), vertexCount, POS_STRIDE);
+    const vtx = new Uint8Array(AABB_BYTES + enc.length);
+    new Float32Array(vtx.buffer, 0, 6).set([minx, miny, minz, maxx, maxy, maxz]);
+    vtx.set(enc, AABB_BYTES);
+    const idx = MeshoptEncoder.encodeIndexBuffer(new Uint8Array(m.indices.buffer, m.indices.byteOffset, m.indices.byteLength), m.indices.length, 4);
+    return { vtx, idx, vertexCount, indexCount: m.indices.length };
+}
+export async function decodeGeometry(enc) {
+    await MeshoptDecoder.ready;
+    const aabb = new Float32Array(enc.vtx.slice(0, AABB_BYTES).buffer); // slice → aligned copy
+    const [minx, miny, minz, maxx, maxy, maxz] = aabb;
+    const qBytes = new Uint8Array(enc.vertexCount * POS_STRIDE);
+    MeshoptDecoder.decodeVertexBuffer(qBytes, enc.vertexCount, POS_STRIDE, enc.vtx.subarray(AABB_BYTES));
+    const q = new Uint16Array(qBytes.buffer);
+    const positions = new Float32Array(enc.vertexCount * 3);
+    const dx = (maxx - minx) / 65535, dy = (maxy - miny) / 65535, dz = (maxz - minz) / 65535;
+    for (let i = 0; i < enc.vertexCount; i++) {
+        positions[i * 3] = minx + q[i * 4] * dx;
+        positions[i * 3 + 1] = miny + q[i * 4 + 1] * dy;
+        positions[i * 3 + 2] = minz + q[i * 4 + 2] * dz;
+    }
+    const idxBytes = new Uint8Array(enc.indexCount * 4);
+    MeshoptDecoder.decodeIndexBuffer(idxBytes, enc.indexCount, 4, enc.idx);
+    return { positions, indices: new Uint32Array(idxBytes.buffer, idxBytes.byteOffset, enc.indexCount) };
+}
+// ── UV (TEXCOORD_0): 16-bit quantized within its 2D bounds, meshopt-encoded, shared across LODs ──
+const UV_STRIDE = 4; // 2 × uint16
+const UVB_BYTES = 16; // 4 × float32: minU, minV, maxU, maxV
+export async function encodeUV(uvs) {
+    await MeshoptEncoder.ready;
+    const n = uvs.length / 2;
+    let minu = Infinity, minv = Infinity, maxu = -Infinity, maxv = -Infinity;
+    for (let i = 0; i < n; i++) {
+        const u = uvs[i * 2], v = uvs[i * 2 + 1];
+        if (u < minu)
+            minu = u;
+        if (v < minv)
+            minv = v;
+        if (u > maxu)
+            maxu = u;
+        if (v > maxv)
+            maxv = v;
+    }
+    const q = new Uint16Array(n * 2);
+    for (let i = 0; i < n; i++) {
+        q[i * 2] = quant(uvs[i * 2], minu, maxu);
+        q[i * 2 + 1] = quant(uvs[i * 2 + 1], minv, maxv);
+    }
+    const enc = MeshoptEncoder.encodeVertexBuffer(new Uint8Array(q.buffer), n, UV_STRIDE);
+    const out = new Uint8Array(UVB_BYTES + enc.length);
+    new Float32Array(out.buffer, 0, 4).set([minu, minv, maxu, maxv]);
+    out.set(enc, UVB_BYTES);
+    return out;
+}
+export async function decodeUV(bytes, vertexCount) {
+    await MeshoptDecoder.ready;
+    const b = new Float32Array(bytes.slice(0, UVB_BYTES).buffer);
+    const [minu, minv, maxu, maxv] = b;
+    const qBytes = new Uint8Array(vertexCount * UV_STRIDE);
+    MeshoptDecoder.decodeVertexBuffer(qBytes, vertexCount, UV_STRIDE, bytes.subarray(UVB_BYTES));
+    const q = new Uint16Array(qBytes.buffer);
+    const out = new Float32Array(vertexCount * 2);
+    const du = (maxu - minu) / 65535, dv = (maxv - minv) / 65535;
+    for (let i = 0; i < vertexCount; i++) {
+        out[i * 2] = minu + q[i * 2] * du;
+        out[i * 2 + 1] = minv + q[i * 2 + 1] * dv;
+    }
+    return out;
+}

package/dist/assets/gpuSkin.d.ts

@@ -0,0 +1,21 @@
+export interface SkinCreature {
+    rest: Float32Array;
+    normals: Float32Array;
+    joints: Uint16Array;
+    weights: Float32Array;
+    colors: Float32Array;
+    indices: Uint32Array;
+    palette: Float32Array;
+    model: Float32Array;
+}
+export declare class GpuSkinRenderer {
+    private device;
+    private skinPipe;
+    private drawPipe;
+    private packed;
+    constructor(device: GPUDevice, format: GPUTextureFormat);
+    setCreatures(list: SkinCreature[]): void;
+    /** Deform + draw every creature with the shared scene lighting. load=true composites over the world;
+     *  otherwise clears to `clear`. sun/sunCol/amb/cam/fog/fogDensity match the terrain & prop renderers. */
+    frame(enc: GPUCommandEncoder, colorView: GPUTextureView, depthView: GPUTextureView, camVP: Float32Array, sunDir: [number, number, number], sunCol: [number, number, number], amb: [number, number, number], camPos: [number, number, number], fog: [number, number, number], fogDensity: number, clear: [number, number, number], load?: boolean): void;
+}

package/dist/assets/gpuSkin.js

@@ -0,0 +1,148 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// GPU SKIN — a reusable WebGPU renderer for skinned creatures (PLATFORM). A compute pass deforms the
+// rest mesh (AND its normals) by each creature's bone palette; the render pass draws them with the SAME
+// lighting model as the terrain/prop renderers — sun lambert on smooth per-vertex normals + ambient +
+// distance fog — so creatures sit in the scene consistently instead of looking flat/mismatched.
+// ─────────────────────────────────────────────────────────────────────────────
+const SKIN = /* wgsl */ `
+@group(0) @binding(0) var<storage,read> rest: array<vec4f>;
+@group(0) @binding(1) var<storage,read> joints: array<vec4u>;
+@group(0) @binding(2) var<storage,read> weights: array<vec4f>;
+@group(0) @binding(3) var<storage,read> palette: array<mat4x4f>;
+@group(0) @binding(4) var<storage,read_write> deformed: array<vec4f>;
+@group(0) @binding(5) var<uniform> P: vec4u;
+@group(0) @binding(6) var<storage,read> restN: array<vec4f>;
+@group(0) @binding(7) var<storage,read_write> defN: array<vec4f>;
+fn rot(m: mat4x4f, v: vec3f) -> vec3f { return mat3x3f(m[0].xyz, m[1].xyz, m[2].xyz) * v; }
+@compute @workgroup_size(64) fn main(@builtin(global_invocation_id) g: vec3u){
+  let i=g.x; if(i>=P.x){return;} let p=vec4f(rest[i].xyz,1.0); let j=joints[i]; let w=weights[i]; let nn=restN[i].xyz;
+  var a=vec4f(0.0); a+=w.x*(palette[j.x]*p); a+=w.y*(palette[j.y]*p); a+=w.z*(palette[j.z]*p); a+=w.w*(palette[j.w]*p);
+  var b=vec3f(0.0); b+=w.x*rot(palette[j.x],nn); b+=w.y*rot(palette[j.y],nn); b+=w.z*rot(palette[j.z],nn); b+=w.w*rot(palette[j.w],nn);
+  deformed[i]=vec4f(a.xyz,1.0); defN[i]=vec4f(normalize(b),0.0);
+}`;
+const DRAW = /* wgsl */ `
+struct U { mvp: mat4x4<f32>, sun: vec4<f32>, sunCol: vec4<f32>, amb: vec4<f32>, cam: vec4<f32>, fog: vec4<f32> };
+@group(0) @binding(0) var<uniform> u: U;
+struct VOut { @builtin(position) pos: vec4<f32>, @location(0) world: vec3<f32>, @location(1) col: vec3<f32>, @location(2) n: vec3<f32> };
+@vertex fn vs(@location(0) p: vec3<f32>, @location(1) c: vec3<f32>, @location(2) nrm: vec3<f32>) -> VOut { var o: VOut; o.pos=u.mvp*vec4(p,1.0); o.world=p; o.col=c; o.n=nrm; return o; }
+@fragment fn fs(i: VOut) -> @location(0) vec4<f32> {
+  let d = clamp(dot(normalize(i.n), -normalize(u.sun.xyz)), 0.0, 1.0);
+  let lit = i.col * (u.amb.xyz + d * u.sunCol.xyz);
+  let dist = length(i.world - u.cam.xyz);
+  let f = clamp(1.0 - exp(-dist * u.fog.w), 0.0, 1.0);
+  return vec4(mix(lit, u.fog.xyz, f), 1.0);
+}`;
+export class GpuSkinRenderer {
+    device;
+    skinPipe;
+    drawPipe;
+    packed = [];
+    constructor(device, format) {
+        this.device = device;
+        const sm = device.createShaderModule({ code: SKIN });
+        this.skinPipe = device.createComputePipeline({ layout: 'auto', compute: { module: sm, entryPoint: 'main' } });
+        const dm = device.createShaderModule({ code: DRAW });
+        this.drawPipe = device.createRenderPipeline({
+            layout: 'auto',
+            vertex: { module: dm, entryPoint: 'vs', buffers: [
+                    { arrayStride: 16, attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }] },
+                    { arrayStride: 12, attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x3' }] },
+                    { arrayStride: 16, attributes: [{ shaderLocation: 2, offset: 0, format: 'float32x3' }] }
+                ] },
+            fragment: { module: dm, entryPoint: 'fs', targets: [{ format }] },
+            primitive: { topology: 'triangle-list', cullMode: 'none' },
+            depthStencil: { format: 'depth24plus', depthWriteEnabled: true, depthCompare: 'less' },
+        });
+    }
+    setCreatures(list) {
+        const dev = this.device, U = GPUBufferUsage;
+        for (const p of this.packed) {
+            p.defB.destroy();
+            p.defNB.destroy();
+            p.colB.destroy();
+            p.idxB.destroy();
+            p.uBuf.destroy();
+            p.palB.destroy();
+        }
+        this.packed = list.map((c) => {
+            const n = c.rest.length / 3;
+            const rest = new Float32Array(n * 4), restN = new Float32Array(n * 4), joints = new Uint32Array(n * 4), weights = new Float32Array(n * 4);
+            for (let i = 0; i < n; i++) {
+                rest[i * 4] = c.rest[i * 3];
+                rest[i * 4 + 1] = c.rest[i * 3 + 1];
+                rest[i * 4 + 2] = c.rest[i * 3 + 2];
+                rest[i * 4 + 3] = 1;
+                restN[i * 4] = c.normals[i * 3];
+                restN[i * 4 + 1] = c.normals[i * 3 + 1];
+                restN[i * 4 + 2] = c.normals[i * 3 + 2];
+            }
+            for (let i = 0; i < n * 4; i++) {
+                joints[i] = c.joints[i];
+                weights[i] = c.weights[i];
+            }
+            const mk = (d, u) => { const b = dev.createBuffer({ size: d.byteLength, usage: u }); dev.queue.writeBuffer(b, 0, d); return b; };
+            const restB = mk(rest, U.STORAGE | U.COPY_DST), restNB = mk(restN, U.STORAGE | U.COPY_DST), jointsB = mk(joints, U.STORAGE | U.COPY_DST), weightsB = mk(weights, U.STORAGE | U.COPY_DST);
+            const colB = mk(c.colors, U.VERTEX | U.COPY_DST), idxB = mk(c.indices, U.INDEX | U.COPY_DST);
+            const palB = dev.createBuffer({ size: c.palette.length * 4, usage: U.STORAGE | U.COPY_DST });
+            dev.queue.writeBuffer(palB, 0, c.palette);
+            const defB = dev.createBuffer({ size: n * 16, usage: U.STORAGE | U.VERTEX }), defNB = dev.createBuffer({ size: n * 16, usage: U.STORAGE | U.VERTEX });
+            const pB = dev.createBuffer({ size: 16, usage: U.UNIFORM | U.COPY_DST });
+            dev.queue.writeBuffer(pB, 0, new Uint32Array([n, 0, 0, 0]));
+            const skinBG = dev.createBindGroup({ layout: this.skinPipe.getBindGroupLayout(0), entries: [
+                    { binding: 0, resource: { buffer: restB } }, { binding: 1, resource: { buffer: jointsB } }, { binding: 2, resource: { buffer: weightsB } },
+                    { binding: 3, resource: { buffer: palB } }, { binding: 4, resource: { buffer: defB } }, { binding: 5, resource: { buffer: pB } },
+                    { binding: 6, resource: { buffer: restNB } }, { binding: 7, resource: { buffer: defNB } }
+                ] });
+            const uBuf = dev.createBuffer({ size: 96 + 16 * 5, usage: U.UNIFORM | U.COPY_DST });
+            const uBG = dev.createBindGroup({ layout: this.drawPipe.getBindGroupLayout(0), entries: [{ binding: 0, resource: { buffer: uBuf } }] });
+            return { defB, defNB, colB, idxB, idxCount: c.indices.length, skinBG, uBuf, uBG, palB, n, model: c.model };
+        });
+    }
+    /** Deform + draw every creature with the shared scene lighting. load=true composites over the world;
+     *  otherwise clears to `clear`. sun/sunCol/amb/cam/fog/fogDensity match the terrain & prop renderers. */
+    frame(enc, colorView, depthView, camVP, sunDir, sunCol, amb, camPos, fog, fogDensity, clear, load = false) {
+        const cp = enc.beginComputePass();
+        cp.setPipeline(this.skinPipe);
+        for (const p of this.packed) {
+            cp.setBindGroup(0, p.skinBG);
+            cp.dispatchWorkgroups(Math.ceil(p.n / 64));
+        }
+        cp.end();
+        for (const p of this.packed) {
+            const u = new Float32Array(24 + 20);
+            u.set(mul16(camVP, p.model), 0);
+            u.set([sunDir[0], sunDir[1], sunDir[2], 0], 16);
+            u.set([sunCol[0], sunCol[1], sunCol[2], 0], 20);
+            u.set([amb[0], amb[1], amb[2], 0], 24);
+            u.set([camPos[0], camPos[1], camPos[2], 0], 28);
+            u.set([fog[0], fog[1], fog[2], fogDensity], 32);
+            this.device.queue.writeBuffer(p.uBuf, 0, u);
+        }
+        const rp = enc.beginRenderPass({
+            colorAttachments: [{ view: colorView, ...(load ? { loadOp: 'load' } : { clearValue: { r: clear[0], g: clear[1], b: clear[2], a: 1 }, loadOp: 'clear' }), storeOp: 'store' }],
+            depthStencilAttachment: { view: depthView, ...(load ? { depthLoadOp: 'load' } : { depthClearValue: 1, depthLoadOp: 'clear' }), depthStoreOp: 'store' },
+        });
+        rp.setPipeline(this.drawPipe);
+        for (const p of this.packed) {
+            rp.setBindGroup(0, p.uBG);
+            rp.setVertexBuffer(0, p.defB);
+            rp.setVertexBuffer(1, p.colB);
+            rp.setVertexBuffer(2, p.defNB);
+            rp.setIndexBuffer(p.idxB, 'uint32');
+            rp.drawIndexed(p.idxCount);
+        }
+        rp.end();
+    }
+}
+/** column-major 4×4 multiply (a·b). */
+function mul16(a, b) {
+    const o = new Float32Array(16);
+    for (let c = 0; c < 4; c++)
+        for (let r = 0; r < 4; r++) {
+            let s = 0;
+            for (let k = 0; k < 4; k++)
+                s += a[k * 4 + r] * b[c * 4 + k];
+            o[c * 4 + r] = s;
+        }
+    return o;
+}

package/dist/assets/lod.d.ts

@@ -0,0 +1,2 @@
+import type { RawMesh } from './geometry';
+export declare function buildLodLadder(m: RawMesh, ratios: number[]): Promise<RawMesh[]>;

package/dist/assets/lod.js

@@ -0,0 +1,18 @@
+// Discrete LOD ladder (design/asset-streaming.md §3 v1) via meshopt simplify.
+// LOD0 is the source; each later LOD targets a fraction of the index count. The test
+// oracle is the triangle count (strictly decreasing) + preserved bounds.
+import { MeshoptSimplifier } from 'meshoptimizer';
+export async function buildLodLadder(m, ratios) {
+    await MeshoptSimplifier.ready;
+    const out = [];
+    for (const r of ratios) {
+        if (r >= 1) {
+            out.push({ positions: m.positions, indices: m.indices });
+            continue;
+        }
+        const targetCount = Math.max(3, Math.floor((m.indices.length * r) / 3) * 3);
+        const [simplified] = MeshoptSimplifier.simplify(m.indices, m.positions, 3, targetCount, 0.05, ['LockBorder']);
+        out.push({ positions: m.positions, indices: Uint32Array.from(simplified) });
+    }
+    return out;
+}

package/dist/assets/meshlet.d.ts

@@ -0,0 +1,23 @@
+import type { RawMesh } from './geometry';
+import type { Plane } from '../mat4';
+export interface MeshletBound {
+    center: [number, number, number];
+    radius: number;
+    coneApex: [number, number, number];
+    coneAxis: [number, number, number];
+    coneCutoff: number;
+}
+export interface MeshletSet {
+    count: number;
+    bounds: MeshletBound[];
+    meshlets: Uint32Array;
+    vertices: Uint32Array;
+    triangles: Uint8Array;
+}
+export declare function buildMeshletSet(mesh: RawMesh, maxV?: number, maxT?: number): Promise<MeshletSet>;
+/** Total triangles across all clusters (each meshlet's triangleCount is meshlets[i*4+3]). */
+export declare function meshletTriangleCount(set: MeshletSet): number;
+/** CPU cull oracle: a cluster is visible when its bounding sphere is inside the frustum AND its
+ *  normal cone does not face entirely away from the camera. meshopt convention: the cluster is
+ *  backfacing (cull) when dot(normalize(coneApex - camera), coneAxis) >= coneCutoff. */
+export declare function cullMeshlets(set: MeshletSet, planes: Plane[], camera: readonly [number, number, number]): number[];

package/dist/assets/meshlet.js

@@ -0,0 +1,53 @@
+// Meshlets (design/asset-streaming.md §3 v2 — the cluster-DAG foundation). A mesh is partitioned
+// into ~128-triangle clusters, each with a bounding sphere + a backface normal cone, so the GPU can
+// cull at cluster granularity (a partly-offscreen or backfacing object only submits its visible
+// clusters) — the precursor to per-cluster continuous LOD. buildMeshletSet wraps meshoptimizer's
+// clusterizer; cullMeshlets is the CPU reference oracle the GPU cull path is validated against
+// (same discipline as renderIR ↔ gpuDriven). This slice is cluster cull only; the LOD DAG (grouping
+// + simplifying clusters into a monotonic-error hierarchy) is the next slice.
+import { MeshoptClusterizer } from 'meshoptimizer';
+const MAX_VERTS = 64, MAX_TRIS = 124, CONE_WEIGHT = 0.5;
+export async function buildMeshletSet(mesh, maxV = MAX_VERTS, maxT = MAX_TRIS) {
+    await MeshoptClusterizer.ready;
+    const r = MeshoptClusterizer.buildMeshlets(mesh.indices, mesh.positions, 3, maxV, maxT, CONE_WEIGHT);
+    const raw = MeshoptClusterizer.computeMeshletBounds(r, mesh.positions, 3);
+    const bounds = raw.slice(0, r.meshletCount).map(b => ({
+        center: [b.centerX, b.centerY, b.centerZ], radius: b.radius,
+        coneApex: [b.coneApexX, b.coneApexY, b.coneApexZ], coneAxis: [b.coneAxisX, b.coneAxisY, b.coneAxisZ], coneCutoff: b.coneCutoff,
+    }));
+    return { count: r.meshletCount, bounds, meshlets: r.meshlets, vertices: r.vertices, triangles: r.triangles };
+}
+/** Total triangles across all clusters (each meshlet's triangleCount is meshlets[i*4+3]). */
+export function meshletTriangleCount(set) {
+    let t = 0;
+    for (let i = 0; i < set.count; i++)
+        t += set.meshlets[i * 4 + 3];
+    return t;
+}
+/** CPU cull oracle: a cluster is visible when its bounding sphere is inside the frustum AND its
+ *  normal cone does not face entirely away from the camera. meshopt convention: the cluster is
+ *  backfacing (cull) when dot(normalize(coneApex - camera), coneAxis) >= coneCutoff. */
+export function cullMeshlets(set, planes, camera) {
+    const vis = [];
+    for (let i = 0; i < set.count; i++) {
+        const b = set.bounds[i];
+        let inFrustum = true;
+        for (const pl of planes) {
+            if (pl[0] * b.center[0] + pl[1] * b.center[1] + pl[2] * b.center[2] + pl[3] < -b.radius) {
+                inFrustum = false;
+                break;
+            }
+        }
+        if (!inFrustum)
+            continue;
+        let dx = b.coneApex[0] - camera[0], dy = b.coneApex[1] - camera[1], dz = b.coneApex[2] - camera[2];
+        const l = Math.hypot(dx, dy, dz) || 1;
+        dx /= l;
+        dy /= l;
+        dz /= l;
+        if (dx * b.coneAxis[0] + dy * b.coneAxis[1] + dz * b.coneAxis[2] >= b.coneCutoff)
+            continue; // backfacing cone
+        vis.push(i);
+    }
+    return vis;
+}

package/dist/assets/morph.d.ts

@@ -0,0 +1,5 @@
+export declare function packMorph(name: string, deltas: Float32Array): Uint8Array;
+export declare function unpackMorph(b: Uint8Array): {
+    name: string;
+    deltas: Float32Array;
+};

package/dist/assets/morph.js

@@ -0,0 +1,75 @@
+// Morph-target blendshape (MORPH chunk, refinement tier — design/asset-streaming.md §5.2).
+// One chunk per shape. A blendshape only displaces a SUBSET of vertices (a viseme moves the mouth;
+// the rest are exactly 0), and the displacements are small, so the chunk is stored SPARSE +
+// QUANTIZED: only moved vertices, each as u32 index + 3×u16 position-delta quantized within the
+// shape's per-component delta bounds. unpack reconstructs the DENSE Float32Array (length 3*vc, zeros
+// elsewhere) so consumers (the WGSL morph deform + its oracle) are unchanged. 16-bit over the delta
+// range is sub-micron. All reads are element-wise DataView, so no alignment constraint.
+// Layout LE: u16 nameLen, name utf8, u32 vertexCount, u32 movedCount, f32 bounds[6]
+// (minX,maxX,minY,maxY,minZ,maxZ), then movedCount × { u32 index, u16 qx, u16 qy, u16 qz }.
+const quant = (v, lo, hi) => hi > lo ? Math.max(0, Math.min(65535, Math.round((v - lo) / (hi - lo) * 65535))) : 0;
+export function packMorph(name, deltas) {
+    const nm = new TextEncoder().encode(name);
+    const vc = deltas.length / 3;
+    const moved = [];
+    let minx = Infinity, maxx = -Infinity, miny = Infinity, maxy = -Infinity, minz = Infinity, maxz = -Infinity;
+    for (let i = 0; i < vc; i++) {
+        const x = deltas[i * 3], y = deltas[i * 3 + 1], z = deltas[i * 3 + 2];
+        if (x !== 0 || y !== 0 || z !== 0) {
+            moved.push(i);
+            if (x < minx)
+                minx = x;
+            if (x > maxx)
+                maxx = x;
+            if (y < miny)
+                miny = y;
+            if (y > maxy)
+                maxy = y;
+            if (z < minz)
+                minz = z;
+            if (z > maxz)
+                maxz = z;
+        }
+    }
+    if (moved.length === 0) {
+        minx = maxx = miny = maxy = minz = maxz = 0;
+    }
+    const mc = moved.length, p0 = 2 + nm.length;
+    const out = new Uint8Array(p0 + 8 + 24 + mc * 10);
+    const dv = new DataView(out.buffer);
+    dv.setUint16(0, nm.length, true);
+    out.set(nm, 2);
+    dv.setUint32(p0, vc, true);
+    dv.setUint32(p0 + 4, mc, true);
+    const bnd = [minx, maxx, miny, maxy, minz, maxz];
+    for (let i = 0; i < 6; i++)
+        dv.setFloat32(p0 + 8 + i * 4, bnd[i], true);
+    let o = p0 + 32;
+    for (const i of moved) {
+        dv.setUint32(o, i, true);
+        dv.setUint16(o + 4, quant(deltas[i * 3], minx, maxx), true);
+        dv.setUint16(o + 6, quant(deltas[i * 3 + 1], miny, maxy), true);
+        dv.setUint16(o + 8, quant(deltas[i * 3 + 2], minz, maxz), true);
+        o += 10;
+    }
+    return out;
+}
+export function unpackMorph(b) {
+    const dv = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    const nameLen = dv.getUint16(0, true);
+    const name = new TextDecoder().decode(b.subarray(2, 2 + nameLen));
+    const p0 = 2 + nameLen;
+    const vc = dv.getUint32(p0, true), mc = dv.getUint32(p0 + 4, true);
+    const minx = dv.getFloat32(p0 + 8, true), maxx = dv.getFloat32(p0 + 12, true), miny = dv.getFloat32(p0 + 16, true), maxy = dv.getFloat32(p0 + 20, true), minz = dv.getFloat32(p0 + 24, true), maxz = dv.getFloat32(p0 + 28, true);
+    const dx = (maxx - minx) / 65535, dy = (maxy - miny) / 65535, dz = (maxz - minz) / 65535;
+    const deltas = new Float32Array(vc * 3);
+    let o = p0 + 32;
+    for (let r = 0; r < mc; r++) {
+        const i = dv.getUint32(o, true);
+        deltas[i * 3] = minx + dv.getUint16(o + 4, true) * dx;
+        deltas[i * 3 + 1] = miny + dv.getUint16(o + 6, true) * dy;
+        deltas[i * 3 + 2] = minz + dv.getUint16(o + 8, true) * dz;
+        o += 10;
+    }
+    return { name, deltas };
+}

package/dist/assets/partkit.d.ts

@@ -0,0 +1,28 @@
+import type { JointTRS } from './pose';
+import type { RawMesh } from './geometry';
+/** Authoring tag: which archetype/socket/region a part fits, and the shared joints it skins to. */
+export interface PartTag {
+    id: string;
+    archetypeId: string;
+    socket: string;
+    region: string;
+    jointRange: [number, number];
+    attach: JointTRS;
+    hasViseme?: boolean;
+}
+/** A cooked part: a positions-only mesh + 4-per-vertex skin (joints index the SHARED skeleton). */
+export interface CookedPart {
+    tag: PartTag;
+    mesh: RawMesh;
+    joints: Uint16Array;
+    weights: Float32Array;
+}
+export interface PartKit {
+    version: number;
+    archetypeId: string;
+    parts: CookedPart[];
+}
+/** Every part that can fill a socket (matches socket id + one of its allowed regions). */
+export declare function partsForSocket(kit: PartKit, socketId: string, allowedRegions: string[]): CookedPart[];
+/** Resolve a genome's socket→partId choices to socket→CookedPart. */
+export declare function resolveKit(kit: PartKit, parts: Record<string, string>): Record<string, CookedPart>;

package/dist/assets/partkit.js

@@ -0,0 +1,21 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// PART KIT — the modular library of body PARTS a genome draws from (PLATFORM, generic). Each part is a
+// small skinned mesh authored to plug into ONE socket of ONE archetype: its per-vertex joints already
+// index the shared skeleton (jointRange ⊆ that archetype), so the assembler just welds + concatenates —
+// no runtime re-binding. A finite kit × continuous deformation × palette = infinite variety. The kit
+// itself is showcase content; this module only defines the format + selection helpers.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Every part that can fill a socket (matches socket id + one of its allowed regions). */
+export function partsForSocket(kit, socketId, allowedRegions) {
+    return kit.parts.filter((p) => p.tag.socket === socketId && allowedRegions.includes(p.tag.region));
+}
+/** Resolve a genome's socket→partId choices to socket→CookedPart. */
+export function resolveKit(kit, parts) {
+    const out = {};
+    for (const [socket, partId] of Object.entries(parts)) {
+        const p = kit.parts.find((q) => q.tag.id === partId);
+        if (p)
+            out[socket] = p;
+    }
+    return out;
+}

package/dist/assets/pose.d.ts

@@ -0,0 +1,26 @@
+import { type Mat4 } from '../mat4';
+import type { AnimClip } from './anim';
+export interface JointTRS {
+    t: [number, number, number];
+    q: [number, number, number, number];
+    s: [number, number, number];
+}
+/** Column-major T·R·S from a translation, quaternion (xyzw), and scale. */
+export declare function composeTRS(t: [number, number, number], q: [number, number, number, number], s: [number, number, number]): Mat4;
+/** Sample the clip at `time`, overriding each animated joint's rest T/R/S, → per-joint local mats. */
+export declare function sampleClipToLocals(clip: AnimClip, time: number, rest: JointTRS[]): Mat4[];
+/** world[j] = world[parent] × local[j]; root joints (parent<0) are seeded with `rootSeed`
+ *  (the armature/skeleton-root world matrix) so the hierarchy resolves in scene space.
+ *  Recursive with memo (parent-order agnostic). */
+export declare function forwardKinematics(locals: Mat4[], parents: Int16Array, rootSeed?: Mat4): Mat4[];
+/** Affine inverse of a column-major TRS matrix (assumes last row [0,0,0,1]). */
+export declare function invert(m: Mat4): Mat4;
+/** Decompose a column-major TRS matrix into translation / rotation-quaternion(xyzw) / scale.
+ *  Assumes no shear (rigid + non-negative axis scale) — true for bind matrices. */
+export declare function decomposeTRS(m: Mat4): JointTRS;
+/** Derive each joint's REST local TRS from the inverseBind matrices, so FK over the result reproduces
+ *  the BIND pose exactly (FK·inverseBind == identity at rest). Use this instead of a glTF's joint node
+ *  TRS, which for some rigs is a non-bind pose — the cause of skinning displacement at rest. */
+export declare function bindLocalsFromInverseBind(parents: Int16Array, inverseBind: Float32Array): JointTRS[];
+/** palette[j] = world[j] × inverseBind[j], packed into a Float32Array (J×16, column-major) for GPU upload. */
+export declare function buildPalette(worlds: Mat4[], inverseBind: Float32Array): Float32Array;