lecodes-assets 0.2.0 → 2.4.10

package/src/fbx/convert.ts

@@ -0,0 +1,327 @@
+// convert: FBX (+ clip FBX files) → one glTF-Transform Document → GLB. Clip files are re-targeted
+// onto the main skeleton BY BONE NAME (exact, then the part after the last ':'/'|' — the same rule
+// the SDK Animator uses), their meshes/skins dropped. See docs/animation-plan.md §2.9.
+
+import { readFileSync } from "node:fs"
+import { basename, dirname, extname } from "node:path"
+import { NodeIO, type Document, type Node } from "@gltf-transform/core"
+import { ALL_EXTENSIONS } from "@gltf-transform/extensions"
+import { readFbx, type FbxScene, type FbxAnimation } from "./read"
+import { toDocument, isGenericClipName, fixQuatContinuity, type ConvertWarning } from "./toDocument"
+import { f32 } from "./read"
+import { qmul, qinv, qnorm, qrot, type Quat, type Vec3 } from "../retarget/rig"
+
+export type ConvertOptions = {
+  /** Extra FBX files whose animations are merged into the model by bone name. */
+  clips?: string[]
+  /** Explicit names for `clips` (parallel array); default: stack name unless generic → file basename. */
+  clipNames?: string[]
+  /** Drop the model file's own clips (e.g. Mixamo's 1-frame T-pose). */
+  dropModelClips?: boolean
+  /** Bone name overrides for clip binding: { clipBoneName: modelBoneName }. */
+  rename?: Record<string, string>
+  /** Rewrite materials from the Unity `.mat` files found next to the FBX (default true when any exist;
+   *  false = FBX references only). A string = folder to look for them in. */
+  unity?: boolean | string
+  /** `unity-index.txt` for GUID → path (default: found walking up from the FBX, else `.meta` sidecars). */
+  unityIndex?: string
+  /** Unreal `.uasset` clips: the skeleton they were authored on (default: resolved from the pack). */
+  skeleton?: string
+  /** Unreal `.uasset` clips: the pack's Content folder, when the walk-up search cannot find it. */
+  contentRoot?: string
+  warn?: (w: ConvertWarning) => void
+}
+
+export type ConvertReport = {
+  clips: { name: string, source: string, duration: number, tracks: number, bound: number }[]
+  warnings: ConvertWarning[]
+  nodes: number
+  meshes: number
+  skins: number
+  textures: number
+  materials: number
+  unity?: import("../unity/materials").ApplyUnityReport
+}
+
+export const shortName = (n: string): string => n.slice(n.search(/[^:|]*$/))
+
+// ---- clip sources ------------------------------------------------------------------------------
+// What `mergeClipScene` needs of a clip file: a bone hierarchy with its rest pose, and baked tracks.
+// An FBX gives it through the ufbx arena; an Unreal AnimSequence builds it from its own keys. Both
+// arrive here in glTF conventions (metres, Y-up), so the merge code below never sees the difference.
+
+export type ClipSourceNode = { name: string, parent: number, t: Vec3, r: Quat, s: Vec3, isRoot: boolean }
+export type ClipSourceTrack = { node: number, path: "translation" | "rotation" | "scale", times: Float32Array, values: Float32Array }
+export type ClipSourceAnimation = { name: string, duration: number, tracks: ClipSourceTrack[] }
+export type ClipSource = {
+  nodes: ClipSourceNode[]
+  animations: ClipSourceAnimation[]
+  /** Written onto every animation this source produces (provenance, fps, events). */
+  extras?: (clipName: string) => Record<string, unknown> | undefined
+}
+
+/** An ufbx scene as a ClipSource (arena views resolved once). */
+export const clipSourceFromFbx = (scene: FbxScene): ClipSource => ({
+  nodes: scene.nodes.map((n) => ({ name: n.name, parent: n.parent, t: n.t, r: n.r, s: n.s, isRoot: n.isRoot })),
+  animations: scene.animations.filter((a) => a.tracks.length > 0).map((a) => ({
+    name: a.name,
+    duration: a.duration,
+    tracks: a.tracks.map((tr) => ({
+      node: tr.node,
+      path: tr.path,
+      times: f32(scene, tr.times, tr.count),
+      values: f32(scene, tr.values, tr.count * (tr.path === "rotation" ? 4 : 3)),
+    })),
+  })),
+})
+
+/** Build the name → node maps used for clip binding (exact first, then short names; first wins). */
+export const nodeNameMaps = (doc: Document): { exact: Map<string, Node>, short: Map<string, Node> } => {
+  const exact = new Map<string, Node>()
+  const short = new Map<string, Node>()
+  for (const n of doc.getRoot().listNodes()) {
+    const name = n.getName()
+    if (!name) continue
+    if (!exact.has(name)) exact.set(name, n)
+    const s = shortName(name)
+    if (!short.has(s)) short.set(s, n)
+  }
+  return { exact, short }
+}
+
+export const findNodeByName = (maps: { exact: Map<string, Node>, short: Map<string, Node> }, name: string, rename?: Record<string, string>): Node | undefined => {
+  const n = rename?.[name] ?? name
+  return maps.exact.get(n) ?? maps.short.get(shortName(n))
+}
+
+
+// ---- parent-space correction for merged tracks -------------------------------------------------
+// A glTF/FBX track is a LOCAL transform — relative to the node's parent. Two files of the same rig
+// do not have to agree on what sits above a bone: Unreal/Unity clip exports put `root` directly
+// under the scene (rest −90°X, the Z-up→Y-up turn), while the skinned-mesh export parks that same
+// turn on an armature node and leaves `root` at identity. Copying the clip's root track verbatim
+// then applies the turn twice and the character plays lying on the floor. So for every bound bone
+// the rest WORLD transform of its parent is compared between the two files and, when they differ,
+// the track is re-expressed in the model's parent space: local_model(t) = inv(Pmodel)·Pclip·local_clip(t).
+// The comparison is made with the clip's FIRST FRAME written onto every bone it animates, in both
+// files — the rest poses of two exports of one rig routinely differ by a hair (Mixamo re-exports the
+// hips 1.6 cm apart) and those differences are overridden by the tracks anyway. What is left is the
+// STATIC structure above a bone: wrapper nodes, a missing root, an unanimated offset.
+type TRS = { t: Vec3, r: Quat, s: Vec3 }
+const TRS_ID: TRS = { t: [ 0, 0, 0 ], r: [ 0, 0, 0, 1 ], s: [ 1, 1, 1 ] }
+const composeTRS = (p: TRS, l: TRS): TRS => {
+  const st: Vec3 = [ p.s[0] * l.t[0], p.s[1] * l.t[1], p.s[2] * l.t[2] ]
+  const rt = qrot(p.r, st)
+  return { t: [ p.t[0] + rt[0], p.t[1] + rt[1], p.t[2] + rt[2] ], r: qnorm(qmul(p.r, l.r)), s: [ p.s[0] * l.s[0], p.s[1] * l.s[1], p.s[2] * l.s[2] ] }
+}
+const invertTRS = (a: TRS): TRS => {
+  const s: Vec3 = [ 1 / a.s[0], 1 / a.s[1], 1 / a.s[2] ]
+  const r = qinv(a.r)
+  const rt = qrot(r, a.t)
+  return { t: [ -s[0] * rt[0], -s[1] * rt[1], -s[2] * rt[2] ], r, s }
+}
+const quatAngleDeg = (q: Quat): number => 2 * Math.acos(Math.min(1, Math.abs(q[3]))) * 180 / Math.PI
+const isIdentityTRS = (m: TRS, eps = 1e-4): boolean =>
+  Math.hypot(m.t[0], m.t[1], m.t[2]) < eps && quatAngleDeg(m.r) < 0.01 && Math.abs(m.s[0] - 1) < eps && Math.abs(m.s[1] - 1) < eps && Math.abs(m.s[2] - 1) < eps
+
+/** First-frame values of a clip per node: whichever of t/r/s it animates. */
+type Frame0 = Map<number, Partial<TRS>>
+const frame0Of = (clip: ClipSource, a: ClipSourceAnimation): Frame0 => {
+  const out: Frame0 = new Map()
+  for (const tr of a.tracks) {
+    if (tr.times.length <= 0) continue
+    const comps = tr.path === "rotation" ? 4 : 3
+    const v = Array.from(tr.values.subarray(0, comps)) as number[]
+    const e = out.get(tr.node) ?? {}
+    if (tr.path === "translation") e.t = v as Vec3
+    else if (tr.path === "rotation") e.r = v as Quat
+    else e.s = v as Vec3
+    out.set(tr.node, e)
+  }
+  return out
+}
+/** World transform of a clip-file node at the clip's first frame (rest where it isn't animated). */
+const clipWorldOf = (clip: ClipSource, f0: Frame0, cache: Map<number, TRS>, idx: number): TRS => {
+  if (idx < 0) return TRS_ID
+  const hit = cache.get(idx)
+  if (hit) return hit
+  const n = clip.nodes[idx]
+  const o = f0.get(idx)
+  const w = composeTRS(clipWorldOf(clip, f0, cache, n.parent), { t: o?.t ?? n.t, r: o?.r ?? n.r, s: o?.s ?? n.s })
+  cache.set(idx, w)
+  return w
+}
+/** World transform of a Document node (null = the scene) with the clip's first frame written onto
+ *  the bones the clip binds to — so only STRUCTURAL differences remain against `clipWorldOf`. */
+const docWorldOf = (clip: ClipSource, f0: Frame0, clipIdxOf: Map<Node, number>, clipCache: Map<number, TRS>, cache: Map<Node, TRS>, node: Node | null): TRS => {
+  if (!node) return TRS_ID
+  const hit = cache.get(node)
+  if (hit) return hit
+  // a bone the clip animates ends up exactly where the clip puts it — its track is re-expressed to
+  // make that so — hence its world IS the clip's world; only the unanimated structure above differs
+  const ci = clipIdxOf.get(node)
+  const w = ci !== undefined && f0.has(ci)
+    ? clipWorldOf(clip, f0, clipCache, ci)
+    : composeTRS(docWorldOf(clip, f0, clipIdxOf, clipCache, cache, node.getParentNode()), { t: node.getTranslation() as Vec3, r: node.getRotation() as Quat, s: node.getScale() as Vec3 })
+  cache.set(node, w)
+  return w
+}
+
+/** Merge every animation of a clip source into `doc`, re-targeted by bone name. Returns per-clip stats. */
+export const mergeClipScene = (doc: Document, clip: ClipSource, sourceLabel: string, explicitName: string | undefined, rename: Record<string, string> | undefined, warn: (w: ConvertWarning) => void): ConvertReport["clips"] => {
+  const maps = nodeNameMaps(doc)
+  const buffer = doc.getRoot().listBuffers()[0] ?? doc.createBuffer("buffer")
+  const out: ConvertReport["clips"] = []
+  // clip node → bound model node (and back), once per clip file
+  const clipIdxOf = new Map<Node, number>()
+  for (let i = 0; i < clip.nodes.length; i++) {
+    const n = clip.nodes[i]
+    if (n.isRoot) continue
+    const t = findNodeByName(maps, n.name, rename)
+    if (t && !clipIdxOf.has(t)) clipIdxOf.set(t, i)
+  }
+  let clipWorlds = new Map<number, TRS>()
+  let docWorlds = new Map<Node, TRS>()
+  let corrections = new Map<number, TRS | null>()   // clip node index → inv(Pmodel)·Pclip (null = parents agree)
+  let f0: Frame0 = new Map()
+  const corrected: string[] = []
+  const correctionFor = (srcIdx: number, target: Node): TRS | null => {
+    const hit = corrections.get(srcIdx)
+    if (hit !== undefined) return hit
+    const pc = clipWorldOf(clip, f0, clipWorlds, clip.nodes[srcIdx].parent)
+    const pm = docWorldOf(clip, f0, clipIdxOf, clipWorlds, docWorlds, target.getParentNode())
+    const m = composeTRS(invertTRS(pm), pc)
+    let res: TRS | null = isIdentityTRS(m) ? null : m
+    if (res && (Math.abs(res.s[0] - 1) > 1e-3 || Math.abs(res.s[1] - 1) > 1e-3 || Math.abs(res.s[2] - 1) > 1e-3)) {
+      warn({ level: "warn", message: `bone '${clip.nodes[srcIdx].name}': the clip file and the model disagree on the SCALE above it (${res.s.map((v) => v.toFixed(3)).join(",")}) — track copied verbatim` })
+      res = null
+    }
+    if (res && !corrected.includes(clip.nodes[srcIdx].name)) corrected.push(clip.nodes[srcIdx].name)
+    corrections.set(srcIdx, res)
+    return res
+  }
+  const emitted = clip.animations.filter((a) => a.tracks.length > 0)
+  const fileBase = basename(sourceLabel, extname(sourceLabel))
+  for (const a of emitted) {
+    let name = explicitName ?? a.name
+    if (!explicitName && (emitted.length === 1 ? isGenericClipName(name) : false)) name = fileBase
+    if (!explicitName && emitted.length > 1 && isGenericClipName(name)) name = `${fileBase}/${a.name || "clip"}`
+    // unique names inside the document
+    const existing = new Set(doc.getRoot().listAnimations().map((x) => x.getName()))
+    let unique = name, k = 2
+    while (existing.has(unique)) unique = `${name} (${k++})`
+    const anim = doc.createAnimation(unique)
+    clipWorlds = new Map(); docWorlds = new Map(); corrections = new Map(); f0 = frame0Of(clip, a)
+    let bound = 0
+    const unbound = new Set<string>()
+    for (const tr of a.tracks) {
+      const srcNode = clip.nodes[tr.node]
+      if (!srcNode || srcNode.isRoot) continue
+      const target = findNodeByName(maps, srcNode.name, rename)
+      if (!target) { unbound.add(srcNode.name || `(unnamed #${tr.node})`); continue }
+      const times = tr.times.slice()
+      const comps = tr.path === "rotation" ? 4 : 3
+      const values = tr.values.slice()
+      const fix = correctionFor(tr.node, target)
+      if (fix) {
+        if (tr.path === "rotation") {
+          for (let k = 0; k < values.length; k += 4) {
+            const q = qnorm(qmul(fix.r, [ values[k], values[k + 1], values[k + 2], values[k + 3] ]))
+            values[k] = q[0]; values[k + 1] = q[1]; values[k + 2] = q[2]; values[k + 3] = q[3]
+          }
+        } else if (tr.path === "translation") {
+          for (let k = 0; k < values.length; k += 3) {
+            const v = qrot(fix.r, [ fix.s[0] * values[k], fix.s[1] * values[k + 1], fix.s[2] * values[k + 2] ])
+            values[k] = v[0] + fix.t[0]; values[k + 1] = v[1] + fix.t[1]; values[k + 2] = v[2] + fix.t[2]
+          }
+        }
+      }
+      if (tr.path === "rotation") fixQuatContinuity(values)
+      const sampler = doc.createAnimationSampler()
+        .setInput(doc.createAccessor().setType("SCALAR").setArray(times).setBuffer(buffer))
+        .setOutput(doc.createAccessor().setType(comps === 4 ? "VEC4" : "VEC3").setArray(values).setBuffer(buffer))
+        .setInterpolation("LINEAR")
+      const channel = doc.createAnimationChannel().setTargetNode(target).setTargetPath(tr.path).setSampler(sampler)
+      anim.addSampler(sampler).addChannel(channel)
+      bound++
+    }
+    const extras = clip.extras?.(a.name)
+    if (extras) anim.setExtras(extras)
+    const total = a.tracks.filter((t) => !clip.nodes[t.node]?.isRoot).length
+    if (bound === 0 && total > 0) warn({ level: "warn", message: `clip '${unique}' (${sourceLabel}): NO track matched a bone of the model — different rig? (bones: ${[ ...unbound ].slice(0, 5).join(", ")}…)` })
+    else if (unbound.size > 0) warn({ level: "warn", message: `clip '${unique}' (${sourceLabel}): ${total - bound}/${total} tracks unbound — bones not in the model: ${[ ...unbound ].slice(0, 8).join(", ")}${unbound.size > 8 ? "…" : ""}` })
+    out.push({ name: unique, source: sourceLabel, duration: a.duration, tracks: total, bound })
+  }
+  if (corrected.length > 0) {
+    const m = corrections.get(clip.nodes.findIndex((n) => n.name === corrected[0]))!
+    const off = Math.hypot(m.t[0], m.t[1], m.t[2])
+    warn({ level: "info", message: `${sourceLabel}: '${corrected.join("', '")}' sit${corrected.length === 1 ? "s" : ""} under a different parent than in the model (rotation ${quatAngleDeg(m.r).toFixed(0)}°${off > 1e-4 ? `, offset ${off.toFixed(3)} m` : ""}) — track${corrected.length === 1 ? "" : "s"} re-expressed in the model's parent space` })
+  }
+  return out
+}
+
+export type ClipSourceOptions = {
+  /** `.uasset` clips: the skeleton they were authored on (default: resolved from the pack). */
+  skeleton?: string
+  /** `.uasset` clips: the pack's Content folder, when the walk-up search cannot find it. */
+  contentRoot?: string
+}
+
+/** A clip file — FBX or Unreal `.uasset` AnimSequence — as a ClipSource. */
+export const loadClipSource = async (path: string, opts: ClipSourceOptions = {}): Promise<ClipSource> => {
+  if (/\.uasset$/i.test(path)) {
+    const { loadUnreal } = await import("../unreal/index")
+    const { clipSourceFromUnreal } = await import("../unreal/clipSource")
+    const u = loadUnreal(path, { skeleton: opts.skeleton, contentRoot: opts.contentRoot })
+    if (!u.anim) throw new Error(`${basename(path)}: not an AnimSequence (${u.kind}) — --clips wants animation assets`)
+    return clipSourceFromUnreal(u.skeleton, u.anim)
+  }
+  return clipSourceFromFbx(await readFbx(new Uint8Array(readFileSync(path))))
+}
+
+export type ConvertResult = { doc: Document, report: ConvertReport }
+
+/** FBX file (+ clip files) → Document. */
+export const convertFbx = async (fbxPath: string, opts: ConvertOptions = {}): Promise<ConvertResult> => {
+  const warnings: ConvertWarning[] = []
+  const warn = (w: ConvertWarning): void => { warnings.push(w); opts.warn?.(w) }
+  const bytes = new Uint8Array(readFileSync(fbxPath))
+  const scene = await readFbx(bytes)
+  const base = basename(fbxPath, extname(fbxPath))
+  const { doc, clipNames } = await toDocument(scene, { baseDir: dirname(fbxPath), defaultClipName: base, warn })
+  let unity: ConvertReport["unity"]
+  if (opts.unity !== false) {
+    const { applyUnityMaterials, pruneUnusedTextures } = await import("../unity/materials")
+    unity = await applyUnityMaterials(doc, fbxPath, { materialDirs: typeof opts.unity === "string" ? [ opts.unity ] : undefined, indexFile: opts.unityIndex, warn })
+    if (unity.applied.length) pruneUnusedTextures(doc)
+  }
+  const clips: ConvertReport["clips"] = []
+  if (opts.dropModelClips) {
+    for (const a of doc.getRoot().listAnimations()) a.dispose()
+  } else {
+    doc.getRoot().listAnimations().forEach((a, i) => {
+      const src = scene.animations.filter((x) => x.tracks.length > 0)[i]
+      clips.push({ name: a.getName(), source: basename(fbxPath), duration: src?.duration ?? 0, tracks: a.listChannels().length, bound: a.listChannels().length })
+    })
+    void clipNames
+  }
+  for (let i = 0; i < (opts.clips ?? []).length; i++) {
+    const clipPath = opts.clips![i]
+    clips.push(...mergeClipScene(doc, await loadClipSource(clipPath, opts), basename(clipPath), opts.clipNames?.[i], opts.rename, warn))
+  }
+  const root = doc.getRoot()
+  return {
+    doc,
+    report: {
+      clips, warnings,
+      nodes: root.listNodes().length, meshes: root.listMeshes().length, skins: root.listSkins().length,
+      textures: root.listTextures().length, materials: root.listMaterials().length,
+      unity,
+    },
+  }
+}
+
+export const makeIO = (): NodeIO => new NodeIO().registerExtensions(ALL_EXTENSIONS)
+
+/** Serialize a Document to GLB bytes. */
+export const writeGlb = async (doc: Document): Promise<Uint8Array> => makeIO().writeBinary(doc)

