lecodes-assets 0.2.1 → 2.5.0

package/src/commands/avatar.ts

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { basename } from "node:path"
+import { defineCommand, missing, notFound, str } from "../cli-kit"
+import type { HumanBone } from "../retarget/humanoid"
+import { log, unrealFlags } from "./shared"
+
+const GROUPS: [string, HumanBone[]][] = [
+  [ "torso", [ "Hips", "Spine", "Chest", "UpperChest", "Neck", "Head", "Jaw", "LeftEye", "RightEye" ] ],
+  [ "left arm", [ "LeftShoulder", "LeftUpperArm", "LeftLowerArm", "LeftHand" ] ], [ "right arm", [ "RightShoulder", "RightUpperArm", "RightLowerArm", "RightHand" ] ],
+  [ "left leg", [ "LeftUpperLeg", "LeftLowerLeg", "LeftFoot", "LeftToes" ] ], [ "right leg", [ "RightUpperLeg", "RightLowerLeg", "RightFoot", "RightToes" ] ],
+]
+
+export default defineCommand({
+  name: "avatar",
+  summary: "A humanoid rig's AVATAR: its bones named in the Unity/VRM canon, read off the skeleton's shape",
+  usage: "<model.fbx|.glb|.uasset>",
+  description: `
+    Hips = the joint two ground-reaching chains hang from, hands = the lateral joints fanning into
+    fingers, head = the last branch above the arms; twist/roll helpers recorded, not mapped.
+
+    --meta checks the result against Unity's own humanoid map (and imports it verbatim when you trust
+    it more: -o with --meta writes Unity's). The file is what \`retarget --avatar\` reads.`,
+  flags: {
+    meta: str("Unity's humanoid map to compare with / import", { value: "model.fbx.meta" }),
+    o: str("write the avatar", { value: "model.avatar.json" }),
+    ...unrealFlags,
+  },
+  run: async ({ args, flags }) => {
+    const input = args[0]
+    if (!input) throw missing("the model file")
+    if (!existsSync(input)) throw notFound(input)
+    const { loadRig, rigFromDocument } = await import("../retarget/rig")
+    const { classifyBiped, avatarFromBiped, avatarFromUnity, avatarToFile, parseUnityAvatar, describeBiped, HUMAN_BONES } = await import("../retarget/humanoid")
+    const { makeIO } = await import("../fbx/convert")
+    const rig = /\.uasset$/i.test(input) ? (await import("../unreal/rig")).rigFromUnreal(input, { skeleton: flags.skeleton, contentRoot: flags["content-root"] })
+      : /\.fbx$/i.test(input) ? await loadRig(input) : rigFromDocument(await makeIO().read(input), basename(input))
+    let shape: ReturnType<typeof avatarFromBiped> | null = null
+    try {
+      const b = classifyBiped(rig)
+      const av = shape = avatarFromBiped(rig, b)
+      log(`🧍 ${basename(input)}: ${describeBiped(rig, b)}`)
+      for (const [ g, keys ] of GROUPS) log(`   ${g}: ${keys.filter((k) => av.bones[k]).map((k) => `${k}=${av.bones[k]}`).join(" ")}`)
+      const fingers = HUMAN_BONES.filter((k) => k.includes(" ") && av.bones[k])
+      if (fingers.length) log(`   fingers: ${fingers.length} phalanges (${fingers.filter((k) => k.endsWith("Proximal")).map((k) => av.bones[k]).join(", ")})`)
+      if (Object.keys(av.twist).length) log(`   twist helpers: ${Object.entries(av.twist).map(([ t, of ]) => `${t}→${of}`).join(", ")}`)
+      if (av.bridged.length) log(`   bridged: ${av.bridged.join(", ")}`)
+      if (b.helpers.length) log(`   not part of the body (${b.helpers.length}): ${b.helpers.map((i) => rig.names[i]).slice(0, 16).join(", ")}${b.helpers.length > 16 ? " …" : ""}`)
+      for (const n of av.notes) log(`   ⚠ ${n}`)
+    } catch (e) {
+      log(`✗ ${basename(input)} does not read as a humanoid: ${(e as Error).message}`)
+    }
+    let unity: ReturnType<typeof avatarFromUnity> | null = null
+    if (flags.meta) {
+      if (!existsSync(flags.meta)) throw notFound(flags.meta)
+      unity = avatarFromUnity(rig, parseUnityAvatar(readFileSync(flags.meta, "utf8")))
+      for (const n of unity.notes) log(`   ⚠ .meta: ${n}`)
+      if (shape) {
+        let agree = 0
+        const differ: string[] = []
+        for (const k of HUMAN_BONES) {
+          const a = shape.bones[k], m = unity.bones[k]
+          if (a === m) { if (a) agree++; continue }
+          differ.push(`${k}: shape=${a ?? "-"} .meta=${m ?? "-"}`)
+        }
+        log(`   vs ${basename(flags.meta)}: ${agree} bones agree${differ.length ? `, ${differ.length} differ:` : ""}`)
+        for (const d of differ) log(`      ${d}`)
+      }
+    }
+    const chosen = unity ?? shape
+    if (!chosen) return 1
+    if (flags.o) {
+      writeFileSync(flags.o, JSON.stringify(avatarToFile(chosen), null, 2) + "\n")
+      log(`💾 wrote ${flags.o}  (${Object.keys(chosen.bones).length} bones, ${unity ? "Unity's map" : "from shape"}) — retarget … --avatar ${basename(flags.o)}`)
+    }
+    return 0
+  },
+})

