@netforge/asset-library 0.0.0-stage → 0.1.0

package/src/three/crowd.ts

@@ -0,0 +1,216 @@
+/**
+ * Crowd models: a library model baked into static geometry for
+ * InstancedMesh, so 2,000 enemies stay one draw per material group. The
+ * model is posed once (a frame of its walk or idle clip, so nobody is
+ * frozen in a T-pose), skinning is applied on the CPU, and parts are merged:
+ * untextured materials become vertex colours in one draw, textured ones
+ * keep their map (one draw per map). Motion comes from the body plan
+ * (bob, waddle, hover, squash) in the template's instance matrices.
+ */
+import { AnimationMixer, BufferAttribute, BufferGeometry, Color, InstancedBufferAttribute, InstancedBufferGeometry, InstancedMesh, Matrix4, Mesh, MeshStandardNodeMaterial, Quaternion, Vector3 } from "three/webgpu";
+import { float, instancedBufferAttribute, positionGeometry } from "three/tsl";
+import { billboardWorld, isSprite } from "@netforge/engine/runtime";
+import type { MeshStandardMaterial } from "three/webgpu";
+import type { AnimationClip, Material, SkinnedMesh, Texture } from "three/webgpu";
+import type { RigDef } from "../rigs.js";
+import { clipFor } from "../rigs.js";
+import type { PreparedModel } from "./prepare.js";
+
+export interface CrowdPart {
+  readonly geometry: BufferGeometry;
+  readonly material: Material;
+}
+
+export interface CrowdModel {
+  readonly parts: readonly CrowdPart[];
+  readonly height: number;
+  readonly triangles: number;
+}
+
+interface Bucket {
+  pos: number[];
+  nor: number[];
+  uv: number[];
+  col: number[];
+  map: Texture | null;
+  emissive: Color;
+  roughness: number;
+  metalness: number;
+}
+
+export interface Placement {
+  readonly x: number;
+  readonly z: number;
+  readonly y?: number;
+  readonly yaw?: number;
+  /** Scale across (x and z) and up (y). Default 1. */
+  readonly across?: number;
+  readonly up?: number;
+}
+
+/** Sprite scenery (pixel style): one draw of camera-facing planes, each at its spot and scale (yaw does not apply). */
+function placeSprites(p: CrowdPart, placements: readonly Placement[]): Mesh {
+  const g = new InstancedBufferGeometry();
+  if (p.geometry.index) g.setIndex(p.geometry.index);
+  for (const [name, a] of Object.entries(p.geometry.attributes)) g.setAttribute(name, a);
+  const spots = new Float32Array(Math.max(1, placements.length) * 4);
+  placements.forEach((pl, i) => spots.set([pl.x, pl.y ?? 0, pl.z, pl.up ?? 1], i * 4));
+  const spot = new InstancedBufferAttribute(spots, 4);
+  g.instanceCount = placements.length;
+  const m = (p.material as MeshStandardNodeMaterial).clone();
+  const at = instancedBufferAttribute<"vec4">(spot, "vec4");
+  m.positionNode = billboardWorld(at.xyz, positionGeometry.x.mul(at.w), positionGeometry.y.mul(at.w), float(1));
+  const mesh = new Mesh(g, m);
+  mesh.frustumCulled = false;
+  return mesh;
+}
+
+/** Static scenery: one InstancedMesh per part (sprites: one billboard draw), every placement drawn. Add the result to the scene. */
+export function placeStatic(model: CrowdModel, placements: readonly Placement[]): Mesh[] {
+  const m = new Matrix4();
+  const q = new Quaternion();
+  const axis = new Vector3(0, 1, 0);
+  const pos = new Vector3();
+  const scl = new Vector3();
+  return model.parts.map((p) => {
+    if (isSprite(p.geometry)) return placeSprites(p, placements);
+    const mesh = new InstancedMesh(p.geometry, p.material, Math.max(1, placements.length));
+    placements.forEach((pl, i) => {
+      q.setFromAxisAngle(axis, pl.yaw ?? 0);
+      pos.set(pl.x, pl.y ?? 0, pl.z);
+      scl.set(pl.across ?? 1, pl.up ?? pl.across ?? 1, pl.across ?? 1);
+      mesh.setMatrixAt(i, m.compose(pos, q, scl));
+    });
+    mesh.count = placements.length;
+    mesh.instanceMatrix.needsUpdate = true;
+    mesh.computeBoundingSphere();
+    return mesh;
+  });
+}
+
+/** Pose a prepared model at a frame of a clip (walk, else idle), in place. */
+export function poseModel(p: PreparedModel, clips: readonly AnimationClip[], rig: RigDef | undefined, at = 0.25): void {
+  if (!rig || clips.length === 0) return;
+  const name = clipFor(rig, "walk", clips.map((c) => c.name)) ?? clipFor(rig, "idle", clips.map((c) => c.name));
+  const clip = clips.find((c) => c.name === name);
+  if (!clip) return;
+  const mixer = new AnimationMixer(p.model);
+  mixer.clipAction(clip).play();
+  mixer.update(Math.min(at, clip.duration * 0.5));
+  p.root.updateMatrixWorld(true);
+}
+
+/**
+ * Skinning and mirrored exports can leave a mesh inside out. Faces of a
+ * closed low-poly model mostly point away from its centre: if the summed
+ * area-weighted outward dot is negative, swap every triangle's winding.
+ */
+function orientOutward(b: Bucket): void {
+  const p = b.pos;
+  const n = p.length / 9;
+  if (n === 0) return;
+  let cx = 0;
+  let cy = 0;
+  let cz = 0;
+  for (let i = 0; i < p.length; i += 3) {
+    cx += p[i] ?? 0;
+    cy += p[i + 1] ?? 0;
+    cz += p[i + 2] ?? 0;
+  }
+  const vn = p.length / 3;
+  cx /= vn;
+  cy /= vn;
+  cz /= vn;
+  let score = 0;
+  for (let t = 0; t < n; t++) {
+    const o = t * 9;
+    const ax = p[o] ?? 0, ay = p[o + 1] ?? 0, az = p[o + 2] ?? 0;
+    const ux = (p[o + 3] ?? 0) - ax, uy = (p[o + 4] ?? 0) - ay, uz = (p[o + 5] ?? 0) - az;
+    const wx = (p[o + 6] ?? 0) - ax, wy = (p[o + 7] ?? 0) - ay, wz = (p[o + 8] ?? 0) - az;
+    const nx = uy * wz - uz * wy, ny = uz * wx - ux * wz, nz = ux * wy - uy * wx;
+    score += nx * (ax - cx) + ny * (ay - cy) + nz * (az - cz);
+  }
+  if (score >= 0) return;
+  const swap = (arr: number[], width: number) => {
+    for (let t = 0; t < n; t++) {
+      const b1 = (t * 3 + 1) * width;
+      const b2 = (t * 3 + 2) * width;
+      for (let k = 0; k < width; k++) {
+        const x = arr[b1 + k] ?? 0;
+        arr[b1 + k] = arr[b2 + k] ?? 0;
+        arr[b2 + k] = x;
+      }
+    }
+  };
+  swap(b.pos, 3);
+  swap(b.col, 3);
+  swap(b.uv, 2);
+}
+
+/** Bake a prepared (and posed) model into merged static parts in the root's frame. */
+export function bakeCrowd(p: PreparedModel): CrowdModel {
+  p.root.updateMatrixWorld(true);
+  const rootInv = p.root.matrixWorld.clone().invert();
+  const buckets = new Map<string, Bucket>();
+  const v = new Vector3();
+  const tmp = new Color();
+  let triangles = 0;
+  p.root.traverse((o) => {
+    const m = o as Mesh;
+    if (!m.isMesh || !m.visible) return;
+    const g = m.geometry as BufferGeometry;
+    const pos = g.getAttribute("position");
+    if (!pos) return;
+    const uv = g.getAttribute("uv");
+    // Vertex colours (the voxel style's per-voxel colour and occlusion) multiply the material's.
+    const vc = g.getAttribute("color");
+    const index = g.getIndex();
+    const mats: Material[] = Array.isArray(m.material) ? m.material : [m.material];
+    const groups = g.groups.length ? g.groups : [{ start: 0, count: index ? index.count : pos.count, materialIndex: 0 }];
+    const world = rootInv.clone().multiply(m.matrixWorld);
+    const skinned = (m as SkinnedMesh).isSkinnedMesh;
+    // A mirrored transform flips triangle winding; swap two corners back so faces point out.
+    const mirrored = world.determinant() < 0;
+    for (const grp of groups) {
+      const mat = (mats[grp.materialIndex ?? 0] ?? mats[0]) as MeshStandardMaterial;
+      const map = mat.map ?? null;
+      const key = map ? `map:${map.uuid}` : "color";
+      let b = buckets.get(key);
+      if (!b) {
+        b = { pos: [], nor: [], uv: [], col: [], map, emissive: (mat.emissive ?? new Color(0)).clone(), roughness: mat.roughness ?? 0.7, metalness: mat.metalness ?? 0 };
+        buckets.set(key, b);
+      }
+      const color = mat.color ? tmp.copy(mat.color) : tmp.setRGB(1, 1, 1);
+      for (let k = grp.start; k < grp.start + grp.count; k++) {
+        const corner = (k - grp.start) % 3;
+        const kk = mirrored && corner > 0 ? k + (corner === 1 ? 1 : -1) : k;
+        const i = index ? index.getX(kk) : kk;
+        if (skinned) (m as SkinnedMesh).getVertexPosition(i, v);
+        else v.fromBufferAttribute(pos, i);
+        v.applyMatrix4(world);
+        b.pos.push(v.x, v.y, v.z);
+        b.uv.push(uv ? uv.getX(i) : 0, uv ? uv.getY(i) : 0);
+        if (vc) b.col.push(color.r * vc.getX(i), color.g * vc.getY(i), color.b * vc.getZ(i));
+        else b.col.push(color.r, color.g, color.b);
+      }
+      triangles += Math.floor(grp.count / 3);
+    }
+  });
+  const parts: CrowdPart[] = [];
+  for (const b of buckets.values()) {
+    orientOutward(b);
+    const geometry = new BufferGeometry();
+    geometry.setAttribute("position", new BufferAttribute(new Float32Array(b.pos), 3));
+    geometry.setAttribute("color", new BufferAttribute(new Float32Array(b.col), 3));
+    if (b.map) geometry.setAttribute("uv", new BufferAttribute(new Float32Array(b.uv), 2));
+    // Flat normals: the library is low-poly and reads best faceted.
+    geometry.computeVertexNormals();
+    geometry.computeBoundingSphere();
+    // A node material (vertex colours on) so the engine's AnimatedCrowd can take it as-is, and plain InstancedMesh draws it too.
+    const material = new MeshStandardNodeMaterial();
+    Object.assign(material, { vertexColors: true, map: b.map, roughness: b.roughness, metalness: b.metalness, flatShading: true });
+    material.emissive.copy(b.emissive);
+    parts.push({ geometry, material });
+  }
+  return { parts, height: p.height, triangles };
+}

