ugly-game 0.2.0 → 0.4.0

package/dist/assets/pose.js

@@ -0,0 +1,208 @@
+// Animation → skinning palette (design/asset-streaming.md §5.2). Samples an ANIM clip at a
+// time, runs forward kinematics over the joint hierarchy, and builds the bone-matrix palette
+// the (proven) WGSL skinning kernel consumes. Pure; column-major mat4 matching mat4.ts + WGSL.
+import { mul } from '../mat4';
+/** Column-major T·R·S from a translation, quaternion (xyzw), and scale. */
+export function composeTRS(t, q, s) {
+    const [x, y, z, w] = q;
+    const [sx, sy, sz] = s;
+    const xx = x * x, yy = y * y, zz = z * z, xy = x * y, xz = x * z, yz = y * z, wx = w * x, wy = w * y, wz = w * z;
+    // rotation (row-major elements m<row><col>)
+    const m00 = 1 - 2 * (yy + zz), m01 = 2 * (xy - wz), m02 = 2 * (xz + wy);
+    const m10 = 2 * (xy + wz), m11 = 1 - 2 * (xx + zz), m12 = 2 * (yz - wx);
+    const m20 = 2 * (xz - wy), m21 = 2 * (yz + wx), m22 = 1 - 2 * (xx + yy);
+    const M = new Float64Array(16); // column-major: M[col*4 + row]
+    M[0] = m00 * sx;
+    M[1] = m10 * sx;
+    M[2] = m20 * sx;
+    M[3] = 0;
+    M[4] = m01 * sy;
+    M[5] = m11 * sy;
+    M[6] = m21 * sy;
+    M[7] = 0;
+    M[8] = m02 * sz;
+    M[9] = m12 * sz;
+    M[10] = m22 * sz;
+    M[11] = 0;
+    M[12] = t[0];
+    M[13] = t[1];
+    M[14] = t[2];
+    M[15] = 1;
+    return M;
+}
+function sampleVec(times, values, stride, time) {
+    const n = times.length;
+    if (n === 0)
+        return new Array(stride).fill(0);
+    if (n === 1 || time <= times[0])
+        return Array.from(values.subarray(0, stride));
+    if (time >= times[n - 1])
+        return Array.from(values.subarray((n - 1) * stride, n * stride));
+    let k = 0;
+    while (k < n - 1 && times[k + 1] < time)
+        k++;
+    const f = (time - times[k]) / (times[k + 1] - times[k]);
+    const a = values.subarray(k * stride, (k + 1) * stride), b = values.subarray((k + 1) * stride, (k + 2) * stride);
+    // quaternion channels (stride 4): take the SHORTEST path — negate b when dot(a,b)<0, else the
+    // interpolation rotates ~300° the wrong way at antipodally-stored keyframes (a periodic blink).
+    let sign = 1;
+    if (stride === 4) {
+        let dot = 0;
+        for (let i = 0; i < 4; i++)
+            dot += a[i] * b[i];
+        if (dot < 0)
+            sign = -1;
+    }
+    const out = [];
+    for (let i = 0; i < stride; i++)
+        out.push(a[i] + (b[i] * sign - a[i]) * f);
+    return out;
+}
+/** Sample the clip at `time`, overriding each animated joint's rest T/R/S, → per-joint local mats. */
+export function sampleClipToLocals(clip, time, rest) {
+    const trs = rest.map(r => ({ t: [...r.t], q: [...r.q], s: [...r.s] }));
+    for (const ch of clip.channels) {
+        if (ch.jointIndex < 0 || ch.jointIndex >= trs.length)
+            continue;
+        const stride = ch.path === 1 ? 4 : 3;
+        const v = sampleVec(ch.times, ch.values, stride, time);
+        const j = trs[ch.jointIndex];
+        if (ch.path === 0)
+            j.t = [v[0], v[1], v[2]];
+        else if (ch.path === 1) {
+            const len = Math.hypot(v[0], v[1], v[2], v[3]) || 1;
+            j.q = [v[0] / len, v[1] / len, v[2] / len, v[3] / len];
+        }
+        else
+            j.s = [v[0], v[1], v[2]];
+    }
+    return trs.map(r => composeTRS(r.t, r.q, r.s));
+}
+/** 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 function forwardKinematics(locals, parents, rootSeed) {
+    const world = new Array(locals.length).fill(null);
+    const resolve = (j) => {
+        if (world[j])
+            return world[j];
+        const p = parents[j];
+        world[j] = p < 0 ? (rootSeed ? mul(rootSeed, locals[j]) : locals[j]) : mul(resolve(p), locals[j]);
+        return world[j];
+    };
+    for (let j = 0; j < locals.length; j++)
+        resolve(j);
+    return world;
+}
+/** Affine inverse of a column-major TRS matrix (assumes last row [0,0,0,1]). */
+export function invert(m) {
+    // linear 3×3 part L (L_rc = m[c*4+r]) and translation t
+    const L00 = m[0], L10 = m[1], L20 = m[2], L01 = m[4], L11 = m[5], L21 = m[6], L02 = m[8], L12 = m[9], L22 = m[10];
+    const t0 = m[12], t1 = m[13], t2 = m[14];
+    const det = L00 * (L11 * L22 - L12 * L21) - L01 * (L10 * L22 - L12 * L20) + L02 * (L10 * L21 - L11 * L20);
+    const out = new Float64Array(16);
+    if (Math.abs(det) < 1e-20) {
+        out[0] = out[5] = out[10] = out[15] = 1;
+        return out;
+    }
+    const id = 1 / det;
+    const i00 = (L11 * L22 - L12 * L21) * id, i01 = (L02 * L21 - L01 * L22) * id, i02 = (L01 * L12 - L02 * L11) * id;
+    const i10 = (L12 * L20 - L10 * L22) * id, i11 = (L00 * L22 - L02 * L20) * id, i12 = (L02 * L10 - L00 * L12) * id;
+    const i20 = (L10 * L21 - L11 * L20) * id, i21 = (L01 * L20 - L00 * L21) * id, i22 = (L00 * L11 - L01 * L10) * id;
+    // column-major: columns are the inverse-linear columns; translation = -invL · t
+    out[0] = i00;
+    out[1] = i10;
+    out[2] = i20;
+    out[3] = 0;
+    out[4] = i01;
+    out[5] = i11;
+    out[6] = i21;
+    out[7] = 0;
+    out[8] = i02;
+    out[9] = i12;
+    out[10] = i22;
+    out[11] = 0;
+    out[12] = -(i00 * t0 + i01 * t1 + i02 * t2);
+    out[13] = -(i10 * t0 + i11 * t1 + i12 * t2);
+    out[14] = -(i20 * t0 + i21 * t1 + i22 * t2);
+    out[15] = 1;
+    return out;
+}
+/** 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 function decomposeTRS(m) {
+    const t = [m[12], m[13], m[14]];
+    // scale = length of each basis column (column-major: col c = m[c*4 .. c*4+2])
+    const sx = Math.sqrt(m[0] * m[0] + m[1] * m[1] + m[2] * m[2]) || 1;
+    const sy = Math.sqrt(m[4] * m[4] + m[5] * m[5] + m[6] * m[6]) || 1;
+    const sz = Math.sqrt(m[8] * m[8] + m[9] * m[9] + m[10] * m[10]) || 1;
+    // rotation matrix R(row,col) = m[col*4+row] / scale_col
+    const r00 = m[0] / sx, r10 = m[1] / sx, r20 = m[2] / sx;
+    const r01 = m[4] / sy, r11 = m[5] / sy, r21 = m[6] / sy;
+    const r02 = m[8] / sz, r12 = m[9] / sz, r22 = m[10] / sz;
+    const tr = r00 + r11 + r22;
+    let x, y, z, w;
+    if (tr > 0) {
+        const s = Math.sqrt(tr + 1) * 2;
+        w = 0.25 * s;
+        x = (r21 - r12) / s;
+        y = (r02 - r20) / s;
+        z = (r10 - r01) / s;
+    }
+    else if (r00 > r11 && r00 > r22) {
+        const s = Math.sqrt(1 + r00 - r11 - r22) * 2;
+        w = (r21 - r12) / s;
+        x = 0.25 * s;
+        y = (r01 + r10) / s;
+        z = (r02 + r20) / s;
+    }
+    else if (r11 > r22) {
+        const s = Math.sqrt(1 + r11 - r00 - r22) * 2;
+        w = (r02 - r20) / s;
+        x = (r01 + r10) / s;
+        y = 0.25 * s;
+        z = (r12 + r21) / s;
+    }
+    else {
+        const s = Math.sqrt(1 + r22 - r00 - r11) * 2;
+        w = (r10 - r01) / s;
+        x = (r02 + r20) / s;
+        y = (r12 + r21) / s;
+        z = 0.25 * s;
+    }
+    return { t, q: [x, y, z, w], s: [sx, sy, sz] };
+}
+/** 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 function bindLocalsFromInverseBind(parents, inverseBind) {
+    const J = parents.length;
+    const globalBind = [];
+    for (let j = 0; j < J; j++) {
+        const ib = new Float64Array(16);
+        for (let i = 0; i < 16; i++)
+            ib[i] = inverseBind[j * 16 + i];
+        globalBind[j] = invert(ib);
+    }
+    const locals = [];
+    for (let j = 0; j < J; j++) {
+        const p = parents[j];
+        const local = p < 0 ? globalBind[j] : mul(invert(globalBind[p]), globalBind[j]);
+        locals[j] = decomposeTRS(local);
+    }
+    return locals;
+}
+/** palette[j] = world[j] × inverseBind[j], packed into a Float32Array (J×16, column-major) for GPU upload. */
+export function buildPalette(worlds, inverseBind) {
+    const J = worlds.length;
+    const out = new Float32Array(J * 16);
+    for (let j = 0; j < J; j++) {
+        const ib = new Float64Array(16);
+        for (let i = 0; i < 16; i++)
+            ib[i] = inverseBind[j * 16 + i];
+        const m = mul(worlds[j], ib);
+        for (let i = 0; i < 16; i++)
+            out[j * 16 + i] = m[i];
+    }
+    return out;
+}