package/src/commands/bvh.ts

@@ -0,0 +1,26 @@
+import { existsSync, writeFileSync } from "node:fs"
+import { defineCommand, int, missing, notFound, str } from "../cli-kit"
+import { log } from "./shared"
+
+export default defineCommand({
+  name: "bvh",
+  summary: "One clip of a GLB as a Kimodo-style BVH",
+  usage: "<model.glb> -o out.bvh",
+  flags: {
+    clip: str("the clip (default: the first)", { value: "<name>" }),
+    fps: int("sampling rate (30)"),
+    o: str("output (required)", { value: "out.bvh" }),
+  },
+  run: async ({ args, flags }) => {
+    const input = args[0]
+    if (!input) throw missing("the GLB")
+    if (!flags.o) throw missing("-o out.bvh")
+    if (!existsSync(input)) throw notFound(input)
+    const { makeIO } = await import("../fbx/convert")
+    const { documentToBvh } = await import("../bvh/fromDocument")
+    const r = documentToBvh(await makeIO().read(input), { clip: flags.clip, fps: flags.fps })
+    writeFileSync(flags.o, r.text)
+    log(`💾 wrote ${flags.o}  ("${r.report.clip}": ${r.report.joints} joints, ${r.report.frames} frames @ ${r.report.fps} fps)`)
+    return 0
+  },
+})

package/src/commands/convert.ts

