lecodes-assets 0.2.0 → 2.4.10

package/src/unreal/toDocument.ts

@@ -0,0 +1,367 @@
+// Unreal skeleton (+ mesh, + clips) → a glTF-Transform Document, in the same conventions the FBX
+// route produces (`src/fbx/toDocument.ts`): metres, Y-up, one Buffer, bones as plain nodes named
+// exactly as Unreal names them (the Animator binds by name, so `_l`/`_r`/`twist`/`ik_*` stay
+// verbatim). The doctor passes, the writer and `probe` then run on it like on any other document.
+//
+// UE's vertex model is wedges (per-corner point + UV) and faces (three wedges + a per-corner
+// normal); glTF wants one vertex array, so normals are accumulated per wedge — one glTF vertex per
+// wedge, exactly what the predecessor Python exporter did.
+
+import { Document, type Node, type Material } from "@gltf-transform/core"
+import { fixQuatContinuity, type ConvertWarning } from "../fbx/toDocument"
+import type { UeSkeleton, UeBone } from "./skeleton"
+import type { UeSkeletalMesh } from "./mesh"
+import { keyTimes, type UeAnimSequence } from "./anim"
+import { ueLocalTransform, ueWorldPoint, ueWorldDir, ueRootTranslation, ueTranslation, ueQuat, ueRootQuat, type Quat, type Vec3 } from "./convert"
+
+export type UnrealDocumentInput = {
+  skeleton: UeSkeleton
+  mesh?: UeSkeletalMesh
+  clips?: UeAnimSequence[]
+}
+
+export type UnrealDocumentOptions = {
+  /** Names for `clips`, positionally (default: the AnimSequence's own asset name). */
+  clipNames?: (string | undefined)[]
+  warn?: (w: ConvertWarning) => void
+}
+
+export type UnrealDocumentResult = {
+  doc: Document
+  /** glTF node per skeleton bone index. */
+  nodes: Node[]
+  clipNames: string[]
+  /** Per clip: how many of its tracks found a bone. */
+  bound: { name: string, bound: number, tracks: number, unbound: string[] }[]
+  /** Set when the winding check flipped the triangles (the Y mirror reverses handedness). */
+  flippedWinding: boolean
+  droppedWeight: number
+}
+
+const MAX_JOINTS_PER_VERTEX = 4
+
+// ---- small matrix helpers (column-major, glTF's layout) -----------------------------------------
+
+type Mat4 = number[]
+const matCompose = (t: Vec3, q: Quat, s: Vec3): Mat4 => {
+  const [ x, y, z, w ] = q, x2 = x + x, y2 = y + y, z2 = z + z
+  const xx = x * x2, xy = x * y2, xz = x * z2, yy = y * y2, yz = y * z2, zz = z * z2, wx = w * x2, wy = w * y2, wz = w * z2
+  return [ (1 - (yy + zz)) * s[0], (xy + wz) * s[0], (xz - wy) * s[0], 0,
+           (xy - wz) * s[1], (1 - (xx + zz)) * s[1], (yz + wx) * s[1], 0,
+           (xz + wy) * s[2], (yz - wx) * s[2], (1 - (xx + yy)) * s[2], 0,
+           t[0], t[1], t[2], 1 ]
+}
+const matMul = (a: Mat4, b: Mat4): Mat4 => {
+  const o = new Array(16).fill(0)
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) o[c * 4 + r] = a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + a[12 + r] * b[c * 4 + 3]
+  return o
+}
+/** Inverse of a rigid matrix with a uniform scale — all a bone's world transform ever is here. */
+const matInvRigid = (m: Mat4): Mat4 => {
+  const s2 = m[0] * m[0] + m[1] * m[1] + m[2] * m[2] || 1
+  const r: Mat4 = [ m[0] / s2, m[4] / s2, m[8] / s2, 0, m[1] / s2, m[5] / s2, m[9] / s2, 0, m[2] / s2, m[6] / s2, m[10] / s2, 0, 0, 0, 0, 1 ]
+  r[12] = -(r[0] * m[12] + r[4] * m[13] + r[8] * m[14])
+  r[13] = -(r[1] * m[12] + r[5] * m[13] + r[9] * m[14])
+  r[14] = -(r[2] * m[12] + r[6] * m[13] + r[10] * m[14])
+  return r
+}
+
+/** Bone world matrices in the glTF frame, from the converted local transforms. */
+export const boneWorldMatrices = (bones: { parent: number, t: number[], q: number[], s: number[] }[]): Mat4[] => {
+  const world: Mat4[] = new Array(bones.length)
+  const visit = (i: number): Mat4 => {
+    const hit = world[i]
+    if (hit) return hit
+    const b = bones[i]
+    const l = ueLocalTransform(b.t, b.q, b.s, b.parent < 0)
+    const local = matCompose(l.t, l.r, l.s)
+    const m = b.parent >= 0 ? matMul(visit(b.parent), local) : local
+    world[i] = m
+    return m
+  }
+  for (let i = 0; i < bones.length; i++) visit(i)
+  return world
+}
+
+/** Inverse-bind matrices for a bone list — the bind pose IS the reference pose in Unreal. */
+export const boneInverseBindMatrices = (bones: { parent: number, t: number[], q: number[], s: number[] }[]): Mat4[] =>
+  boneWorldMatrices(bones).map(matInvRigid)
+
+/** A mesh's own bone list as a skeleton (a mesh carries the bind reference itself, §4.3). */
+export const skeletonFromMesh = (mesh: UeSkeletalMesh): UeSkeleton => ({
+  name: mesh.skeletonName || mesh.name,
+  bones: mesh.bones.map((b): UeBone => ({ name: b.name, parent: b.parent, t: b.t, q: b.q, s: b.s })),
+})
+
+// ---- clip tracks -----------------------------------------------------------------------------
+
+export type UnrealTrack = {
+  /** Index into the skeleton's bones. */
+  node: number
+  path: "translation" | "rotation" | "scale"
+  times: Float32Array
+  values: Float32Array
+}
+
+export type UnrealClipTracks = {
+  tracks: UnrealTrack[]
+  /** Bones the clip names that the skeleton does not have. */
+  unbound: string[]
+  /** How many of the clip's tracks produced at least one channel. */
+  bound: number
+}
+
+/**
+ * A clip's keys in the glTF frame, bound to a skeleton BY BONE NAME. The one place UE keys are
+ * converted — both the document builder and the `--clips` merge go through it, so a uasset clip
+ * lands identically whether it is written straight out or merged onto another model.
+ */
+export const unrealClipTracks = (skeleton: UeSkeleton, clip: UeAnimSequence, warn?: (w: ConvertWarning) => void): UnrealClipTracks => {
+  const index = new Map<string, number>()
+  skeleton.bones.forEach((b, i) => { if (!index.has(b.name)) index.set(b.name, i) })
+  const times = keyTimes(clip)
+  const constantTimes = new Float32Array(clip.playLength > 0 ? [ 0, clip.playLength ] : [ 0 ])
+  const tracks: UnrealTrack[] = []
+  const unbound: string[] = []
+  let bound = 0
+  for (const tr of clip.tracks) {
+    const node = index.get(tr.name)
+    if (node === undefined) { unbound.push(tr.name); continue }
+    const isRoot = skeleton.bones[node].parent < 0
+    let any = false
+    const add = (path: UnrealTrack["path"], comps: number, src: Float32Array): void => {
+      const n = src.length / comps
+      if (n === 0) return
+      const constant = n === 1
+      if (!constant && n !== times.length) {
+        warn?.({ level: "warn", message: `clip '${clip.name}' bone '${tr.name}': ${n} ${path} keys for a ${times.length}-key clip — track dropped` })
+        return
+      }
+      const t = constant ? constantTimes : times
+      const values = new Float32Array(t.length * comps)
+      for (let k = 0; k < n; k++) {
+        const o = k * comps
+        const v = path === "translation" ? (isRoot ? ueRootTranslation(src[o], src[o + 1], src[o + 2]) : ueTranslation(src[o], src[o + 1], src[o + 2]))
+          : path === "rotation" ? (isRoot ? ueRootQuat(src[o], src[o + 1], src[o + 2], src[o + 3]) : ueQuat(src[o], src[o + 1], src[o + 2], src[o + 3]))
+          : [ src[o], src[o + 1], src[o + 2] ]
+        values.set(v, o)
+      }
+      // a constant track is written as two keys so the clip keeps its length on its own
+      if (constant) for (let k = 1; k < t.length; k++) values.copyWithin(k * comps, 0, comps)
+      if (path === "rotation") fixQuatContinuity(values)
+      tracks.push({ node, path, times: t, values })
+      any = true
+    }
+    add("translation", 3, tr.pos)
+    add("rotation", 4, tr.rot)
+    add("scale", 3, tr.scale)
+    if (any) bound++
+  }
+  return { tracks, unbound, bound }
+}
+
+/** Clip extras every route writes, so `probe` can print where a clip came from. */
+export const clipExtras = (clip: UeAnimSequence): Record<string, unknown> => ({
+  lecodes: {
+    source: "unreal", fps: clip.fps, frames: clip.numFrames, keys: clip.numKeys,
+    rootMotion: clip.rootMotion, additive: clip.additive ?? undefined,
+    events: clip.events.length ? clip.events.map((e) => ({ name: e.name, time: e.time, kind: e.kind })) : undefined,
+  },
+})
+
+// ---- the builder ---------------------------------------------------------------------------------
+
+export const unrealToDocument = (input: UnrealDocumentInput, opts: UnrealDocumentOptions = {}): UnrealDocumentResult => {
+  const warn = opts.warn ?? (() => {})
+  const { skeleton, mesh } = input
+  const clips = input.clips ?? []
+  const doc = new Document()
+  const buffer = doc.createBuffer("buffer")
+  const scene = doc.createScene("Scene")
+
+  // ---- bones ----
+  const nodes: Node[] = skeleton.bones.map((b) => {
+    const l = ueLocalTransform(b.t, b.q, b.s, b.parent < 0)
+    return doc.createNode(b.name).setTranslation(l.t).setRotation(l.r).setScale(l.s)
+  })
+  skeleton.bones.forEach((b, i) => {
+    if (b.parent >= 0) nodes[b.parent].addChild(nodes[i])
+    else scene.addChild(nodes[i])
+  })
+  const boneIndex = new Map<string, number>()
+  skeleton.bones.forEach((b, i) => { if (!boneIndex.has(b.name)) boneIndex.set(b.name, i) })
+
+  let flippedWinding = false
+  let droppedWeight = 0
+  let unweighted = 0
+
+  // ---- mesh + skin ----
+  if (mesh) {
+    // joints keep the mesh's OWN bone order, so `influences.boneIndex` maps 1:1
+    const joints: Node[] = []
+    const missing: string[] = []
+    for (const b of mesh.bones) {
+      const i = boneIndex.get(b.name)
+      if (i === undefined) { missing.push(b.name); joints.push(nodes[0]) } else joints.push(nodes[i])
+    }
+    if (missing.length) warn({ level: "warn", message: `mesh '${mesh.name}': ${missing.length} skin bone(s) are not in the skeleton (${missing.slice(0, 4).join(", ")}) — weights on them land on the root` })
+
+    // per-point influences, top 4 by weight
+    const perPoint: UeSkeletalMesh["influences"][] = Array.from({ length: mesh.points.length / 3 }, () => [])
+    for (const inf of mesh.influences) {
+      if (inf.point >= 0 && inf.point < perPoint.length) perPoint[inf.point].push(inf)
+    }
+    const pointJoints = new Uint16Array(perPoint.length * MAX_JOINTS_PER_VERTEX)
+    const pointWeights = new Float32Array(perPoint.length * MAX_JOINTS_PER_VERTEX)
+    for (let p = 0; p < perPoint.length; p++) {
+      const list = perPoint[p].slice().sort((a, b) => b.weight - a.weight)
+      const keep = list.slice(0, MAX_JOINTS_PER_VERTEX)
+      const total = list.reduce((n, i) => n + i.weight, 0)
+      const kept = keep.reduce((n, i) => n + i.weight, 0)
+      if (total > 0) droppedWeight += total - kept
+      // A point with NO influence is bound to the ROOT bone — what UE's importer does with every
+      // unweighted vertex. Left at weight 0 it skins to the origin: the FPS Animation Pack's MX16A4
+      // keeps its whole barrel and handguard unweighted (14 088 of 15 696 points in one section),
+      // and those collapsed triangles took the desktop host down inside the next UI draw.
+      if (kept <= 0) { pointJoints[p * MAX_JOINTS_PER_VERTEX] = 0; pointWeights[p * MAX_JOINTS_PER_VERTEX] = 1; unweighted++; continue }
+      const norm = kept > 0 ? 1 / kept : 0
+      keep.forEach((inf, k) => {
+        pointJoints[p * MAX_JOINTS_PER_VERTEX + k] = inf.bone >= 0 && inf.bone < joints.length ? inf.bone : 0
+        pointWeights[p * MAX_JOINTS_PER_VERTEX + k] = inf.weight * norm
+      })
+    }
+    if (unweighted) warn({ level: "info", message: `mesh '${mesh.name}': ${unweighted} of ${perPoint.length} points carry no skin weight — bound to the root bone '${mesh.bones[0]?.name ?? "?"}', as UE's importer does` })
+
+    // normals: the per-corner TangentZ of every face using a wedge, accumulated
+    const wedgeCount = mesh.wedgePoint.length
+    const normals = new Float32Array(wedgeCount * 3)
+    const faceCount = mesh.faceWedges.length / 3
+    for (let f = 0; f < faceCount; f++) {
+      for (let c = 0; c < 3; c++) {
+        const w = mesh.faceWedges[f * 3 + c]
+        normals[w * 3] += mesh.faceNormals[f * 9 + c * 3]
+        normals[w * 3 + 1] += mesh.faceNormals[f * 9 + c * 3 + 1]
+        normals[w * 3 + 2] += mesh.faceNormals[f * 9 + c * 3 + 2]
+      }
+    }
+
+    // The Y mirror reverses handedness, so UE's winding may or may not survive it. Decide from the
+    // data — for a sample of faces, does the geometric normal agree with the shading normal? —
+    // rather than hiding the answer behind a double-sided material.
+    {
+      let agree = 0, disagree = 0
+      const step = Math.max(1, Math.floor(faceCount / 500))
+      for (let f = 0; f < faceCount; f += step) {
+        const w = [ mesh.faceWedges[f * 3], mesh.faceWedges[f * 3 + 1], mesh.faceWedges[f * 3 + 2] ]
+        const p = w.map((x) => {
+          const pt = mesh.wedgePoint[x] * 3
+          return ueWorldPoint(mesh.points[pt], mesh.points[pt + 1], mesh.points[pt + 2])
+        })
+        const n = ueWorldDir(
+          mesh.faceNormals[f * 9] + mesh.faceNormals[f * 9 + 3] + mesh.faceNormals[f * 9 + 6],
+          mesh.faceNormals[f * 9 + 1] + mesh.faceNormals[f * 9 + 4] + mesh.faceNormals[f * 9 + 7],
+          mesh.faceNormals[f * 9 + 2] + mesh.faceNormals[f * 9 + 5] + mesh.faceNormals[f * 9 + 8],
+        )
+        const e1 = [ p[1][0] - p[0][0], p[1][1] - p[0][1], p[1][2] - p[0][2] ]
+        const e2 = [ p[2][0] - p[0][0], p[2][1] - p[0][1], p[2][2] - p[0][2] ]
+        const cr = [ e1[1] * e2[2] - e1[2] * e2[1], e1[2] * e2[0] - e1[0] * e2[2], e1[0] * e2[1] - e1[1] * e2[0] ]
+        const d = cr[0] * n[0] + cr[1] * n[1] + cr[2] * n[2]
+        if (d > 0) agree++
+        else if (d < 0) disagree++
+      }
+      flippedWinding = disagree > agree
+    }
+
+    // materials, one per import-data slot (textures are a later phase: grey PBR, named by the slot)
+    const materials: Material[] = (mesh.materials.length ? mesh.materials : [ "material" ]).map((name) => {
+      const m = doc.createMaterial(name).setRoughnessFactor(0.75).setMetallicFactor(0).setDoubleSided(false)
+      if (/glass/i.test(name)) m.setAlphaMode("BLEND").setBaseColorFactor([ 1, 1, 1, 0.35 ])
+      return m
+    })
+
+    const gmesh = doc.createMesh(mesh.name)
+    const slots = new Set<number>()
+    for (const s of mesh.faceMaterial) slots.add(s)
+    for (const slot of [ ...slots ].sort((a, b) => a - b)) {
+      // one glTF vertex per wedge this slot uses
+      const remap = new Int32Array(wedgeCount).fill(-1)
+      const used: number[] = []
+      const indices: number[] = []
+      for (let f = 0; f < faceCount; f++) {
+        if (mesh.faceMaterial[f] !== slot) continue
+        const tri = [ mesh.faceWedges[f * 3], mesh.faceWedges[f * 3 + 1], mesh.faceWedges[f * 3 + 2] ]
+        if (flippedWinding) { const t = tri[1]; tri[1] = tri[2]; tri[2] = t }
+        for (const w of tri) {
+          if (remap[w] < 0) { remap[w] = used.length; used.push(w) }
+          indices.push(remap[w])
+        }
+      }
+      if (!used.length) continue
+      const n = used.length
+      const pos = new Float32Array(n * 3), nrm = new Float32Array(n * 3), uv0 = new Float32Array(n * 2)
+      const uv1 = mesh.hasUv1 ? new Float32Array(n * 2) : null
+      const jnt = new Uint16Array(n * 4), wgt = new Float32Array(n * 4)
+      for (let i = 0; i < n; i++) {
+        const w = used[i]
+        const p = mesh.wedgePoint[w] * 3
+        const wp = ueWorldPoint(mesh.points[p], mesh.points[p + 1], mesh.points[p + 2])
+        pos.set(wp, i * 3)
+        const nw = ueWorldDir(normals[w * 3], normals[w * 3 + 1], normals[w * 3 + 2])
+        const len = Math.hypot(nw[0], nw[1], nw[2]) || 1
+        nrm[i * 3] = nw[0] / len; nrm[i * 3 + 1] = nw[1] / len; nrm[i * 3 + 2] = nw[2] / len
+        uv0[i * 2] = mesh.wedgeUv0[w * 2]; uv0[i * 2 + 1] = mesh.wedgeUv0[w * 2 + 1]
+        if (uv1) { uv1[i * 2] = mesh.wedgeUv1[w * 2]; uv1[i * 2 + 1] = mesh.wedgeUv1[w * 2 + 1] }
+        const pj = mesh.wedgePoint[w] * MAX_JOINTS_PER_VERTEX
+        for (let k = 0; k < 4; k++) { jnt[i * 4 + k] = pointJoints[pj + k]; wgt[i * 4 + k] = pointWeights[pj + k] }
+      }
+      const prim = doc.createPrimitive()
+      prim.setAttribute("POSITION", doc.createAccessor().setType("VEC3").setArray(pos).setBuffer(buffer))
+      prim.setAttribute("NORMAL", doc.createAccessor().setType("VEC3").setArray(nrm).setBuffer(buffer))
+      prim.setAttribute("TEXCOORD_0", doc.createAccessor().setType("VEC2").setArray(uv0).setBuffer(buffer))
+      if (uv1) prim.setAttribute("TEXCOORD_1", doc.createAccessor().setType("VEC2").setArray(uv1).setBuffer(buffer))
+      prim.setAttribute("JOINTS_0", doc.createAccessor().setType("VEC4").setArray(jnt).setBuffer(buffer))
+      prim.setAttribute("WEIGHTS_0", doc.createAccessor().setType("VEC4").setArray(wgt).setBuffer(buffer))
+      const idx = n <= 65535 ? Uint16Array.from(indices) : Uint32Array.from(indices)
+      prim.setIndices(doc.createAccessor().setType("SCALAR").setArray(idx).setBuffer(buffer))
+      prim.setMaterial(materials[Math.min(slot, materials.length - 1)])
+      gmesh.addPrimitive(prim)
+    }
+
+    const ibm = new Float32Array(mesh.bones.length * 16)
+    boneInverseBindMatrices(mesh.bones).forEach((m, i) => ibm.set(m, i * 16))
+    const skin = doc.createSkin(mesh.name)
+    for (const j of joints) skin.addJoint(j)
+    skin.setInverseBindMatrices(doc.createAccessor().setType("MAT4").setArray(ibm).setBuffer(buffer))
+    const meshNode = doc.createNode(mesh.name).setMesh(gmesh).setSkin(skin)
+    scene.addChild(meshNode)
+  }
+
+  // ---- clips ----
+  const clipNames: string[] = []
+  const bound: UnrealDocumentResult["bound"] = []
+  clips.forEach((clip, ci) => {
+    let name = opts.clipNames?.[ci] ?? clip.name
+    const taken = new Set(doc.getRoot().listAnimations().map((a) => a.getName()))
+    if (taken.has(name)) { let k = 2; while (taken.has(`${name} (${k})`)) k++; name = `${name} (${k})` }
+    clipNames.push(name)
+    const anim = doc.createAnimation(name)
+    const interpolation = clip.interpolation === "Step" ? "STEP" : "LINEAR"
+    const t = unrealClipTracks(skeleton, clip, warn)
+    for (const tr of t.tracks) {
+      const comps = tr.path === "rotation" ? 4 : 3
+      const sampler = doc.createAnimationSampler()
+        .setInput(doc.createAccessor().setType("SCALAR").setArray(tr.times.slice()).setBuffer(buffer))
+        .setOutput(doc.createAccessor().setType(comps === 4 ? "VEC4" : "VEC3").setArray(tr.values.slice()).setBuffer(buffer))
+        .setInterpolation(interpolation)
+      anim.addSampler(sampler)
+      anim.addChannel(doc.createAnimationChannel().setTargetNode(nodes[tr.node]).setTargetPath(tr.path).setSampler(sampler))
+    }
+    anim.setExtras(clipExtras(clip))
+    if (t.unbound.length) {
+      warn({ level: "warn", message: `clip '${name}': ${t.unbound.length}/${clip.tracks.length} tracks name a bone the skeleton does not have (${t.unbound.slice(0, 5).join(", ")}${t.unbound.length > 5 ? "…" : ""})` })
+    }
+    bound.push({ name, bound: t.bound, tracks: clip.tracks.length, unbound: t.unbound })
+  })
+
+  return { doc, nodes, clipNames, bound, flippedWinding, droppedWeight }
+}