package/dist/assets/renderAssets.d.ts

@@ -0,0 +1,37 @@
+import { type Budget, type Detail } from './select';
+export interface AssetMeta {
+    lodCount: number;
+    mipCount: number;
+    residentFinestLod: number;
+}
+export interface InstanceView {
+    x: number;
+    y: number;
+    z: number;
+    boundsRadius: number;
+    meshId: number;
+}
+export interface CameraView {
+    px: number;
+    py: number;
+    pz: number;
+    fov: number;
+    viewportPx: number;
+}
+export declare function selectBatchDetail(insts: InstanceView[], cam: CameraView, budget: Budget, metaOf: (meshId: number) => AssetMeta): Detail[];
+export interface LodDrawArg {
+    pipeline: number;
+    lod: number;
+    first: number;
+    count: number;
+}
+/** Compact visible instance indices grouped by (pipeline, lod); one draw per non-empty
+ *  group. Draw count = O(pipelines×lods), independent of instance count — the LOD-aware
+ *  extension of renderIR.ts's cull/batch that the gpuDriven.ts cull pass mirrors. */
+export declare function batchByPipelineAndLod(visible: number[], pipelineOf: (i: number) => number, lodOf: (i: number) => number): {
+    order: Int32Array;
+    draws: LodDrawArg[];
+};
+/** Fetch order for the streaming loader (design/asset-streaming.md §6): instance indices
+ *  sorted by descending screen coverage — near/large first, off-screen/small last. */
+export declare function streamPriority(insts: InstanceView[], cam: CameraView): number[];