@@ -0,0 +1,156 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { basename, dirname, extname, join } from "node:path"
+import type { Document } from "@gltf-transform/core"
+import { bool, defineCommand, int, list, missing, notFound, CliError, str } from "../cli-kit"
+import { doctorFlags, doctorOptions, ktx2Progress, log, logDoctorResult, megabytes, resolveInputs, seconds, unrealFlags, wantsDoctorFix, warnLine } from "./shared"
+
+type ClipReport = { clips: { name: string, source: string, duration: number, tracks: number, bound: number }[] }
+
+export default defineCommand({
+  name: "convert",
+  summary: "FBX, an existing GLB, an UNREAL asset or a BVH → a LeCodes-ready GLB",
+  usage: "<model.fbx|.glb|.uasset|.bvh>",
+  flags: {
+    o: str("output (default: <model>.glb next to the input)", { value: "out.glb" }),
+    clips: list("merge these files' animations into the model, bound by BONE NAME (FBX or Unreal AnimSequence; globs and folders expand)", { value: "a.fbx b.uasset …", group: "Clips" }),
+    "clip-names": list("names for --clips (default: stack name, or the file name when generic)", { value: "n1 n2 …" }),
+    "drop-model-clips": bool("drop the model file's own clips (e.g. Mixamo's 1-frame T-pose)"),
+    rename: list("bone name overrides for clip binding", { value: "clipBone=modelBone …" }),
+    "merge-skins": list("modular characters: move these files' SKINNED meshes onto the model's skeleton (joints matched by name), drop their skeleton copies", { value: "b.fbx c.glb …" }),
+    "unity-mats": str("Unity .mat files are read for the REAL textures (metallic / roughness / ORM / emission / alpha mode) when they sit next to the FBX — point elsewhere with this", { value: "<dir>", group: "Unity materials" }),
+    "no-unity": bool("…or switch it off"),
+    "unity-index": str("GUID → path table (default: found above the FBX, else .meta files)", { value: "<unity-index.txt>" }),
+    ...unrealFlags,
+    "lod-level": int("(Unreal) which mesh LOD to read (default 0)"),
+    "no-textures": bool("(Unreal) keep the grey material slots instead of pulling the pack's textures (they need an Oodle library — see the README)"),
+    "no-normal-flip": bool("(Unreal) keep normal maps DirectX-style (UE authors them green-down; glTF wants green-up, so they are flipped)"),
+    "list-nodes": int("print the scene's nodes (multi-variant prop files) and exit", { value: "depth", bare: 1, group: "Multi-variant prop files" }),
+    keep: list("keep only these nodes (+ their subtrees), re-origin the result (footprint centre at X/Z = 0, lowest point at Y = 0)", { value: "<node> …" }),
+    "no-ground": bool("…keep the file's own placement instead"),
+    split: str("one GLB per top-level node, each re-origined (default: <out>/)", { value: "dir", bare: "" }),
+    ...doctorFlags,
+  },
+  examples: [
+    "lecodes assets convert hero.fbx --clips anims/*.fbx --drop-model-clips -o hero.glb",
+    "lecodes assets convert props.fbx --list-nodes 2",
+    "lecodes assets convert gun.fbx --fix --ktx2-uastc --scale-to 0.9",
+  ],
+  run: async ({ args, flags, given }) => {
+    const input = args[0]
+    if (!input) throw missing("the model file")
+    if (!existsSync(input)) throw notFound(input)
+    const { convertFbx, mergeClipScene, loadClipSource, makeIO, writeGlb } = await import("../fbx/convert")
+    const clips = resolveInputs(flags.clips, /\.(fbx|glb|uasset)$/i, false)
+    const clipNames = flags["clip-names"].length ? flags["clip-names"] : undefined
+    const rename: Record<string, string> = {}
+    for (const r of flags.rename) { const [ a, b ] = r.split("="); if (a && b) rename[a] = b }
+    const t0 = performance.now()
+    log(`🔄 ${input}${clips.length ? ` + ${clips.length} clip file(s)` : ""}`)
+
+    const unrealOpts = { skeleton: flags.skeleton, contentRoot: flags["content-root"], lod: flags["lod-level"] }
+    const unity = { unity: flags["no-unity"] ? false as const : (flags["unity-mats"] ?? true), unityIndex: flags["unity-index"] }
+    const ext = extname(input).toLowerCase()
+    let doc: Document
+    let report: ClipReport = { clips: [] }
+    if (ext === ".uasset") {
+      // Unreal: a SkeletalMesh → mesh + skin + skeleton; a Skeleton or an AnimSequence → that
+      // skeleton (resolved from the pack for a clip) plus, for a clip, its own animation.
+      const { convertUnreal } = await import("../unreal/convertAsset")
+      const r = await convertUnreal(input, { clips, clipNames, rename, dropModelClips: flags["drop-model-clips"], warn: warnLine, ...unrealOpts, textures: !flags["no-textures"], maxSize: flags["max-size"], flipNormalGreen: !flags["no-normal-flip"] })
+      doc = r.doc; report = r.report
+      log(`   ${r.info}`)
+      for (const s of r.textures?.slots ?? []) {
+        if (!s.material) continue
+        log(`   🎨 ${s.slot.padEnd(16)} ${s.material}${s.roles.length ? `  ${s.roles.join(" + ")}` : "  (no texture wired)"}${s.skipped.length ? `  · not in glTF: ${s.skipped.slice(0, 4).join(", ")}` : ""}`)
+      }
+    } else if (ext === ".bvh") {
+      // BVH (mocap, Kimodo's SOMA export): a skeleton-only rig — nodes, a skin with inverse binds, no
+      // mesh — plus the file's motion as one clip (named by --clip-names, else the file's stem)
+      const { bvhToDocument, describeBvh } = await import("../bvh/toDocument")
+      const r = bvhToDocument(readFileSync(input, "utf8"), { name: clipNames?.[0] ?? basename(input).replace(/\.bvh$/i, "") })
+      doc = r.doc
+      log(`   ${describeBvh(r.report)}`)
+    } else if (ext === ".fbx") {
+      const r = await convertFbx(input, { clips, clipNames, rename, dropModelClips: flags["drop-model-clips"], warn: warnLine, ...unrealOpts, ...unity })
+      doc = r.doc; report = r.report
+      if (r.report.unity) {
+        const { describeUnityReport } = await import("../unity/materials")
+        for (const l of describeUnityReport(r.report.unity)) log(`   ${l}`)
+        if (r.report.unity.applied.length && r.report.unity.resolver) log(`   ℹ textures resolved via ${r.report.unity.resolver}`)
+      }
+    } else {
+      doc = await makeIO().read(input)
+      for (let i = 0; i < clips.length; i++) report.clips.push(...mergeClipScene(doc, await loadClipSource(clips[i], unrealOpts), basename(clips[i]), clipNames?.[i], rename, warnLine))
+    }
+    for (const c of report.clips) log(`   🎞  ${c.name.padEnd(24)} ${c.duration.toFixed(2)}s  ${c.bound}/${c.tracks} tracks  (${c.source})`)
+
+    // --merge-skins: modular pieces (shirt, gloves, boots…) onto this model's skeleton
+    if (flags["merge-skins"].length) {
+      const { mergeSkins } = await import("../mergeSkins")
+      const donors = []
+      for (const f of flags["merge-skins"]) {
+        if (!existsSync(f)) throw notFound(f)
+        const d = extname(f).toLowerCase() === ".fbx" ? (await convertFbx(f, { dropModelClips: true, warn: warnLine, ...unity })).doc : await makeIO().read(f)
+        donors.push({ doc: d, label: basename(f) })
+      }
+      const mr = await mergeSkins(doc, donors, warnLine)
+      for (const d of mr.donors) log(`   🧵 ${d.label.padEnd(24)} ${d.meshes} skinned mesh(es) onto the ${mr.joints}-joint skeleton${d.missingJoints.length ? `  (${d.missingJoints.length} donor joint(s) not in the base${d.lostWeight > 0.01 ? `, ${d.lostWeight.toFixed(1)} weight lost` : ", unweighted"})` : ""}`)
+    }
+
+    // multi-variant prop files: list / keep / split
+    const ground = !flags["no-ground"]
+    if (given.has("list-nodes")) {
+      const { listNodes } = await import("../props")
+      const depth = flags["list-nodes"] || 1
+      log(`   nodes (depth ${depth}) — pick with --keep <name>:`)
+      for (const n of listNodes(doc, depth)) log(`   ${"  ".repeat(n.depth)}${n.name || "(unnamed)"}  ${n.meshes ? `${n.meshes} mesh · ${n.tris} tris · ${n.size.map((v) => v.toFixed(2)).join("×")} m` : n.children ? `${n.children} children` : "empty"}`)
+      return 0
+    }
+    if (flags.keep.length) {
+      const { keepNodes } = await import("../props")
+      const r = await keepNodes(doc, flags.keep, { ground })
+      if (r.missing.length) throw new CliError(`node(s) not in the file: ${r.missing.join(", ")}  (--list-nodes prints them)`)
+      log(`   ✂  kept ${r.kept.join(", ")} · ${r.size.map((v) => v.toFixed(2)).join("×")} m${ground ? ` · re-origined (moved ${r.offset.map((v) => v.toFixed(2)).join(",")})` : ""}`)
+    }
+
+    if (wantsDoctorFix(flags)) {
+      const { analyzeDoc, applyPlan, reportPlan } = await import("../doctor/doctor")
+      const { ensureCodecs } = await import("../doctor/reduceGlbBones")
+      await ensureCodecs()
+      const opts = doctorOptions(flags)
+      const plan = await analyzeDoc(doc, opts)
+      log(reportPlan(plan).text)
+      logDoctorResult(await applyPlan(doc, plan, { ...opts, fixMetallic: flags["fix-metallic"], progress: ktx2Progress }))
+    }
+
+    const stem = join(dirname(input), basename(input, extname(input)))
+    const out = flags.o ?? `${stem}.glb`
+    const { validateGlb, formatReport } = await import("../doctor/validateGlb")
+    if (given.has("split")) {
+      // one GLB per top-level node (the doctor passes above already ran on the whole document)
+      const { splitDoc, fileStem } = await import("../props")
+      const dir = flags.split || (flags.o ? out.replace(/\.glb$/i, "") : stem)
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+      const parts = await splitDoc(doc, { ground })
+      let total = 0
+      for (const part of parts) {
+        const f = join(dir, fileStem(part.name) + ".glb")
+        const glb = await writeGlb(part.doc)
+        writeFileSync(f, glb)
+        total += glb.byteLength
+        log(`   ${validateGlb(glb).ok ? "✅" : "✗"} ${basename(f).padEnd(40)} ${part.size.map((x) => x.toFixed(2)).join("×")} m  ${(glb.byteLength / 1024).toFixed(0)} KB`)
+      }
+      log(`💾 wrote ${parts.length} file(s) → ${dir}  (${megabytes(total)}, ${seconds(t0)})`)
+      return 0
+    }
+    const glb = await writeGlb(doc)
+    const dir = dirname(out)
+    if (dir && !existsSync(dir)) mkdirSync(dir, { recursive: true })
+    writeFileSync(out, glb)
+    const { probeDocument } = await import("../probe")
+    log(formatReport(validateGlb(glb), out))
+    log(probeDocument(doc, out).split("\n").slice(1).join("\n"))
+    log(`💾 wrote ${out}  (${megabytes(glb.byteLength)}, ${seconds(t0)})`)
+    return 0
+  },
+})

