lecodes-assets 0.2.0 → 2.4.10

package/src/unreal/anim.ts

@@ -0,0 +1,284 @@
+// AnimSequence → tracks. The raw, uncompressed bone curves an editor asset keeps in its
+// `AnimDataModel` (§4.2): one track per animated bone, keyed by bone NAME, local space, UE frame,
+// centimetres. `NumberOfKeys` = `NumberOfFrames` + 1 — key i sits at i / fps and the last key at
+// `PlayLength`; a track with a single key is constant for the whole clip.
+//
+// Two data models exist in the wild and both are read here. `AnimDataModel` (the FBX-import
+// default) keeps bone tracks; `AnimationSequencerDataModel` (UE 5.2+, a clip authored or edited in
+// Sequencer) keeps the same motion as MovieScene ControlRig channels — `sequencer.ts` evaluates
+// those onto the same grid, so callers never learn which one a file used.
+
+import {
+  classOf, readProperties, readObjectProperties, readArrayHeader, readFloatArray,
+  propFloat, propInt, propName, propObject, propEnum, resolveObject, findExport,
+  type PropertyTag, type UePackage, type BinaryReader,
+} from "./package"
+import { readSequencerSection, rotatorToQuat, sampleChannel } from "./sequencer"
+
+export type UeTrack = {
+  /** Bone name — the only binding key; `boneIndex` is the skeleton's own index, a cross-check. */
+  name: string
+  boneIndex: number
+  /** n × 3 (cm), n × 4 (x,y,z,w), n × 3 — each either `keys` long or 1 (constant), or empty. */
+  pos: Float32Array
+  rot: Float32Array
+  scale: Float32Array
+}
+
+export type UeClipEvent = { name: string, time: number, kind: "marker" | "notify" }
+
+export type UeAnimSequence = {
+  name: string
+  fps: number
+  numFrames: number
+  numKeys: number
+  playLength: number
+  tracks: UeTrack[]
+  /** `/Game/…/SK_Mannequin` — the skeleton asset this clip was authored on (§6.3 resolves it). */
+  skeletonPath: string
+  skeletonName: string
+  rootMotion: boolean
+  /** `AAT_None` → null; anything else means the poses are DELTAS against a base pose. */
+  additive: string | null
+  interpolation: "Linear" | "Step"
+  rateScale: number
+  events: UeClipEvent[]
+}
+
+/** What an AnimSequence says about itself, tracks aside (`readAnimMeta`). */
+export type UeAnimMeta = {
+  name: string
+  export: NonNullable<ReturnType<typeof findExport>>
+  props: ReturnType<typeof readProperties>
+  /** Positioned reader over the export — the caller may dig further into `props`. */
+  reader: BinaryReader
+  skeletonPath: string
+  skeletonName: string
+  rootMotion: boolean
+  additive: string | null
+  interpolation: "Linear" | "Step"
+  rateScale: number
+  events: UeClipEvent[]
+  sequenceLength: number
+  targetFps: number | undefined
+  dataModel: DataModelKind
+}
+
+const timeOfKey = (i: number, fps: number, numKeys: number, playLength: number): number =>
+  (numKeys <= 1 ? 0 : Math.min(i / fps, playLength))
+
+/** Key times of a clip: i / fps, the last one clamped to PlayLength. */
+export const keyTimes = (a: UeAnimSequence): Float32Array => {
+  const out = new Float32Array(a.numKeys)
+  for (let i = 0; i < a.numKeys; i++) out[i] = timeOfKey(i, a.fps, a.numKeys, a.playLength)
+  return out
+}
+
+/** `FrameRate` is a TAGGED struct — Denominator is omitted when it is 1. */
+const readFrameRate = (r: BinaryReader, pkg: UePackage, tag: PropertyTag | undefined): number | undefined => {
+  if (!tag) return undefined
+  r.offset = tag.data
+  const p = readProperties(r, pkg)
+  const num = propInt(r, p.byName.get("Numerator"))
+  const den = propInt(r, p.byName.get("Denominator")) ?? 1
+  return num && den ? num / den : undefined
+}
+
+/** Array of TAGGED structs: `{ name, time }` pairs out of AnimSyncMarker / AnimNotifyEvent. */
+const readEvents = (r: BinaryReader, pkg: UePackage, tag: PropertyTag | undefined, kind: "marker" | "notify"): UeClipEvent[] => {
+  if (!tag) return []
+  const { names } = pkg
+  const out: UeClipEvent[] = []
+  const { count } = readArrayHeader(r, pkg, tag)
+  for (let i = 0; i < count; i++) {
+    const p = readProperties(r, pkg)
+    const after = r.offset
+    const name = propName(r, names, p.byName.get("MarkerName")) ?? propName(r, names, p.byName.get("NotifyName")) ?? `${kind}${i}`
+    // AnimSyncMarker keeps `Time`; an AnimNotifyEvent's time is its linked value (older assets:
+    // DisplayTime). Whichever is present wins; the events are informational either way.
+    const time = propFloat(r, p.byName.get("Time")) ?? propFloat(r, p.byName.get("LinkValue")) ?? propFloat(r, p.byName.get("DisplayTime_DEPRECATED")) ?? 0
+    if (name !== "None") out.push({ name, time, kind })
+    r.offset = after
+  }
+  return out
+}
+
+/** One `RawAnimSequenceTrack` (tagged since UE5): PosKeys / RotKeys / ScaleKeys. */
+const readTrackData = (r: BinaryReader, pkg: UePackage, tag: PropertyTag): { pos: Float32Array, rot: Float32Array, scale: Float32Array } => {
+  r.offset = tag.data
+  const p = readProperties(r, pkg)
+  const grab = (key: string, comps: number): Float32Array => {
+    const t = p.byName.get(key)
+    if (!t) return new Float32Array(0)
+    const a = readFloatArray(r, pkg, t)
+    if (a.comps !== comps) throw new Error(`${r.label}: ${key} holds ${a.comps}-component keys, expected ${comps}`)
+    return a.values
+  }
+  return { pos: grab("PosKeys", 3), rot: grab("RotKeys", 4), scale: grab("ScaleKeys", 3) }
+}
+
+/**
+ * A track whose keys are all the same value, collapsed to the one key UE would normally have
+ * stored for it. Some packs write a static pose as N identical keys with a key count that does
+ * not match the model's (the Archer pack's aim-offset cells: 2 identical keys, `NumberOfKeys 3`),
+ * and a constant track is a constant track whatever the count says. Anything that actually varies
+ * is left alone, so a real count mismatch still reaches the check below.
+ */
+const collapseConstant = (a: Float32Array, comps: number): Float32Array => {
+  const n = a.length / comps
+  if (n < 2) return a
+  for (let k = comps; k < a.length; k++) if (Math.abs(a[k] - a[k % comps]) > 1e-6) return a
+  return a.slice(0, comps)
+}
+
+export type DataModelKind = "AnimDataModel" | "AnimationSequencerDataModel" | "none"
+
+/** Which data model an AnimSequence uses — what decides whether it can be read at all. */
+export const dataModelKind = (pkg: UePackage): DataModelKind => {
+  for (const e of pkg.exports) {
+    const c = classOf(pkg, e)
+    if (c === "AnimDataModel" || c === "AnimationSequencerDataModel") return c
+  }
+  return "none"
+}
+
+/**
+ * A Sequencer-authored clip: the motion sits in a MovieScene ControlRig section instead of bone
+ * tracks (`sequencer.ts`). The channels are evaluated on the clip's own frame grid, which produces
+ * exactly what `AnimDataModel` hands over — same bones, same key times, same units — so nothing
+ * downstream can tell the two apart.
+ */
+const sequencerAnimSequence = (pkg: UePackage, meta: UeAnimMeta): UeAnimSequence => {
+  let section: ReturnType<typeof readSequencerSection>
+  try { section = readSequencerSection(pkg) } catch (e) {
+    throw new Error(`${pkg.label}: ${(e as Error).message}. ${SEQUENCER_MODEL_MESSAGE}`)
+  }
+  const fps = section.displayRate || meta.targetFps || 30
+  const playLength = meta.sequenceLength
+  const numFrames = Math.max(0, Math.round(playLength * fps))
+  const numKeys = numFrames + 1
+  const tracks: UeTrack[] = []
+  for (const c of section.controls) {
+    const animated = [ ...c.translation, ...c.rotation, ...c.scale ].some((ch) => ch && ch.times.length > 0)
+    const keys = animated ? numKeys : 1
+    const pos = new Float32Array(keys * 3), rot = new Float32Array(keys * 4), scale = new Float32Array(keys * 3)
+    for (let k = 0; k < keys; k++) {
+      const time = k / fps
+      for (let axis = 0; axis < 3; axis++) {
+        const t = c.translation[axis], s = c.scale[axis]
+        pos[k * 3 + axis] = t ? sampleChannel(t, time, 0) : 0
+        scale[k * 3 + axis] = s ? sampleChannel(s, time, 1) : 1
+      }
+      // rotation channels are an FRotator in degrees: [0] roll (X), [1] pitch (Y), [2] yaw (Z)
+      const e = [ 0, 1, 2 ].map((axis) => (c.rotation[axis] ? sampleChannel(c.rotation[axis]!, time, 0) : 0))
+      const q = rotatorToQuat(e[0], e[1], e[2])
+      rot.set(q, k * 4)
+    }
+    tracks.push({ name: c.bone, boneIndex: -1, pos, rot, scale })
+  }
+  return {
+    name: meta.name, fps, numFrames, numKeys, playLength,
+    tracks,
+    skeletonPath: meta.skeletonPath, skeletonName: meta.skeletonName,
+    rootMotion: meta.rootMotion, additive: meta.additive, interpolation: meta.interpolation,
+    rateScale: meta.rateScale, events: meta.events,
+  }
+}
+
+export const SEQUENCER_MODEL_MESSAGE =
+  "this clip uses the Sequencer data model, and its ControlRig section could not be read. " +
+  "Re-save the asset in UE with 'Animation Sequencer Data Model' disabled, or export it to FBX."
+
+/**
+ * Everything an AnimSequence says about ITSELF — length, rate, root motion, sync markers, the
+ * skeleton it belongs to — without touching the data model that holds the tracks. Kept separate
+ * because a Sequencer-model clip's metadata is perfectly readable even though its motion is not:
+ * `probe` can then say what the clip is before saying why its tracks cannot be had.
+ */
+export const readAnimMeta = (pkg: UePackage): UeAnimMeta => {
+  const found = findExport(pkg, "AnimSequence")
+  if (!found) throw new Error(`${pkg.label}: no AnimSequence export (exports: ${pkg.exports.map((e) => `${e.objectName}:${classOf(pkg, e)}`).join(", ")})`)
+  const { reader: r, props: seq } = readObjectProperties(pkg, found.export)
+  const skelRef = resolveObject(pkg, propObject(r, seq.byName.get("Skeleton")) ?? 0)
+  const additiveRaw = propEnum(r, pkg.names, seq.byName.get("AdditiveAnimType"))
+  const interpRaw = propEnum(r, pkg.names, seq.byName.get("Interpolation"))
+  return {
+    name: found.export.objectName,
+    export: found,
+    props: seq,
+    reader: r,
+    skeletonPath: skelRef?.packagePath ?? "",
+    skeletonName: skelRef?.name ?? "",
+    rootMotion: seq.byName.get("bEnableRootMotion")?.bool ?? false,
+    additive: additiveRaw && !/AAT_None|^0$/.test(additiveRaw) ? additiveRaw : null,
+    interpolation: interpRaw && /Step/i.test(interpRaw) ? "Step" : "Linear",
+    rateScale: propFloat(r, seq.byName.get("RateScale")) ?? 1,
+    events: [
+      ...readEvents(r, pkg, seq.byName.get("AuthoredSyncMarkers"), "marker"),
+      ...readEvents(r, pkg, seq.byName.get("Notifies"), "notify"),
+    ].sort((a, b) => a.time - b.time),
+    sequenceLength: propFloat(r, seq.byName.get("SequenceLength")) ?? 0,
+    targetFps: readFrameRate(r, pkg, seq.byName.get("TargetFrameRate")),
+    dataModel: dataModelKind(pkg),
+  }
+}
+
+/** The `AnimSequence` export of a package (an `A_*.uasset`), with its raw tracks. */
+export const readAnimSequence = (pkg: UePackage): UeAnimSequence => {
+  const meta = readAnimMeta(pkg)
+  const { reader: r, props: seq, rootMotion, additive, interpolation, rateScale, events, sequenceLength, targetFps } = meta
+
+  // Which data model: the DataModel property points at the export that holds the tracks; a 5.3
+  // sequencer asset instead carries DataModelInterface and a MovieScene export.
+  const modelRef = resolveObject(pkg, propObject(r, seq.byName.get("DataModel")) ?? 0)
+  const kind = meta.dataModel
+  if (kind === "AnimationSequencerDataModel") return sequencerAnimSequence(pkg, meta)
+  const model = modelRef?.kind === "export" ? pkg.exports[modelRef.index] : findExport(pkg, "AnimDataModel")?.export
+  if (!model) throw new Error(`${pkg.label}: the AnimSequence names no readable data model (found ${kind})`)
+
+  const { reader: mr, props: m } = readObjectProperties(pkg, model)
+  const playLength = propFloat(mr, m.byName.get("PlayLength")) ?? sequenceLength
+  const numFrames = propInt(mr, m.byName.get("NumberOfFrames")) ?? 0
+  const numKeys = propInt(mr, m.byName.get("NumberOfKeys")) ?? numFrames + 1
+  const fps = readFrameRate(mr, pkg, m.byName.get("FrameRate")) ?? targetFps ?? (playLength > 0 ? numFrames / playLength : 30)
+
+  const tracks: UeTrack[] = []
+  const tracksTag = m.byName.get("BoneAnimationTracks")
+  if (tracksTag) {
+    const { count } = readArrayHeader(mr, pkg, tracksTag)
+    for (let i = 0; i < count; i++) {
+      const el = readProperties(mr, pkg)
+      const after = mr.offset
+      const name = propName(mr, pkg.names, el.byName.get("Name")) ?? ""
+      const boneIndex = propInt(mr, el.byName.get("BoneTreeIndex")) ?? -1
+      const data = el.byName.get("InternalTrackData")
+      const keys = data ? readTrackData(mr, pkg, data) : { pos: new Float32Array(0), rot: new Float32Array(0), scale: new Float32Array(0) }
+      for (const [ key, comps, field ] of [ [ "PosKeys", 3, "pos" ], [ "RotKeys", 4, "rot" ], [ "ScaleKeys", 3, "scale" ] ] as const) {
+        let arr = keys[field]
+        let n = arr.length / comps
+        // an off-count track that never actually varies is a constant one written long-hand
+        if (n !== 0 && n !== 1 && n !== numKeys) { arr = collapseConstant(arr, comps); n = arr.length / comps; keys[field] = arr }
+        if (n !== 0 && n !== 1 && n !== numKeys) {
+          throw new Error(`${pkg.label}: bone "${name}" has ${n} ${key} for a ${numKeys}-key clip — unexpected key count`)
+        }
+      }
+      if (name) tracks.push({ name, boneIndex, ...keys })
+      mr.offset = after
+    }
+  }
+
+  return {
+    name: meta.name,
+    fps, numFrames, numKeys, playLength: playLength || (numFrames && fps ? numFrames / fps : 0),
+    tracks,
+    skeletonPath: meta.skeletonPath,
+    skeletonName: meta.skeletonName,
+    rootMotion, additive, interpolation, rateScale, events,
+  }
+}
+
+/** Cheap classification for `probe` / listings: what an export table says a package holds. */
+export const packageKind = (pkg: UePackage): "AnimSequence" | "SkeletalMesh" | "Skeleton" | "Texture2D" | "other" => {
+  for (const want of [ "AnimSequence", "SkeletalMesh", "Skeleton", "Texture2D" ] as const) if (findExport(pkg, want)) return want
+  return "other"
+}