package/dist/assets/renderAssets.js

@@ -0,0 +1,54 @@
+// Bridges cooked assets to the render path (design/asset-streaming.md §6). Per-instance
+// LOD/mip/tier from screen-space error + device budget, clamped to resident LODs, then
+// grouped into O(pipelines×lods) draws — the CPU reference for the gpuDriven.ts cull pass.
+import { projectedError, selectDetail } from './select';
+export function selectBatchDetail(insts, cam, budget, metaOf) {
+    return insts.map(it => {
+        const m = metaOf(it.meshId);
+        const dist = Math.hypot(it.x - cam.px, it.y - cam.py, it.z - cam.pz);
+        const err = projectedError(it.boundsRadius, dist, cam.fov, cam.viewportPx);
+        const d = selectDetail(err, m.lodCount, m.mipCount, budget);
+        const lodIndex = Math.max(d.lodIndex, m.residentFinestLod); // never finer than resident
+        return { ...d, lodIndex };
+    });
+}
+/** Compact visible instance indices grouped by (pipeline, lod); one draw per non-empty
+ *  group. Draw count = O(pipelines×lods), independent of instance count — the LOD-aware
+ *  extension of renderIR.ts's cull/batch that the gpuDriven.ts cull pass mirrors. */
+export function batchByPipelineAndLod(visible, pipelineOf, lodOf) {
+    const keyOf = (i) => `${pipelineOf(i)}:${lodOf(i)}`;
+    const counts = new Map();
+    for (const i of visible)
+        counts.set(keyOf(i), (counts.get(keyOf(i)) ?? 0) + 1);
+    // deterministic group order: ascending pipeline, then lod
+    const keys = [...counts.keys()].sort((a, b) => { const [pa, la] = a.split(':').map(Number); const [pb, lb] = b.split(':').map(Number); return (pa - pb) || (la - lb); });
+    const start = new Map();
+    let cursor = 0;
+    const draws = [];
+    for (const k of keys) {
+        const [p, l] = k.split(':').map(Number);
+        const c = counts.get(k);
+        start.set(k, cursor);
+        draws.push({ pipeline: p, lod: l, first: cursor, count: c });
+        cursor += c;
+    }
+    const scatter = new Map(start);
+    const order = new Int32Array(visible.length);
+    for (const i of visible) {
+        const k = keyOf(i);
+        const at = scatter.get(k);
+        order[at] = i;
+        scatter.set(k, at + 1);
+    }
+    return { order, draws };
+}
+/** Fetch order for the streaming loader (design/asset-streaming.md §6): instance indices
+ *  sorted by descending screen coverage — near/large first, off-screen/small last. */
+export function streamPriority(insts, cam) {
+    const score = insts.map((it, i) => {
+        const dist = Math.hypot(it.x - cam.px, it.y - cam.py, it.z - cam.pz);
+        return { i, cov: projectedError(it.boundsRadius, dist, cam.fov, cam.viewportPx) };
+    });
+    score.sort((a, b) => b.cov - a.cov); // descending screen coverage
+    return score.map(s => s.i);
+}