package/src/unreal/versions.ts

@@ -0,0 +1,108 @@
+// Package format versions — the ONE place a layout threshold is named. `package.ts` gates every
+// field on these, never on a bare number, so a new engine release is a new constant here plus the
+// fields it added, not a hunt through the reader.
+//
+// A package carries three versions: the legacy file version (the shape of the summary's head),
+// `FileVersionUE4` (frozen at 522 for every UE5 file) and `FileVersionUE5` (what actually moves
+// between releases). Values below are `EUnrealEngineObjectUE5Version` / `EUnrealEngineObjectUE4Version`
+// from ObjectVersion.h, verified on real files of each release (Stairs Set 5.0, soldier 5.3,
+// Roll & Dodge 5.4, AGLS 5.5 / 5.6 / 5.7).
+
+/** `FileVersionUE5` — the version that changes between UE5 releases. */
+export const UE5 = {
+  INITIAL_VERSION: 1000,
+  /** The name table is split: names [0, count) are referenced from export data. */
+  NAMES_REFERENCED_FROM_EXPORT_DATA: 1001,
+  /** Payload table of contents (virtualised bulk) offset in the summary. */
+  PAYLOAD_TOC: 1002,
+  /** `bImportOptional` per import, `bGeneratePublicHash` per export. */
+  OPTIONAL_RESOURCES: 1003,
+  /** Large world coordinates: core types serialise doubles (`FTransform` = 80 bytes). UE 5.0. */
+  LARGE_WORLD_COORDINATES: 1004,
+  /** Package guid dropped from `FObjectExport`. */
+  REMOVE_OBJECT_EXPORT_PACKAGE_GUID: 1005,
+  /** `bIsInheritedInstance` per export. */
+  TRACK_OBJECT_EXPORT_IS_INHERITED: 1006,
+  FSOFTOBJECTPATH_REMOVE_ASSET_PATH_FNAMES: 1007,
+  /** Soft object path list count/offset in the summary. */
+  ADD_SOFTOBJECTPATH_LIST: 1008,
+  /** Bulk/data resource table offset in the summary. UE 5.3. */
+  DATA_RESOURCES: 1009,
+  /** Script (tagged property) start/end offsets per export — where an object's tag list sits. */
+  SCRIPT_SERIALIZATION_OFFSET: 1010,
+  /**
+   * Every object's tag list opens with a class-serialization-control byte, and every tag (old or
+   * new layout) may carry an extension byte. UE 5.4.
+   */
+  PROPERTY_TAG_EXTENSION_AND_OVERRIDABLE_SERIALIZATION: 1011,
+  /**
+   * The tag's type is a TREE of names (`ArrayProperty(StructProperty(Vector3f(/Script/CoreUObject)))`)
+   * instead of a type name plus per-type extras, and array index / guid / bool live in a flags byte.
+   */
+  PROPERTY_TAG_COMPLETE_TYPE_NAME: 1012,
+  ASSETREGISTRY_PACKAGEBUILDDEPENDENCIES: 1013,
+  /** Metadata offset in the summary. UE 5.5. */
+  METADATA_SERIALIZATION_OFFSET: 1014,
+  /** Verse cell import/export tables in the summary. */
+  VERSE_CELLS: 1015,
+  /** The summary's guid becomes a 20-byte saved hash, written up front with the header size. */
+  PACKAGE_SAVED_HASH: 1016,
+  /** UE 5.6. */
+  OS_SUB_OBJECT_SHADOW_SERIALIZATION: 1017,
+  /** Import type hierarchy table in the summary. UE 5.7. */
+  IMPORT_TYPE_HIERARCHIES: 1018,
+} as const
+
+/** `FileVersionUE4` thresholds the layouts still key on (all satisfied by 522). */
+export const UE4 = {
+  ENGINE_VERSION_OBJECT: 336,
+  ADD_STRING_ASSET_REFERENCES_MAP: 384,
+  PACKAGE_SUMMARY_HAS_COMPATIBLE_ENGINE_VERSION: 444,
+  SERIALIZE_TEXT_IN_PACKAGES: 459,
+  COOKED_ASSETS_IN_EDITOR_SUPPORT: 485,
+  /** A struct array's payload opens with an inner tag naming the struct. */
+  INNER_ARRAY_TAG_INFO: 500,
+  /** A property tag may carry a property guid (a has-guid byte after the extras). */
+  PROPERTY_GUID_IN_PROPERTY_TAG: 503,
+  NAME_HASHES_SERIALIZED: 504,
+  PRELOAD_DEPENDENCIES_IN_COOKED_EXPORTS: 507,
+  TEMPLATE_INDEX_IN_COOKED_EXPORTS: 508,
+  ADDED_SEARCHABLE_NAMES: 510,
+  BIG_EXPORT_SIZE_FIXES: 511,
+  ADDED_PACKAGE_SUMMARY_LOCALIZATION_ID: 516,
+  ADDED_PACKAGE_OWNER: 518,
+  NON_OUTER_PACKAGE_IMPORT: 520,
+  /** What every UE5 package carries — frozen since 4.27. */
+  FROZEN: 522,
+} as const
+
+/** Legacy file version: the shape of the summary's first fields. */
+export const LEGACY = {
+  /** UE4 packages — float transforms, older export layout; not read here. */
+  UE4: -7,
+  /** UE 5.0 – 5.5: `FileVersionUE5` follows `FileVersionUE4`. */
+  UE5: -8,
+  /** UE 5.6+: same head (the UE3 field is still written); the differences are versioned below. */
+  UE5_6: -9,
+} as const
+
+/** The oldest `FileVersionUE4` a UE4 package may carry when a reader opts in (`{ ue4: true }`):
+ *  `ADDED_PACKAGE_OWNER`, UE 4.25 — the "Bullet Impact VFX" pack, whose "UE_5.0" download is 4.25
+ *  packages throughout. */
+export const UE4_VERSION_MIN = 459
+
+/** The newest `FileVersionUE5` this reader has verified against real files. */
+export const UE5_VERSION_MAX = UE5.IMPORT_TYPE_HIERARCHIES
+/** The oldest — UE 5.0. Earlier UE5 previews are refused. */
+export const UE5_VERSION_MIN = UE5.LARGE_WORLD_COORDINATES
+
+/** The engine release a `FileVersionUE5` belongs to, for messages ("UE 5.4" for 1011–1013). */
+export const releaseOfVersion = (ue5: number): string => {
+  if (ue5 >= UE5.IMPORT_TYPE_HIERARCHIES) return "5.7"
+  if (ue5 >= UE5.OS_SUB_OBJECT_SHADOW_SERIALIZATION) return "5.6"
+  if (ue5 >= UE5.METADATA_SERIALIZATION_OFFSET) return "5.5"
+  if (ue5 >= UE5.PROPERTY_TAG_EXTENSION_AND_OVERRIDABLE_SERIALIZATION) return "5.4"
+  if (ue5 >= UE5.DATA_RESOURCES) return "5.3"
+  if (ue5 >= UE5.FSOFTOBJECTPATH_REMOVE_ASSET_PATH_FNAMES) return "5.1"
+  return "5.0"
+}

