lecodes-assets 0.2.0 → 2.4.10

package/src/filmstrip.ts

@@ -0,0 +1,263 @@
+// Software-skinned mesh filmstrip — the real silhouette of a GLB clip with no browser, no GPU, no
+// engine and no native dependency. Evaluates the animation, skins the vertices on the CPU, flat-
+// shades and z-buffers the triangles into one PNG strip (own encoder). This is the sanity check for
+// `convert --clips`, `retarget` and `--merge-skins`: "does the character actually walk upright" is
+// not a question a numeric check answers. `probe --filmstrip` and tools/filmstrip.ts both call it.
+
+import { type Document } from "@gltf-transform/core"
+import { rigFromDocument, qnorm, qslerp, type Pose, type Quat, type Vec3 } from "./retarget/rig"
+import { encodePng } from "./textures/resolveImage"
+
+export type FilmstripView = "side" | "front" | "top" | "threequarter" | "lowfront"
+export type FilmstripOptions = {
+  /** clip name; null/undefined = the rest pose (one frame) */
+  clip?: string | null
+  frames?: number
+  view?: FilmstripView
+  /** pixels per frame (default 240) */
+  cell?: number
+  /** overlay the skeleton (joints + bones) */
+  bones?: boolean
+  /** the rest frame shows the BIND pose (from the IBMs) rather than the node TRS */
+  bind?: boolean
+  /** reference frames from other documents, drawn first at the same projection */
+  refs?: { doc: Document, clip?: string | null, time?: number, label?: string }[]
+  /** RGB of the mesh */
+  color?: [number, number, number]
+}
+export type FilmstripResult = { png: Uint8Array, width: number, height: number, label: string, duration: number }
+
+const matMul = (a: number[], b: number[]): number[] => {
+  const o = new Array(16).fill(0)
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) o[c * 4 + r] = a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + a[12 + r] * b[c * 4 + 3]
+  return o
+}
+const compose = (t: Vec3, q: Quat, s: Vec3): number[] => {
+  const [ x, y, z, w ] = q, x2 = x + x, y2 = y + y, z2 = z + z
+  const xx = x * x2, xy = x * y2, xz = x * z2, yy = y * y2, yz = y * z2, zz = z * z2, wx = w * x2, wy = w * y2, wz = w * z2
+  return [ (1 - (yy + zz)) * s[0], (xy + wz) * s[0], (xz - wy) * s[0], 0, (xy - wz) * s[1], (1 - (xx + zz)) * s[1], (yz + wx) * s[1], 0,
+           (xz + wy) * s[2], (yz - wx) * s[2], (1 - (xx + yy)) * s[2], 0, t[0], t[1], t[2], 1 ]
+}
+
+type Frame = { pos: Float32Array, tris: ArrayLike<number> }[]
+type Bone = { a: Vec3, b: Vec3 }
+
+/** Everything needed to pose + skin one document: rig, channels, skinned mesh nodes. */
+const prepare = (doc: Document, clipName: string | null | undefined, label: string) => {
+  const rig: any = rigFromDocument(doc, label)
+  const anim = clipName ? doc.getRoot().listAnimations().find((a) => a.getName() === clipName) ?? null : null
+  if (clipName && !anim) throw new Error(`no clip "${clipName}" in ${label} (has: ${doc.getRoot().listAnimations().map((a) => a.getName()).join(", ") || "none"})`)
+  const chans = (anim?.listChannels() ?? []).map((ch) => ({
+    node: rig.nodes.indexOf(ch.getTargetNode()!), path: ch.getTargetPath(),
+    times: ch.getSampler()!.getInput()!.getArray()!, vals: ch.getSampler()!.getOutput()!.getArray()!,
+  })).filter((c) => c.node >= 0)
+  let duration = 0
+  for (const c of chans) duration = Math.max(duration, c.times[c.times.length - 1])
+  const poseAt = (t: number, base: Pose): Pose => {
+    const p: Pose = { t: base.t.map((v: Vec3) => [ ...v ] as Vec3), r: base.r.map((v: Quat) => [ ...v ] as Quat), s: base.s.map((v: Vec3) => [ ...v ] as Vec3) }
+    for (const c of chans) {
+      const n = c.path === "rotation" ? 4 : 3, last = c.times.length - 1
+      let i = 0; while (i < last && c.times[i + 1] < t) i++
+      const u = i < last ? Math.max(0, Math.min(1, (t - c.times[i]) / (c.times[i + 1] - c.times[i] || 1))) : 0
+      const a = Array.from(c.vals.slice(i * n, i * n + n)) as number[]
+      const b = i < last ? Array.from(c.vals.slice((i + 1) * n, (i + 1) * n + n)) as number[] : a
+      const v = n === 4 ? qslerp(a as Quat, b as Quat, u) : a.map((x, k) => x + (b[k] - x) * u)
+      if (c.path === "rotation") p.r[c.node] = qnorm(v as Quat)
+      else if (c.path === "translation") p.t[c.node] = v as Vec3
+      else p.s[c.node] = v as Vec3
+    }
+    return p
+  }
+  const worldMats = (pose: Pose): number[][] => {
+    const out: number[][] = new Array(rig.names.length)
+    for (const i of rig.order) {
+      const local = compose(pose.t[i], pose.r[i], pose.s[i])
+      out[i] = rig.parents[i] >= 0 ? matMul(out[rig.parents[i]], local) : local
+    }
+    return out
+  }
+  // every skinned mesh node (a modular character has several); static meshes go through their node matrix
+  const skinnedNodes = rig.nodes.filter((n: any) => n.getMesh() && n.getSkin())
+  const staticNodes = rig.nodes.filter((n: any) => n.getMesh() && !n.getSkin())
+  if (skinnedNodes.length === 0 && staticNodes.length === 0) throw new Error(`${label}: no mesh to draw`)
+  const skinned = (pose: Pose): Frame => {
+    const wm = worldMats(pose)
+    const out: Frame = []
+    for (const meshNode of skinnedNodes) {
+      const skin = meshNode.getSkin(), ibmAcc = skin.getInverseBindMatrices()
+      const jointIdx = skin.listJoints().map((j: any) => rig.nodes.indexOf(j))
+      const mats = jointIdx.map((n: number, j: number) => matMul(wm[n], ibmAcc.getElement(j, [])))
+      for (const prim of meshNode.getMesh().listPrimitives()) {
+        const P = prim.getAttribute("POSITION")?.getArray(), J = prim.getAttribute("JOINTS_0")?.getArray(), W = prim.getAttribute("WEIGHTS_0")?.getArray()
+        if (!P || !J || !W) continue
+        const count = prim.getAttribute("POSITION").getCount()
+        const o = new Float32Array(count * 3)
+        for (let v = 0; v < count; v++) {
+          let x = 0, y = 0, z = 0
+          for (let k = 0; k < 4; k++) {
+            const w = W[v * 4 + k]
+            if (!w) continue
+            const m = mats[J[v * 4 + k]]
+            if (!m) continue
+            const px = P[v * 3], py = P[v * 3 + 1], pz = P[v * 3 + 2]
+            x += w * (m[0] * px + m[4] * py + m[8] * pz + m[12]); y += w * (m[1] * px + m[5] * py + m[9] * pz + m[13]); z += w * (m[2] * px + m[6] * py + m[10] * pz + m[14])
+          }
+          o[v * 3] = x; o[v * 3 + 1] = y; o[v * 3 + 2] = z
+        }
+        out.push({ pos: o, tris: prim.getIndices()?.getArray() ?? seq(count) })
+      }
+    }
+    for (const meshNode of staticNodes) {
+      const m = wm[rig.nodes.indexOf(meshNode)]
+      for (const prim of meshNode.getMesh().listPrimitives()) {
+        const P = prim.getAttribute("POSITION")?.getArray()
+        if (!P) continue
+        const count = prim.getAttribute("POSITION").getCount(), o = new Float32Array(count * 3)
+        for (let v = 0; v < count; v++) {
+          const px = P[v * 3], py = P[v * 3 + 1], pz = P[v * 3 + 2]
+          o[v * 3] = m[0] * px + m[4] * py + m[8] * pz + m[12]; o[v * 3 + 1] = m[1] * px + m[5] * py + m[9] * pz + m[13]; o[v * 3 + 2] = m[2] * px + m[6] * py + m[10] * pz + m[14]
+        }
+        out.push({ pos: o, tris: prim.getIndices()?.getArray() ?? seq(count) })
+      }
+    }
+    return out
+  }
+  const bonesOf = (pose: Pose): Bone[] => {
+    const wm = worldMats(pose)
+    const out: Bone[] = []
+    for (let i = 0; i < rig.names.length; i++) {
+      const p = rig.parents[i]
+      if (p < 0 || !rig.bind.fromSkin[i]) continue
+      out.push({ a: [ wm[p][12], wm[p][13], wm[p][14] ], b: [ wm[i][12], wm[i][13], wm[i][14] ] })
+    }
+    return out
+  }
+  return { rig, anim, duration, poseAt, skinned, bonesOf }
+}
+const seq = (n: number): Uint32Array => { const a = new Uint32Array(n); for (let i = 0; i < n; i++) a[i] = i; return a }
+
+// 3×5 glyphs for the time labels ("0.25s") and the header — enough without a font library.
+const FONT: Record<string, number[]> = {
+  "0": [ 7, 5, 5, 5, 7 ], "1": [ 2, 6, 2, 2, 7 ], "2": [ 7, 1, 7, 4, 7 ], "3": [ 7, 1, 7, 1, 7 ], "4": [ 5, 5, 7, 1, 1 ],
+  "5": [ 7, 4, 7, 1, 7 ], "6": [ 7, 4, 7, 5, 7 ], "7": [ 7, 1, 1, 1, 1 ], "8": [ 7, 5, 7, 5, 7 ], "9": [ 7, 5, 7, 1, 7 ],
+  ".": [ 0, 0, 0, 0, 2 ], "s": [ 0, 3, 4, 2, 6 ], " ": [ 0, 0, 0, 0, 0 ], "-": [ 0, 0, 7, 0, 0 ], ":": [ 0, 2, 0, 2, 0 ], "@": [ 7, 5, 7, 4, 7 ],
+}
+const drawText = (img: Uint8Array, W: number, x: number, y: number, text: string, rgb: [number, number, number], scale = 2): void => {
+  for (const ch of text.toLowerCase()) {
+    const g = FONT[ch] ?? FONT[" "]
+    for (let r = 0; r < 5; r++) for (let c = 0; c < 3; c++) if (g[r] & (4 >> c)) {
+      for (let sy = 0; sy < scale; sy++) for (let sx = 0; sx < scale; sx++) {
+        const px = x + c * scale + sx, py = y + r * scale + sy
+        const i = (py * W + px) * 4
+        if (i >= 0 && i + 3 < img.length) { img[i] = rgb[0]; img[i + 1] = rgb[1]; img[i + 2] = rgb[2] }
+      }
+    }
+    x += 4 * scale
+  }
+}
+const drawLine = (img: Uint8Array, W: number, H: number, x0: number, y0: number, x1: number, y1: number, rgb: [number, number, number]): void => {
+  const n = Math.max(1, Math.ceil(Math.max(Math.abs(x1 - x0), Math.abs(y1 - y0))))
+  for (let i = 0; i <= n; i++) {
+    const x = Math.round(x0 + (x1 - x0) * i / n), y = Math.round(y0 + (y1 - y0) * i / n)
+    if (x < 0 || y < 0 || x >= W || y >= H) continue
+    const o = (y * W + x) * 4
+    img[o] = rgb[0]; img[o + 1] = rgb[1]; img[o + 2] = rgb[2]
+  }
+}
+
+export const renderFilmstrip = (doc: Document, opts: FilmstripOptions = {}): FilmstripResult => {
+  const VIEW = opts.view ?? "side"
+  const main = prepare(doc, opts.clip, "model")
+  const N = main.anim ? Math.max(1, Math.floor(opts.frames ?? 8)) : 1   // the rest pose is one frame
+  const restPose: Pose = opts.bind ? main.rig.bind.local : main.rig.rest
+  const times = Array.from({ length: N }, (_, i) => (main.anim ? (i / Math.max(1, N - 1)) * main.duration : 0))
+  const frames: Frame[] = times.map((t) => main.skinned(main.anim ? main.poseAt(t, main.rig.rest) : restPose))
+  const boneLines: Bone[][] = opts.bones ? times.map((t) => main.bonesOf(main.anim ? main.poseAt(t, main.rig.rest) : restPose)) : []
+  const labels = times.map((t) => (main.anim ? `${t.toFixed(2)}s` : "rest"))
+  // reference frames (other files / clips) first, same projection
+  for (const ref of [ ...(opts.refs ?? []) ].reverse()) {
+    const r = prepare(ref.doc, ref.clip, ref.label ?? "ref")
+    frames.unshift(r.skinned(r.anim ? r.poseAt(ref.time ?? 0, r.rig.rest) : r.rig.rest))
+    if (opts.bones) boneLines.unshift([])
+    labels.unshift(ref.label ?? (ref.clip ? `${ref.clip}@${ref.time ?? 0}` : "ref"))
+  }
+  const NF = frames.length
+
+  // one projection for the whole strip, from the union of every frame's bounds
+  const lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+  for (const f of frames) for (const p of f) for (let v = 0; v < p.pos.length; v += 3)
+    for (let i = 0; i < 3; i++) { lo[i] = Math.min(lo[i], p.pos[v + i]); hi[i] = Math.max(hi[i], p.pos[v + i]) }
+  if (!Number.isFinite(lo[0])) { lo[0] = lo[1] = lo[2] = -1; hi[0] = hi[1] = hi[2] = 1 }
+
+  const CELL = opts.cell ?? 240, PAD = 10, HEAD = 20
+  const bases: Record<string, { r: Vec3, u: Vec3, d: Vec3 }> = {
+    side:         { r: [ 0, 0, 1 ], u: [ 0, 1, 0 ], d: [ -1, 0, 0 ] },
+    front:        { r: [ 1, 0, 0 ], u: [ 0, 1, 0 ], d: [ 0, 0, -1 ] },
+    top:          { r: [ 0, 0, 1 ], u: [ 1, 0, 0 ], d: [ 0, -1, 0 ] },
+    threequarter: { r: [ 0.7, 0, 0.71 ], u: [ -0.2, 0.96, 0.2 ], d: [ -0.68, -0.28, 0.68 ] },
+    lowfront:     { r: [ 1, 0, 0 ], u: [ 0, 0.87, -0.5 ], d: [ 0, 0.5, -0.87 ] },
+  }
+  const B = bases[VIEW] ?? bases.side
+  const dot = (a: Vec3, b: ArrayLike<number>): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+  const corners: Vec3[] = []
+  for (let i = 0; i < 8; i++) corners.push([ i & 1 ? hi[0] : lo[0], i & 2 ? hi[1] : lo[1], i & 4 ? hi[2] : lo[2] ])
+  const ru = corners.map((c) => [ dot(B.r, c), dot(B.u, c) ])
+  const rlo = [ Math.min(...ru.map((p) => p[0])), Math.min(...ru.map((p) => p[1])) ]
+  const rhi = [ Math.max(...ru.map((p) => p[0])), Math.max(...ru.map((p) => p[1])) ]
+  const k = (CELL - 2 * PAD) / Math.max(rhi[0] - rlo[0], rhi[1] - rlo[1], 1e-9)
+  const sx = (ox: number, q: ArrayLike<number>): number => ox + PAD + (dot(B.r, q) - rlo[0]) * k + (CELL - 2 * PAD - (rhi[0] - rlo[0]) * k) / 2
+  const sy = (q: ArrayLike<number>): number => HEAD + CELL - PAD - (dot(B.u, q) - rlo[1]) * k
+
+  const W = CELL * NF, H = CELL + HEAD
+  const img = new Uint8Array(W * H * 4)
+  for (let i = 0; i < W * H; i++) { img[i * 4] = 17; img[i * 4 + 1] = 21; img[i * 4 + 2] = 28; img[i * 4 + 3] = 255 }
+  const depth = new Float32Array(W * H).fill(Infinity)
+  const light: Vec3 = [ -0.4, 0.75, 0.53 ]
+  const base = opts.color ?? [ 214, 126, 58 ]
+  frames.forEach((frame, f) => {
+    const ox = f * CELL
+    for (const { pos, tris } of frame) {
+      for (let t = 0; t + 2 < tris.length; t += 3) {
+        const p: number[][] = []
+        for (let c = 0; c < 3; c++) { const v = tris[t + c] * 3; p.push([ pos[v], pos[v + 1], pos[v + 2] ]) }
+        const e1 = [ p[1][0] - p[0][0], p[1][1] - p[0][1], p[1][2] - p[0][2] ], e2 = [ p[2][0] - p[0][0], p[2][1] - p[0][1], p[2][2] - p[0][2] ]
+        const nx = e1[1] * e2[2] - e1[2] * e2[1], ny = e1[2] * e2[0] - e1[0] * e2[2], nz = e1[0] * e2[1] - e1[1] * e2[0]
+        const nl = Math.hypot(nx, ny, nz) || 1
+        const shade = 0.22 + 0.78 * Math.abs((nx / nl) * light[0] + (ny / nl) * light[1] + (nz / nl) * light[2])
+        const col = [ Math.round(base[0] * shade), Math.round(base[1] * shade), Math.round(base[2] * shade) ]
+        const sp = p.map((q) => [ sx(ox, q), sy(q), -dot(B.d, q) ])
+        const minX = Math.max(ox, Math.floor(Math.min(sp[0][0], sp[1][0], sp[2][0]))), maxX = Math.min(ox + CELL - 1, Math.ceil(Math.max(sp[0][0], sp[1][0], sp[2][0])))
+        const minY = Math.max(HEAD, Math.floor(Math.min(sp[0][1], sp[1][1], sp[2][1]))), maxY = Math.min(H - 1, Math.ceil(Math.max(sp[0][1], sp[1][1], sp[2][1])))
+        const d = (sp[1][0] - sp[0][0]) * (sp[2][1] - sp[0][1]) - (sp[2][0] - sp[0][0]) * (sp[1][1] - sp[0][1])
+        if (Math.abs(d) < 1e-12) continue
+        for (let y = minY; y <= maxY; y++) for (let x = minX; x <= maxX; x++) {
+          const px = x + 0.5, py = y + 0.5
+          const w0 = ((sp[1][0] - px) * (sp[2][1] - py) - (sp[2][0] - px) * (sp[1][1] - py)) / d
+          const w1 = ((sp[2][0] - px) * (sp[0][1] - py) - (sp[0][0] - px) * (sp[2][1] - py)) / d
+          const w2 = 1 - w0 - w1
+          if (w0 < 0 || w1 < 0 || w2 < 0) continue
+          const z = w0 * sp[0][2] + w1 * sp[1][2] + w2 * sp[2][2]
+          const i = y * W + x
+          if (z >= depth[i]) continue
+          depth[i] = z
+          img[i * 4] = col[0]; img[i * 4 + 1] = col[1]; img[i * 4 + 2] = col[2]
+        }
+      }
+    }
+  })
+  // overlays: cell borders, bones, labels
+  for (let f = 0; f < NF; f++) {
+    const ox = f * CELL
+    drawLine(img, W, H, ox, HEAD, ox, H - 1, [ 35, 44, 56 ])
+    drawLine(img, W, H, ox, HEAD, ox + CELL - 1, HEAD, [ 35, 44, 56 ])
+    for (const { a, b } of boneLines[f] ?? []) {
+      drawLine(img, W, H, sx(ox, a), sy(a), sx(ox, b), sy(b), [ 127, 224, 255 ])
+      const bx = Math.round(sx(ox, b)), by = Math.round(sy(b))
+      for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) if (bx + dx >= 0 && by + dy >= 0 && bx + dx < W && by + dy < H) { const o = ((by + dy) * W + bx + dx) * 4; img[o] = 255; img[o + 1] = 255; img[o + 2] = 255 }
+    }
+    drawText(img, W, ox + 6, HEAD + 6, labels[f], [ 140, 150, 170 ])
+  }
+  const label = `${main.anim ? main.anim.getName() : "rest pose"} · ${VIEW} view · ${NF} frames`
+  drawText(img, W, 6, 5, main.anim ? `${main.duration.toFixed(2)}s - ${N}` : "-", [ 136, 170, 170 ])   // the 3×5 font has digits, '.', 's', '-' only
+  return { png: encodePng({ width: W, height: H, data: img }), width: W, height: H, label, duration: main.duration }
+}