package/dist/assets/residency.d.ts

@@ -0,0 +1,13 @@
+export declare class Residency {
+    private budgetBytes;
+    private order;
+    private size;
+    private pinned;
+    private used;
+    constructor(budgetBytes: number);
+    admit(key: string, bytes: number, base: boolean): void;
+    touch(key: string): void;
+    has(key: string): boolean;
+    residentBytes(): number;
+    private evictOne;
+}

package/dist/assets/residency.js

@@ -0,0 +1,45 @@
+// GPU-memory residency with LRU eviction (design/asset-streaming.md §7). Base-tier chunks
+// are pinned (never evicted) so something always renders; fine chunks evict LRU under budget.
+export class Residency {
+    budgetBytes;
+    order = []; // MRU at the end
+    size = new Map();
+    pinned = new Set();
+    used = 0;
+    constructor(budgetBytes) {
+        this.budgetBytes = budgetBytes;
+    }
+    admit(key, bytes, base) {
+        if (this.size.has(key)) {
+            this.touch(key);
+            return;
+        }
+        while (this.used + bytes > this.budgetBytes) {
+            if (!this.evictOne())
+                break;
+        }
+        this.size.set(key, bytes);
+        this.order.push(key);
+        this.used += bytes;
+        if (base)
+            this.pinned.add(key);
+    }
+    touch(key) { const i = this.order.indexOf(key); if (i >= 0) {
+        this.order.splice(i, 1);
+        this.order.push(key);
+    } }
+    has(key) { return this.size.has(key); }
+    residentBytes() { return this.used; }
+    evictOne() {
+        for (let i = 0; i < this.order.length; i++) {
+            const k = this.order[i];
+            if (this.pinned.has(k))
+                continue;
+            this.order.splice(i, 1);
+            this.used -= this.size.get(k);
+            this.size.delete(k);
+            return true;
+        }
+        return false; // nothing evictable (all pinned)
+    }
+}

