lecodes-assets 0.2.0 → 0.2.1

package/src/doctor/lightmapUv.ts

@@ -0,0 +1,452 @@
+// Lightmap UV pass — `--lightmap-uv`: a second texture-coordinate set (TEXCOORD_1) that lays every
+// triangle of the file out in ONE non-overlapping unit square, made by xatlas (vendor/xatlas, run
+// as wasm — src/wasm/lightmapUv.js). This is what creator-gl's lightmap bake samples and writes
+// (docs/lightmap-plan.md): each placed instance of the prop gets a rectangle of the scene atlas and
+// its UV1 is mapped into it, so the props stay clones and one unwrap per file is enough.
+//
+// xatlas RE-INDEXES the mesh: a vertex that sits on a chart seam is split into one copy per chart,
+// and every output vertex carries `xref`, the input vertex it came from. So this pass rebuilds every
+// attribute (positions, normals, UV0, colours, joints/weights, tangents, morph targets) by that map,
+// preserving each accessor's component type and normalization, and widens the index buffer past
+// 65535 when the split pushes it there. Skinned meshes are left alone: a lightmap is baked in ONE
+// pose, and a rigged character never stays in it.
+//
+// LOD siblings (`<name>_LOD<n>`, n ≥ 1 — the kit's own or `doctor --lod`'s) are NOT unwrapped: the
+// engine's lightmap pass traces level 0 only and binds ONE atlas rect per instance, which every
+// level reads. So level 0 gets the xatlas layout and the LODs get level 0's UV1 by PROJECTION: each
+// LOD triangle's centroid picks the closest level-0 triangle and with it a chart, and each corner
+// takes the UV of its closest point on that chart (a corner that straddles charts is split, like a
+// seam vertex). A decimated surface then samples the very texels its full-detail twin was traced
+// into — no atlas paid twice, no LOD reading texels nothing lit (the two-features-corrupt-each-other
+// bug of fps-demo FEEDBACK 92).
+import type { Accessor, Document, Mesh, Node as GltfNode, Primitive } from '@gltf-transform/core'
+// @ts-ignore — generated by build-wasm.sh (Emscripten single-file module)
+import createLightmapUv from '../wasm/lightmapUv.js'
+
+const TRIANGLES = 4
+
+type Module = {
+  _malloc(n: number): number
+  _free(p: number): void
+  _lmuv_begin(hint: number): number
+  _lmuv_add_mesh(h: number, pos: number, normals: number, uv: number, vertexCount: number, indices: number, indexCount: number): number
+  _lmuv_generate(h: number, padding: number, iterations: number): number
+  _lmuv_width(h: number): number
+  _lmuv_height(h: number): number
+  _lmuv_chart_count(h: number): number
+  _lmuv_mesh_count(h: number): number
+  _lmuv_mesh_vertex_count(h: number, i: number): number
+  _lmuv_mesh_index_count(h: number, i: number): number
+  _lmuv_mesh_xref(h: number, i: number): number
+  _lmuv_mesh_uv(h: number, i: number): number
+  _lmuv_mesh_indices(h: number, i: number): number
+  _lmuv_error(): number
+  _lmuv_end(h: number): void
+  HEAPU8: Uint8Array
+  HEAPU32: Uint32Array
+  HEAPF32: Float32Array
+  UTF8ToString(ptr: number): string
+}
+
+let modulePromise: Promise<Module> | undefined
+const getModule = (): Promise<Module> => (modulePromise ??= (createLightmapUv as () => Promise<Module>)())
+
+export interface LightmapUvOptions {
+  lightmapUv?: boolean
+  /** gutter between charts, in texels of xatlas's ~1024² layout (default 4) */
+  lightmapPadding?: number
+  /** xatlas chart-growing iterations — more = better charts, slower (default 1) */
+  lightmapIterations?: number
+}
+
+export interface LightmapUvPrim { mesh: Mesh; prim: Primitive; name: string; triangles: number; vertices: number; hasUv1: boolean }
+/** A LOD sibling's primitive: takes its UV1 from `baseNode`'s (level-0) mesh by projection. */
+export interface LightmapUvLod { mesh: Mesh; prim: Primitive; node: GltfNode; baseNode: GltfNode; level: number; name: string; triangles: number }
+export interface LightmapUvPlan {
+  prims: LightmapUvPrim[]
+  lods: LightmapUvLod[]
+  skipped: { name: string; reason: string }[]
+  enabled: boolean
+  padding: number
+  iterations: number
+}
+
+export const DEFAULT_LIGHTMAP_PADDING = 4
+
+const LOD_SUFFIX = /_LOD(\d+)$/
+/** "<base>_LOD<n>" → n (≥ 1), else 0 — the suffix creator-gl's lod.cpp groups renderables by. */
+export const lodLevelOf = (name: string): number => { const m = LOD_SUFFIX.exec(name); return m ? Number(m[1]) : 0 }
+
+const primName = (mesh: Mesh, i: number): string => `${mesh.getName() || 'mesh'}${mesh.listPrimitives().length > 1 ? `[${i}]` : ''}`
+
+export function analyzeLightmapUv(doc: Document, opts: LightmapUvOptions = {}): LightmapUvPlan {
+  const root = doc.getRoot()
+  const skinnedMeshes = new Set<Mesh>()
+  const byName = new Map<string, GltfNode>()
+  for (const node of root.listNodes()) {
+    const mesh = node.getMesh()
+    if (mesh && node.getSkin()) skinnedMeshes.add(mesh)
+    if (mesh && node.getName() && !byName.has(node.getName())) byName.set(node.getName(), node)
+  }
+  // LOD siblings: a mesh drawn by a `<base>_LOD<n≥1>` node whose level-0 node (`<base>` or
+  // `<base>_LOD0`) has a mesh of its own; a mesh SHARED with level 0 needs nothing.
+  const lodMeshes = new Map<Mesh, { node: GltfNode; baseNode: GltfNode; level: number }>()
+  const level0Meshes = new Set<Mesh>()
+  for (const node of root.listNodes()) {
+    const mesh = node.getMesh()
+    if (!mesh) continue
+    if (lodLevelOf(node.getName()) === 0) level0Meshes.add(mesh)
+  }
+  for (const node of root.listNodes()) {
+    const mesh = node.getMesh()
+    if (!mesh || level0Meshes.has(mesh) || lodMeshes.has(mesh)) continue
+    const level = lodLevelOf(node.getName())
+    if (level === 0) continue
+    const base = node.getName().replace(LOD_SUFFIX, '')
+    const baseNode = byName.get(base) ?? byName.get(`${base}_LOD0`)
+    if (!baseNode || !baseNode.getMesh() || baseNode.getMesh() === mesh || skinnedMeshes.has(baseNode.getMesh()!)) continue
+    lodMeshes.set(mesh, { node, baseNode, level })
+  }
+  const prims: LightmapUvPrim[] = []
+  const lods: LightmapUvLod[] = []
+  const skipped: { name: string; reason: string }[] = []
+  for (const mesh of root.listMeshes()) {
+    const lod = lodMeshes.get(mesh)
+    mesh.listPrimitives().forEach((prim, i) => {
+      const name = primName(mesh, i)
+      const pos = prim.getAttribute('POSITION')
+      if (!pos || pos.getCount() === 0) { skipped.push({ name, reason: 'no positions' }); return }
+      if (prim.getMode() !== TRIANGLES) { skipped.push({ name, reason: 'not a triangle list' }); return }
+      if (skinnedMeshes.has(mesh)) { skipped.push({ name, reason: 'skinned' }); return }
+      const idx = prim.getIndices()
+      const triangles = Math.floor((idx ? idx.getCount() : pos.getCount()) / 3)
+      if (triangles === 0) { skipped.push({ name, reason: 'no triangles' }); return }
+      if (lod) { lods.push({ mesh, prim, node: lod.node, baseNode: lod.baseNode, level: lod.level, name, triangles }); return }
+      prims.push({ mesh, prim, name, triangles, vertices: pos.getCount(), hasUv1: !!prim.getAttribute('TEXCOORD_1') })
+    })
+  }
+  return {
+    prims, lods, skipped, enabled: !!opts.lightmapUv,
+    padding: opts.lightmapPadding ?? DEFAULT_LIGHTMAP_PADDING,
+    iterations: opts.lightmapIterations ?? 1,
+  }
+}
+
+export interface LightmapUvResult {
+  primitives: number; charts: number; width: number; height: number; verticesBefore: number; verticesAfter: number
+  /** LOD primitives that took level 0's layout by projection, and the vertices they hold afterwards */
+  lodPrimitives: number; lodVertices: number
+}
+
+/** Every element of `acc` as floats (dequantized), `size` per element. */
+const floats = (acc: Accessor, size: number): Float32Array => {
+  const n = acc.getCount()
+  const out = new Float32Array(n * size)
+  const el: number[] = new Array(acc.getElementSize()).fill(0)
+  for (let i = 0; i < n; i++) { acc.getElement(i, el); for (let k = 0; k < size; k++) out[i * size + k] = el[k] ?? 0 }
+  return out
+}
+
+/** A copy of `acc` with its elements reordered by `xref` — same type, component type, normalization. */
+const remapAccessor = (doc: Document, acc: Accessor, xref: Uint32Array, buffer: ReturnType<Document['createBuffer']>): Accessor => {
+  const src = acc.getArray()!
+  const es = acc.getElementSize()
+  const Ctor = src.constructor as { new (n: number): typeof src }
+  const out = new Ctor(xref.length * es)
+  for (let v = 0; v < xref.length; v++) {
+    const s = xref[v] * es
+    for (let k = 0; k < es; k++) out[v * es + k] = src[s + k]
+  }
+  return doc.createAccessor(acc.getName()).setType(acc.getType()).setNormalized(acc.getNormalized()).setArray(out).setBuffer(buffer)
+}
+
+/** Rebuild a primitive's attributes, morph targets and indices by `xref` (re-indexed geometry) and give it `uv1`. */
+const reindexPrimitive = (doc: Document, prim: Primitive, xref: Uint32Array, indices32: Uint32Array<ArrayBuffer>, uv1: Float32Array<ArrayBuffer>,
+                          buffer: ReturnType<Document['createBuffer']>, retired: Set<Accessor>): void => {
+  for (const semantic of prim.listSemantics()) {
+    const acc = prim.getAttribute(semantic)!
+    if (semantic === 'TEXCOORD_1') { retired.add(acc); continue }   // replaced below
+    retired.add(acc)
+    prim.setAttribute(semantic, remapAccessor(doc, acc, xref, buffer))
+  }
+  for (const target of prim.listTargets()) {
+    for (const semantic of target.listSemantics()) {
+      const acc = target.getAttribute(semantic)!
+      retired.add(acc)
+      target.setAttribute(semantic, remapAccessor(doc, acc, xref, buffer))
+    }
+  }
+  const oldIdx = prim.getIndices()
+  if (oldIdx) retired.add(oldIdx)
+  const indices = xref.length <= 65535 ? Uint16Array.from(indices32) : indices32
+  prim.setIndices(doc.createAccessor().setType('SCALAR').setArray(indices).setBuffer(buffer))
+  prim.setAttribute('TEXCOORD_1', doc.createAccessor('lightmap_uv').setType('VEC2').setArray(uv1).setBuffer(buffer))
+}
+
+// ---- LOD projection ------------------------------------------------------------------------------
+
+const xformPoint = (m: number[], x: number, y: number, z: number, out: Float32Array, o: number): void => {
+  out[o] = m[0] * x + m[4] * y + m[8] * z + m[12]
+  out[o + 1] = m[1] * x + m[5] * y + m[9] * z + m[13]
+  out[o + 2] = m[2] * x + m[6] * y + m[10] * z + m[14]
+}
+
+/** Level 0's triangles in world space with their UV1 and chart, on a uniform grid for nearest-point queries. */
+class BaseSurface {
+  readonly tris: Float32Array       // 9 floats per triangle (world positions)
+  readonly uvs: Float32Array        // 6 floats per triangle
+  readonly chart: Int32Array        // chart id per triangle (an xatlas chart = connected output vertices)
+  readonly count: number
+  private readonly min = [ 0, 0, 0 ]
+  private readonly cell: number
+  private readonly dims = [ 1, 1, 1 ]
+  private readonly cells = new Map<number, number[]>()
+
+  constructor(node: GltfNode) {
+    const world = node.getWorldMatrix()
+    const triPos: number[] = [], triUv: number[] = [], triChart: number[] = []
+    let chartBase = 0
+    for (const prim of node.getMesh()!.listPrimitives()) {
+      const pos = prim.getAttribute('POSITION'), uv1 = prim.getAttribute('TEXCOORD_1')
+      if (!pos || !uv1 || prim.getMode() !== TRIANGLES) continue
+      const idxAcc = prim.getIndices()
+      const idx = idxAcc ? idxAcc.getArray()! : Uint32Array.from({ length: pos.getCount() }, (_, i) => i)
+      const p = floats(pos, 3), u = floats(uv1, 2)
+      // charts = connected components over the (seam-split) index buffer
+      const parent = Int32Array.from({ length: pos.getCount() }, (_, i) => i)
+      const find = (a: number): number => { while (parent[a] !== a) { parent[a] = parent[parent[a]]; a = parent[a] } return a }
+      for (let i = 0; i + 2 < idx.length; i += 3) {
+        const a = find(idx[i]), b = find(idx[i + 1]), c = find(idx[i + 2])
+        parent[b] = a; parent[find(c)] = find(a)
+      }
+      const chartOf = new Map<number, number>()
+      for (let i = 0; i + 2 < idx.length; i += 3) {
+        const r = find(idx[i])
+        let ch = chartOf.get(r)
+        if (ch === undefined) { ch = chartBase + chartOf.size; chartOf.set(r, ch) }
+        const w = new Float32Array(9)
+        for (let k = 0; k < 3; k++) { const v = idx[i + k]; xformPoint(world, p[v * 3], p[v * 3 + 1], p[v * 3 + 2], w, k * 3); triUv.push(u[v * 2], u[v * 2 + 1]) }
+        for (let k = 0; k < 9; k++) triPos.push(w[k])
+        triChart.push(ch)
+      }
+      chartBase += chartOf.size
+    }
+    this.tris = Float32Array.from(triPos); this.uvs = Float32Array.from(triUv); this.chart = Int32Array.from(triChart)
+    this.count = triChart.length
+    if (this.count === 0) { this.cell = 1; return }
+    const min = [ Infinity, Infinity, Infinity ], max = [ -Infinity, -Infinity, -Infinity ]
+    for (let i = 0; i < this.tris.length; i += 3) for (let k = 0; k < 3; k++) { min[k] = Math.min(min[k], this.tris[i + k]); max[k] = Math.max(max[k], this.tris[i + k]) }
+    const ext = [ max[0] - min[0], max[1] - min[1], max[2] - min[2] ]
+    const longest = Math.max(ext[0], ext[1], ext[2], 1e-6)
+    // ~4 triangles per cell along the longest axis, 48 cells at most: a crate's 10k triangles land in a few hundred cells
+    this.cell = Math.max(longest / Math.min(48, Math.max(4, Math.cbrt(this.count) * 2)), 1e-5)
+    this.min = [ min[0] - this.cell * 0.5, min[1] - this.cell * 0.5, min[2] - this.cell * 0.5 ]
+    this.dims = ext.map((e) => Math.max(1, Math.ceil(e / this.cell) + 1))
+    for (let t = 0; t < this.count; t++) {
+      const lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+      for (let k = 0; k < 3; k++) for (let a = 0; a < 3; a++) { const v = this.tris[t * 9 + k * 3 + a]; lo[a] = Math.min(lo[a], v); hi[a] = Math.max(hi[a], v) }
+      const c0 = this.cellOf(lo), c1 = this.cellOf(hi)
+      for (let z = c0[2]; z <= c1[2]; z++) for (let y = c0[1]; y <= c1[1]; y++) for (let x = c0[0]; x <= c1[0]; x++) {
+        const key = this.key(x, y, z)
+        let list = this.cells.get(key)
+        if (!list) { list = []; this.cells.set(key, list) }
+        list.push(t)
+      }
+    }
+  }
+
+  private cellOf(p: ArrayLike<number>): number[] {
+    return [ 0, 1, 2 ].map((a) => Math.min(this.dims[a] - 1, Math.max(0, Math.floor((p[a] - this.min[a]) / this.cell))))
+  }
+  private key(x: number, y: number, z: number): number { return (z * this.dims[1] + y) * this.dims[0] + x }
+
+  /** Closest point on triangle `t` to `p` (Ericson, Real-Time Collision Detection 5.1.5): squared distance + barycentrics. */
+  private closest(t: number, p: number[], out: { d2: number; b: number[] }): void {
+    const T = this.tris, o = t * 9
+    const ax = T[o], ay = T[o + 1], az = T[o + 2], bx = T[o + 3], by = T[o + 4], bz = T[o + 5], cx = T[o + 6], cy = T[o + 7], cz = T[o + 8]
+    const abx = bx - ax, aby = by - ay, abz = bz - az, acx = cx - ax, acy = cy - ay, acz = cz - az
+    const apx = p[0] - ax, apy = p[1] - ay, apz = p[2] - az
+    const d1 = abx * apx + aby * apy + abz * apz, d2 = acx * apx + acy * apy + acz * apz
+    let u: number, v: number, w: number
+    if (d1 <= 0 && d2 <= 0) { u = 1; v = 0; w = 0 } else {
+      const bpx = p[0] - bx, bpy = p[1] - by, bpz = p[2] - bz
+      const d3 = abx * bpx + aby * bpy + abz * bpz, d4 = acx * bpx + acy * bpy + acz * bpz
+      if (d3 >= 0 && d4 <= d3) { u = 0; v = 1; w = 0 } else {
+        const vc = d1 * d4 - d3 * d2
+        if (vc <= 0 && d1 >= 0 && d3 <= 0) { v = d1 / (d1 - d3); u = 1 - v; w = 0 } else {
+          const cpx = p[0] - cx, cpy = p[1] - cy, cpz = p[2] - cz
+          const d5 = abx * cpx + aby * cpy + abz * cpz, d6 = acx * cpx + acy * cpy + acz * cpz
+          if (d6 >= 0 && d5 <= d6) { u = 0; v = 0; w = 1 } else {
+            const vb = d5 * d2 - d1 * d6
+            if (vb <= 0 && d2 >= 0 && d6 <= 0) { w = d2 / (d2 - d6); u = 1 - w; v = 0 } else {
+              const va = d3 * d6 - d5 * d4
+              if (va <= 0 && d4 - d3 >= 0 && d5 - d6 >= 0) { w = (d4 - d3) / ((d4 - d3) + (d5 - d6)); v = 1 - w; u = 0 } else {
+                const denom = 1 / (va + vb + vc)
+                v = vb * denom; w = vc * denom; u = 1 - v - w
+              }
+            }
+          }
+        }
+      }
+    }
+    const qx = ax * u + bx * v + cx * w, qy = ay * u + by * v + cy * w, qz = az * u + bz * v + cz * w
+    out.d2 = (qx - p[0]) ** 2 + (qy - p[1]) ** 2 + (qz - p[2]) ** 2
+    out.b[0] = u; out.b[1] = v; out.b[2] = w
+  }
+
+  /** The closest triangle to `p` (within chart `chart` when ≥ 0) and the barycentrics of the closest point; -1 = none. */
+  nearest(p: number[], chart: number, bary: number[]): number {
+    if (this.count === 0) return -1
+    const c = this.cellOf(p)
+    let best = -1, bestD2 = Infinity
+    const tmp = { d2: 0, b: [ 0, 0, 0 ] }
+    const maxR = Math.max(this.dims[0], this.dims[1], this.dims[2])
+    for (let r = 0; r <= maxR; r++) {
+      // everything not yet visited lies at least (r − 1) cells away: stop once the best is closer than that
+      if (best >= 0 && Math.sqrt(bestD2) <= (r - 1) * this.cell) break
+      for (let z = c[2] - r; z <= c[2] + r; z++) {
+        if (z < 0 || z >= this.dims[2]) continue
+        for (let y = c[1] - r; y <= c[1] + r; y++) {
+          if (y < 0 || y >= this.dims[1]) continue
+          const edgeYZ = Math.abs(z - c[2]) === r || Math.abs(y - c[1]) === r
+          for (let x = c[0] - r; x <= c[0] + r; x++) {
+            if (x < 0 || x >= this.dims[0]) continue
+            if (!edgeYZ && Math.abs(x - c[0]) !== r) continue   // only the ring's shell
+            const list = this.cells.get(this.key(x, y, z))
+            if (!list) continue
+            for (const t of list) {
+              if (chart >= 0 && this.chart[t] !== chart) continue
+              this.closest(t, p, tmp)
+              if (tmp.d2 < bestD2) { bestD2 = tmp.d2; best = t; bary[0] = tmp.b[0]; bary[1] = tmp.b[1]; bary[2] = tmp.b[2] }
+            }
+          }
+        }
+      }
+    }
+    return best
+  }
+
+  uvAt(t: number, bary: number[], out: Float32Array, o: number): void {
+    const U = this.uvs, k = t * 6
+    out[o] = U[k] * bary[0] + U[k + 2] * bary[1] + U[k + 4] * bary[2]
+    out[o + 1] = U[k + 1] * bary[0] + U[k + 3] * bary[1] + U[k + 5] * bary[2]
+  }
+}
+
+/** Give a LOD primitive level 0's UV1: per triangle the centroid picks a chart, per corner the closest point on it. */
+const projectLodPrimitive = (doc: Document, lod: LightmapUvLod, base: BaseSurface, buffer: ReturnType<Document['createBuffer']>,
+                             retired: Set<Accessor>): number => {
+  const prim = lod.prim
+  const pos = prim.getAttribute('POSITION')!
+  const idxAcc = prim.getIndices()
+  const idx = idxAcc ? Uint32Array.from(idxAcc.getArray()!) : Uint32Array.from({ length: pos.getCount() }, (_, i) => i)
+  const local = floats(pos, 3)
+  const world = lod.node.getWorldMatrix()
+  const wp = new Float32Array(local.length)
+  for (let v = 0; v < pos.getCount(); v++) xformPoint(world, local[v * 3], local[v * 3 + 1], local[v * 3 + 2], wp, v * 3)
+  const xref: number[] = [], uv: number[] = [], out: number[] = []
+  const slot = new Map<number, number>()   // (vertex, chart) → output vertex
+  const bary = [ 0, 0, 0 ]
+  const centroid = [ 0, 0, 0 ], corner = [ 0, 0, 0 ]
+  const uv2 = new Float32Array(2)
+  for (let i = 0; i + 2 < idx.length; i += 3) {
+    for (let a = 0; a < 3; a++) centroid[a] = (wp[idx[i] * 3 + a] + wp[idx[i + 1] * 3 + a] + wp[idx[i + 2] * 3 + a]) / 3
+    const ct = base.nearest(centroid, -1, bary)
+    const chart = ct >= 0 ? base.chart[ct] : -1
+    for (let k = 0; k < 3; k++) {
+      const v = idx[i + k]
+      const key = v * 65536 + (chart + 1)
+      let o = slot.get(key)
+      if (o === undefined) {
+        corner[0] = wp[v * 3]; corner[1] = wp[v * 3 + 1]; corner[2] = wp[v * 3 + 2]
+        let t = base.nearest(corner, chart, bary)
+        if (t < 0) t = base.nearest(corner, -1, bary)
+        if (t >= 0) base.uvAt(t, bary, uv2, 0); else { uv2[0] = 0; uv2[1] = 0 }
+        o = xref.length
+        slot.set(key, o)
+        xref.push(v); uv.push(uv2[0], uv2[1])
+      }
+      out.push(o)
+    }
+  }
+  reindexPrimitive(doc, prim, Uint32Array.from(xref), Uint32Array.from(out), Float32Array.from(uv), buffer, retired)
+  return xref.length
+}
+
+export async function applyLightmapUv(doc: Document, plan: LightmapUvPlan): Promise<LightmapUvResult> {
+  const res: LightmapUvResult = { primitives: 0, charts: 0, width: 0, height: 0, verticesBefore: 0, verticesAfter: 0, lodPrimitives: 0, lodVertices: 0 }
+  if (!plan.enabled || plan.prims.length === 0) return res
+  const m = await getModule()
+  const h = m._lmuv_begin(plan.prims.length)
+  if (h === 0) throw new Error(`lightmap UV: ${m.UTF8ToString(m._lmuv_error())}`)
+  const allocs: number[] = []
+  const upload = (arr: Float32Array | Uint32Array): number => {
+    const ptr = m._malloc(arr.byteLength)
+    allocs.push(ptr)
+    if (arr instanceof Float32Array) m.HEAPF32.set(arr, ptr >> 2)
+    else m.HEAPU32.set(arr, ptr >> 2)
+    return ptr
+  }
+  const buffer = doc.getRoot().listBuffers()[0] ?? doc.createBuffer()
+  const retired = new Set<Accessor>()
+  try {
+    for (const p of plan.prims) {
+      const pos = p.prim.getAttribute('POSITION')!
+      const nrm = p.prim.getAttribute('NORMAL')
+      const uv0 = p.prim.getAttribute('TEXCOORD_0')
+      const idxAcc = p.prim.getIndices()
+      const indices = idxAcc ? Uint32Array.from(idxAcc.getArray()!) : Uint32Array.from({ length: pos.getCount() }, (_, i) => i)
+      const indexCount = indices.length - (indices.length % 3)
+      const posPtr = upload(floats(pos, 3))
+      const nrmPtr = nrm && nrm.getCount() === pos.getCount() ? upload(floats(nrm, 3)) : 0
+      const uvPtr = uv0 && uv0.getCount() === pos.getCount() ? upload(floats(uv0, 2)) : 0
+      const idxPtr = upload(indices)
+      const err = m._lmuv_add_mesh(h, posPtr, nrmPtr, uvPtr, pos.getCount(), idxPtr, indexCount)
+      if (err !== 0) throw new Error(`lightmap UV: ${p.name}: ${m.UTF8ToString(m._lmuv_error())}`)
+      res.verticesBefore += pos.getCount()
+    }
+    // xatlas copies the mesh data in AddMesh — the inputs can go before the (long) generate.
+    for (const ptr of allocs) m._free(ptr)
+    allocs.length = 0
+    const err = m._lmuv_generate(h, plan.padding, plan.iterations)
+    if (err !== 0) throw new Error(`lightmap UV: ${m.UTF8ToString(m._lmuv_error())}`)
+    res.width = m._lmuv_width(h)
+    res.height = m._lmuv_height(h)
+    res.charts = m._lmuv_chart_count(h)
+    if (m._lmuv_mesh_count(h) !== plan.prims.length) throw new Error('lightmap UV: xatlas returned a different mesh count')
+
+    plan.prims.forEach((p, i) => {
+      const vcount = m._lmuv_mesh_vertex_count(h, i)
+      const icount = m._lmuv_mesh_index_count(h, i)
+      const xrefPtr = m._lmuv_mesh_xref(h, i) >> 2
+      const xref = m.HEAPU32.slice(xrefPtr, xrefPtr + vcount)
+      const uvPtr = m._lmuv_mesh_uv(h, i) >> 2
+      const uv1 = m.HEAPF32.slice(uvPtr, uvPtr + vcount * 2)
+      const idxPtr = m._lmuv_mesh_indices(h, i) >> 2
+      const idx32 = m.HEAPU32.slice(idxPtr, idxPtr + icount)
+      reindexPrimitive(doc, p.prim, xref, idx32, uv1, buffer, retired)
+      res.verticesAfter += vcount
+      res.primitives++
+    })
+  } finally {
+    for (const ptr of allocs) m._free(ptr)
+    m._lmuv_end(h)
+  }
+
+  // the LOD siblings, from the level-0 meshes that now carry the layout
+  const surfaces = new Map<GltfNode, BaseSurface>()
+  for (const lod of plan.lods) {
+    let base = surfaces.get(lod.baseNode)
+    if (!base) { base = new BaseSurface(lod.baseNode); surfaces.set(lod.baseNode, base) }
+    if (base.count === 0) continue   // level 0 got no layout (skipped above): the LOD keeps what it had
+    res.lodVertices += projectLodPrimitive(doc, lod, base, buffer, retired)
+    res.lodPrimitives++
+  }
+
+  // A retired accessor may still back another primitive (shared POSITION with different indices)
+  // or a morph target we did not touch — only drop the ones nothing references any more.
+  for (const acc of retired) {
+    if (acc.listParents().every((parent) => parent.propertyType === 'Root')) acc.dispose()
+  }
+  return res
+}

