lecodes-assets 0.2.1 → 2.5.0

package/src/fbx/read.ts

@@ -22,6 +22,8 @@ export type FbxPrimitive = {
   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]
 }

package/src/fbx/toDocument.ts

@@ -1,209 +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 }
-
-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
-  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 (p.col >= 0) prim.setAttribute("COLOR_0", doc.createAccessor().setType("VEC4").setArray(f32(scene, p.col, p.vertexCount * 4).slice()).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 ? "" : "")
-}
+// 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 ? "" : "")
+}