package/dist/assets/retarget.d.ts

@@ -0,0 +1,11 @@
+import type { AnimClip } from './anim';
+import type { AssembledMesh } from './assemble';
+import type { GlobalProportion } from './genome';
+/** Sample `clip` at time `t` onto the assembled (deformed) rig → the joint palette (jointCount×16). */
+export declare function poseAssembled(a: AssembledMesh, clip: AnimClip, t: number): Float32Array;
+/** The bone palette for the (deformed) rest pose — no clip. Skinning with this reproduces the deformed
+ *  creature standing at rest, which is what the Genome Garden shows. */
+export declare function restPalette(a: AssembledMesh): Float32Array;
+/** Pre-scale a clip's TRANSLATION channels (path 0) by the proportion, so a clip authored on the base
+ *  rig tracks a resized rig (rotation channels are metric-free and pass through unchanged). */
+export declare function retargetClip(clip: AnimClip, prop: GlobalProportion): AnimClip;

package/dist/assets/retarget.js

@@ -0,0 +1,37 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// RETARGET — plays a shared archetype animation clip on an assembled (deformed) creature (PLATFORM).
+// Same-archetype retarget is EXACT + trivial: every creature shares the joint set/numbering; the genome
+// only deforms rest translations, so a library clip samples straight onto the deformed rest and FK does
+// the rest. retargetClip pre-scales a clip's translation channels by the proportion so absolute
+// positions track the resized rig. poseAssembled returns the bone palette the WGSL skin kernel consumes.
+// ─────────────────────────────────────────────────────────────────────────────
+import { sampleClipToLocals, forwardKinematics, buildPalette } from './pose';
+function toMat(arr) { const m = new Float64Array(16); for (let i = 0; i < 16; i++)
+    m[i] = arr[i] ?? 0; return m; }
+/** Sample `clip` at time `t` onto the assembled (deformed) rig → the joint palette (jointCount×16). */
+export function poseAssembled(a, clip, t) {
+    const locals = sampleClipToLocals(clip, t, a.restLocals);
+    const worlds = forwardKinematics(locals, a.parents, toMat(a.rootWorld));
+    return buildPalette(worlds, a.inverseBind);
+}
+/** The bone palette for the (deformed) rest pose — no clip. Skinning with this reproduces the deformed
+ *  creature standing at rest, which is what the Genome Garden shows. */
+export function restPalette(a) {
+    return poseAssembled(a, { name: 'rest', duration: 0, channels: [] }, 0);
+}
+/** Pre-scale a clip's TRANSLATION channels (path 0) by the proportion, so a clip authored on the base
+ *  rig tracks a resized rig (rotation channels are metric-free and pass through unchanged). */
+export function retargetClip(clip, prop) {
+    const channels = clip.channels.map((ch) => {
+        if (ch.path !== 0)
+            return ch;
+        const v = new Float32Array(ch.values.length);
+        for (let i = 0; i + 2 < v.length; i += 3) {
+            v[i] = ch.values[i] * prop.girth;
+            v[i + 1] = ch.values[i + 1] * prop.height;
+            v[i + 2] = ch.values[i + 2] * prop.girth;
+        }
+        return { ...ch, values: v };
+    });
+    return { ...clip, channels };
+}

package/dist/assets/rig.d.ts