package/src/commands/doctor.ts

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { bool, CliError, defineCommand, int, missing, str } from "../cli-kit"
+import { doctorFlags, doctorOptions, impostorFlag, ktx2Progress, log, logDoctorResult, resolveInputs, wantsDoctorFix, wantsKtx2 } from "./shared"
+
+export default defineCommand({
+  name: "doctor",
+  summary: "Analyze / fix a GLB against creator-gl limits (bone cap, textures, KTX2, scale, shading, merge, LOD)",
+  usage: `<in.glb | dir | "*.glb"> …`,
+  description: `
+    Without a fixing flag the file is only REPORTED on (lossless / lossy / blocking findings; exit 1
+    when something blocks). Any flag that changes the file writes <in>.fixed.glb / <in>.ktx2.glb, or -o.`,
+  flags: {
+    o: str("output file (one input) or folder (several)", { value: "out" }),
+    dump: str("write the file's textures out instead (default: <in>-textures/)", { value: "dir", bare: "" }),
+    ...doctorFlags,
+    lod: str("add mesh LOD levels (<name>_LOD1… siblings at these triangle ratios, same skin; >= 2000-tri meshes only) — creator-gl shows one by screen size (docs/lod-plan.md)", { value: "0.5,0.2", group: "LOD" }),
+    "lod-bones": bool("fold fingers / toes / twists onto their parents in the last level's skin"),
+    impostor: str("bake the level-0 geometry into an impostor atlas (albedo + hull normal / AO) and add it as a LOD level, one camera-facing quad (<name>_LOD<k>, k = --impostor-level, never past the first missing level; the levels from k up are replaced). PNG / JPEG base colours only — run it with --ktx2, not after it; the atlases skip --max-size. <A>x<E>[@<px>] = A azimuths × E elevation rows (0°, 90°/E, …; 8x2@256), oct<N>[@<px>] = the N×N hemi-octahedron (steep views too); bare = 12x3; px = a frame's pixels (default 256 for a plant ≥ 8 m, 128 under)", { value: "<A>x<E>[@px]|oct<N>[@px]", bare: "12x3" }),
+    "impostor-level": int("the LOD slot the quad takes (default 2: shown under 0.12 of the viewport height; 1 = under 0.30)"),
+  },
+  examples: [
+    "lecodes assets doctor hero.glb",
+    "lecodes assets doctor hero.glb --fix --ktx2",
+    `lecodes assets doctor "props/**/*.glb" --ktx2 --max-size 1024 -o out/`,
+  ],
+  run: async ({ args, flags, given }) => {
+    const files = resolveInputs(args)
+    if (files.length === 0) throw missing("the GLB file(s)")
+    const { analyzeDoc, applyPlan, reportPlan, dumpTextures, outputFor, findKtxEncoder, KTX_ENCODER_MISSING, kb } = await import("../doctor/doctor")
+    const { ensureCodecs, makeIO } = await import("../doctor/reduceGlbBones")
+    const { validateGlb, formatReport } = await import("../doctor/validateGlb")
+    const useKtx2 = wantsKtx2(flags)
+    const lod = (flags.lod ?? "").split(",").map(Number).filter((n) => n > 0 && n < 1)
+    const impostor = impostorFlag(flags.impostor, flags["impostor-level"])
+    const doFix = wantsDoctorFix(flags) || flags["fix-metallic"] || lod.length > 0 || !!impostor
+    const opts = { ...doctorOptions(flags), lod, lodBones: flags["lod-bones"] }
+    const ktxEncoder = useKtx2 ? findKtxEncoder() : null
+    if (useKtx2) {
+      if (!ktxEncoder) throw new CliError(KTX_ENCODER_MISSING, 2)
+      log(`   using ${ktxEncoder.version}${ktxEncoder.kind === "ktx" ? " (ktx create)" : ""}`)
+    }
+    await ensureCodecs()
+    const io = makeIO()
+    if (files.length > 1) log(`Processing ${files.length} files…`)
+    let exitCode = 0
+    for (const input of files) {
+      if (!existsSync(input)) { console.error(`\n✗ not found: ${input}`); exitCode = 1; continue }
+      const doc = await io.read(input)
+      if (given.has("dump")) { await dumpTextures(doc, flags.dump && files.length === 1 ? flags.dump : input.replace(/\.glb$/i, "-textures")); continue }
+      // before the analysis: the plan then sees the atlases (KTX2 encodes them) and not the levels the quad replaced
+      if (impostor) {
+        const { bakeImpostor, impostorLabel } = await import("../doctor/impostor")
+        try {
+          const imp = await bakeImpostor(doc, { ...impostor, log })
+          if (imp) log(`   impostor: ${imp.node} · ${impostorLabel(imp)} · r ${imp.radius.toFixed(2)} m · ${imp.triangles} triangles in ${imp.ms} ms`)
+          else log(`   impostor: no level-0 triangles in ${input}`)
+        } catch (e) { console.error(`\n✗ ${input}: ${(e as Error).message}`); exitCode = 1; continue }
+      }
+      const plan = await analyzeDoc(doc, opts)
+      const rep = reportPlan(plan)
+      log(`\n🔍 ${input}`)
+      log(rep.text)
+      log(`   ${rep.lossless} lossless · ${rep.lossy} lossy · ${rep.blocking} blocking`)
+      if (rep.blocking > 0) exitCode = 1
+      if (!doFix) { if (rep.lossless + rep.lossy > 0) log(`   run with --fix or --ktx2 to apply`); continue }
+      logDoctorResult(await applyPlan(doc, plan, { ...opts, fixMetallic: flags["fix-metallic"], ktxEncoder: ktxEncoder ?? undefined, progress: ktx2Progress }))
+      const output = outputFor(input, flags.o ?? null, files.length > 1, useKtx2)
+      // glTF's top-level `scene` is optional and glTF-Transform only writes it when set — strict
+      // loaders (OGL: `scenes[undefined]`) then load zero roots and draw nothing. Pin the first scene.
+      const root = doc.getRoot()
+      if (!root.getDefaultScene() && root.listScenes().length > 0) root.setDefaultScene(root.listScenes()[0])
+      await io.write(output, doc)
+      const after = readFileSync(output)
+      log(`💾 wrote ${output}  (${kb(statSync(input).size)} → ${kb(after.byteLength)})`)
+      log(formatReport(validateGlb(after), output))
+    }
+    return exitCode
+  },
+})