package/src/three/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @netforge/asset-library/three: draw library models with three.js
+ * (WebGPU with the WebGL2 fallback, through the engine runtime).
+ */
+export { LibraryClient, spriteMultiple } from "./client.js";
+export type { CharacterInstance, LibraryClientOptions, ModelSource } from "./client.js";
+export { RigAnimator, StaticAnimator } from "./animator.js";
+export type { CharacterAnimator } from "./animator.js";
+export { bakeCrowd, placeStatic, poseModel } from "./crowd.js";
+export type { CrowdModel, CrowdPart, Placement } from "./crowd.js";
+export { prepareModel, shiftColor } from "./prepare.js";
+export type { LoadedModel, PreparedModel } from "./prepare.js";
+export { buildPart, proceduralAsset } from "./parts.js";

package/src/three/parts.ts

@@ -0,0 +1,149 @@
+/**
+ * Look parts and procedural pickups, built from three.js primitives.
+ * Parts are sized from the model's height and placed at an anchor; the
+ * caller parents them so they follow the animation.
+ */
+import {
+  BoxGeometry,
+  BufferGeometry,
+  Color,
+  ConeGeometry,
+  CylinderGeometry,
+  Group,
+  IcosahedronGeometry,
+  Mesh,
+  MeshStandardMaterial,
+  OctahedronGeometry,
+  SphereGeometry,
+  TorusGeometry,
+} from "three/webgpu";
+import type { AppearancePart } from "@netforge/engine";
+import { voxel } from "@netforge/engine/runtime";
+
+const mat = (color: number, emissive = 0, intensity = 1) =>
+  new MeshStandardMaterial({ color: new Color(color), emissive: new Color(emissive), emissiveIntensity: intensity, roughness: 0.6, flatShading: true });
+
+function mesh(g: BufferGeometry, m: MeshStandardMaterial, x = 0, y = 0, z = 0, rx = 0, ry = 0, rz = 0): Mesh {
+  const o = new Mesh(g, m);
+  o.position.set(x, y, z);
+  o.rotation.set(rx, ry, rz);
+  return o;
+}
+
+/**
+ * One part as a group whose origin is its anchor point, sized for a model
+ * `h` metres tall and `w` metres wide, in the model's frame (facing -z,
+ * y up). `accent` colours it; `body` is the model's main colour.
+ */
+export function buildPart(part: AppearancePart, h: number, w: number, accent: number, body: number): Group {
+  const g = new Group();
+  g.name = `look:${part}`;
+  const a = mat(accent);
+  const b = mat(body);
+  const s = h * 0.12;
+  switch (part) {
+    case "horns":
+      for (const side of [-1, 1]) g.add(mesh(new ConeGeometry(s * 0.35, s * 1.4, 6), a, side * w * 0.22, s * 0.5, 0, 0, 0, -side * 0.45));
+      break;
+    case "ears_long":
+      for (const side of [-1, 1]) {
+        const ear = new SphereGeometry(s * 0.45, 8, 6);
+        ear.scale(0.45, 2.4, 0.3);
+        g.add(mesh(ear, b, side * w * 0.2, s * 0.9, 0, 0, 0, -side * 0.25));
+        const tip = new ConeGeometry(s * 0.22, s * 0.55, 6);
+        g.add(mesh(tip, a, side * (w * 0.2 + s * 0.27), s * 1.85, 0, 0, 0, -side * 0.25));
+      }
+      break;
+    case "ears_round":
+      for (const side of [-1, 1]) {
+        const ear = new SphereGeometry(s * 0.5, 10, 8);
+        ear.scale(1, 1, 0.35);
+        g.add(mesh(ear, b, side * w * 0.24, s * 0.35, 0));
+      }
+      break;
+    case "antenna":
+      g.add(mesh(new CylinderGeometry(s * 0.05, s * 0.05, s * 1.2, 5), a, 0, s * 0.6, 0));
+      g.add(mesh(new SphereGeometry(s * 0.2, 8, 6), mat(accent, accent, 1.5), 0, s * 1.25, 0));
+      break;
+    case "crown": {
+      g.add(mesh(new CylinderGeometry(w * 0.2, w * 0.22, s * 0.35, 10, 1, true), mat(0xffd34d, 0x6a4a00, 0.4), 0, s * 0.15, 0));
+      for (let i = 0; i < 5; i++) {
+        const t = (i / 5) * Math.PI * 2;
+        g.add(mesh(new ConeGeometry(s * 0.12, s * 0.35, 4), mat(0xffd34d, 0x6a4a00, 0.4), Math.cos(t) * w * 0.2, s * 0.45, Math.sin(t) * w * 0.2));
+      }
+      break;
+    }
+    case "hat_cap": {
+      const dome = new SphereGeometry(w * 0.24, 10, 6, 0, Math.PI * 2, 0, Math.PI / 2);
+      g.add(mesh(dome, a, 0, -s * 0.1, 0));
+      const brim = new CylinderGeometry(w * 0.16, w * 0.16, s * 0.06, 10, 1, false, -Math.PI / 2, Math.PI);
+      g.add(mesh(brim, a, 0, -s * 0.08, -w * 0.18, 0, 0, 0));
+      break;
+    }
+    case "hat_top":
+      g.add(mesh(new CylinderGeometry(w * 0.3, w * 0.3, s * 0.08, 12), a, 0, 0, 0));
+      g.add(mesh(new CylinderGeometry(w * 0.17, w * 0.18, s * 1.1, 12), a, 0, s * 0.55, 0));
+      break;
+    case "mustache":
+      for (const side of [-1, 1]) {
+        const m = new SphereGeometry(s * 0.28, 8, 6);
+        m.scale(1.6, 0.55, 0.6);
+        g.add(mesh(m, a, side * s * 0.32, 0, 0, 0, 0, side * 0.35));
+      }
+      break;
+    case "tail": {
+      const t = new ConeGeometry(s * 0.3, s * 2, 7);
+      g.add(mesh(t, b, 0, s * 0.3, s * 0.8, -1.1, 0, 0));
+      break;
+    }
+    case "tail_bolt": {
+      const seg = (len: number) => new BoxGeometry(s * 0.28, len, s * 0.12);
+      g.add(mesh(seg(s * 0.9), mat(accent, accent, 0.6), 0, s * 0.3, s * 0.35, -0.9, 0, 0));
+      g.add(mesh(seg(s * 0.8), mat(accent, accent, 0.6), s * 0.18, s * 0.75, s * 0.7, 0.5, 0, 0.3));
+      g.add(mesh(seg(s * 1.1), mat(accent, accent, 0.6), 0, s * 1.2, s * 1.05, -0.9, 0, 0));
+      break;
+    }
+    case "wings":
+      for (const side of [-1, 1]) {
+        const wing = new BoxGeometry(s * 2.2, s * 0.9, s * 0.08);
+        wing.translate(side * s * 1.1, 0, 0);
+        g.add(mesh(wing, a, side * w * 0.08, 0, 0, 0, side * 0.5, side * 0.35));
+      }
+      break;
+    case "armor":
+      g.add(mesh(new BoxGeometry(w * 0.7, h * 0.28, w * 0.55), mat(0x9aa4b2, 0x101418, 0.2), 0, 0, 0));
+      break;
+    case "backpack":
+      g.add(mesh(new BoxGeometry(w * 0.45, h * 0.25, w * 0.25), a, 0, 0, w * 0.1));
+      break;
+    case "big_wheels":
+      // Applied to the model's wheel nodes (see prepare.ts), not added as geometry.
+      break;
+  }
+  return g;
+}
+
+/** Procedural pickups (no file): gems, cells. Geometry centred at the origin. */
+export function proceduralAsset(name: string): { geometry: BufferGeometry; material: MeshStandardMaterial } | null {
+  // The voxel style's pickups are built from voxels ("voxel_gem_small").
+  if (name.startsWith("voxel_")) return voxel.voxelPickup(name.slice(6)) as { geometry: BufferGeometry; material: MeshStandardMaterial } | null;
+  switch (name) {
+    case "gem_small":
+      return { geometry: new OctahedronGeometry(0.16), material: mat(0xffc04d, 0xff8a00, 1.6) };
+    case "gem_mid":
+      return { geometry: new OctahedronGeometry(0.24), material: mat(0x7ad7ff, 0x1e90ff, 1.8) };
+    case "gem_large":
+      return { geometry: new IcosahedronGeometry(0.4), material: mat(0xff7ad9, 0xff2fb0, 2) };
+    case "cell_heal": {
+      const g = new OctahedronGeometry(0.3);
+      g.scale(1, 1.5, 1);
+      return { geometry: g, material: mat(0x7dff9a, 0x2bff6a, 1.8) };
+    }
+    case "cell_spark":
+      return { geometry: new IcosahedronGeometry(0.22), material: mat(0x7ad7ff, 0x1e9bff, 1.8) };
+    case "ring":
+      return { geometry: new TorusGeometry(0.3, 0.06, 6, 16), material: mat(0xffd34d, 0xff9a00, 1) };
+    default:
+      return null;
+  }
+}