@@ -0,0 +1,13 @@
+import type { JointTRS } from './pose';
+export interface SkelData {
+    jointCount: number;
+    vertexCount: number;
+    parents: Int16Array;
+    inverseBind: Float32Array;
+    jointsPerVertex: Uint16Array;
+    weightsPerVertex: Float32Array;
+    rootWorld?: number[];
+    restLocals?: JointTRS[];
+}
+export declare function packSkel(s: SkelData): Uint8Array;
+export declare function unpackSkel(b: Uint8Array): Required<SkelData>;

package/dist/assets/rig.js

@@ -0,0 +1,93 @@
+const align4 = (n) => (n + 3) & ~3;
+const IDENT16 = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+// Quantize 4 weights to u8 summing to exactly 255 (largest-remainder), so decode (÷255) sums to 1.
+function quantWeights4(w0, w1, w2, w3) {
+    const sum = w0 + w1 + w2 + w3;
+    if (sum <= 0)
+        return [0, 0, 0, 0];
+    const scaled = [w0 / sum * 255, w1 / sum * 255, w2 / sum * 255, w3 / sum * 255];
+    const floor = scaled.map(Math.floor);
+    let rem = 255 - (floor[0] + floor[1] + floor[2] + floor[3]);
+    // hand the leftover units to the largest fractional parts
+    const order = [0, 1, 2, 3].sort((a, b) => (scaled[b] - floor[b]) - (scaled[a] - floor[a]));
+    for (let k = 0; k < rem; k++)
+        floor[order[k % 4]]++;
+    return [floor[0], floor[1], floor[2], floor[3]];
+}
+export function packSkel(s) {
+    const jc = s.jointCount, vc = s.vertexCount;
+    const jb = jc <= 255 ? 1 : 2; // joint-index bytes
+    const pParents = 12, pIB = align4(pParents + jc * 2), pJoints = pIB + jc * 16 * 4;
+    const pWeights = pJoints + vc * 4 * jb, pRoot = align4(pWeights + vc * 4), pRest = pRoot + 64;
+    const out = new Uint8Array(pRest + jc * 40);
+    const dv = new DataView(out.buffer);
+    dv.setUint32(0, jc, true);
+    dv.setUint32(4, vc, true);
+    dv.setUint8(8, jb);
+    for (let i = 0; i < jc; i++)
+        dv.setInt16(pParents + i * 2, s.parents[i], true);
+    for (let i = 0; i < jc * 16; i++)
+        dv.setFloat32(pIB + i * 4, s.inverseBind[i], true);
+    for (let i = 0; i < vc * 4; i++) {
+        const j = s.jointsPerVertex[i];
+        if (jb === 1)
+            dv.setUint8(pJoints + i, j);
+        else
+            dv.setUint16(pJoints + i * 2, j, true);
+    }
+    for (let v = 0; v < vc; v++) {
+        const q = quantWeights4(s.weightsPerVertex[v * 4], s.weightsPerVertex[v * 4 + 1], s.weightsPerVertex[v * 4 + 2], s.weightsPerVertex[v * 4 + 3]);
+        for (let k = 0; k < 4; k++)
+            dv.setUint8(pWeights + v * 4 + k, q[k]);
+    }
+    const root = s.rootWorld ?? IDENT16;
+    for (let i = 0; i < 16; i++)
+        dv.setFloat32(pRoot + i * 4, root[i] ?? IDENT16[i], true);
+    for (let j = 0; j < jc; j++) {
+        const r = s.restLocals?.[j];
+        const base = pRest + j * 40;
+        const t = r?.t ?? [0, 0, 0], q = r?.q ?? [0, 0, 0, 1], sc = r?.s ?? [1, 1, 1];
+        dv.setFloat32(base, t[0], true);
+        dv.setFloat32(base + 4, t[1], true);
+        dv.setFloat32(base + 8, t[2], true);
+        dv.setFloat32(base + 12, q[0], true);
+        dv.setFloat32(base + 16, q[1], true);
+        dv.setFloat32(base + 20, q[2], true);
+        dv.setFloat32(base + 24, q[3], true);
+        dv.setFloat32(base + 28, sc[0], true);
+        dv.setFloat32(base + 32, sc[1], true);
+        dv.setFloat32(base + 36, sc[2], true);
+    }
+    return out;
+}
+export function unpackSkel(b) {
+    const dv = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    const jc = dv.getUint32(0, true), vc = dv.getUint32(4, true), jb = dv.getUint8(8) || 2;
+    const pParents = 12, pIB = align4(pParents + jc * 2), pJoints = pIB + jc * 16 * 4;
+    const pWeights = pJoints + vc * 4 * jb, pRoot = align4(pWeights + vc * 4), pRest = pRoot + 64;
+    const parents = new Int16Array(jc);
+    for (let i = 0; i < jc; i++)
+        parents[i] = dv.getInt16(pParents + i * 2, true);
+    const inverseBind = new Float32Array(jc * 16);
+    for (let i = 0; i < jc * 16; i++)
+        inverseBind[i] = dv.getFloat32(pIB + i * 4, true);
+    const jointsPerVertex = new Uint16Array(vc * 4);
+    for (let i = 0; i < vc * 4; i++)
+        jointsPerVertex[i] = jb === 1 ? dv.getUint8(pJoints + i) : dv.getUint16(pJoints + i * 2, true);
+    const weightsPerVertex = new Float32Array(vc * 4);
+    for (let i = 0; i < vc * 4; i++)
+        weightsPerVertex[i] = dv.getUint8(pWeights + i) / 255;
+    const rootWorld = [];
+    for (let i = 0; i < 16; i++)
+        rootWorld.push(dv.getFloat32(pRoot + i * 4, true));
+    const restLocals = [];
+    for (let j = 0; j < jc; j++) {
+        const base = pRest + j * 40;
+        restLocals.push({
+            t: [dv.getFloat32(base, true), dv.getFloat32(base + 4, true), dv.getFloat32(base + 8, true)],
+            q: [dv.getFloat32(base + 12, true), dv.getFloat32(base + 16, true), dv.getFloat32(base + 20, true), dv.getFloat32(base + 24, true)],
+            s: [dv.getFloat32(base + 28, true), dv.getFloat32(base + 32, true), dv.getFloat32(base + 36, true)],
+        });
+    }
+    return { jointCount: jc, vertexCount: vc, parents, inverseBind, jointsPerVertex, weightsPerVertex, rootWorld, restLocals };
+}