package/src/commands/geometry.ts

@@ -0,0 +1,45 @@
+import { existsSync, writeFileSync } from "node:fs"
+import { basename, extname } from "node:path"
+import { defineCommand, int, missing, notFound, num, str, usageError } from "../cli-kit"
+import { log } from "./shared"
+
+export default defineCommand({
+  name: "geometry",
+  summary: "A GLB's triangles as ONE plain vertex buffer for the SDK's `Geometry`",
+  usage: "<model.glb>",
+  description: `
+    \`Geometry.load(asset('x.geometry.json'))\` — debris the particle system draws per particle (shell
+    casings, rubble, coins). Every mesh node's world transform is baked in, primitives merged;
+    materials, skins and clips are dropped. <= 65535 vertices (uint16 indices).`,
+  flags: {
+    node: str("only this node's subtree (--list-nodes prints them)", { value: "<name>" }),
+    origin: str("re-origin: bounds centre at 0 / footprint centre at X/Z = 0, lowest at Y = 0", { value: "center|bottom" }),
+    scale: num("uniform scale after the origin move (cm-modelled → 0.01)", { positive: true }),
+    o: str("output (default: <model>.geometry.json next to the input)", { value: "out.geometry.json" }),
+    "list-nodes": int("print the nodes and exit", { value: "depth", bare: 1 }),
+  },
+  run: async ({ args, flags, given }) => {
+    const input = args[0]
+    if (!input) throw missing("the GLB")
+    if (!existsSync(input)) throw notFound(input)
+    if (extname(input).toLowerCase() !== ".glb") throw usageError("geometry wants a GLB (convert first)")
+    const { makeIO } = await import("../fbx/convert")
+    const doc = await makeIO().read(input)
+    if (given.has("list-nodes")) {
+      const { listNodes } = await import("../props")
+      for (const r of listNodes(doc, flags["list-nodes"] ?? 1)) log(`${"  ".repeat(r.depth)}${r.name}  ${r.meshes} mesh(es) · ${r.tris} tris · ${r.size.map((v) => v.toFixed(3)).join("×")} m`)
+      return 0
+    }
+    const origin = flags.origin
+    if (origin !== undefined && origin !== "center" && origin !== "bottom") throw usageError(`--origin wants center or bottom, got "${origin}"`)
+    const { extractGeometry, formatGeometryFile } = await import("../geometry")
+    const { data, report } = extractGeometry(doc, { node: flags.node, origin, scale: flags.scale })
+    data.source = { file: basename(input), nodes: report.nodes }
+    const out = flags.o ?? input.replace(/\.glb$/i, "") + ".geometry.json"
+    const text = formatGeometryFile(data)
+    writeFileSync(out, text)
+    for (const w of report.warnings) log(`⚠ ${w}`)
+    log(`💾 wrote ${out}  (${(text.length / 1024).toFixed(1)} KB · ${report.vertices} verts / ${report.triangles} tris · ${report.size.map((v) => (v * 1000).toFixed(1)).join("×")} mm · nodes: ${report.nodes.join(", ")})`)
+    return 0
+  },
+})