package/src/geometry.ts

@@ -0,0 +1,222 @@
+// geometry — a GLB's triangles as ONE plain vertex buffer the SDK's `Geometry` can hold
+// (`lecodes assets geometry casing.glb` → casing.geometry.json → `Geometry.load(asset(...))`).
+// Made for small debris the particle system draws per particle (shell casings, rubble, coins):
+// every mesh node's world transform is baked in, primitives are merged, and the result is what
+// `Geometry` carries — positions, normals, one UV set, uint16 indices. Materials, skins and
+// animations are dropped on purpose: the particle material is the SDK's.
+
+import type { Document, Node, Primitive } from "@gltf-transform/core"
+
+export type GeometryFile = {
+  format: "lecodes-geometry"
+  version: 1
+  /** xyz per vertex, metres, Y-up. */
+  vertices: number[]
+  /** xyz per vertex, unit length. */
+  normals: number[]
+  /** uv per vertex (zeros when the source has no TEXCOORD_0). */
+  uv: number[]
+  /** Triangle list, 3 per face, counter-clockwise front faces. */
+  indices: number[]
+  bounds: { min: [number, number, number], max: [number, number, number] }
+  /** What went in — for the reader's eyes only. */
+  source?: { file?: string, nodes: string[] }
+}
+
+export type ExtractOptions = {
+  /** Take only this node's subtree (name, exact match). Default: every mesh in the scene. */
+  node?: string
+  /** Re-origin the result: `center` = bounds centre at 0, `bottom` = footprint centre at X/Z = 0
+   *  and the lowest point at Y = 0. Default: keep the file's placement. */
+  origin?: "keep" | "center" | "bottom"
+  /** Uniform scale applied after the origin move (a casing modelled in cm → 0.01). */
+  scale?: number
+  /** Significant digits written to the file (default 6). */
+  precision?: number
+}
+
+export type ExtractReport = {
+  nodes: string[]
+  vertices: number
+  triangles: number
+  size: [number, number, number]
+  warnings: string[]
+}
+
+/** The SDK caps a Geometry's index buffer at uint16, and the particle vertex stream at ~1 M
+ *  vertices per system — a debris mesh past this is the wrong asset for the job anyway. */
+export const MAX_VERTICES = 65535
+
+type Mat4 = number[]
+
+const mul3 = (m: Mat4, x: number, y: number, z: number, w: number): [number, number, number] => [
+  m[0] * x + m[4] * y + m[8] * z + m[12] * w,
+  m[1] * x + m[5] * y + m[9] * z + m[13] * w,
+  m[2] * x + m[6] * y + m[10] * z + m[14] * w,
+]
+
+/** Inverse-transpose of the upper 3×3 (row-major 3×3 for `mulN`), null when singular. */
+const normalMatrix = (m: Mat4): number[] | null => {
+  const a = m[0], b = m[4], c = m[8], d = m[1], e = m[5], f = m[9], g = m[2], h = m[6], i = m[10]
+  const det = a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g)
+  if (Math.abs(det) < 1e-20) return null
+  const inv = [
+    (e * i - f * h) / det, (c * h - b * i) / det, (b * f - c * e) / det,
+    (f * g - d * i) / det, (a * i - c * g) / det, (c * d - a * f) / det,
+    (d * h - e * g) / det, (b * g - a * h) / det, (a * e - b * d) / det,
+  ]
+  // transpose(inverse): n' = inv^T · n → n'[r] = Σ inv[c*3 + r] · n[c]
+  return [ inv[0], inv[3], inv[6], inv[1], inv[4], inv[7], inv[2], inv[5], inv[8] ]
+}
+
+const det3 = (m: Mat4): number =>
+  m[0] * (m[5] * m[10] - m[6] * m[9]) - m[4] * (m[1] * m[10] - m[2] * m[9]) + m[8] * (m[1] * m[6] - m[2] * m[5])
+
+const meshNodes = (doc: Document, only?: string): { nodes: Node[], missing: boolean } => {
+  const all = doc.getRoot().listNodes()
+  if (!only) return { nodes: all.filter((n) => n.getMesh()), missing: false }
+  const root = all.find((n) => n.getName() === only)
+  if (!root) return { nodes: [], missing: true }
+  const out: Node[] = []
+  root.traverse((n) => { if (n.getMesh()) out.push(n) })
+  return { nodes: out, missing: false }
+}
+
+const round = (v: number, precision: number): number => {
+  const r = Number(v.toPrecision(precision))
+  return r === 0 ? 0 : r    // no "-0" in the file
+}
+
+/** Smooth, area-weighted vertex normals for a primitive that ships none. */
+const computeNormals = (pos: Float32Array, idx: Uint32Array): Float32Array => {
+  const n = new Float32Array(pos.length)
+  for (let t = 0; t < idx.length; t += 3) {
+    const a = idx[t] * 3, b = idx[t + 1] * 3, c = idx[t + 2] * 3
+    const ux = pos[b] - pos[a], uy = pos[b + 1] - pos[a + 1], uz = pos[b + 2] - pos[a + 2]
+    const vx = pos[c] - pos[a], vy = pos[c + 1] - pos[a + 1], vz = pos[c + 2] - pos[a + 2]
+    const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx
+    for (const k of [ a, b, c ]) { n[k] += nx; n[k + 1] += ny; n[k + 2] += nz }
+  }
+  for (let i = 0; i < n.length; i += 3) {
+    const l = Math.hypot(n[i], n[i + 1], n[i + 2]) || 1
+    n[i] /= l; n[i + 1] /= l; n[i + 2] /= l
+  }
+  return n
+}
+
+const primitiveIndices = (prim: Primitive, count: number): Uint32Array => {
+  const acc = prim.getIndices()
+  if (acc) return Uint32Array.from(acc.getArray() as ArrayLike<number>)
+  const seq = new Uint32Array(count)
+  for (let i = 0; i < count; i++) seq[i] = i
+  return seq
+}
+
+/** The merged, world-space triangle buffer of `doc` (or of one node's subtree). */
+export const extractGeometry = (doc: Document, opts: ExtractOptions = {}): { data: GeometryFile, report: ExtractReport } => {
+  const precision = opts.precision ?? 6
+  const warnings: string[] = []
+  const { nodes, missing } = meshNodes(doc, opts.node)
+  if (missing) throw new Error(`no node "${opts.node}" in the file (--list-nodes prints them)`)
+  if (nodes.length === 0) throw new Error(opts.node ? `node "${opts.node}" has no mesh` : "the file has no mesh")
+
+  const V: number[] = [], N: number[] = [], UV: number[] = [], I: number[] = []
+  const used: string[] = []
+  for (const node of nodes) {
+    const mesh = node.getMesh()!
+    const world = Array.from(node.getWorldMatrix()) as Mat4
+    const nm = normalMatrix(world)
+    if (!nm) { warnings.push(`${node.getName() || "(unnamed)"}: zero-scale transform, skipped`); continue }
+    const flip = det3(world) < 0
+    if (node.getSkin()) warnings.push(`${node.getName() || "(unnamed)"}: skinned — baked in its bind pose`)
+    let took = false
+    for (const prim of mesh.listPrimitives()) {
+      const mode = prim.getMode()
+      if (mode !== 4) { warnings.push(`${node.getName() || "(unnamed)"}: primitive mode ${mode} (not TRIANGLES) skipped`); continue }
+      const posAcc = prim.getAttribute("POSITION")
+      if (!posAcc) continue
+      const pos = Float32Array.from(posAcc.getArray() as ArrayLike<number>)
+      const count = pos.length / 3
+      const idx = primitiveIndices(prim, count)
+      const nrmAcc = prim.getAttribute("NORMAL")
+      const nrm = nrmAcc ? Float32Array.from(nrmAcc.getArray() as ArrayLike<number>) : computeNormals(pos, idx)
+      const uvAcc = prim.getAttribute("TEXCOORD_0")
+      const uv = uvAcc ? Float32Array.from(uvAcc.getArray() as ArrayLike<number>) : new Float32Array(count * 2)
+      if (uvAcc && uvAcc.getNormalized()) warnings.push(`${node.getName() || "(unnamed)"}: TEXCOORD_0 is a normalized integer set, read as floats`)
+      const base = V.length / 3
+      for (let i = 0; i < count; i++) {
+        const p = mul3(world, pos[i * 3], pos[i * 3 + 1], pos[i * 3 + 2], 1)
+        V.push(p[0], p[1], p[2])
+        const nx = nrm[i * 3], ny = nrm[i * 3 + 1], nz = nrm[i * 3 + 2]
+        let tx = nm[0] * nx + nm[1] * ny + nm[2] * nz
+        let ty = nm[3] * nx + nm[4] * ny + nm[5] * nz
+        let tz = nm[6] * nx + nm[7] * ny + nm[8] * nz
+        const l = Math.hypot(tx, ty, tz) || 1
+        tx /= l; ty /= l; tz /= l
+        N.push(tx, ty, tz)
+        UV.push(uv[i * 2], uv[i * 2 + 1])
+      }
+      for (let t = 0; t < idx.length; t += 3) {
+        // a mirrored transform turns the winding inside out — swap two corners to keep front faces
+        if (flip) I.push(base + idx[t], base + idx[t + 2], base + idx[t + 1])
+        else I.push(base + idx[t], base + idx[t + 1], base + idx[t + 2])
+      }
+      took = true
+    }
+    if (took) used.push(node.getName() || "(unnamed)")
+  }
+  const vertexCount = V.length / 3
+  if (vertexCount === 0) throw new Error("no triangles to take")
+  if (vertexCount > MAX_VERTICES) throw new Error(`${vertexCount} vertices — a Geometry holds at most ${MAX_VERTICES} (uint16 indices). Pick one node (--node) or decimate the asset first`)
+
+  // origin + scale, then bounds
+  const min: [number, number, number] = [ Infinity, Infinity, Infinity ], max: [number, number, number] = [ -Infinity, -Infinity, -Infinity ]
+  const bounds = (): void => {
+    min.fill(Infinity); max.fill(-Infinity)
+    for (let i = 0; i < V.length; i += 3) for (let k = 0; k < 3; k++) { min[k] = Math.min(min[k], V[i + k]); max[k] = Math.max(max[k], V[i + k]) }
+  }
+  bounds()
+  const origin = opts.origin ?? "keep"
+  if (origin !== "keep") {
+    const dx = (min[0] + max[0]) / 2, dz = (min[2] + max[2]) / 2
+    const dy = origin === "center" ? (min[1] + max[1]) / 2 : min[1]
+    for (let i = 0; i < V.length; i += 3) { V[i] -= dx; V[i + 1] -= dy; V[i + 2] -= dz }
+  }
+  const scale = opts.scale ?? 1
+  if (scale !== 1) for (let i = 0; i < V.length; i++) V[i] *= scale
+  bounds()
+
+  const data: GeometryFile = {
+    format: "lecodes-geometry",
+    version: 1,
+    vertices: V.map((v) => round(v, precision)),
+    normals: N.map((v) => round(v, 4)),
+    uv: UV.map((v) => round(v, precision)),
+    indices: I,
+    bounds: { min: min.map((v) => round(v, precision)) as typeof min, max: max.map((v) => round(v, precision)) as typeof max },
+    source: { nodes: used },
+  }
+  const report: ExtractReport = {
+    nodes: used, vertices: vertexCount, triangles: I.length / 3,
+    size: [ max[0] - min[0], max[1] - min[1], max[2] - min[2] ], warnings,
+  }
+  return { data, report }
+}
+
+/** Compact JSON: one number list per line, so the file diffs and reads like an asset, not a dump. */
+export const formatGeometryFile = (g: GeometryFile): string => {
+  const list = (a: number[]): string => `[${a.join(",")}]`
+  return [
+    "{",
+    `  "format": ${JSON.stringify(g.format)},`,
+    `  "version": ${g.version},`,
+    `  "bounds": ${JSON.stringify(g.bounds)},`,
+    ...(g.source ? [ `  "source": ${JSON.stringify(g.source)},` ] : []),
+    `  "vertices": ${list(g.vertices)},`,
+    `  "normals": ${list(g.normals)},`,
+    `  "uv": ${list(g.uv)},`,
+    `  "indices": ${list(g.indices)}`,
+    "}",
+    "",
+  ].join("\n")
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// lecodes-assets — programmatic API. CLI: src/cli.ts (`lecodes-assets …` / `lecodes assets …`).
+export { mirrorClips, partnerName, type MirrorOptions, type MirrorReport } from './retarget/mirror'
+export { readFbx, type FbxScene } from "./fbx/read"
+export { toDocument, type ToDocumentOptions, type ConvertWarning } from "./fbx/toDocument"
+export { convertFbx, mergeClipScene, writeGlb, makeIO, type ConvertOptions, type ConvertReport, type ConvertResult } from "./fbx/convert"
+export { probeFile, probeFbx, probeDocument } from "./probe"
+export { analyzeDoc, applyPlan, reportPlan, dumpTextures, type DoctorPlan, type DoctorOptions } from "./doctor/doctor"
+export { validateGlb, formatReport } from "./doctor/validateGlb"
+export { unwrapGlbFile, unwrapGlbFiles, unwrapDocument, planUnwrap, applyUnwrap, type UnwrapOptions, type UnwrapFileOptions, type UnwrapFileReport, type UnwrapResult } from "./unwrap"
+export { planMerge, applyMerge, findKtxTool, type MergeOptions, type MergePlan, type MergeResult } from "./doctor/merge"
+export { measureScale, applyScale, sceneBounds, type ScaleInfo } from "./doctor/normalizeScale"
+export { loadRig, rigFromFbx, rigFromDocument, checkUniformScale, type Rig, type DocRig } from "./retarget/rig"
+export { retarget, analyzeFacing, facingMismatch, bindAccessors, type BoneMap, type RetargetOptions, type RetargetReport, type AlignPolicy, type DonorRef, type LegReport, type ClipContacts, type ContactSpan, type RetargetEvent } from "./retarget/retarget"
+export { makeInPlace, speedProfile, yawProfile, type InPlaceResult, type InPlaceOptions } from "./retarget/inPlace"
+export { detectMarks, fitStaircase, readMarks, stairsMatcher, describeMarks, type ClipMarks, type MarkSpan, type Stairs, type FootTrack, type MarksInput } from "./retarget/marks"
+export { writeMarks, type WriteMarksOptions } from "./retarget/writeMarks"
+export { autoMap, classify, describeSkeleton, type AutoMapResult, type Skeleton } from "./retarget/automap"
+export { packTerrainTextures, resolveTerrainLayer, type TerrainPackLayer, type TerrainPackOptions, type TerrainPackResult } from "./terrainPack"
+export { runAssetsCli } from "./cli"

package/src/mergeSkins.ts

@@ -0,0 +1,117 @@
+// Modular characters: the body, the shirt, the gloves and the boots each come as their OWN skinned
+// FBX over the same skeleton. `mergeSkins` moves the donors' skinned meshes onto the base skeleton
+// (joints matched by name — exact, then the part after the last ':'/'|', the Animator's own rule)
+// and drops the donors' skeleton copies entirely. Leaving those copies in is the classic silent
+// failure: every bone name exists twice, a name-bound Animator finds the unskinned copy first, and
+// the mesh freezes in its rest pose. See docs/animation-plan.md §2.9.
+
+import { Logger, type Document, type Node, type Skin } from "@gltf-transform/core"
+import { mergeDocuments, prune, unpartition } from "@gltf-transform/functions"
+
+export type MergeSkinsWarning = { level: "warn" | "info", message: string }
+export type MergeSkinsReport = {
+  /** per donor: meshes moved, joints that had no counterpart in the base, total skin weight lost to them */
+  donors: { label: string, meshes: number, missingJoints: string[], lostWeight: number }[]
+  joints: number
+}
+
+const shortName = (n: string): string => n.slice(n.search(/[^:|]*$/))
+
+const findSkinnedNode = (doc: Document): Node | null => {
+  let found: Node | null = null
+  for (const scene of doc.getRoot().listScenes()) scene.traverse((n) => { if (!found && n.getSkin() && n.getMesh()) found = n })
+  return found
+}
+
+/** Merge the skinned meshes of `donors` into `base` (mutated). Donor documents are consumed. */
+export const mergeSkins = async (base: Document, donors: { doc: Document, label: string }[], warn: (w: MergeSkinsWarning) => void = () => {}): Promise<MergeSkinsReport> => {
+  const baseSkin: Skin | undefined = base.getRoot().listSkins()[0]
+  if (!baseSkin) throw new Error("the base model has no skin — --merge-skins needs a skinned base (the body)")
+  const baseJoints = baseSkin.listJoints()
+  const byName = new Map<string, number>(), byShort = new Map<string, number>()
+  baseJoints.forEach((j, i) => {
+    const n = j.getName()
+    if (!byName.has(n)) byName.set(n, i)
+    const s = shortName(n)
+    if (!byShort.has(s)) byShort.set(s, i)
+  })
+  const baseScene = base.getRoot().getDefaultScene() ?? base.getRoot().listScenes()[0]
+  const baseMeshNode = findSkinnedNode(base)
+  const homeParent = baseMeshNode?.getParentNode() ?? null
+  const report: MergeSkinsReport = { donors: [], joints: baseJoints.length }
+
+  for (const { doc: donor, label } of donors) {
+    const donorSkins = donor.getRoot().listSkins()
+    if (donorSkins.length === 0) { warn({ level: "warn", message: `${label}: no skin — nothing to merge (static meshes attach at runtime instead)` }); continue }
+    // donor joint index → base joint index, per donor skin
+    const remaps = new Map<Skin, number[]>()
+    const missing = new Set<string>()
+    for (const s of donorSkins) {
+      remaps.set(s, s.listJoints().map((j) => {
+        const n = j.getName()
+        const hit = byName.get(n) ?? byShort.get(shortName(n))
+        if (hit === undefined) missing.add(n)
+        return hit ?? -1
+      }))
+    }
+    const donorMeshNodes: Node[] = []
+    for (const scene of donor.getRoot().listScenes()) scene.traverse((n) => { if (n.getSkin() && n.getMesh()) donorMeshNodes.push(n) })
+    const donorScenes = donor.getRoot().listScenes()
+
+    const map = mergeDocuments(base, donor)
+    let lostWeight = 0
+    for (const src of donorMeshNodes) {
+      const node = map.get(src) as Node | undefined
+      if (!node) continue
+      const remap = remaps.get(src.getSkin()!)!
+      for (const prim of node.getMesh()!.listPrimitives()) {
+        const J = prim.getAttribute("JOINTS_0"), W = prim.getAttribute("WEIGHTS_0")
+        if (!J) continue
+        const ja = J.getArray()!, wa = W?.getArray() ?? null
+        const wNorm = W ? (W.getComponentType() === 5126 ? 1 : W.getComponentType() === 5121 ? 255 : 65535) : 1
+        for (let i = 0; i < ja.length; i++) {
+          const m = remap[ja[i]]
+          if (m >= 0) { ja[i] = m; continue }
+          if (wa) { lostWeight += wa[i] / wNorm; wa[i] = 0 }
+          ja[i] = 0
+        }
+        J.setArray(ja)
+        if (wa) W!.setArray(wa)
+      }
+      node.setSkin(baseSkin)
+      // keep the mesh node's own TRS; it is re-homed next to the base skinned mesh
+      if (homeParent) homeParent.addChild(node)
+      else baseScene.addChild(node)
+    }
+    // drop the donor's skeleton copy: every merged node that is not one of the re-homed mesh nodes
+    const kept = new Set(donorMeshNodes.map((n) => map.get(n)))
+    for (const s of donorSkins) { const ms = map.get(s) as Skin | undefined; if (ms && ms !== baseSkin) ms.dispose() }
+    for (const ds of donorScenes) {
+      const scene = map.get(ds)
+      if (!scene) continue
+      const doomed: Node[] = []
+      for (const root of (scene as typeof baseScene).listChildren()) root.traverse((n) => { if (!kept.has(n)) doomed.push(n) })
+      for (const n of doomed.reverse()) n.dispose()
+      if (scene !== baseScene) (scene as typeof baseScene).dispose()
+    }
+    if (lostWeight > 0.5) warn({ level: "warn", message: `${label}: ${lostWeight.toFixed(1)} of skin weight sat on bones the base skeleton lacks (${[ ...missing ].slice(0, 5).join(", ")}${missing.size > 5 ? "…" : ""}) — those vertices now follow the root` })
+    report.donors.push({ label, meshes: donorMeshNodes.length, missingJoints: [ ...missing ], lostWeight })
+  }
+  await base.setLogger(new Logger(Logger.Verbosity.SILENT)).transform(prune(), unpartition())
+  return report
+}
+
+/** Node names that occur more than once, and whether a skin joint is shadowed by a plain node of the same name. */
+export const duplicateNodeNames = (doc: Document): { name: string, count: number, shadowsJoint: boolean }[] => {
+  const joints = new Set(doc.getRoot().listSkins().flatMap((s) => s.listJoints()))
+  const seen = new Map<string, { count: number, joint: number, plain: number }>()
+  for (const n of doc.getRoot().listNodes()) {
+    const name = n.getName()
+    if (!name) continue
+    const e = seen.get(name) ?? { count: 0, joint: 0, plain: 0 }
+    e.count++
+    if (joints.has(n)) e.joint++; else e.plain++
+    seen.set(name, e)
+  }
+  return [ ...seen ].filter(([ , e ]) => e.count > 1).map(([ name, e ]) => ({ name, count: e.count, shadowsJoint: e.joint > 0 && e.plain > 0 }))
+}