package/dist/assets/select.d.ts

@@ -0,0 +1,10 @@
+export declare function projectedError(radius: number, distance: number, fov: number, viewportPx: number): number;
+export interface Budget {
+    scalar: number;
+}
+export interface Detail {
+    lodIndex: number;
+    mipBase: number;
+    materialTier: 0 | 1;
+}
+export declare function selectDetail(errPx: number, lodCount: number, mipCount: number, budget: Budget): Detail;

package/dist/assets/select.js

@@ -0,0 +1,24 @@
+// The unifying selection driver (design/asset-streaming.md §6). One screen-error metric,
+// scaled by a per-device budget, picks LOD + mip base + material tier. Pure & monotone.
+export function projectedError(radius, distance, fov, viewportPx) {
+    const d = Math.max(distance, 1e-3);
+    // angular size → fraction of the vertical FOV → pixels
+    const angular = 2 * Math.atan(radius / d);
+    return (angular / fov) * viewportPx;
+}
+export function selectDetail(errPx, lodCount, mipCount, budget) {
+    const e = errPx * Math.max(budget.scalar, 1e-3); // weaker device shrinks effective error
+    // LOD: ≥256px ⇒ LOD0, halving thresholds down the ladder.
+    let lodIndex = 0;
+    for (let l = 0; l < lodCount; l++) {
+        if (e >= 256 / (1 << l)) {
+            lodIndex = l;
+            break;
+        }
+        lodIndex = l;
+    }
+    // mip base: finest (0) when large on screen; coarser as it shrinks.
+    const mipBase = Math.min(mipCount - 1, Math.max(0, Math.floor(Math.log2(Math.max(1, 512 / Math.max(e, 1))))));
+    const materialTier = e >= 64 ? 1 : 0;
+    return { lodIndex, mipBase, materialTier };
+}