package/src/commands/index.ts

@@ -0,0 +1,24 @@
+// Every command, in the order the help lists them. A command is one file here (a folder when it has
+// helpers of its own); the flags several share live in shared.ts.
+
+import type { Program } from "../cli-kit"
+import avatar from "./avatar"
+import bvh from "./bvh"
+import convert from "./convert"
+import doctor from "./doctor"
+import geometry from "./geometry"
+import marks from "./marks"
+import mirror from "./mirror"
+import probe from "./probe"
+import retarget from "./retarget"
+import scene from "./scene"
+import sky from "./sky"
+import terrainPack from "./terrainPack"
+import unpack from "./unpack"
+import unreal from "./unreal"
+import unwrap from "./unwrap"
+
+export const program: Program = {
+  title: "lecodes-assets — the LeCodes asset pipeline: FBX / Unreal / Unity → GLB, the GLB doctor, retargeting",
+  commands: [ convert, probe, doctor, unwrap, retarget, avatar, mirror, marks, bvh, geometry, unpack, scene, unreal, sky, terrainPack ],
+}

package/src/commands/marks.ts

@@ -0,0 +1,38 @@
+import { existsSync, writeFileSync } from "node:fs"
+import { bool, defineCommand, int, list, missing, notFound, num, str } from "../cli-kit"
+import { log, seconds } from "./shared"
+
+export default defineCommand({
+  name: "marks",
+  summary: "Measure every clip's FOOT MARKS and write them into the GLB (extras.lecodes.contacts)",
+  usage: "<model.glb>",
+  description: `
+    Touch spans, still windows, lift-offs, the staircase of a stair clip — measured on the model's
+    own skeleton. For packs that are not retargeted; \`retarget\` writes the same block itself.`,
+  flags: {
+    stairs: str(`clips to fit a STAIRCASE to (default: names containing "stair")`, { value: "<regex>|all|none" }),
+    platforms: str(`clips with a PLATFORM: two levels, the floor and the top (default "platform")`, { value: "<regex>|all|none" }),
+    fps: int("sampling rate"),
+    clips: list("only these clips", { value: "a b …" }),
+    "heading-end": num("the baked heading curve must END here", { value: "DEG" }),
+    loop: bool("the --clips are LOOPS (last frame = first): the heading is smoothed periodically"),
+    o: str("output (default: in place)", { value: "out.glb" }),
+  },
+  run: async ({ args, flags }) => {
+    const input = args[0]
+    if (!input) throw missing("the GLB")
+    if (!existsSync(input)) throw notFound(input)
+    const { makeIO, writeGlb } = await import("../fbx/convert")
+    const { writeMarks } = await import("../retarget/writeMarks")
+    const { stairsMatcher, describeMarks } = await import("../retarget/marks")
+    const t0 = performance.now()
+    const doc = await makeIO().read(input)
+    const clips = flags.clips.length ? flags.clips : undefined
+    const rows = writeMarks(doc, { stairs: stairsMatcher(flags.stairs, flags.platforms), fps: flags.fps, clips, headingEnd: flags["heading-end"], loops: flags.loop ? clips : undefined, warn: (w) => log(`   ⚠ ${w}`) })
+    for (const r of rows) log(`   🦶 ${r.clip.padEnd(22)} ${describeMarks(r.marks)}`)
+    const out = flags.o ?? input
+    writeFileSync(out, await writeGlb(doc))
+    log(`💾 wrote ${out}  (${rows.length} clips marked, ${seconds(t0)})`)
+    return 0
+  },
+})

