lecodes-assets 0.2.0 → 2.4.10

package/src/cli-kit/run.ts

@@ -0,0 +1,52 @@
+import { CliError, usageError, type Command, type Flags } from "./command"
+import { PROGRAM, renderCommand, renderRoot } from "./help"
+import { nearestFlag, parseArgs } from "./parse"
+
+// The tree walk: `unreal tex x.uasset -o y.png` → the `tex` command under `unreal`, its flags read
+// against its own declaration. stdout = the result, stderr = diagnostics (errors, warnings).
+
+export type Program = { title: string, commands: Command<any>[] }
+
+const isHelp = (a: string | undefined): boolean => a === "--help" || a === "-h" || a === "help"
+
+export const runProgram = async (program: Program, argv: string[]): Promise<number> => {
+  const [ first ] = argv
+  if (first === undefined || isHelp(first)) { console.log(renderRoot(program.title, program.commands)); return 0 }
+  const top = program.commands.find((c) => c.name === first)
+  if (!top) {
+    console.error(`✗ unknown command "${first}"\n`)
+    console.log(renderRoot(program.title, program.commands))
+    return 2
+  }
+  let cmd: Command<any> = top
+  const path = [ first ]
+  let rest = argv.slice(1)
+  // descend while the next word names a subcommand
+  for (;;) {
+    const sub: Command<any> | undefined = cmd.commands?.find((c: Command<any>) => c.name === rest[0])
+    if (!sub) break
+    cmd = sub
+    path.push(rest[0])
+    rest = rest.slice(1)
+  }
+  if (rest.some((a) => a === "--help" || a === "-h")) { console.log(renderCommand(cmd, path)); return 0 }
+  if (!cmd.run) { console.log(renderCommand(cmd, path)); return rest.length ? 2 : 0 }
+  try {
+    const spec = (cmd.flags ?? {}) as Flags
+    const parsed = parseArgs(spec, rest)
+    // an unknown flag is an error, not a warning: whether it takes a value cannot be known, so the word
+    // after it would be read as a positional (a second input file)
+    if (parsed.unknown.length) {
+      const notes = parsed.unknown.map((u) => { const near = nearestFlag(spec, u); return near ? `${u} (did you mean ${near}?)` : u })
+      throw usageError(`unknown flag${notes.length > 1 ? "s" : ""}: ${notes.join(", ")} — ${PROGRAM} ${path.join(" ")} --help lists them`)
+    }
+    return await cmd.run({ args: parsed.args, flags: parsed.flags, given: parsed.given, argv: rest, path })
+  } catch (e) {
+    const err = e as Error
+    console.error(`✗ ${err?.message ?? e}`)
+    if (!(e instanceof CliError)) { if (process.env.LECODES_DEBUG && err?.stack) console.error(err.stack); return 1 }
+    // a wrong command line gets the command's own page, not the whole manual
+    if (e.showHelp) console.log(`\n${renderCommand(cmd, path)}`)
+    return e.code
+  }
+}

package/src/cli.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// lecodes-assets — the LeCodes asset pipeline CLI (also reachable as `lecodes assets …`).
+//
+// A command is DATA (`src/commands/<name>.ts`, listed in `src/commands/index.ts`): its flags are
+// declared once, the argv is parsed against that declaration and every help page is rendered from
+// it (`src/cli-kit`). `lecodes assets` for the command list, `lecodes assets <command> --help` for one.
+
+import { runProgram } from "./cli-kit"
+import { program } from "./commands"
+
+/** Run one command line (the command first). Resolves to the exit code. */
+export const runAssetsCli = (argv: string[]): Promise<number> => runProgram(program, argv)
+
+/** The lightmap unwrap of whole GLB files, in place (src/unwrap) — what `lecodes lightmap bake` runs on the GLBs the app
+ *  references that have no TEXCOORD_1. Loaded on the first call, so the command line stays light. */
+export const unwrapGlbFiles = async (...args: Parameters<typeof import("./unwrap").unwrapGlbFiles>): ReturnType<typeof import("./unwrap").unwrapGlbFiles> =>
+  (await import("./unwrap")).unwrapGlbFiles(...args)
+export type { UnwrapFileOptions, UnwrapFileReport } from "./unwrap"
+
+// Direct invocation (`bun src/cli.ts …` / the package bin) — `lecodes assets` imports runAssetsCli instead.
+const isMain = typeof process !== "undefined" && process.argv[1] !== undefined && /cli.(ts|js)$/.test(process.argv[1]) && !process.env.LECODES_ASSETS_NO_MAIN
+if (isMain) {
+  runAssetsCli(process.argv.slice(2)).then((code) => process.exit(code), (e) => { console.error(`✗ ${e?.message ?? e}`); process.exit(1) })
+}

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,67 @@
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { bool, CliError, defineCommand, missing, str } from "../cli-kit"
+import { doctorFlags, doctorOptions, 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"),
+  },
+  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 doFix = wantsDoctorFix(flags) || flags["fix-metallic"] || lod.length > 0
+    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 }
+      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
+  },
+})