package/src/three/prepare.ts

@@ -0,0 +1,207 @@
+/**
+ * Turn a loaded glTF into a library model: cloned (skeletons included),
+ * turned to face -z, scaled to its height, standing on y = 0, centred on
+ * x/z, its palette shifted toward the look's tint, and its look parts
+ * attached so they follow the animation.
+ */
+import { Box3, Color, Group, Matrix4, Mesh, Object3D, Quaternion, SRGBColorSpace, Vector3 } from "three/webgpu";
+import type { BufferGeometry, Material, MeshStandardMaterial } from "three/webgpu";
+import { clone as cloneSkinned } from "three/addons/utils/SkeletonUtils.js";
+import type { ResolvedLook } from "../look.js";
+import { RIGS } from "../rigs.js";
+import { buildPart } from "./parts.js";
+
+export interface LoadedModel {
+  readonly scene: Object3D;
+  readonly animations: readonly import("three/webgpu").AnimationClip[];
+}
+
+export interface PreparedModel {
+  /** Add this to the scene. Origin at the feet, facing -z. */
+  readonly root: Group;
+  /** The cloned glTF scene inside root (what an AnimationMixer drives). */
+  readonly model: Object3D;
+  readonly height: number;
+  readonly width: number;
+  readonly depth: number;
+  /** The right-hand bone or node, for a held weapon (null when the rig has none). */
+  readonly hand: Object3D | null;
+}
+
+const tmpColor = new Color();
+const hsl = { h: 0, s: 0, l: 0 };
+const tintHsl = { h: 0, s: 0, l: 0 };
+
+/** Shift a colour's hue toward the tint, keep its lightness; near-greys and near-whites (eyes, teeth) stay. */
+export function shiftColor(c: Color, tint: number, keepSkin = false): void {
+  c.getHSL(hsl, SRGBColorSpace);
+  tmpColor.setHex(tint).getHSL(tintHsl, SRGBColorSpace);
+  if (hsl.s < 0.12 || hsl.l > 0.92 || hsl.l < 0.06) return;
+  // People keep their skin: warm, mid-light, moderately saturated tones stay as they are.
+  if (keepSkin && hsl.h >= 0.02 && hsl.h <= 0.12 && hsl.s <= 0.75 && hsl.l >= 0.35) return;
+  c.setHSL(tintHsl.h, Math.min(1, hsl.s * 0.4 + tintHsl.s * 0.6), hsl.l * 0.5 + tintHsl.l * 0.5, SRGBColorSpace);
+}
+
+/**
+ * Vertex-coloured models (the voxel style keeps each voxel's colour, with its
+ * occlusion baked in, per vertex): shift each colour's hue toward the tint,
+ * and scale lightness by one factor for the whole model so baked occlusion
+ * keeps its contrast. Near-greys and near-whites (eyes, teeth) stay.
+ */
+function tintVertexColors(root: Object3D, tint: number, keepSkin: boolean): void {
+  const done = new Map<BufferGeometry, BufferGeometry>();
+  tmpColor.setHex(tint).getHSL(tintHsl, SRGBColorSpace);
+  const c = new Color();
+  root.traverse((o) => {
+    const m = o as Mesh;
+    if (!m.isMesh) return;
+    const src = m.geometry as BufferGeometry;
+    const attr = src.getAttribute("color");
+    if (!attr) return;
+    let g = done.get(src);
+    if (!g) {
+      g = src.clone();
+      const col = g.getAttribute("color");
+      let sum = 0;
+      for (let i = 0; i < col.count; i++) sum += c.setRGB(col.getX(i), col.getY(i), col.getZ(i)).getHSL(hsl, SRGBColorSpace).l;
+      const mean = col.count ? sum / col.count : 0.5;
+      const k = mean > 0.02 ? (mean * 0.5 + tintHsl.l * 0.5) / mean : 1;
+      for (let i = 0; i < col.count; i++) {
+        c.setRGB(col.getX(i), col.getY(i), col.getZ(i)).getHSL(hsl, SRGBColorSpace);
+        if (hsl.s < 0.12 || hsl.l > 0.92 || hsl.l < 0.04) continue;
+        if (keepSkin && hsl.h >= 0.02 && hsl.h <= 0.12 && hsl.s <= 0.75 && hsl.l >= 0.3) continue;
+        c.setHSL(tintHsl.h, Math.min(1, hsl.s * 0.4 + tintHsl.s * 0.6), Math.min(1, hsl.l * k), SRGBColorSpace);
+        col.setXYZ(i, c.r, c.g, c.b);
+      }
+      col.needsUpdate = true;
+      done.set(src, g);
+    }
+    m.geometry = g;
+  });
+}
+
+function tintMaterials(root: Object3D, tint: number, keepSkin: boolean): void {
+  const done = new Map<Material, Material>();
+  tintVertexColors(root, tint, keepSkin);
+  root.traverse((o) => {
+    const m = o as Mesh;
+    if (!m.isMesh) return;
+    const swap = (mat: Material): Material => {
+      let c = done.get(mat);
+      if (!c) {
+        c = mat.clone();
+        const sm = c as MeshStandardMaterial;
+        if (sm.color) {
+          if (sm.map) sm.color.lerp(tmpColor.setHex(tint), 0.3);
+          else shiftColor(sm.color, tint, keepSkin);
+        }
+        done.set(mat, c);
+      }
+      return c;
+    };
+    m.material = Array.isArray(m.material) ? m.material.map(swap) : swap(m.material);
+  });
+}
+
+function findNode(root: Object3D, re: RegExp | null): Object3D | null {
+  if (!re) return null;
+  let hit: Object3D | null = null;
+  root.traverse((o) => {
+    if (!hit && re.test(o.name)) hit = o;
+  });
+  return hit;
+}
+
+/** Parent `child` to `bone` keeping the world placement it has now (relative to `frame`). */
+function attachKeepingPlacement(child: Object3D, bone: Object3D): void {
+  bone.updateWorldMatrix(true, false);
+  const inv = new Matrix4().copy(bone.matrixWorld).invert();
+  child.updateWorldMatrix(true, false);
+  const local = inv.multiply(child.matrixWorld);
+  const p = new Vector3();
+  const q = new Quaternion();
+  const s = new Vector3();
+  local.decompose(p, q, s);
+  child.removeFromParent();
+  bone.add(child);
+  child.position.copy(p);
+  child.quaternion.copy(q);
+  child.scale.copy(s);
+}
+
+/**
+ * Prepare a loaded model for drawing. `height` overrides the asset's own
+ * (enemies are sized from their hit radius); the look's scale multiplies it.
+ */
+export function prepareModel(loaded: LoadedModel, look: ResolvedLook, opts: { height?: number } = {}): PreparedModel {
+  const asset = look.asset;
+  const model = cloneSkinned(loaded.scene);
+  const inner = new Group();
+  inner.add(model);
+  // glTF models face +z; the runtime's forward is -z.
+  inner.rotation.y = Math.PI + asset.yaw;
+  const root = new Group();
+  root.name = look.requested;
+  root.add(inner);
+  // Big wheels: grow the wheel nodes before measuring, so the truck stands on them.
+  if (look.parts.some((p) => p.part === "big_wheels")) {
+    const wheels: Object3D[] = [];
+    model.traverse((o) => {
+      // Outermost wheel nodes only, so a wheel and its child mesh are not both scaled.
+      if (/wheel/i.test(o.name) && !(o.parent && /wheel/i.test(o.parent.name))) wheels.push(o);
+    });
+    for (const w of wheels) w.scale.multiplyScalar(1.9);
+  }
+  root.updateMatrixWorld(true);
+  const box = new Box3().setFromObject(root, true);
+  const size = box.getSize(new Vector3());
+  const target = (opts.height ?? asset.height) * look.scale;
+  const k = size.y > 1e-6 ? target / size.y : 1;
+  inner.scale.setScalar(k);
+  const centre = box.getCenter(new Vector3());
+  inner.position.set(-centre.x * k, -box.min.y * k, -centre.z * k);
+  root.updateMatrixWorld(true);
+  const height = size.y * k;
+  const width = size.x * k;
+  const depth = size.z * k;
+  if (look.tint !== null) tintMaterials(model, look.tint, asset.kind === "character");
+
+  const rig = asset.rig ? RIGS[asset.rig] : undefined;
+  const head = findNode(model, rig?.headBone ?? null);
+  const headEnd = head ? findNode(model, /^head_end$/i) : null;
+  const body = findNode(model, /^(torso|chest|spine|body)/i);
+  const bodyColor = look.tint ?? 0xcccccc;
+  for (const p of look.parts) {
+    if (p.part === "big_wheels") continue;
+    const part = buildPart(p.part, height, Math.max(width, depth * 0.6), look.accent, bodyColor);
+    // Anchor points in the root's frame (facing -z): head on top, face in front, back and tail behind.
+    // Anchors in the root's frame (facing -z). The head bone, when the rig has one, places head and face parts;
+    // otherwise four-legged bodies carry their head at the front and bipeds on top.
+    const four = asset.plan === "quadruped";
+    const hp = head ? head.getWorldPosition(new Vector3()) : four ? new Vector3(0, height * 0.8, -depth * 0.4) : new Vector3(0, height * 0.85, 0);
+    // The head bone sits at the neck; its end (when the rig has one) is the crown.
+    const crown = headEnd ? headEnd.getWorldPosition(new Vector3()) : null;
+    const headTop = crown ? crown.y : head ? Math.min(height * 0.99, hp.y + height * (four ? 0.12 : 0.1)) : four ? height * 0.95 : height * 0.97;
+    const headSize = Math.max(0.05, headTop - (head ? hp.y : height * 0.75));
+    switch (p.anchor) {
+      case "head":
+        part.position.set(crown?.x ?? hp.x, headTop - headSize * 0.08, crown?.z ?? hp.z);
+        break;
+      case "face":
+        part.position.set(hp.x, head ? hp.y + headSize * 0.35 : height * 0.72, (head ? hp.z : 0) - (four ? depth * 0.12 : headSize * 0.62));
+        break;
+      case "back":
+        part.position.set(0, height * (four ? 0.7 : 0.62), four ? 0 : depth * 0.35);
+        break;
+      case "tail":
+        part.position.set(0, height * (four ? 0.55 : 0.3), depth * 0.48);
+        break;
+      default:
+        part.position.set(0, height * 0.5, 0);
+    }
+    root.add(part);
+    const bone = p.anchor === "head" || p.anchor === "face" ? head : p.anchor === "back" || p.anchor === "body" ? body : null;
+    if (bone) attachKeepingPlacement(part, bone);
+  }
+  return { root, model, height, width, depth, hand: findNode(model, rig?.handBone ?? null) };
+}

