sindicate 0.1.0 → 0.4.0

package/src/systems/vat.js

@@ -0,0 +1,327 @@
+// Vertex-Animation-Texture (VAT) instancing for the county's livestock and wildlife: bake a skinned
+// creature's clips into a texture ONCE, then render any number of individuals as ONE InstancedMesh,
+// each at its own clip + loop phase + coat tint. One draw call per species, and no animator on the
+// CPU at all. Individual skinned meshes per animal would tank the frame rate outright (r184 WebGPU
+// pays pipeline setup per skinned mesh object).
+//
+// PORTED FROM /Users/nick/Sites/fable/src/game/vat.js, which has been shipping it for months. Two
+// things were deliberately LEFT BEHIND:
+//
+//   1. loadVillagerVAT — fable's humanoid-crowd baker. It calls buildRetargetContext/retargetClip and
+//      mergeCharacterBody, and pulling it across would have dragged core/retarget.js and game/entity.js
+//      into this module for no reason. THIS IS ALSO WHY THE PORT IS SAFE IN A GAME WITH TWO SOURCE
+//      RIGS: an animal brings its own skeleton and its own clips in its own FBX, loadSpeciesVAT never
+//      calls the retargeter, and so western's two-source-rig problem (core/retarget.js, game/clips.js)
+//      cannot touch it. Nothing here knows the anim rig exists.
+//   2. The seagull's flySegment scanner. This county is eight hundred miles from the sea.
+//
+// THE BINS WRITE THEMSELVES. A bake is a pure function of (rig geometry, clip set) — byte-identical
+// every boot — so it lives as a .bin under public/assets/vat/ and boot is a FILE READ, not a
+// mixer-sampling cook. On a miss we bake live and POST the bin to the dev server (vite
+// /__save-vatbin, already registered in vite.config.js). Playing once cooks everything.
+import * as THREE from 'three/webgpu';
+import { Fn, texture, attribute, uniform, uniformArray, vec2, int, float, floor, mod, uv } from 'three/tsl';
+import { loadModel, instantiate, loadTexture } from '../core/assets.js';
+
+// Stack N coat textures side-by-side into one atlas, so a herd can show a different colour per
+// individual (a per-instance aLayer offsets U). Horizontal keeps V/flipY identical to the original.
+async function stackTextures(urls) {
+  const imgs = (await Promise.all(urls.map(loadTexture))).map((t) => t.image);
+  const w = imgs[0].width, h = imgs[0].height, n = imgs.length;
+  const canvas = document.createElement('canvas'); canvas.width = w * n; canvas.height = h;
+  const ctx = canvas.getContext('2d');
+  imgs.forEach((img, i) => ctx.drawImage(img, i * w, 0, w, h));
+  const tex = new THREE.CanvasTexture(canvas);
+  tex.colorSpace = THREE.SRGBColorSpace;
+  tex.minFilter = THREE.LinearMipmapLinearFilter; tex.magFilter = THREE.LinearFilter;
+  return { tex, layers: n };
+}
+
+// Derive ground speed from a clip's ROOT MOTION: how far the animation carries the creature (the
+// largest-travelling position track's net XZ displacement) over one cycle ÷ the cycle time, scaled to
+// metres. legs-move == space-moved → no foot-sliding. 0 if in-place (caller falls back).
+function rootMotionSpeed(clip, scale) {
+  if (!clip || clip.duration <= 0) return 0;
+  let best = 0;
+  for (const tr of clip.tracks) {
+    if (!tr.name.endsWith('.position') || tr.times.length < 2) continue;
+    const v = tr.values, n = tr.times.length;
+    best = Math.max(best, Math.hypot(v[(n - 1) * 3] - v[0], v[(n - 1) * 3 + 2] - v[2]));
+  }
+  const s = (best * scale) / clip.duration;
+  return s > 0.05 && s < 12 ? s : 0;
+}
+
+// Implied ground speed of an IN-PLACE clip (no root motion): the planted foot slides backward at the
+// ground speed. Track the centroid of the bottom-of-body contact verts in the baked VAT frame to
+// frame; the median horizontal speed ignores the foot-swap spikes ≈ the true ground speed.
+function footSlideSpeed(vat, clipRow, scale) {
+  const e = vat.table[clipRow]; if (!e || e.frames < 3) return 0;
+  const d = vat.data ?? vat.tex.image.data, V = vat.vCount, W = vat.W, RPF = vat.rowsPerFrame, cen = [];
+  const tIdx = (i, gf) => (gf * RPF + ((i / W) | 0)) * W + (i % W);   // tiled VAT texel index (matches bake)
+  for (let f = 0; f < e.frames; f++) {
+    const gf = e.start + f;
+    let minY = 1e9, maxY = -1e9;
+    for (let i = 0; i < V; i++) { const y = d[tIdx(i, gf) * 4 + 1]; if (y < minY) minY = y; if (y > maxY) maxY = y; }
+    const thr = minY + (maxY - minY) * 0.08; // contact patch = lowest 8% of the body height
+    let cx = 0, cz = 0, c = 0;
+    for (let i = 0; i < V; i++) { const b = tIdx(i, gf) * 4; if (d[b + 1] <= thr) { cx += d[b]; cz += d[b + 2]; c++; } }
+    cen.push(c ? [cx / c, cz / c] : [0, 0]);
+  }
+  const sp = [];
+  for (let f = 0; f < e.frames; f++) { const a = cen[f], b = cen[(f + 1) % e.frames]; sp.push(Math.hypot(b[0] - a[0], b[1] - a[1])); }
+  sp.sort((a, b) => a - b);
+  const s = sp[sp.length >> 1] * vat.fps * scale; // median per-frame slide × fps × display scale
+  return s > 0.15 ? s : 0; // below this the contact-tracking didn't lock on → caller falls back
+}
+
+const FPS = 30;
+
+// A STANDING POSE, from a clip that has no standing in it. Take every track's value at time t and
+// hold it — 2 frames of a motionless animal. The deer's pack ships walk/run/attack/death and no idle
+// whatsoever, and a deer marching on the spot is a worse animal than a deer standing still.
+// Duration 0.14 s × the 15 fps idle bake = exactly 2 frames, so it costs 2 rows of the VAT texture.
+function freezeClip(clip, name, t = 0) {
+  const tracks = clip.tracks.map((tr) => {
+    const stride = tr.getValueSize();
+    let k = 0;
+    for (let i = 0; i < tr.times.length; i++) if (tr.times[i] <= t) k = i;
+    const v = Array.from(tr.values.slice(k * stride, (k + 1) * stride));
+    return new tr.constructor(tr.name, [0, 0.14], [...v, ...v]);
+  });
+  return new THREE.AnimationClip(name, 0.14, tracks);
+}
+
+// PolyPerfect anim FBX pack every clip onto ONE shared timeline, so each clip's `duration` is its END
+// time while its keys live in a sub-range — trim to the real keyframe range and shift to 0.
+export function trimClip(clip, name) {
+  let t0 = Infinity, t1 = -Infinity;
+  for (const tr of clip.tracks) if (tr.times.length) { t0 = Math.min(t0, tr.times[0]); t1 = Math.max(t1, tr.times[tr.times.length - 1]); }
+  if (!isFinite(t0)) return clip;
+  const tracks = clip.tracks.map((tr) => {
+    const stride = tr.getValueSize(), times = [], values = [];
+    for (let i = 0; i < tr.times.length; i++) {
+      const t = tr.times[i];
+      if (t >= t0 - 1e-4 && t <= t1 + 1e-4) { times.push(t - t0); for (let j = 0; j < stride; j++) values.push(tr.values[i * stride + j]); }
+    }
+    return new tr.constructor(tr.name, times, values);
+  });
+  return new THREE.AnimationClip(name || clip.name, t1 - t0, tracks);
+}
+
+// The bin name hashes model + vertex count + every clip's name/fps/duration — any content change
+// misses cleanly and re-cooks. Format: [u32 header-len LE][JSON header][u16 half-float texels].
+const VAT_BIN_VER = 1;
+function vatBinName(key, clips, fps, vCount) {
+  const id = `${VAT_BIN_VER}|${key}|${vCount}|` + clips.map((c) => `${c.name}@${c.userData?.bakeFps ?? fps}x${+c.duration.toFixed(3)}`).join(',');
+  let h = 5381;
+  for (let i = 0; i < id.length; i++) h = ((h << 5) + h + id.charCodeAt(i)) >>> 0;
+  // fable named these off the LAST path segment, which is "anims.fbx" for every species that ships a
+  // separate anim file — so its vat/ directory is a wall of anims-<hash>.bin you cannot read. Name
+  // them for the ANIMAL.
+  const parts = key.split('|')[0].split('/');
+  const base = (parts[parts.length - 2] || 'vat').replace(/[^\w-]/g, '_');
+  return `${base}-${h.toString(16)}.bin`;
+}
+
+export async function bakeVATCached(key, root, skinned, clips, fps = FPS) {
+  const name = vatBinName(key, clips, fps, skinned.geometry.attributes.position.count);
+  try {
+    const r = await fetch(`/assets/vat/${name}`);
+    if (r.ok) {
+      const buf = await r.arrayBuffer();
+      const hlen = new DataView(buf).getUint32(0, true);
+      const meta = JSON.parse(new TextDecoder().decode(new Uint8Array(buf, 4, hlen)));
+      const half = new Uint16Array(buf.slice(4 + hlen));
+      // float32 CPU copy (footSlideSpeed reads positions back) reconstructed from the halves —
+      // they're exactly what the GPU renders anyway
+      const data = new Float32Array(half.length);
+      for (let i = 0; i < half.length; i++) data[i] = THREE.DataUtils.fromHalfFloat(half[i]);
+      const tex = new THREE.DataTexture(half, meta.W, meta.texH, THREE.RGBAFormat, THREE.HalfFloatType);
+      tex.minFilter = tex.magFilter = THREE.NearestFilter;
+      tex.needsUpdate = true;
+      return { tex, data, ...meta };
+    }
+    console.warn(`[vat] MISS ${name} (${key}) — cooking`);
+  } catch (e) { console.warn(`[vat] bin unreadable ${name} — cooking`, e); }
+  const vat = bakeVAT(root, skinned, clips, fps);
+  if (import.meta.env?.DEV) {
+    try {
+      const meta = { vCount: vat.vCount, total: vat.total, table: vat.table, fps: vat.fps, W: vat.W, rowsPerFrame: vat.rowsPerFrame, texH: vat.texH };
+      const hjson = new TextEncoder().encode(JSON.stringify(meta));
+      const out = new Uint8Array(4 + hjson.length + vat.tex.image.data.byteLength);
+      new DataView(out.buffer).setUint32(0, hjson.length, true);
+      out.set(hjson, 4);
+      out.set(new Uint8Array(vat.tex.image.data.buffer), 4 + hjson.length);
+      fetch(`/__save-vatbin?name=${name}`, { method: 'POST', body: out }).catch(() => { /* sink offline */ });
+      console.log(`[vat] cooked → ${name} (${(out.length / 1048576).toFixed(1)} MB)`);
+    } catch (e) { /* live bake still returned */ }
+  }
+  return vat;
+}
+
+// Bake clips → DataTexture: each texel = that vertex's posed LOCAL position at that frame. `root` is
+// the rig group (the mixer binds on it).
+export function bakeVAT(root, skinned, clips, fps = FPS) {
+  const savedS = root.scale.x; root.scale.set(1, 1, 1); // bake in native units, not display scale
+  const vCount = skinned.geometry.attributes.position.count;
+  const table = []; let total = 0;
+  for (const c of clips) { const cfps = c.userData?.bakeFps ?? fps; const frames = Math.max(2, Math.round(c.duration * cfps)); table.push({ name: c.name, start: total, frames, fps: cfps }); total += frames; }
+  // Tile the texture so WIDTH stays within the GPU limit: width = vertexCount would blow past the
+  // common maxTextureDimension2D = 8192 on a high-poly rig, and an over-wide DataTexture corrupts the
+  // whole frame. Pack each frame across `rowsPerFrame` rows of width W. For vCount <= 8192 this is
+  // W = vCount, rowsPerFrame = 1 — byte-identical to a plain single-row layout.
+  const MAXW = 8192;
+  const W = Math.min(vCount, MAXW), rowsPerFrame = Math.ceil(vCount / W), texH = total * rowsPerFrame;
+  const data = new Float32Array(W * texH * 4);
+  const mixer = new THREE.AnimationMixer(root);
+  const _v = new THREE.Vector3();
+  const posAttr = skinned.geometry.attributes.position; // bind positions
+  for (let ci = 0; ci < clips.length; ci++) {
+    const e = table[ci];
+    // strip position tracks → bake IN PLACE (locomotion is code-driven in herd.js, not baked)
+    const c = new THREE.AnimationClip(clips[ci].name, clips[ci].duration, clips[ci].tracks.filter((t) => !t.name.endsWith('.position')));
+    const action = mixer.clipAction(c); action.reset().play();
+    for (let f = 0; f < e.frames; f++) {
+      mixer.setTime((f / e.frames) * c.duration); // [0,duration) so the last frame wraps to the first
+      root.updateMatrixWorld(true);
+      const frameBaseRow = (e.start + f) * rowsPerFrame;
+      for (let i = 0; i < vCount; i++) {
+        _v.fromBufferAttribute(posAttr, i); // r184: applyBoneTransform reads the bind pos FROM target
+        skinned.applyBoneTransform(i, _v);
+        const idx = ((frameBaseRow + ((i / W) | 0)) * W + (i % W)) * 4;   // tiled: col = i%W, row-in-frame = i/W
+        data[idx] = _v.x; data[idx + 1] = _v.y; data[idx + 2] = _v.z; data[idx + 3] = 1;
+      }
+    }
+    action.stop();
+  }
+  root.scale.setScalar(savedS); root.updateMatrixWorld(true);
+  // HALF-float GPU texture — poses do not need float32, and this halves the VAT's VRAM. The float32
+  // bake stays on vat.data for footSlideSpeed, which reads positions back on the CPU.
+  const half = new Uint16Array(data.length);
+  for (let i = 0; i < data.length; i++) half[i] = THREE.DataUtils.toHalfFloat(data[i]);
+  const tex = new THREE.DataTexture(half, W, texH, THREE.RGBAFormat, THREE.HalfFloatType);
+  tex.minFilter = tex.magFilter = THREE.NearestFilter;
+  tex.needsUpdate = true;
+  return { tex, data, vCount, total, table, fps, W, rowsPerFrame, texH };
+}
+
+// MeshStandardNodeMaterial whose vertex position is read from the VAT for THIS instance's clip and
+// phase (aClip, aPhase) and whose albedo is tinted per-instance (aTint). uTime drives playback.
+export function vatMaterial(vat, albedo, layers = 1) {
+  const mat = new THREE.MeshStandardNodeMaterial({ roughness: 0.92, metalness: 0 });
+  const uTime = uniform(0); mat.userData.uTime = uTime;
+  const aClip = attribute('aClip', 'float'), aPhase = attribute('aPhase', 'float'), aTint = attribute('aTint', 'vec3');
+  const vId = attribute('vertexId', 'float');
+  const aLayer = layers > 1 ? attribute('aLayer', 'float') : null; // coat-variant column in the atlas
+  const uTable = uniformArray(vat.table.map((e) => new THREE.Vector3(e.start, e.frames, (e.fps ?? vat.fps) * ((vat.playFps ?? vat.fps) / vat.fps))));
+  const W = float(vat.W), RPF = float(vat.rowsPerFrame), texH = float(vat.texH);
+  mat.positionNode = Fn(() => {
+    const e = uTable.element(int(aClip));                       // vec3(startFrame, frameCount, fps)
+    const localFrame = floor(mod(uTime.add(aPhase).mul(e.z), e.y));
+    const globalFrame = e.x.add(localFrame);                    // frame index along the timeline
+    const col = mod(vId, W);
+    const texRow = globalFrame.mul(RPF).add(floor(vId.div(W)));
+    const u = col.add(0.5).div(W);
+    const v = texRow.add(0.5).div(texH);
+    return texture(vat.tex, vec2(u, v)).xyz;
+  })();
+  if (!albedo) mat.colorNode = aTint;
+  else if (layers > 1) mat.colorNode = texture(albedo, vec2(aLayer.add(uv().x).div(layers), uv().y)).mul(aTint);
+  else mat.colorNode = texture(albedo).mul(aTint);
+  return mat;
+}
+
+// Load a species' rig + animations, bake the requested clips, and return everything a Herd needs.
+// `def`: { rig, anims, texture, clips: { name: /regex/ }, height }. `clips` maps a logical name
+// (idle/walk/run/graze/…) to a regex picking the source clip; the KEY ORDER defines the aClip indices.
+export async function loadSpeciesVAT(def) {
+  const rig = await instantiate(def.rig, { texture: def.texture ?? def.textures?.[0], scale: 1 });
+  let skinned = null; rig.traverse((o) => { if (o.isSkinnedMesh && !skinned) skinned = o; });
+  if (!skinned) throw new Error(`no SkinnedMesh in ${def.rig}`);
+  skinned.normalizeSkinWeights?.();
+  const srcClips = ((await loadModel(def.anims ?? def.rig, { scale: 1 })).animations || []).map((c) => trimClip(c));
+
+  // ── PICK + BAKE EACH REQUESTED CLIP. THE FALLBACK IS NOT fable's, AND IT MATTERS. ──────────────
+  // fable falls back to srcClips[0] when a regex matches nothing. That is a disaster here, because
+  // these PolyPerfect packs are NOT uniform, and I read every one of their animation stacks out of
+  // the FBX binaries before writing a line of this:
+  //     cow     Walk, Idle1, Idle2, Attack, Death, Sleep     — NO run, NO graze
+  //     deer    walk, run, attack, death                     — NO idle at all
+  //     wolf    Idle, Walk, Run, Attack, Death               — no graze (fine: it is a predator)
+  //     goat    Idle, Walk, Run, Attack, Death, Eating
+  //     pig     idle2, walk, run, Eat, Sleep, attack, death
+  //     hen     Idle_2/3/Roost, Walk, Run, Eat, Fly, Sleep, Attack
+  //     eagle   Idle, Walk, Run, Flying, Death
+  // Under fable's rule a spooked cow would flee playing whichever stack came first in its file. So:
+  //   `alias`  — a missing clip REUSES another logical clip's bake. Costs nothing: same row block.
+  //   `still`  — a missing clip is a FROZEN POSE lifted from another clip. This is what the deer's
+  //              idle is: with no idle in the pack, aliasing idle→walk gives you a deer marching on
+  //              the spot, which is worse than a deer standing still.
+  const baked = [], clipIndex = {}, missing = [];
+  const pick = (re) => srcClips.find((x) => re.test(x.name) && !/ to | to$|_to_/i.test(x.name)) || srcClips.find((x) => re.test(x.name));
+  // TWO SLOTS THAT RESOLVE TO THE SAME SOURCE CLIP GET ONE BAKE, NOT TWO. The eagle's idle, walk and
+  // run all pick Eagle_Flying (it has no glide reel and a soaring bird has no business walking), and
+  // baking that three times would put three identical copies of the same 24 MB rig's frames into the
+  // VAT texture. Row blocks are shared by index; nothing downstream can tell.
+  const seen = new Map();
+  for (const n of Object.keys(def.clips)) {
+    const c = pick(def.clips[n]);
+    if (!c) { missing.push(n); continue; }
+    if (seen.has(c)) { clipIndex[n] = seen.get(c); continue; }
+    seen.set(c, baked.length);
+    clipIndex[n] = baked.length;
+    baked.push(trimClip(c, n));
+  }
+  for (const n of missing) {                       // second pass: every real clip is now indexed
+    // `still: { idle: 'walk' }` freezes the source's FIRST pose; `still: { dead: ['death', 1] }`
+    // freezes the pose at that FRACTION of the source — how a carcass holds a death take's last frame.
+    const stRaw = def.still?.[n];
+    const [st, stFrac] = Array.isArray(stRaw) ? stRaw : [stRaw, 0];
+    if (st && clipIndex[st] != null) {
+      const src = baked[clipIndex[st]];
+      clipIndex[n] = baked.length; baked.push(freezeClip(src, n, src.duration * stFrac)); continue;
+    }
+    const al = def.alias?.[n];
+    if (al && clipIndex[al] != null) { clipIndex[n] = clipIndex[al]; continue; }
+    console.warn(`[vat] ${def.rig.split('/').slice(-2)[0]}: no clip and no alias for "${n}" — it will play clip 0`);
+    clipIndex[n] = 0;
+  }
+  if (!baked.length) throw new Error(`no clips to bake for ${def.rig}`);
+  // idles at 15 fps — halves the rows they cost in the VAT texture, and a sway does not need 30
+  for (const c of baked) if (!/^(walk|run)$/.test(c.name)) (c.userData ??= {}).bakeFps = 15;
+
+  const vat = await bakeVATCached(`${def.rig}|${def.anims ?? ''}`, rig, skinned, baked);
+  vat.playFps = vat.fps * (def.playRate ?? 1);
+
+  // Size and ground the species from THE BAKE ITSELF (frame-0 posed positions) — the exact space
+  // vatMaterial renders from. Bind-space geometry.boundingBox is a trap on GLB rigs: the bind
+  // geometry sits in a different space than the posed skin, which pins def.height against the wrong
+  // denominator (fable's half-size sheep).
+  const box = new THREE.Box3();
+  {
+    const Wt = vat.W, v = new THREE.Vector3();
+    for (let i = 0; i < vat.vCount; i++) {
+      const idx = ((((i / Wt) | 0)) * Wt + (i % Wt)) * 4;   // frame 0 occupies rows 0..rowsPerFrame-1
+      v.set(vat.data[idx], vat.data[idx + 1], vat.data[idx + 2]);
+      box.expandByPoint(v);
+    }
+  }
+  const size = box.getSize(new THREE.Vector3());
+  // sizeBy 'max': a bird binds wings-SPREAD, so Y is its THINNEST axis and height/size.y would make a
+  // pterodactyl of it. Its def.height targets the WINGSPAN instead. Land animals keep Y.
+  const dim = def.sizeBy === 'max' ? Math.max(size.x, size.y, size.z) : size.y;
+  const scale = (def.height ?? 1.4) / (dim || 1);
+  // ground speeds derived from the walk/run animations themselves — no foot-sliding
+  const walkSpeed = rootMotionSpeed(baked[clipIndex.walk], scale) || footSlideSpeed(vat, clipIndex.walk, scale);
+  const runSpeed = rootMotionSpeed(baked[clipIndex.run], scale) || footSlideSpeed(vat, clipIndex.run, scale);
+  // coat: a single map, or N side-by-side variants the herd picks from per-instance
+  let albedo, layers = 1;
+  if (def.textures) { const a = await stackTextures(def.textures); albedo = a.tex; layers = a.layers; }
+  else albedo = (Array.isArray(skinned.material) ? skinned.material[0] : skinned.material).map;
+  // static geometry: positions come from the VAT; carry a vertexId column index
+  const geometry = skinned.geometry.clone();
+  const vid = new Float32Array(vat.vCount); for (let i = 0; i < vat.vCount; i++) vid[i] = i;
+  geometry.setAttribute('vertexId', new THREE.BufferAttribute(vid, 1));
+  return { vat, geometry, albedo, layers, scale, clipIndex, walkSpeed, runSpeed, footY: box.min.y * scale, size };
+}