package/src/unreal/clipSource.ts

@@ -0,0 +1,25 @@
+// An Unreal AnimSequence as a `ClipSource` — the shape `mergeClipScene` merges into an existing
+// model by bone name. Same conversion as the document builder uses (`unrealClipTracks`), so a
+// `.uasset` clip lands identically whether it is written out on its own skeleton or merged onto a
+// character that came from somewhere else.
+//
+// `isRoot` is false for every node: it marks ufbx's synthetic scene root, which Unreal data has
+// none of — UE's `root` is a real bone whose track must be merged like any other.
+
+import type { ClipSource } from "../fbx/convert"
+import type { UeSkeleton } from "./skeleton"
+import type { UeAnimSequence } from "./anim"
+import { unrealClipTracks, clipExtras } from "./toDocument"
+import { ueLocalTransform } from "./convert"
+
+export const clipSourceFromUnreal = (skeleton: UeSkeleton, clip: UeAnimSequence): ClipSource => {
+  const { tracks } = unrealClipTracks(skeleton, clip)
+  return {
+    nodes: skeleton.bones.map((b) => {
+      const l = ueLocalTransform(b.t, b.q, b.s, b.parent < 0)
+      return { name: b.name, parent: b.parent, t: l.t, r: l.r, s: l.s, isRoot: false }
+    }),
+    animations: [ { name: clip.name, duration: clip.playLength, tracks } ],
+    extras: () => clipExtras(clip),
+  }
+}