package/src/fbx/read.ts

@@ -0,0 +1,111 @@
+// FBX reading via the ufbx wasm module (native/fbx_reader.c → src/wasm/fbxReader.js). Returns a
+// plain intermediate representation already in glTF conventions (meters, Y-up, triangulated,
+// baked animations); `toDocument` turns it into a glTF-Transform Document.
+
+// @ts-ignore — generated by build-wasm.sh (Emscripten single-file module)
+import createFbxReader from "../wasm/fbxReader.js"
+
+export type FbxNode = {
+  name: string
+  parent: number
+  t: [number, number, number]
+  r: [number, number, number, number]
+  s: [number, number, number]
+  mesh: number
+  skin: number
+  isRoot: boolean
+  isBone: boolean
+  helper: boolean
+}
+export type FbxPrimitive = {
+  material: number
+  vertexCount: number
+  indexCount: number
+  pos: number; nrm: number; uv: number; col: number; joints: number; weights: number; indices: number
+  /** UV sets 1..3 (Unity uv2 / uv3 / uv4) — a pack's detail layer lives there; -1 when the mesh has none. */
+  uv1: number; uv2: number; uv3: number
+  min: [number, number, number]
+  max: [number, number, number]
+}
+export type FbxMesh = { name: string, primitives: FbxPrimitive[] }
+export type FbxSkin = { name: string, joints: number[], ibm: number }
+export type FbxMaterial = {
+  name: string
+  baseColor: [number, number, number, number]
+  baseTex: number
+  metallic: number
+  roughness: number
+  metallicTex: number
+  roughnessTex: number
+  normalTex: number
+  occlusionTex: number
+  emissive: [number, number, number]
+  emissiveTex: number
+  opacity: number
+  opacityTex: number
+  doubleSided: boolean
+  unlit: boolean
+  shader: string
+}
+export type FbxTexture = { name: string, filename: string, relative: string, absolute: string, content: number, size: number }
+export type FbxTrack = { node: number, path: "translation" | "rotation" | "scale", count: number, times: number, values: number, constant: boolean }
+export type FbxAnimation = { name: string, duration: number, tracks: FbxTrack[] }
+
+export type FbxScene = {
+  meta: { unitMeters: number, exporter: number, creator: string, version: number }
+  nodes: FbxNode[]
+  meshes: FbxMesh[]
+  skins: FbxSkin[]
+  materials: FbxMaterial[]
+  textures: FbxTexture[]
+  animations: FbxAnimation[]
+  /** The binary arena every offset above points into (a private copy — safe after close). */
+  arena: Uint8Array
+}
+
+type Module = {
+  _malloc(n: number): number
+  _free(p: number): void
+  _fbx_open(ptr: number, size: number): number
+  _fbx_error(): number
+  _fbx_json(h: number): number
+  _fbx_arena(h: number): number
+  _fbx_arena_size(h: number): number
+  _fbx_close(h: number): void
+  HEAPU8: Uint8Array
+  UTF8ToString(ptr: number): string
+}
+
+let modulePromise: Promise<Module> | undefined
+const getModule = (): Promise<Module> => (modulePromise ??= (createFbxReader as () => Promise<Module>)())
+
+/** Parse an FBX (bytes) into the intermediate representation. Throws with ufbx's message on failure. */
+export const readFbx = async (bytes: Uint8Array): Promise<FbxScene> => {
+  const m = await getModule()
+  const ptr = m._malloc(bytes.byteLength)
+  m.HEAPU8.set(bytes, ptr)
+  const handle = m._fbx_open(ptr, bytes.byteLength)
+  m._free(ptr)
+  if (handle === 0) throw new Error(`FBX: ${m.UTF8ToString(m._fbx_error()) || "unknown error"}`)
+  try {
+    const json = m.UTF8ToString(m._fbx_json(handle))
+    const arenaPtr = m._fbx_arena(handle)
+    const arenaSize = m._fbx_arena_size(handle)
+    const arena = new Uint8Array(arenaSize)
+    arena.set(m.HEAPU8.subarray(arenaPtr, arenaPtr + arenaSize))
+    const scene = JSON.parse(json) as Omit<FbxScene, "arena">
+    return { ...scene, arena }
+  } finally {
+    m._fbx_close(handle)
+  }
+}
+
+// ---- arena readers ----
+export const f32 = (scene: FbxScene, offset: number, count: number): Float32Array =>
+  new Float32Array(scene.arena.buffer, scene.arena.byteOffset + offset, count)
+export const u16 = (scene: FbxScene, offset: number, count: number): Uint16Array =>
+  new Uint16Array(scene.arena.buffer, scene.arena.byteOffset + offset, count)
+export const u32 = (scene: FbxScene, offset: number, count: number): Uint32Array =>
+  new Uint32Array(scene.arena.buffer, scene.arena.byteOffset + offset, count)
+export const bytes = (scene: FbxScene, offset: number, size: number): Uint8Array =>
+  scene.arena.subarray(offset, offset + size)