package/dist/assets/stream.d.ts

@@ -0,0 +1,12 @@
+import { type TocEntry } from './ugm';
+export interface Transport {
+    range(start: number, end: number): Promise<Uint8Array>;
+    bytesFetched: number;
+}
+export interface TierEvent {
+    detailLevel: number;
+    kinds: number[];
+    bytesFetchedSoFar: number;
+    decodeWrites: number;
+}
+export declare function streamUgm(t: Transport, onTier: (e: TierEvent) => void, priority?: (e: TocEntry) => number): Promise<void>;

package/dist/assets/stream.js

@@ -0,0 +1,32 @@
+// Streaming loader (design/asset-streaming.md §8,§10-12). Reads the header (trivial JS
+// DataView), fetches the base prefix first (emits a coarse tier), then refinement chunks
+// by priority. Counts decode-writes to hold the §12 data-copy budget: one per chunk.
+import { readHeader, readToc, HEADER_BYTES } from './ugm';
+export async function streamUgm(t, onTier, priority = e => e.detailLevel) {
+    // 1. header (fixed 64B) — trivial JS parse
+    const head = await t.range(0, HEADER_BYTES);
+    const h = readHeader(head);
+    // 2. base prefix — one contiguous fetch containing header + TOC + base chunks (coarse render now)
+    const prefix = await t.range(0, h.basePayloadLen);
+    const toc = readToc(prefix, h);
+    const baseEntries = toc.filter(e => e.offset + e.length <= h.basePayloadLen);
+    emit(baseEntries, 0);
+    // 3. refinements grouped by detail level, in priority order
+    const refine = toc.filter(e => e.offset + e.length > h.basePayloadLen).sort((a, b) => priority(a) - priority(b));
+    const byLevel = new Map();
+    for (const e of refine) {
+        const g = byLevel.get(e.detailLevel) ?? [];
+        g.push(e);
+        byLevel.set(e.detailLevel, g);
+    }
+    for (const level of [...byLevel.keys()].sort((a, b) => a - b)) {
+        const group = byLevel.get(level);
+        for (const e of group)
+            await t.range(e.offset, e.offset + e.length);
+        emit(group, level);
+    }
+    function emit(entries, detailLevel) {
+        // one decode-write per chunk (meshopt/basis decode → upload-ready buffer); Phase 2 does the real GPU upload.
+        onTier({ detailLevel, kinds: entries.map(e => e.kind), bytesFetchedSoFar: t.bytesFetched, decodeWrites: entries.length });
+    }
+}

package/dist/assets/style.d.ts

@@ -0,0 +1,10 @@
+export type RGB = [number, number, number];
+export interface StyleGuide {
+    id: string;
+    roles: Record<string, RGB>;
+    regionRole: Record<string, string>;
+}
+/** The role a region resolves to under this guide (falls back to the first role if unmapped). */
+export declare function resolveRole(guide: StyleGuide, region: string): string;
+/** The rgb for a region under this guide. */
+export declare function resolveRGB(guide: StyleGuide, region: string): RGB;

package/dist/assets/style.js

@@ -0,0 +1,17 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// STYLE GUIDE — the cohesion layer (PLATFORM, generic; see design/content-architecture.md Component 1).
+// Content references color BY ROLE, never by raw value, so re-grading the guide re-grades every
+// assembled creature at once — the mechanism that makes AI/procedural bulk read as one art direction.
+// The assembler assigns each part's vertex range a role via resolveRole; the renderer looks up the rgb.
+// ─────────────────────────────────────────────────────────────────────────────
+/** The role a region resolves to under this guide (falls back to the first role if unmapped). */
+export function resolveRole(guide, region) {
+    const r = guide.regionRole[region];
+    if (r && guide.roles[r])
+        return r;
+    return Object.keys(guide.roles)[0] ?? 'default';
+}
+/** The rgb for a region under this guide. */
+export function resolveRGB(guide, region) {
+    return guide.roles[resolveRole(guide, region)] ?? [0.7, 0.7, 0.7];
+}