package/src/commands/mirror.ts

@@ -0,0 +1,35 @@
+import { defineCommand, list, missing, str } from "../cli-kit"
+import { log } from "./shared"
+
+export default defineCommand({
+  name: "mirror",
+  summary: "Add MIRRORED copies of clips (left ↔ right)",
+  usage: "<model.glb>",
+  description: `
+    A stop that brakes on the left foot becomes one that brakes on the right. World-space deltas from
+    the bind reflected across the sagittal plane, bones paired by name (Left/Right, L_/R_, .L/.R) and
+    checked against the bind geometry. Needs the skin (the bind pose) in the file.`,
+  flags: {
+    clips: list("only these clips (default: all)", { value: "a b …" }),
+    suffix: str("appended to the mirrored clip's name (_M)", { value: "_M" }),
+    axis: str("the mirror plane's normal (default: measured from the bind)", { value: "x|y|z" }),
+    o: str("output (default: in place)", { value: "out.glb" }),
+  },
+  run: async ({ args, flags }) => {
+    const input = args[0]
+    if (!input) throw missing("the GLB")
+    const { makeIO } = await import("../fbx/convert")
+    const { mirrorClips } = await import("../retarget/mirror")
+    const io = makeIO()
+    const doc = await io.read(input)
+    const suffix = flags.suffix ?? "_M"
+    const rep = mirrorClips(doc, { clips: flags.clips.length ? flags.clips : undefined, rename: (n) => `${n}${suffix}`, axis: flags.axis as "x" | "y" | "z" | undefined, log })
+    log(`== mirror across ${rep.axis.toUpperCase()} = 0: ${rep.pairs.length} bone pairs, ${rep.self.length} on the plane; worst pair mismatch ${(rep.worst.error * 100).toFixed(1)} cm (${rep.worst.bone})`)
+    if (rep.worst.error > 0.05) log(`   ⚠ a pair is off by more than 5 cm — the bind pose is not symmetric, or a bone is paired wrongly`)
+    if (!rep.clips.length) { log(`   ✗ no clip matched`); return 1 }
+    const output = flags.o ?? input
+    await io.write(output, doc)
+    log(`💾 wrote ${output} (+${rep.clips.length} clips)`)
+    return 0
+  },
+})

package/src/commands/probe.ts

@@ -0,0 +1,43 @@
+import { existsSync, writeFileSync } from "node:fs"
+import { extname } from "node:path"
+import { bool, CliError, defineCommand, int, missing, notFound, str, usageError } from "../cli-kit"
+import type { FilmstripView } from "../filmstrip"
+import { log } from "./shared"
+
+export default defineCommand({
+  name: "probe",
+  summary: "What a file holds: skeleton, clips (+ per-clip root motion), meshes, materials, textures, bind sanity, world size",
+  usage: "<file.fbx|.glb|.uasset>",
+  flags: {
+    filmstrip: str(`(GLB) CPU-skinned PNG strip of every clip — the fastest "does it play upright" check, no GPU`, { value: "out.png", bare: "", group: "Filmstrip" }),
+    clip: str("only this clip", { value: "<name>" }),
+    frames: int("frames per strip (6)"),
+    view: str("camera", { value: "side|front|top|threequarter|lowfront" }),
+    bones: bool("draw the skeleton over the mesh"),
+    cell: int("cell size", { value: "px" }),
+  },
+  run: async ({ args, flags, given }) => {
+    const input = args[0]
+    if (!input) throw missing("the file to probe")
+    if (!existsSync(input)) throw notFound(input)
+    const { probeFile } = await import("../probe")
+    log(await probeFile(input))
+    if (!given.has("filmstrip")) return 0
+    if (extname(input).toLowerCase() === ".fbx") throw usageError("--filmstrip wants a GLB (convert first)")
+    const { renderFilmstrip } = await import("../filmstrip")
+    const { makeIO } = await import("../fbx/convert")
+    const doc = await makeIO().read(input)
+    const clips = doc.getRoot().listAnimations().map((a) => a.getName()).filter((n) => !flags.clip || n === flags.clip)
+    if (flags.clip && clips.length === 0) throw new CliError(`no clip "${flags.clip}"`)
+    const stem = flags.filmstrip || input.replace(/\.glb$/i, "")
+    const targets = clips.length ? clips : [ null ]
+    const opts = { frames: flags.frames ?? 6, view: (flags.view ?? "side") as FilmstripView, cell: flags.cell, bones: flags.bones }
+    for (const clip of targets) {
+      const r = renderFilmstrip(doc, { ...opts, clip })
+      const file = targets.length === 1 && /\.png$/i.test(stem) ? stem : `${stem.replace(/\.png$/i, "")}.${(clip ?? "rest").replace(/[^\w.-]+/g, "_")}.png`
+      writeFileSync(file, r.png)
+      log(`🖼  ${file}  ${r.label}`)
+    }
+    return 0
+  },
+})