package/src/unreal/convert.ts

@@ -0,0 +1,67 @@
+// UE frame → glTF frame. The ONE place the axis/unit convention lives.
+//
+// Unreal is centimetres, X-forward / Y-right / Z-up, LEFT-handed; glTF is metres, Y-up,
+// right-handed. The recipe below is not a free choice: a GLB made from a `.uasset` has to be
+// interchangeable with the GLB the FBX route makes from the same pack's FBX sources, because both
+// feed `--clips` merging by bone name and the retargeter. UE's FBX exporter mirrors Y (left-handed
+// → right-handed Z-up) and ufbx then turns Z-up into Y-up by rotating the root −90° about X, so
+// that is exactly what is reproduced here:
+//
+//   S = 0.01 (cm → m).  M = mirror Y.  Rx = −90° about X, qRx = (−√½, 0, 0, √½).
+//   non-root bone (local transform and every local animation key):
+//       t' = ( tx, −ty, tz ) · S
+//       q' = ( −qx, qy, −qz, qw )        // M q M⁻¹ for an improper M: axis mirrored, angle negated
+//   root bone (local = world):
+//       t' = Rx · ( tx, −ty, tz ) · S = ( tx, tz, ty ) · S
+//       q' = qRx ⊗ ( −qx, qy, −qz, qw )
+//   mesh points / normals (already in the skeleton's world = bind space):
+//       p' = ( px, pz, py ) · S ;  n' = ( nx, nz, ny )
+//
+// Verified numerically against the FBX route on all 267 channels of a real clip: worst translation
+// error 1.1e-7 m, worst rotation 0.30° (the FBX route's own key reduction). docs/unreal-assets-plan.md §5.
+
+export type Vec3 = [ number, number, number ]
+export type Quat = [ number, number, number, number ]
+
+/** cm → m. */
+export const UE_SCALE = 0.01
+
+const R2 = Math.SQRT1_2
+/** −90° about X: the Z-up → Y-up turn, applied to root bones only. */
+export const Q_ZUP_TO_YUP: Quat = [ -R2, 0, 0, R2 ]
+
+/** Hamilton product (x, y, z, w). */
+export const qmul = (a: Quat, b: Quat): Quat => [
+  a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+  a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+  a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+  a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+]
+
+/** A UE translation in a bone's LOCAL frame → glTF, metres. */
+export const ueTranslation = (x: number, y: number, z: number): Vec3 => [ x * UE_SCALE, -y * UE_SCALE, z * UE_SCALE ]
+
+/** A UE rotation in a bone's LOCAL frame → glTF (the Y mirror flips the axis and the angle). */
+export const ueQuat = (x: number, y: number, z: number, w: number): Quat => [ -x, y, -z, w ]
+
+/** A ROOT bone's translation → glTF: the mirror, then the Z-up → Y-up turn. */
+export const ueRootTranslation = (x: number, y: number, z: number): Vec3 => [ x * UE_SCALE, z * UE_SCALE, y * UE_SCALE ]
+
+/** A ROOT bone's rotation → glTF. */
+export const ueRootQuat = (x: number, y: number, z: number, w: number): Quat => qmul(Q_ZUP_TO_YUP, ueQuat(x, y, z, w))
+
+/** A point/vector already in the skeleton's WORLD (bind) space → glTF, metres. */
+export const ueWorldPoint = (x: number, y: number, z: number): Vec3 => [ x * UE_SCALE, z * UE_SCALE, y * UE_SCALE ]
+
+/** A direction already in the skeleton's WORLD space (a normal) → glTF; length preserved. */
+export const ueWorldDir = (x: number, y: number, z: number): Vec3 => [ x, z, y ]
+
+/** UE scale is per-axis and handedness-free. */
+export const ueScale = (x: number, y: number, z: number): Vec3 => [ x, y, z ]
+
+/** Local transform of one bone (root or not) → glTF. */
+export const ueLocalTransform = (t: Vec3 | number[], q: Quat | number[], s: Vec3 | number[], isRoot: boolean): { t: Vec3, r: Quat, s: Vec3 } => ({
+  t: isRoot ? ueRootTranslation(t[0], t[1], t[2]) : ueTranslation(t[0], t[1], t[2]),
+  r: isRoot ? ueRootQuat(q[0], q[1], q[2], q[3]) : ueQuat(q[0], q[1], q[2], q[3]),
+  s: ueScale(s[0], s[1], s[2]),
+})