package/src/unwrap/index.ts

@@ -0,0 +1,167 @@
+// The lightmap unwrap of whole GLB files — `lecodes assets unwrap` (commands/unwrap.ts) and `lecodes lightmap bake`'s
+// pre-step (the CLI reaches it through `unwrapGlbFiles` in src/cli.ts). The geometry work is ./lightmapUv.ts.
+//
+// IN PLACE, not `<name>.fixed.glb` like the doctor's passes: scenes reference the original file, so a fixed copy next
+// to it was one the owner copied over the original by hand (and the copies stayed). A file whose every primitive the
+// unwrap would lay out already carries TEXCOORD_1 is left alone (`force` re-unwraps it). The write is atomic: a temp
+// file beside the target, renamed over it — a failed or killed run leaves the original as it was.
+
+import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+import type { Document, Material, TextureInfo } from "@gltf-transform/core"
+import { ensureCodecs, makeIO } from "../doctor/reduceGlbBones"
+import { applyUnwrap, planNeedsUnwrap, planUnwrap, type UnwrapOptions, type UnwrapPlan, type UnwrapResult } from "./lightmapUv"
+
+export { applyUnwrap, planNeedsUnwrap, planUnwrap, DEFAULT_UNWRAP_TEXEL, UNWRAP_PADDING } from "./lightmapUv"
+export type { UnwrapGroup, UnwrapOptions, UnwrapPlan, UnwrapResult } from "./lightmapUv"
+
+export interface UnwrapFileOptions extends UnwrapOptions {
+  /** unwrap again even when every primitive already carries TEXCOORD_1 */
+  force?: boolean
+  /** write here instead of over the input */
+  output?: string
+}
+
+export interface UnwrapFileReport {
+  input: string
+  /** where the unwrapped file went; null when nothing was written */
+  output: string | null
+  status: "unwrapped" | "skipped" | "failed"
+  /** why it was skipped or failed */
+  reason?: string
+  /** one line: what the unwrap made of the file (describeUnwrap) */
+  summary: string
+  result?: UnwrapResult
+  /** primitives the unwrap leaves as they are (skinned, not a triangle list, …) */
+  kept: { name: string, reason: string }[]
+  /** TEXCOORD_1 sets the unwrap replaced (`force`, or a file that had them on some primitives only) */
+  replaced: number
+  warnings: string[]
+  ms: number
+  bytesBefore: number
+  bytesAfter: number
+}
+
+const message = (e: unknown): string => (e instanceof Error ? e.message : String(e))
+
+/** Materials of the planned primitives with a texture on TEXCOORD_1 (an AO map on the second set): they would sample the
+ *  lightmap layout once the set is replaced. */
+const uv1Samplers = (plan: UnwrapPlan): string[] => {
+  const names = new Set<string>()
+  const infos = (m: Material): (TextureInfo | null)[] => [
+    m.getBaseColorTextureInfo(), m.getNormalTextureInfo(), m.getOcclusionTextureInfo(), m.getEmissiveTextureInfo(), m.getMetallicRoughnessTextureInfo(),
+  ]
+  for (const p of [ ...plan.prims, ...plan.lods ]) {
+    const m = p.prim.getMaterial()
+    if (m && infos(m).some((i) => i?.getTexCoord() === 1)) names.add(m.getName() || "material")
+  }
+  return [ ...names ]
+}
+
+/** Write `bytes` to `target` through a temp file beside it, renamed over it. */
+const writeAtomic = (target: string, bytes: Uint8Array): void => {
+  const dir = dirname(target)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  const tmp = join(dir, `.${basename(target)}.unwrap-${process.pid}.tmp`)
+  try {
+    writeFileSync(tmp, bytes)
+    renameSync(tmp, target)
+  } catch (e) {
+    try { unlinkSync(tmp) } catch { /* never written */ }
+    throw e
+  }
+}
+
+/** Unwrap one document in memory (no file): the plan's verdict, and the result when it did. */
+export async function unwrapDocument(doc: Document, opts: UnwrapFileOptions = {}): Promise<Omit<UnwrapFileReport, "input" | "output" | "summary" | "ms" | "bytesBefore" | "bytesAfter">> {
+  const plan = planUnwrap(doc, opts)
+  const kept = plan.skipped
+  if (plan.prims.length === 0) return { status: "skipped", reason: kept.length ? "nothing to unwrap" : "no meshes", kept, replaced: 0, warnings: [] }
+  if (!opts.force && !planNeedsUnwrap(plan)) {
+    return { status: "skipped", reason: `has TEXCOORD_1 on its ${plan.prims.length + plan.lods.length} primitive(s)`, kept, replaced: 0, warnings: [] }
+  }
+  const replaced = plan.prims.filter((p) => p.hasUv1).length + plan.lods.filter((l) => l.hasUv1).length
+  const warnings: string[] = []
+  const samplers = replaced ? uv1Samplers(plan) : []
+  if (samplers.length) warnings.push(`${samplers.join(", ")} sample${samplers.length === 1 ? "s" : ""} a texture on TEXCOORD_1 — it now reads the lightmap layout`)
+  const result = await applyUnwrap(doc, plan)
+  // glTF's top-level `scene` is optional and glTF-Transform only writes it when set; strict loaders then load no roots.
+  const root = doc.getRoot()
+  if (!root.getDefaultScene() && root.listScenes().length > 0) root.setDefaultScene(root.listScenes()[0])
+  return { status: "unwrapped", result, kept, replaced, warnings }
+}
+
+/** Unwrap one GLB file: in place unless `output` names another file. Never throws for the file's sake — a failure is the
+ *  report's status. */
+export async function unwrapGlbFile(input: string, opts: UnwrapFileOptions = {}): Promise<UnwrapFileReport> {
+  const t0 = performance.now()
+  const rep: UnwrapFileReport = { input, output: null, status: "failed", summary: "", kept: [], replaced: 0, warnings: [], ms: 0, bytesBefore: 0, bytesAfter: 0 }
+  const done = (): UnwrapFileReport => { rep.ms = performance.now() - t0; rep.summary = describeUnwrap(rep); return rep }
+  if (!existsSync(input)) { rep.reason = "not found"; return done() }
+  rep.bytesBefore = statSync(input).size
+  await ensureCodecs()
+  const io = makeIO()
+  let doc: Document
+  try { doc = await io.read(input) } catch (e) { rep.reason = `unreadable: ${message(e)}`; return done() }
+  try {
+    Object.assign(rep, await unwrapDocument(doc, opts))
+  } catch (e) {
+    rep.status = "failed"
+    rep.reason = message(e)
+    return done()
+  }
+  if (rep.status !== "unwrapped") return done()
+  const output = opts.output ?? input
+  try {
+    const bytes = await io.writeBinary(doc)
+    writeAtomic(output, bytes)
+    rep.output = output
+    rep.bytesAfter = bytes.byteLength
+  } catch (e) {
+    rep.status = "failed"
+    rep.reason = `not written: ${message(e)}`
+  }
+  return done()
+}
+
+/** Where `-o` sends an input: none = in place; one input and a path that is not a folder = that file; else the folder. */
+export const unwrapOutputFor = (input: string, out: string | undefined, batch: boolean): string | undefined => {
+  if (!out) return undefined
+  const norm = out.replace(/\\/g, "/")
+  const asDir = batch || norm.endsWith("/") || (existsSync(norm) && statSync(norm).isDirectory())
+  return asDir ? join(norm, basename(input)).replace(/\\/g, "/") : out
+}
+
+/** Unwrap several GLB files one after the other (xatlas is single-threaded wasm; memory stays one file's). `out` as `-o`;
+ *  `onFile` hears each report as it lands. */
+export async function unwrapGlbFiles(files: string[], opts: UnwrapFileOptions & { out?: string, onFile?: (r: UnwrapFileReport) => void } = {}): Promise<UnwrapFileReport[]> {
+  const { out, onFile, ...rest } = opts
+  const reports: UnwrapFileReport[] = []
+  for (const input of files) {
+    const r = await unwrapGlbFile(input, { ...rest, output: unwrapOutputFor(input, out, files.length > 1) ?? rest.output })
+    reports.push(r)
+    onFile?.(r)
+  }
+  return reports
+}
+
+const kb = (n: number): string => `${Math.round(n / 1024)} KB`
+
+/** One line per file: what the unwrap made of it. */
+export const describeUnwrap = (r: UnwrapFileReport): string => {
+  if (r.status !== "unwrapped" || !r.result) return `${r.status === "failed" ? "failed" : "skipped"}: ${r.reason ?? "?"}`
+  const res = r.result
+  const lod = res.lodPrimitives ? `; ${res.lodPrimitives} LOD primitive(s) by projection` : ""
+  const groups = res.groups.length ? `, ${res.groups.length} groups${res.splitNodes ? ` (${res.splitNodes} node(s) cut)` : ""}` : ""
+  return `${res.charts} charts over ${res.primitives} primitive(s)${groups}, vertices ${res.verticesBefore} → ${res.verticesAfter} (+${res.verticesAfter - res.verticesBefore} on seams)${lod}${r.replaced ? `; ${r.replaced} TEXCOORD_1 set(s) replaced` : ""}, ${(r.ms / 1000).toFixed(1)} s`
+}
+
+/** The detail lines under a file's line: groups, what was left as it was, warnings, where it went. */
+export const detailUnwrap = (r: UnwrapFileReport): string[] => {
+  const lines: string[] = []
+  r.result?.groups.forEach((g, k) => lines.push(`group ${k}: ${g.primitives} primitive(s), ${g.area.toFixed(0)} m², ${g.charts} charts${g.texelScale > 1 ? `, texel ×${g.texelScale}` : ""}`))
+  if (r.kept.length) lines.push(`left as is: ${r.kept.slice(0, 6).map((s) => `${s.name} (${s.reason})`).join(", ")}${r.kept.length > 6 ? ` … ${r.kept.length - 6} more` : ""}`)
+  for (const w of r.warnings) lines.push(`⚠ ${w}`)
+  if (r.output) lines.push(`${r.output === r.input ? "written in place" : `written to ${r.output}`} (${kb(r.bytesBefore)} → ${kb(r.bytesAfter)})`)
+  return lines
+}