package/src/commands/retarget/donor.ts

@@ -0,0 +1,63 @@
+// Loading the rigs of a retarget: any of the formats, a skeleton-only clip file bound onto the rig it
+// was animated on, and clip ASSETS (Unity .anim / Unreal AnimSequence) attached to the donor.
+
+import { existsSync, readFileSync } from "node:fs"
+import { basename } from "node:path"
+import { CliError, notFound } from "../../cli-kit"
+import type { Clip, Rig } from "../../retarget/rig"
+import { log, resolveInputs } from "../shared"
+
+export type UnrealLocation = { skeleton?: string, contentRoot?: string }
+
+const unboundNote = (names: string[]): string => `${names.slice(0, 3).join(", ")}${names.length > 3 ? ` +${names.length - 3}` : ""}`
+
+export const loadAnyRig = async (path: string, unreal: UnrealLocation): Promise<Rig> => {
+  const { loadRig, rigFromDocument } = await import("../../retarget/rig")
+  const lower = path.toLowerCase()
+  if (lower.endsWith(".uasset")) return (await import("../../unreal/rig")).rigFromUnreal(path, unreal)
+  if (lower.endsWith(".bvh")) {
+    const { bvhToDocument, describeBvh } = await import("../../bvh/toDocument")
+    const r = bvhToDocument(readFileSync(path, "utf8"), { name: basename(path).replace(/\.bvh$/i, "") })
+    log(`   ${basename(path)}: ${describeBvh(r.report)}`)
+    return rigFromDocument(r.doc, basename(path))
+  }
+  if (lower.endsWith(".fbx")) return loadRig(path)
+  const { makeIO } = await import("../../fbx/convert")
+  return rigFromDocument(await makeIO().read(path), basename(path))
+}
+
+/** A skeleton-only clip file (a mocap pack's FBX: nodes + curves, no mesh) has no skin to classify
+ *  and no bind to measure from: its clips are bound by bone name onto the rig it was animated on. */
+export const bindToDonorRig = async (donor: Rig, donorPath: string, rigPath: string, unreal: UnrealLocation): Promise<Rig> => {
+  if (!existsSync(rigPath)) throw notFound(rigPath)
+  const { rebindClips } = await import("../../retarget/rig")
+  const r = rebindClips(await loadAnyRig(rigPath, unreal), donor)
+  log(`   📎 ${basename(donorPath)}: ${r.bound}/${r.total} bones bound to ${basename(rigPath)} by name${Math.abs(r.scale - 1) > 0.01 ? ` · the clip's skeleton is ×${(1 / r.scale).toFixed(2)} the rig's size (rotations taken, lengths the rig's)` : ""}${r.unbound.length ? ` (no bone: ${unboundNote(r.unbound)})` : ""}`)
+  return r.rig
+}
+
+/** Clip assets that stand in for clips the donor rig file does not carry: Unity `.anim`
+ *  AnimationClips, or Unreal `.uasset` AnimSequences (each on its own skeleton, bound by name). */
+export const attachClipAssets = async (donor: Rig, files: string[], unreal: UnrealLocation): Promise<Rig> => {
+  const animFiles = resolveInputs(files, /\.(anim|uasset)$/i, false)
+  if (!animFiles.length) return donor
+  for (const f of animFiles) if (!existsSync(f)) throw notFound(f)
+  const attached: Clip[] = []
+  const report: { name: string, bound: number, total: number, unbound: string[] }[] = []
+  const unity = animFiles.filter((f) => /\.anim$/i.test(f))
+  if (unity.length) {
+    const { parseUnityAnim, attachUnityClips } = await import("../../retarget/unityAnim")
+    const r = attachUnityClips(donor, unity.map((f) => parseUnityAnim(readFileSync(f, "utf8"), basename(f).replace(/\.anim$/i, ""))))
+    attached.push(...r.clips); report.push(...r.report)
+  }
+  for (const f of animFiles.filter((x) => /\.uasset$/i.test(x))) {
+    const { loadUnreal } = await import("../../unreal/index")
+    const { attachUnrealClips } = await import("../../unreal/rig")
+    const u = loadUnreal(f, unreal)
+    if (!u.anim) throw new CliError(`${basename(f)}: not an AnimSequence (${u.kind}) — --anim wants animation assets`)
+    const r = attachUnrealClips(donor, u.skeleton, [ u.anim ])
+    attached.push(...r.clips); report.push(...r.report)
+  }
+  for (const r of report) log(`   📎 ${r.name.padEnd(20)} ${r.bound}/${r.total} curves bound${r.unbound.length ? `  (no bone: ${unboundNote(r.unbound)})` : ""}`)
+  return { ...donor, clips: [ ...donor.clips, ...attached ] }
+}