package/src/unreal/convertAsset.ts

@@ -0,0 +1,81 @@
+// `convert <x.uasset>` — the asset-level entry point, the counterpart of `convertFbx`.
+//
+//   SkeletalMesh  → mesh + skin + its own bone list
+//   Skeleton      → the skeleton alone
+//   AnimSequence  → the skeleton it was authored on (found in the pack, §6.3) + that clip
+//
+// `--clips` files (FBX or `.uasset`) are merged onto the result by bone name through the same
+// `mergeClipScene` the FBX route uses.
+
+import { basename } from "node:path"
+import type { Document } from "@gltf-transform/core"
+import { mergeClipScene, loadClipSource, type ConvertReport } from "../fbx/convert"
+import type { ConvertWarning } from "../fbx/toDocument"
+import { loadUnreal, type LoadUnrealOptions } from "./index"
+import { unrealToDocument } from "./toDocument"
+import { meshBounds } from "./mesh"
+import { applyUnrealTextures } from "./materials"
+
+export type ConvertUnrealOptions = LoadUnrealOptions & {
+  clips?: string[]
+  clipNames?: string[]
+  rename?: Record<string, string>
+  dropModelClips?: boolean
+  /** Pull the pack's textures onto the materials (default: on when a decoder is available). */
+  textures?: boolean
+  /** Longest texture edge kept (default 2048, 0 = the source's own size). */
+  maxSize?: number
+  /** UE authors normal maps DirectX-style; glTF wants OpenGL. Default: flip. */
+  flipNormalGreen?: boolean
+  /** Last-resort object-path lookup for hosts with no pack on disk (see `TextureOptions`). */
+  resolveAsset?: (objectPath: string) => string | null
+  warn?: (w: ConvertWarning) => void
+}
+
+export type ConvertUnrealResult = {
+  doc: Document
+  report: { clips: ConvertReport["clips"] }
+  /** One line for the CLI: what was read and where its skeleton came from. */
+  info: string
+  textures?: Awaited<ReturnType<typeof applyUnrealTextures>>
+}
+
+export const convertUnreal = async (path: string, opts: ConvertUnrealOptions = {}): Promise<ConvertUnrealResult> => {
+  const warn = opts.warn ?? (() => {})
+  const u = loadUnreal(path, opts)
+  const own = u.anim && !opts.dropModelClips ? [ u.anim ] : []
+  const r = unrealToDocument({ skeleton: u.skeleton, mesh: u.mesh, clips: own }, { warn })
+
+  const clips: ConvertReport["clips"] = r.bound.map((b, i) => ({
+    name: b.name, source: basename(path), duration: own[i]?.playLength ?? 0, tracks: b.tracks, bound: b.bound,
+  }))
+  for (let i = 0; i < (opts.clips ?? []).length; i++) {
+    const file = opts.clips![i]
+    const source = await loadClipSource(file, { skeleton: opts.skeleton, contentRoot: opts.contentRoot })
+    clips.push(...mergeClipScene(r.doc, source, basename(file), opts.clipNames?.[i], opts.rename, warn))
+  }
+
+  // Textures: the pack's material instances name them, and the source images sit Oodle-compressed
+  // inside the texture assets (see `materials.ts` / `oodle.ts`). Without a decoder the materials
+  // stay the grey slots the document was built with — the geometry is unaffected either way.
+  let textures: Awaited<ReturnType<typeof applyUnrealTextures>> | undefined
+  if (u.mesh && opts.textures !== false && u.mesh.materials.length) {
+    textures = await applyUnrealTextures(r.doc, path, u.mesh.materials, {
+      maxSize: opts.maxSize, flipNormalGreen: opts.flipNormalGreen, contentRoot: opts.contentRoot, resolveAsset: opts.resolveAsset, warn,
+    })
+  }
+
+  const parts = [ `${u.engine} · ${u.kind === "anim" ? "AnimSequence" : u.kind === "mesh" ? "SkeletalMesh" : "Skeleton"} · skeleton ${u.skeleton.name} (${u.skeleton.bones.length} bones)` ]
+  if (u.skeletonFile !== path) parts.push(`from ${basename(u.skeletonFile)}`)
+  if (u.mesh) {
+    const b = meshBounds(u.mesh)
+    parts.push(`LOD ${u.mesh.lod} of ${u.mesh.lods.length} · ${u.mesh.faceWedges.length / 3} tris · ${((b.max[2] - b.min[2]) / 100).toFixed(2)} m tall`)
+    if (r.flippedWinding) parts.push("winding flipped (mirror)")
+    const points = u.mesh.points.length / 3
+    if (r.droppedWeight > 0.005 * points) parts.push(`skin trimmed to 4 bones/vertex (${(100 * r.droppedWeight / points).toFixed(1)} % of weight redistributed)`)
+  }
+  if (textures?.textures) parts.push(`${textures.textures} texture(s) from ${textures.slots.filter((s) => s.roles.length).length} material instance(s)`)
+  if (u.anim?.additive) parts.push(`ADDITIVE (${u.anim.additive}) — poses are deltas`)
+  if (u.anim?.rootMotion) parts.push("root motion")
+  return { doc: r.doc, report: { clips }, info: parts.join(" · "), textures }
+}