package/src/vite.ts

@@ -0,0 +1,89 @@
+/**
+ * Vite plugin: serve the built library at ./library in dev and copy it into
+ * the build, so a template plays with real models offline once the library
+ * is built (or copied from @netforge/asset-library-files). With `ids`, only those assets
+ * (and the bases of variants) are copied: a draft build ships what it uses.
+ * In production the page reads VITE_LIBRARY_URL (the published CID) instead
+ * and nothing needs copying (`copy: false`).
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, normalize, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Plugin } from "vite";
+import { assetById, baseAsset, library, soundById } from "./library.js";
+import { assetPath, soundPath } from "./paths.js";
+
+/** This package's root (the published package holds no scripts/, so this is found here rather than imported from them). */
+const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+export const DEFAULT_LIBRARY_DIR = join(PACKAGE_DIR, ".library");
+
+const TYPES: Readonly<Record<string, string>> = { glb: "model/gltf-binary", png: "image/png", webp: "image/webp", json: "application/json", ogg: "audio/ogg", mp3: "audio/mpeg" };
+
+export interface LibraryPluginOptions {
+  readonly dir?: string;
+  /** Library ids to copy into the build; all of them when omitted. */
+  readonly ids?: () => readonly string[];
+  /** Copy into the build (default true). */
+  readonly copy?: boolean;
+  /** With ids: also copy the audio section (every sound, about 3.5 MB). Default true. */
+  readonly audio?: boolean;
+}
+
+/** Library paths for some ids: their files, the files of variant bases, and sounds (audio.*). */
+export function filesFor(ids: readonly string[]): string[] {
+  const out = new Set<string>();
+  for (const id of ids) {
+    const s = soundById(id);
+    if (s) out.add(soundPath(s));
+    const a = assetById(id);
+    if (!a) continue;
+    const p = assetPath(baseAsset(a));
+    if (p) out.add(p);
+  }
+  return [...out].sort();
+}
+
+function allFiles(dir: string): string[] {
+  const index = join(dir, "index.json");
+  if (!existsSync(index)) return [];
+  const parsed = JSON.parse(readFileSync(index, "utf8")) as { assets: Record<string, { path: string }> };
+  return [...new Set(Object.values(parsed.assets).map((a) => a.path))].sort();
+}
+
+export function assetLibrary(o: LibraryPluginOptions = {}): Plugin {
+  const dir = resolve(o.dir ?? DEFAULT_LIBRARY_DIR);
+  return {
+    name: "netnet-asset-library",
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const url = (req.url ?? "").split("?")[0] ?? "";
+        const i = url.indexOf("/library/");
+        if (i < 0) return next();
+        const rel = normalize(decodeURIComponent(url.slice(i + "/library/".length)));
+        const file = join(dir, rel);
+        if (!file.startsWith(dir) || !existsSync(file) || !statSync(file).isFile()) {
+          res.statusCode = 404;
+          res.end("not in the built library (see @netforge/asset-library-files)");
+          return;
+        }
+        res.setHeader("content-type", TYPES[rel.split(".").pop() ?? ""] ?? "application/octet-stream");
+        res.setHeader("cache-control", "no-cache");
+        res.end(readFileSync(file));
+      });
+    },
+    generateBundle() {
+      if (o.copy === false) return;
+      if (!existsSync(dir)) {
+        this.warn(`no built asset library at ${dir}; the build draws primitive shapes (pass the library folder as dir; @netforge/asset-library-files has the built library)`);
+        return;
+      }
+      const files = o.ids ? filesFor([...o.ids(), ...(o.audio === false ? [] : library().sounds.keys())]) : allFiles(dir);
+      for (const f of files) {
+        const src = join(dir, f);
+        if (!existsSync(src)) continue;
+        this.emitFile({ type: "asset", fileName: `library/${f}`, source: readFileSync(src) });
+      }
+    },
+  };
+}