package/src/doctor/lod.ts

@@ -0,0 +1,177 @@
+// Mesh + skeleton LOD levels for creator-gl's LOD pass (docs/lod-plan.md §5).
+//
+//   --lod 0.5,0.2     every mesh node with ≥ MIN_TRIS triangles gets sibling nodes `<name>_LOD1`,
+//                     `<name>_LOD2` … (same parent / transform / skin / materials) whose primitives are
+//                     meshoptimizer-simplified copies at the given ratios of the ORIGINAL triangle count.
+//                     Skinned primitives keep JOINTS/WEIGHTS (the simplifier only collapses vertices), so
+//                     every level rides the same skin. Morph targets are not carried to the levels.
+//   --lod-bones       the LAST level of a skinned node also gets a reduced SKIN: vertices weighted to
+//                     finger / toe / twist / leaf joints are re-weighted onto their nearest kept ancestor
+//                     and the level references a new Skin over the kept joints only — the engine
+//                     uploads a third of the bones for a far character.
+//
+// The engine groups levels by the `_LOD<n>` name (creator-gl src/lod.cpp) and shows one at a time; a
+// viewer without LOD support draws them all — harmless. Extras carry the bookkeeping for probes.
+
+import type { Accessor, Document, Mesh, Node as GltfNode, Primitive, Skin } from '@gltf-transform/core'
+import { simplifyPrimitive, weldPrimitive } from '@gltf-transform/functions'
+import { MeshoptSimplifier } from 'meshoptimizer'
+
+export interface LodOptions { lod?: number[]; lodBones?: boolean }
+export interface LodNodePlan { node: GltfNode; name: string; tris: number; skinned: boolean }
+export interface LodPlan { ratios: number[]; bones: boolean; nodes: LodNodePlan[]; existing: number }
+export interface LodResult { levels: number; nodes: number; tris: { name: string; levels: number[] }[]; bones: { name: string; before: number; after: number }[]; skipped: { name: string; level: number; tris: number }[] }
+
+/** Meshes under this go without levels — a crate does not need one. */
+export const LOD_MIN_TRIS = 2000
+/** Joints a far character stops animating / weighting — the same vocabulary as creator-gl's joint mask
+ *  (animation/animator.cpp lodMaskedName) and the retargeter's helper classes. Keep them in step. */
+export const LOD_JOINT_MASK = /finger|thumb|index|middle|ring|pinky|toe|twist|roll|leaf|_end$/i
+const LOD_NAME = /_LOD\d+$/
+
+const shortName = (s: string): string => { const p = Math.max(s.lastIndexOf(':'), s.lastIndexOf('|')); return p < 0 ? s : s.slice(p + 1) }
+
+const primTris = (p: Primitive): number => {
+  if (p.getMode() !== 4) return 0   // TRIANGLES only
+  const idx = p.getIndices()
+  const n = idx ? idx.getCount() : (p.getAttribute('POSITION')?.getCount() ?? 0)
+  return Math.floor(n / 3)
+}
+const meshTris = (m: Mesh): number => m.listPrimitives().reduce((s, p) => s + primTris(p), 0)
+
+export function planLod(doc: Document, opts: LodOptions): LodPlan | null {
+  const ratios = (opts.lod ?? []).filter((r) => r > 0 && r < 1).sort((a, b) => b - a)
+  if (!ratios.length) return null
+  const nodes: LodNodePlan[] = []
+  let existing = 0
+  for (const node of doc.getRoot().listNodes()) {
+    const mesh = node.getMesh()
+    if (!mesh) continue
+    if (LOD_NAME.test(node.getName())) { existing++; continue }
+    const tris = meshTris(mesh)
+    if (tris < LOD_MIN_TRIS) continue
+    nodes.push({ node, name: node.getName() || mesh.getName() || `mesh${nodes.length}`, tris, skinned: !!node.getSkin() })
+  }
+  return { ratios, bones: !!opts.lodBones, nodes, existing }
+}
+
+/** A deep copy of a primitive's geometry (own accessors — simplify rewrites them in place), sharing the material. */
+const clonePrimitive = (doc: Document, prim: Primitive): Primitive => {
+  const buffer = doc.getRoot().listBuffers()[0] ?? doc.createBuffer()
+  const cloneAcc = (a: Accessor): Accessor => doc.createAccessor(a.getName(), buffer).setType(a.getType()).setNormalized(a.getNormalized()).setArray(a.getArray()!.slice())
+  const out = doc.createPrimitive().setMode(prim.getMode()).setMaterial(prim.getMaterial())
+  for (const sem of prim.listSemantics()) out.setAttribute(sem, cloneAcc(prim.getAttribute(sem)!))
+  const idx = prim.getIndices()
+  if (idx) out.setIndices(cloneAcc(idx))
+  return out
+}
+
+/** The last level of a skinned node: masked joints fold onto their nearest kept ancestor, on a new Skin over the kept joints. */
+const reduceSkinForLod = (doc: Document, lodNode: GltfNode): { before: number; after: number } | null => {
+  const skin = lodNode.getSkin()
+  const mesh = lodNode.getMesh()
+  if (!skin || !mesh) return null
+  const joints = skin.listJoints()
+  const removed = new Set<number>()
+  joints.forEach((j, i) => { if (LOD_JOINT_MASK.test(shortName(j.getName()))) removed.add(i) })
+  if (!removed.size) return null
+  const idxOf = new Map<GltfNode, number>(joints.map((j, i) => [j, i]))
+  const remap = joints.map((j, i) => {
+    if (!removed.has(i)) return i
+    for (let p = j.getParentNode(); p; p = p.getParentNode()) { const k = idxOf.get(p); if (k !== undefined && !removed.has(k)) return k }
+    return i   // no kept ancestor: keep the joint
+  })
+  const kept = [...new Set(remap)].sort((a, b) => a - b)
+  const newIndex = new Map<number, number>(kept.map((old, k) => [old, k]))
+  const buffer = doc.getRoot().listBuffers()[0] ?? doc.createBuffer()
+  const newSkin: Skin = doc.createSkin(`${skin.getName() || 'skin'}_LOD`)
+  if (skin.getSkeleton()) newSkin.setSkeleton(skin.getSkeleton())
+  for (const i of kept) newSkin.addJoint(joints[i]!)
+  const ibm = skin.getInverseBindMatrices()
+  if (ibm) {
+    const src = ibm.getArray()!
+    const out = new Float32Array(kept.length * 16)
+    kept.forEach((i, k) => out.set(src.subarray(i * 16, i * 16 + 16), k * 16))
+    newSkin.setInverseBindMatrices(doc.createAccessor(`${ibm.getName() || 'ibm'}_LOD`, buffer).setType('MAT4').setArray(out))
+  }
+  const jv: number[] = [], wv: number[] = []
+  for (const prim of mesh.listPrimitives()) {
+    // every set is gathered per vertex, folded by target joint, then written back set by set (largest first)
+    const sets: { j: Accessor; w: Accessor }[] = []
+    for (let s = 0; ; s++) { const j = prim.getAttribute(`JOINTS_${s}`), w = prim.getAttribute(`WEIGHTS_${s}`); if (!j || !w) break; sets.push({ j, w }) }
+    if (!sets.length) continue
+    const count = sets[0]!.j.getCount()
+    const folded = new Map<number, number>()
+    for (let v = 0; v < count; v++) {
+      folded.clear()
+      for (const { j, w } of sets) {
+        j.getElement(v, jv); w.getElement(v, wv)
+        for (let k = 0; k < 4; k++) {
+          const weight = wv[k] ?? 0
+          if (weight <= 0) continue
+          const target = newIndex.get(remap[jv[k]!] ?? jv[k]!) ?? 0
+          folded.set(target, (folded.get(target) ?? 0) + weight)
+        }
+      }
+      const pairs = [...folded].sort((a, b) => b[1] - a[1])
+      let n = 0
+      for (const { j, w } of sets) {
+        for (let k = 0; k < 4; k++) { const p = pairs[n++]; jv[k] = p ? p[0] : 0; wv[k] = p ? p[1] : 0 }
+        j.setElement(v, jv); w.setElement(v, wv)
+      }
+    }
+  }
+  lodNode.setSkin(newSkin)
+  return { before: joints.length, after: kept.length }
+}
+
+export async function applyLod(doc: Document, plan: LodPlan): Promise<LodResult> {
+  await MeshoptSimplifier.ready
+  const result: LodResult = { levels: plan.ratios.length, nodes: 0, tris: [], bones: [], skipped: [] }
+  for (const entry of plan.nodes) {
+    const { node } = entry
+    const baseMesh = node.getMesh()!
+    const parent = node.getParentNode()
+    const scenes = parent ? [] : doc.getRoot().listScenes().filter((s) => s.listChildren().includes(node))
+    const baseExtras = (node.getExtras() ?? {}) as Record<string, unknown>
+    const baseLecodes = (baseExtras.lecodes ?? {}) as Record<string, unknown>
+    node.setExtras({ ...baseExtras, lecodes: { ...baseLecodes, lod: { level: 0, levels: plan.ratios.length + 1, tris: entry.tris } } })
+    const levels: number[] = [entry.tris]
+    for (let i = 0; i < plan.ratios.length; i++) {
+      const level = i + 1
+      const ratio = plan.ratios[i]!
+      const mesh = doc.createMesh(`${baseMesh.getName() || entry.name}_LOD${level}`)
+      let tris = 0
+      for (const prim of baseMesh.listPrimitives()) {
+        if (prim.getMode() !== 4) continue
+        let copy = clonePrimitive(doc, prim)
+        weldPrimitive(copy)
+        copy = simplifyPrimitive(copy, { simplifier: MeshoptSimplifier, ratio, error: 0.02, lockBorder: false })
+        tris += primTris(copy)
+        mesh.addPrimitive(copy)
+      }
+      // A level the simplifier could not shrink (hard-surface meshes with many seams stop early) is not
+      // worth its bytes or its draw: drop it rather than ship a near-duplicate.
+      if (tris > levels[levels.length - 1]! * 0.85) {
+        for (const p of mesh.listPrimitives()) { for (const sem of p.listSemantics()) p.getAttribute(sem)?.dispose(); p.getIndices()?.dispose(); p.dispose() }
+        mesh.dispose()
+        result.skipped.push({ name: entry.name, level, tris })
+        break
+      }
+      const lodNode = doc.createNode(`${node.getName() || entry.name}_LOD${level}`).setMesh(mesh)
+        .setTranslation(node.getTranslation()).setRotation(node.getRotation()).setScale(node.getScale())
+      if (node.getSkin()) lodNode.setSkin(node.getSkin())
+      lodNode.setExtras({ lecodes: { lod: { level, ratio, tris } } })
+      if (parent) parent.addChild(lodNode)
+      else for (const s of scenes) s.addChild(lodNode)
+      levels.push(tris)
+      if (plan.bones && i === plan.ratios.length - 1 && node.getSkin()) {
+        const r = reduceSkinForLod(doc, lodNode)
+        if (r) result.bones.push({ name: entry.name, ...r })
+      }
+    }
+    result.nodes++
+    result.tris.push({ name: entry.name, levels })
+  }
+  return result
+}