package/src/unreal/index.ts

@@ -0,0 +1,115 @@
+// One call for the CLI: a `.uasset` path in, everything the pipeline needs out — the asset's kind,
+// its skeleton (resolved from the pack's Content folder when the file is a clip), the clip, the
+// mesh. Skeletons are cached per path because 42 clips of a pack share one.
+
+import { readFileSync } from "node:fs"
+import { basename, dirname } from "node:path"
+import { readPackage, engineLabel, classOf, importPackagePath, type UePackage, type ReadPackageOptions } from "./package"
+import { readSkeleton, type UeSkeleton } from "./skeleton"
+import { readAnimSequence, dataModelKind, packageKind, type UeAnimSequence, type DataModelKind } from "./anim"
+import { readSkeletalMesh, type UeSkeletalMesh } from "./mesh"
+import { resolveObjectFile, searchedRoots } from "./resolve"
+import { skeletonFromMesh } from "./toDocument"
+
+export type UnrealKind = "anim" | "skeleton" | "mesh"
+
+export type LoadUnrealOptions = {
+  /** Explicit skeleton asset (`SK_*.uasset`, or a `SKM_*.uasset` whose bone list is used). */
+  skeleton?: string
+  /** The pack's Content folder, when the walk-up search cannot find it. */
+  contentRoot?: string
+  /** Mesh LOD to read (default 0). */
+  lod?: number
+}
+
+export type LoadedUnreal = {
+  kind: UnrealKind
+  path: string
+  package: UePackage
+  engine: string
+  dataModel: DataModelKind
+  skeleton: UeSkeleton
+  /** Where the skeleton came from — this file, or the asset an object path named. */
+  skeletonFile: string
+  anim?: UeAnimSequence
+  mesh?: UeSkeletalMesh
+}
+
+const packageCache = new Map<string, UePackage>()
+const skeletonCache = new Map<string, UeSkeleton>()
+
+export const readPackageFile = (path: string, opts: ReadPackageOptions = {}): UePackage => {
+  const key = opts.ue4 ? `${path}\0ue4` : path
+  const hit = packageCache.get(key)
+  if (hit) return hit
+  const pkg = readPackage(new Uint8Array(readFileSync(path)), basename(path), opts)
+  packageCache.set(key, pkg)
+  return pkg
+}
+
+/** A skeleton out of a `Skeleton` asset, or out of a `SkeletalMesh`'s own bone list. */
+export const readSkeletonFile = (path: string): UeSkeleton => {
+  const hit = skeletonCache.get(path)
+  if (hit) return hit
+  const pkg = readPackageFile(path)
+  const kind = packageKind(pkg)
+  const sk = kind === "Skeleton" ? readSkeleton(pkg)
+    : kind === "SkeletalMesh" ? skeletonFromMesh(readSkeletalMesh(pkg))
+    : (() => { throw new Error(`${basename(path)}: not a Skeleton or SkeletalMesh asset (${pkg.exports.map((e) => classOf(pkg, e)).join(", ")})`) })()
+  skeletonCache.set(path, sk)
+  return sk
+}
+
+export const loadUnreal = (path: string, opts: LoadUnrealOptions = {}): LoadedUnreal => {
+  const pkg = readPackageFile(path)
+  const engine = engineLabel(pkg.summary)
+  const dataModel = dataModelKind(pkg)
+  const kind = packageKind(pkg)
+
+  if (kind === "AnimSequence") {
+    const anim = readAnimSequence(pkg)
+    let skeletonFile = opts.skeleton
+    if (!skeletonFile) {
+      const found = anim.skeletonPath ? resolveObjectFile(anim.skeletonPath, dirname(path), opts.contentRoot) : null
+      if (!found) {
+        throw new Error(
+          `${basename(path)}: cannot find the skeleton asset "${anim.skeletonPath || "(unnamed)"}" this clip was authored on. ` +
+          `Looked for it in ${searchedRoots(dirname(path)).slice(0, 4).map((d) => `${d}${anim.skeletonPath.replace("/Game", "")}.uasset`).join(", ")}… ` +
+          `— point at it with --skeleton <SK_*.uasset>, or name the pack's Content folder with --content-root <dir>.`,
+        )
+      }
+      skeletonFile = found.file
+    }
+    return { kind: "anim", path, package: pkg, engine, dataModel, skeleton: readSkeletonFile(skeletonFile), skeletonFile, anim }
+  }
+
+  if (kind === "SkeletalMesh") {
+    const mesh = readSkeletalMesh(pkg, { lod: opts.lod })
+    return { kind: "mesh", path, package: pkg, engine, dataModel, skeleton: skeletonFromMesh(mesh), skeletonFile: path, mesh }
+  }
+
+  if (kind === "Skeleton") {
+    return { kind: "skeleton", path, package: pkg, engine, dataModel, skeleton: readSkeleton(pkg), skeletonFile: path }
+  }
+
+  throw new Error(`${basename(path)}: holds no skeleton, mesh or animation (${engine}; exports: ${pkg.exports.map((e) => `${e.objectName}:${classOf(pkg, e)}`).slice(0, 6).join(", ")})`)
+}
+
+export const isUasset = (path: string): boolean => /\.uasset$/i.test(path)
+
+/**
+ * The `/Game/...` path of the skeleton an asset belongs to, read off the IMPORT TABLE alone — no
+ * geometry, no tracks. A clip and the meshes bound to one rig all name the same path, which is what
+ * groups a pack (and what lets a flat file store find the skeleton a dropped clip needs).
+ */
+export const skeletonPathOf = (pkg: UePackage): string => {
+  for (let i = 0; i < pkg.imports.length; i++) if (pkg.imports[i].className === "Skeleton") return importPackagePath(pkg, i)
+  return pkg.summary.packageName.startsWith("/") ? pkg.summary.packageName : ""
+}
+
+export { readPackage, engineLabel, classOf } from "./package"
+export { readSkeleton, type UeSkeleton, type UeBone } from "./skeleton"
+export { readAnimSequence, readAnimMeta, packageKind, dataModelKind, keyTimes, type UeAnimSequence, type UeAnimMeta, type UeTrack } from "./anim"
+export { readSkeletalMesh, meshBounds, type UeSkeletalMesh } from "./mesh"
+export { unrealToDocument, skeletonFromMesh, boneWorldMatrices, type UnrealDocumentResult } from "./toDocument"
+export { resolveObjectFile, objectPathToFile } from "./resolve"