package/src/fbx/toDocument.ts

@@ -0,0 +1,227 @@
+// FbxScene (IR from the ufbx wasm reader) → glTF-Transform Document. Nodes/meshes/skins/materials/
+// textures/animations; the doctor passes and the writer then run on the Document like on any GLB.
+
+import { Document, type Node, type Texture, type Material } from "@gltf-transform/core"
+import { type FbxScene, type FbxTexture, f32, u16, u32, bytes } from "./read"
+import { resolveTextureImage, type ResolvedImage } from "../textures/resolveImage"
+
+export type ConvertWarning = { level: "warn" | "info", message: string }
+
+/** A COLOR_0 set (RGBA per vertex) that is black on EVERY vertex - a channel nobody authored, never a colour to multiply by. */
+export function deadVertexColor(col: Float32Array): boolean {
+  for (let i = 0; i + 3 < col.length; i += 4) if (col[i] > 0 || col[i + 1] > 0 || col[i + 2] > 0) return false
+  return col.length > 0
+}
+
+export type ToDocumentOptions = {
+  /** Directory of the source .fbx — external texture references are resolved against it. */
+  baseDir?: string
+  /** Name used for the file's single clip when its stack name is generic (`mixamo.com`, `Take 001`, `Unreal Take`). */
+  defaultClipName?: string
+  /** Skip meshes/skins/materials/textures (clip-only conversion). */
+  animationsOnly?: boolean
+  /** Also write the FBX's further UV sets as TEXCOORD_1..3 (off by default: TEXCOORD_1 is the lightmap set in
+   *  every LeCodes GLB, and a pack's extra sets are shader inputs — the Unity kind builder reads them and
+   *  drops them again). */
+  extraUvSets?: boolean
+  warn?: (w: ConvertWarning) => void
+}
+
+const GENERIC_CLIP_NAMES = new Set([ "", "mixamo.com", "take 001", "take001", "unreal take", "default take", "unnamed", "scene" ])
+export const isGenericClipName = (name: string): boolean => GENERIC_CLIP_NAMES.has(name.trim().toLowerCase())
+
+const isIdentityTransform = (t: number[], r: number[], s: number[]): boolean =>
+  Math.hypot(t[0], t[1], t[2]) < 1e-9 && Math.abs(r[3] - 1) < 1e-9 && Math.hypot(r[0], r[1], r[2]) < 1e-9 &&
+  Math.abs(s[0] - 1) < 1e-9 && Math.abs(s[1] - 1) < 1e-9 && Math.abs(s[2] - 1) < 1e-9
+
+/** Make consecutive quaternions hemisphere-consistent so LINEAR (slerp) interpolation never takes the long way. */
+export const fixQuatContinuity = (q: Float32Array): void => {
+  for (let i = 4; i < q.length; i += 4) {
+    const dot = q[i] * q[i - 4] + q[i + 1] * q[i - 3] + q[i + 2] * q[i - 2] + q[i + 3] * q[i - 1]
+    if (dot < 0) { q[i] = -q[i]; q[i + 1] = -q[i + 1]; q[i + 2] = -q[i + 2]; q[i + 3] = -q[i + 3] }
+  }
+}
+
+export type ToDocumentResult = {
+  doc: Document
+  /** glTF node per FBX node index (null for the ufbx root when it was flattened away). */
+  nodes: (Node | null)[]
+  clipNames: string[]
+}
+
+export const toDocument = async (scene: FbxScene, opts: ToDocumentOptions = {}): Promise<ToDocumentResult> => {
+  const warn = opts.warn ?? (() => {})
+  const doc = new Document()
+  const buffer = doc.createBuffer("buffer")
+  const gscene = doc.createScene("Scene")
+
+  // ---- nodes ----
+  const nodes: (Node | null)[] = new Array(scene.nodes.length).fill(null)
+  const rootIdx = scene.nodes.findIndex((n) => n.isRoot)
+  const root = rootIdx >= 0 ? scene.nodes[rootIdx] : undefined
+  let rootNode: Node | null = null
+  if (root && !isIdentityTransform(root.t, root.r, root.s)) {
+    rootNode = doc.createNode(root.name || "RootNode").setTranslation(root.t).setRotation(root.r).setScale(root.s)
+    gscene.addChild(rootNode)
+    nodes[rootIdx] = rootNode
+  }
+  for (let i = 0; i < scene.nodes.length; i++) {
+    const n = scene.nodes[i]
+    if (n.isRoot) continue
+    const g = doc.createNode(n.name).setTranslation(n.t).setRotation(n.r).setScale(n.s)
+    nodes[i] = g
+  }
+  for (let i = 0; i < scene.nodes.length; i++) {
+    const n = scene.nodes[i]
+    const g = nodes[i]
+    if (!g || n.isRoot) continue
+    const parent = n.parent >= 0 ? nodes[n.parent] : null
+    if (parent) parent.addChild(g)
+    else gscene.addChild(g)
+  }
+
+  if (!opts.animationsOnly) {
+    // ---- textures ----
+    const textures: (Texture | null)[] = []
+    const byHash = new Map<string, Texture>()
+    for (let i = 0; i < scene.textures.length; i++) {
+      const t = scene.textures[i]
+      const img = await resolveTextureImage(t, t.content >= 0 ? bytes(scene, t.content, t.size) : null, opts.baseDir, warn)
+      if (!img) { textures.push(null); continue }
+      const key = img.hash
+      let tex = byHash.get(key)
+      if (!tex) {
+        tex = doc.createTexture(textureName(t, img)).setImage(img.data).setMimeType(img.mimeType)
+        byHash.set(key, tex)
+      }
+      textures.push(tex)
+    }
+    const texAt = (i: number): Texture | null => (i >= 0 && i < textures.length ? textures[i] : null)
+
+    // ---- materials ----
+    const materials: Material[] = scene.materials.map((m) => {
+      const mat = doc.createMaterial(m.name)
+      mat.setBaseColorFactor([ clamp01(m.baseColor[0]), clamp01(m.baseColor[1]), clamp01(m.baseColor[2]), clamp01(m.baseColor[3]) ])
+      const base = texAt(m.baseTex)
+      if (base) { mat.setBaseColorTexture(base); mat.setBaseColorFactor([ 1, 1, 1, clamp01(m.baseColor[3]) ]) }
+      mat.setMetallicFactor(clamp01(m.metallic))
+      mat.setRoughnessFactor(clamp01(m.roughness))
+      // glTF packs metallic (B) + roughness (G) into ONE texture; FBX keeps them apart. Only when both
+      // point at the same image can we forward it — otherwise the factors above stand in.
+      if (m.metallicTex >= 0 && m.metallicTex === m.roughnessTex) {
+        const mr = texAt(m.metallicTex); if (mr) { mat.setMetallicRoughnessTexture(mr); mat.setMetallicFactor(1); mat.setRoughnessFactor(1) }
+      } else if (m.metallicTex >= 0 || m.roughnessTex >= 0) {
+        warn({ level: "info", message: `material '${m.name}': separate metallic/roughness maps are not packed (factors used)` })
+      }
+      const nrm = texAt(m.normalTex); if (nrm) mat.setNormalTexture(nrm)
+      const occ = texAt(m.occlusionTex); if (occ) mat.setOcclusionTexture(occ)
+      const em = texAt(m.emissiveTex)
+      if (em) { mat.setEmissiveTexture(em); mat.setEmissiveFactor([ 1, 1, 1 ]) }
+      else mat.setEmissiveFactor([ clamp01(m.emissive[0]), clamp01(m.emissive[1]), clamp01(m.emissive[2]) ])
+      // alpha: an opacity map → cutout (hair cards, leaves); a factor < 1 → blend
+      if (m.opacityTex >= 0) {
+        mat.setAlphaMode("MASK").setAlphaCutoff(0.5)
+        if (!base && texAt(m.opacityTex)) mat.setBaseColorTexture(texAt(m.opacityTex)!)
+      } else if (m.opacity < 0.999) {
+        mat.setAlphaMode("BLEND")
+        const f = mat.getBaseColorFactor(); mat.setBaseColorFactor([ f[0], f[1], f[2], clamp01(m.opacity) ])
+      }
+      mat.setDoubleSided(m.doubleSided)
+      return mat
+    })
+
+    // ---- meshes ----
+    // An FBX geometry is often unnamed (Maya exports, "wolf" → mesh ""); name it after the node that
+    // carries it so probe/doctor/pick-by-name have something to print.
+    const meshNodeName: string[] = new Array(scene.meshes.length).fill("")
+    for (const n of scene.nodes) if (n.mesh >= 0 && n.mesh < meshNodeName.length && !meshNodeName[n.mesh]) meshNodeName[n.mesh] = n.name
+    const meshes = scene.meshes.map((m, mi) => {
+      const mesh = doc.createMesh(m.name || meshNodeName[mi])
+      for (const p of m.primitives) {
+        const prim = doc.createPrimitive()
+        prim.setAttribute("POSITION", doc.createAccessor().setType("VEC3").setArray(f32(scene, p.pos, p.vertexCount * 3).slice()).setBuffer(buffer))
+        if (p.nrm >= 0) prim.setAttribute("NORMAL", doc.createAccessor().setType("VEC3").setArray(f32(scene, p.nrm, p.vertexCount * 3).slice()).setBuffer(buffer))
+        if (p.uv >= 0) prim.setAttribute("TEXCOORD_0", doc.createAccessor().setType("VEC2").setArray(f32(scene, p.uv, p.vertexCount * 2).slice()).setBuffer(buffer))
+        if (opts.extraUvSets) for (const [ k, off ] of [ p.uv1, p.uv2, p.uv3 ].entries()) if (off !== undefined && off >= 0) prim.setAttribute(`TEXCOORD_${k + 1}`, doc.createAccessor().setType("VEC2").setArray(f32(scene, off, p.vertexCount * 2).slice()).setBuffer(buffer))
+        if (p.col >= 0) {
+          const col = f32(scene, p.col, p.vertexCount * 4).slice()
+          // An all-black colour set is an UNUSED channel: Unity's Standard shader never reads vertex colour, so a pack
+          // ships whatever its DCC left there (the Military FPS hands: zeros on the skin mesh) - while every glTF
+          // renderer multiplies it into the base colour, and the mesh comes out black. Dropped, with a note.
+          if (deadVertexColor(col)) warn({ level: "info", message: `mesh '${m.name || meshNodeName[mi]}': all-black COLOR_0 dropped (it would multiply the base colour to black)` })
+          else prim.setAttribute("COLOR_0", doc.createAccessor().setType("VEC4").setArray(col).setBuffer(buffer))
+        }
+        if (p.joints >= 0 && p.weights >= 0) {
+          prim.setAttribute("JOINTS_0", doc.createAccessor().setType("VEC4").setArray(u16(scene, p.joints, p.vertexCount * 4).slice()).setBuffer(buffer))
+          prim.setAttribute("WEIGHTS_0", doc.createAccessor().setType("VEC4").setArray(f32(scene, p.weights, p.vertexCount * 4).slice()).setBuffer(buffer))
+        }
+        const idx = u32(scene, p.indices, p.indexCount)
+        const indices = p.vertexCount <= 65535 ? Uint16Array.from(idx) : idx.slice()
+        prim.setIndices(doc.createAccessor().setType("SCALAR").setArray(indices).setBuffer(buffer))
+        if (p.material >= 0 && p.material < materials.length) prim.setMaterial(materials[p.material])
+        mesh.addPrimitive(prim)
+      }
+      return mesh
+    })
+
+    // ---- skins ----
+    const skins = scene.skins.map((s) => {
+      const skin = doc.createSkin(s.name)
+      const ibm = f32(scene, s.ibm, s.joints.length * 16).slice()
+      for (let j = 0; j < s.joints.length; j++) {
+        const jn = s.joints[j] >= 0 ? nodes[s.joints[j]] : null
+        if (jn) skin.addJoint(jn)
+        else {
+          // a cluster without a bone: bind it to the first available node so joint indices stay aligned
+          const fallback = nodes.find((n) => n) ?? doc.createNode("missing-joint")
+          skin.addJoint(fallback)
+          warn({ level: "warn", message: `skin '${s.name}': cluster ${j} has no bone node — bound to a placeholder` })
+        }
+      }
+      skin.setInverseBindMatrices(doc.createAccessor().setType("MAT4").setArray(ibm).setBuffer(buffer))
+      return skin
+    })
+
+    for (let i = 0; i < scene.nodes.length; i++) {
+      const n = scene.nodes[i]
+      const g = nodes[i]
+      if (!g) continue
+      if (n.mesh >= 0 && n.mesh < meshes.length) g.setMesh(meshes[n.mesh])
+      if (n.skin >= 0 && n.skin < skins.length) g.setSkin(skins[n.skin])
+    }
+  }
+
+  // ---- animations ----
+  const emitted = scene.animations.filter((a) => a.tracks.length > 0)
+  const clipNames: string[] = []
+  for (const a of emitted) {
+    let name = a.name
+    if (emitted.length === 1 && isGenericClipName(name) && opts.defaultClipName) name = opts.defaultClipName
+    clipNames.push(name)
+    const anim = doc.createAnimation(name)
+    for (const tr of a.tracks) {
+      const target = nodes[tr.node]
+      if (!target) continue
+      const times = f32(scene, tr.times, tr.count).slice()
+      const comps = tr.path === "rotation" ? 4 : 3
+      const values = f32(scene, tr.values, tr.count * comps).slice()
+      if (tr.path === "rotation") fixQuatContinuity(values)
+      const sampler = doc.createAnimationSampler()
+        .setInput(doc.createAccessor().setType("SCALAR").setArray(times).setBuffer(buffer))
+        .setOutput(doc.createAccessor().setType(comps === 4 ? "VEC4" : "VEC3").setArray(values).setBuffer(buffer))
+        .setInterpolation("LINEAR")
+      const channel = doc.createAnimationChannel().setTargetNode(target).setTargetPath(tr.path).setSampler(sampler)
+      anim.addSampler(sampler).addChannel(channel)
+    }
+  }
+
+  return { doc, nodes, clipNames }
+}
+
+const clamp01 = (v: number): number => (v < 0 ? 0 : v > 1 ? 1 : v)
+
+const textureName = (t: FbxTexture, img: ResolvedImage): string => {
+  const src = t.relative || t.filename || t.absolute || t.name
+  const base = src.split(/[\\/]/).pop() ?? t.name
+  return (base.replace(/\.[^.]+$/, "") || t.name || "texture") + (img.converted ? "" : "")
+}