lecodes-assets 0.2.0 → 2.4.10

package/src/unreal/probe.ts

@@ -0,0 +1,144 @@
+// `probe <x.uasset>` — what an Unreal asset holds, before converting anything: engine version,
+// class, data model, the skeleton (and WHICH FILE it was found in), a clip's keys/rate/root travel,
+// a mesh's LODs, counts and size. Anything the reader cannot handle is printed as the reason, not
+// thrown — the point of probing a pack is to find out which assets are usable.
+
+import { basename, dirname } from "node:path"
+import { engineLabel, classOf, type UePackage } from "./package"
+import { readSkeleton, rootBones, type UeSkeleton } from "./skeleton"
+import { readAnimSequence, readAnimMeta, dataModelKind, packageKind, type UeAnimSequence } from "./anim"
+import { readSkeletalMesh, meshBounds, type UeSkeletalMesh } from "./mesh"
+import { readPackageFile, readSkeletonFile } from "./index"
+import { resolveObjectFile } from "./resolve"
+import { UE_SCALE } from "./convert"
+import { readTexture2D, findCompressedBuffer } from "./texture"
+import { findOodle } from "./oodle"
+import { resolveSlotMaterials, readMaterialTextures, classifyTexture } from "./materials"
+
+const f = (n: number, d = 2): string => n.toFixed(d)
+
+/** Where a clip's root ends up travelling, in the glTF frame (X right, Y up, Z forward). */
+export const rootTravel = (anim: UeAnimSequence, skeleton: UeSkeleton): { size: [ number, number, number ], up: number, fwd: number } | null => {
+  const roots = new Set(rootBones(skeleton).map((i) => skeleton.bones[i].name))
+  const track = anim.tracks.find((t) => roots.has(t.name) && t.pos.length >= 6)
+  if (!track) return null
+  const lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+  for (let i = 0; i < track.pos.length; i += 3) {
+    for (let k = 0; k < 3; k++) { lo[k] = Math.min(lo[k], track.pos[i + k]); hi[k] = Math.max(hi[k], track.pos[i + k]) }
+  }
+  const n = track.pos.length / 3
+  // UE root local = world; the glTF frame turns (x, y, z)cm into (x, z, y)m
+  const size: [ number, number, number ] = [ (hi[0] - lo[0]) * UE_SCALE, (hi[2] - lo[2]) * UE_SCALE, (hi[1] - lo[1]) * UE_SCALE ]
+  return { size, up: (track.pos[(n - 1) * 3 + 2] - track.pos[2]) * UE_SCALE, fwd: (track.pos[(n - 1) * 3 + 1] - track.pos[1]) * UE_SCALE }
+}
+
+const skeletonLine = (sk: UeSkeleton, file: string, from: string): string => {
+  const roots = rootBones(sk).map((i) => sk.bones[i].name)
+  return `  skeleton ${sk.name} (${sk.bones.length} bones, root${roots.length > 1 ? "s" : ""}: ${roots.join(", ") || "none"})${file !== from ? ` ← ${basename(file)}` : ""}`
+}
+
+const animLines = (anim: UeAnimSequence, sk: UeSkeleton): string[] => {
+  const out: string[] = []
+  const travel = rootTravel(anim, sk)
+  out.push(`  ${anim.tracks.length}/${sk.bones.length} bones animated · ${anim.numKeys} keys @ ${+anim.fps.toFixed(3)} fps · ${f(anim.playLength, 3)} s · ${anim.interpolation.toLowerCase()} interpolation${anim.rateScale !== 1 ? ` · rate ×${anim.rateScale}` : ""}`)
+  out.push(`  root motion: ${travel ? `travels ${f(travel.size[0])}×${f(travel.size[1])}×${f(travel.size[2])} m (up ${f(travel.up)}, fwd ${f(travel.fwd)})` : "root not animated"} · bEnableRootMotion ${anim.rootMotion ? "ON" : "off"}`)
+  if (anim.additive) out.push(`  ⚠ ADDITIVE clip (${anim.additive}) — its poses are DELTAS against a base pose, not a playable pose`)
+  if (anim.events.length) out.push(`  events ${anim.events.length}: ${anim.events.slice(0, 8).map((e) => `${e.name}@${f(e.time, 2)}s`).join(", ")}${anim.events.length > 8 ? "…" : ""}`)
+  const missing = anim.tracks.filter((t) => !sk.bones.some((b) => b.name === t.name)).map((t) => t.name)
+  if (missing.length) out.push(`  ⚠ ${missing.length} track(s) name a bone this skeleton lacks: ${missing.slice(0, 6).join(", ")}`)
+  return out
+}
+
+const meshLines = (mesh: UeSkeletalMesh): string[] => {
+  const b = meshBounds(mesh)
+  const dims = [ (b.max[0] - b.min[0]) * UE_SCALE, (b.max[2] - b.min[2]) * UE_SCALE, (b.max[1] - b.min[1]) * UE_SCALE ]
+  return [
+    `  LODs ${mesh.lods.length}: ${mesh.lods.map((l) => `${l.index}${l.hasSource ? `=${(l.bytes / 1e6).toFixed(1)}MB${l.compressed ? " zlib" : " raw"}` : "=no source"}`).join(", ")}  (reading LOD ${mesh.lod}, import-data v${mesh.version})`,
+    `  ${mesh.faceWedges.length / 3} tris · ${mesh.points.length / 3} points / ${mesh.wedgePoint.length} wedges · ${mesh.influences.length} influences · ${mesh.bones.length} bones · size ${dims.map((d) => f(d, 3)).join("×")} m${mesh.hasUv1 ? " · UV1" : ""}`,
+    `  materials ${mesh.materials.length}: ${mesh.materials.join(", ") || "none"}`,
+  ]
+}
+
+/** Per slot: the material asset it uses and the textures that material names. */
+const materialLines = (pkg: UePackage, slots: string[], meshPath: string): string[] => {
+  const out: string[] = []
+  const assets = resolveSlotMaterials(pkg, slots)
+  slots.forEach((slot, i) => {
+    const assetPath = assets[i]
+    if (!assetPath) { out.push(`    ${slot}: no material asset referenced`); return }
+    const file = resolveObjectFile(assetPath, dirname(meshPath))
+    const name = assetPath.split("/").pop()
+    if (!file) { out.push(`    ${slot} ← ${name} (asset not found next to the mesh)`); return }
+    try {
+      const params = readMaterialTextures(readPackageFile(file.file))
+      const roles = params.map((t) => `${t.asset}${classifyTexture(t.param, t.asset) !== "other" ? ` [${classifyTexture(t.param, t.asset)}]` : ""}`)
+      out.push(`    ${slot} ← ${name}: ${roles.join(", ") || "no textures"}`)
+    } catch (e) { out.push(`    ${slot} ← ${name}: ${(e as Error).message}`) }
+  })
+  return out
+}
+
+export const probeUnreal = async (path: string): Promise<string> => {
+  const lines: string[] = []
+  let pkg: UePackage
+  try { pkg = readPackageFile(path) } catch (e) { return `UASSET ${path}\n  ✗ ${(e as Error).message}` }
+  const kind = packageKind(pkg)
+  void findCompressedBuffer
+  const model = dataModelKind(pkg)
+  lines.push(`UASSET ${path}`)
+  lines.push(`  ${engineLabel(pkg.summary)} (ue4 ${pkg.summary.ue4}, ue5 ${pkg.summary.ue5}) · ${kind === "other" ? pkg.exports.map((e) => classOf(pkg, e)).slice(0, 4).join(", ") : kind}${model !== "none" ? ` · data model ${model}` : ""}`)
+
+  let skeleton: UeSkeleton | undefined
+  let anim: UeAnimSequence | undefined
+  let mesh: UeSkeletalMesh | undefined
+  try {
+    if (kind === "AnimSequence") {
+      anim = readAnimSequence(pkg)
+      const found = anim.skeletonPath ? resolveObjectFile(anim.skeletonPath, dirname(path)) : null
+      lines.push(`  authored on ${anim.skeletonName || "?"} (${anim.skeletonPath || "no skeleton named"})`)
+      if (found) { skeleton = readSkeletonFile(found.file); lines.push(skeletonLine(skeleton, found.file, path)) }
+      else lines.push(`  ⚠ that skeleton asset is not next to this file — pass --skeleton <SK_*.uasset> to convert it`)
+      if (skeleton) lines.push(...animLines(anim, skeleton))
+    } else if (kind === "SkeletalMesh") {
+      mesh = readSkeletalMesh(pkg)
+      skeleton = { name: mesh.skeletonName || mesh.name, bones: mesh.bones.map((b) => ({ name: b.name, parent: b.parent, t: b.t, q: b.q, s: b.s })) }
+      lines.push(`  bound to ${mesh.skeletonName || "?"} (${mesh.skeletonPath || "no skeleton named"})`)
+      lines.push(...meshLines(mesh))
+      lines.push(...materialLines(pkg, mesh.materials, path))
+    } else if (kind === "Texture2D") {
+      const t = readTexture2D(pkg)
+      lines.push(`  ${t.source.width}×${t.source.height} · ${t.source.format || "format?"} · ${t.source.compression || "uncompressed"} · ${t.compressionSettings}${t.srgb ? " · sRGB" : ""}${t.sourceFile ? ` · from ${t.sourceFile}` : ""}`)
+      const buf = findCompressedBuffer(pkg)
+      lines.push(buf
+        ? `  source payload: ${(buf.rawSize / 1e6).toFixed(1)} MB in ${buf.blocks.length} block(s), ${buf.method === 0 ? "stored" : buf.method === 3 ? "Oodle" : `method ${buf.method}`}${buf.method === 3 ? ` (${findOodle() ? "decoder found" : "NO decoder — set LECODES_OODLE"})` : ""}`
+        : "  ⚠ no source payload in this package")
+      return lines.join("\n")
+    } else if (kind === "Skeleton") {
+      skeleton = readSkeleton(pkg)
+      lines.push(skeletonLine(skeleton, path, path))
+    } else {
+      lines.push(`  nothing this pipeline reads (exports: ${pkg.exports.map((e) => `${e.objectName}:${classOf(pkg, e)}`).slice(0, 6).join(", ")})`)
+    }
+  } catch (e) {
+    lines.push(`  ✗ ${(e as Error).message}`)
+    // A Sequencer-model clip (or any clip whose tracks fail) still describes itself: length, rate,
+    // root motion and the sync markers all live on the AnimSequence, not in the data model.
+    if (kind === "AnimSequence") {
+      try {
+        const meta = readAnimMeta(pkg)
+        lines.push(`  the clip itself: ${f(meta.sequenceLength, 3)} s${meta.targetFps ? ` @ ${+meta.targetFps.toFixed(3)} fps` : ""} · authored on ${meta.skeletonName || "?"} (${meta.skeletonPath || "unnamed"})${meta.rootMotion ? " · root motion ON" : ""}${meta.additive ? ` · ADDITIVE (${meta.additive})` : ""}`)
+        if (meta.events.length) lines.push(`  events ${meta.events.length}: ${meta.events.slice(0, 8).map((x) => `${x.kind === "marker" ? "sync" : "notify"} ${x.name}@${f(x.time, 2)}s`).join(", ")}${meta.events.length > 8 ? "…" : ""}`)
+      } catch { /* the export itself is unreadable — the message above already says so */ }
+    }
+    return lines.join("\n")
+  }
+
+  // …and what it would convert to, through the normal GLB probe
+  if (skeleton) {
+    const { unrealToDocument } = await import("./toDocument")
+    const { probeDocument } = await import("../probe")
+    const r = unrealToDocument({ skeleton, mesh, clips: anim ? [ anim ] : [] })
+    lines.push(...probeDocument(r.doc, path).split("\n").slice(1))
+  }
+  return lines.join("\n")
+}

package/src/unreal/resolve.ts

@@ -0,0 +1,53 @@
+// Finding the file an object path names. An AnimSequence knows its skeleton only as
+// `/Game/StairsSet/Demo/Mannequins/Meshes/SK_Mannequin`, where `/Game/` is the pack's Content
+// folder — which is not marked in any way on disk. So: turn the path into a relative file name and
+// walk up from the clip until a directory answers to it. The first one that does IS the content root.
+
+import { existsSync, statSync } from "node:fs"
+import { dirname, join, resolve, sep } from "node:path"
+
+export const GAME_PREFIX = "/Game/"
+
+/** `/Game/A/B/Name` → `A/B/Name.uasset`. A PLUGIN's content mounts at `/<PluginName>/` instead of
+ *  `/Game/` (KINEMATION's FPS Animation Pack: `/FPSAnimationPack/Meshes/…/SK_Mannequin`), and its
+ *  Content folder on disk is just as unmarked — so any mount point is stripped the same way. */
+export const objectPathToFile = (objectPath: string): string | null => {
+  const m = /^\/[^/]+\/(.+)$/.exec(objectPath)
+  if (!m) return null
+  return `${m[1].replace(/\//g, sep)}.uasset`
+}
+
+export type ResolveResult = { file: string, contentRoot: string } | null
+
+/**
+ * The `.uasset` an object path points at, searched from `fromDir` upwards.
+ * `contentRoot` short-circuits the search (`--content-root`).
+ */
+export const resolveObjectFile = (objectPath: string, fromDir: string, contentRoot?: string): ResolveResult => {
+  const rel = objectPathToFile(objectPath)
+  if (!rel) return null
+  if (contentRoot) {
+    const f = join(contentRoot, rel)
+    return existsSync(f) ? { file: f, contentRoot } : null
+  }
+  let dir = resolve(fromDir)
+  for (;;) {
+    const f = join(dir, rel)
+    if (existsSync(f) && statSync(f).isFile()) return { file: f, contentRoot: dir }
+    const up = dirname(dir)
+    if (up === dir) return null
+    dir = up
+  }
+}
+
+/** The directories `resolveObjectFile` looked in — for the error message when it finds nothing. */
+export const searchedRoots = (fromDir: string): string[] => {
+  const out: string[] = []
+  let dir = resolve(fromDir)
+  for (;;) {
+    out.push(dir)
+    const up = dirname(dir)
+    if (up === dir) return out
+    dir = up
+  }
+}

package/src/unreal/rig.ts

@@ -0,0 +1,149 @@
+// An Unreal asset as a retargeter `Rig` (src/retarget/rig.ts) — built directly, not through a
+// Document, so `retarget --from SKM_Manny.uasset` costs one file read.
+//
+// In Unreal the REFERENCE POSE IS THE BIND POSE, so bind == rest exactly; the inverse-bind matrices
+// handed to `makeRig` are just the inverses of the rest world transforms. What they really carry is
+// WHICH BONES THE SKIN USES: the classifiers read `fromSkin` as "part of the body", and a UE rig is
+// full of bones no vertex is weighted to — `ik_foot_l`, `ik_hand_gun`, `interaction`,
+// `center_of_mass`. With a mesh at hand those come out unskinned, exactly as they should; with only
+// a `Skeleton` asset there is nothing to tell them apart, so every bone counts.
+
+import { makeRig, qnorm, qslerp, type Clip, type Pose, type Quat, type Rig, type Vec3 } from "../retarget/rig"
+import { boneInverseBindMatrices, unrealClipTracks, type UnrealTrack } from "./toDocument"
+import { ueLocalTransform } from "./convert"
+import type { UeSkeleton } from "./skeleton"
+import type { UeSkeletalMesh } from "./mesh"
+import type { UeAnimSequence } from "./anim"
+import { loadUnreal, type LoadUnrealOptions } from "./index"
+
+const sampleTrack = (tr: UnrealTrack, time: number): number[] => {
+  const n = tr.path === "rotation" ? 4 : 3
+  const last = tr.times.length - 1
+  const at = (i: number): number[] => Array.from(tr.values.subarray(i * n, i * n + n))
+  if (time <= tr.times[0]) return at(0)
+  if (time >= tr.times[last]) return at(last)
+  let i = 0
+  while (i < last && tr.times[i + 1] < time) i++
+  const u = (time - tr.times[i]) / (tr.times[i + 1] - tr.times[i] || 1)
+  const a = at(i), b = at(i + 1)
+  if (n === 4) return qslerp(a as Quat, b as Quat, u)
+  return a.map((v, k) => v + (b[k] - v) * u)
+}
+
+/**
+ * Add the bones that lie INSIDE the skinned subtree — a skinned ancestor above, a skinned bone
+ * somewhere below — to the body set.
+ *
+ * The UE5 mannequin weights its limbs to the twist helpers (`thigh_twist_01_l`, `upperarm_twist_02_r`)
+ * and leaves `thigh_l` / `upperarm_l` themselves without a single vertex. Taking "has weights"
+ * literally then cuts the legs and arms out of the body, and the humanoid classifier — which looks
+ * for a pelvis with two chains reaching the ground — reads the rig as not a biped at all. A bone
+ * between two skinned bones is part of the body whatever the weights say; a bone with nothing
+ * skinned below it (`ik_foot_root`, `ik_hand_gun`, `weapon_l`, `interaction`, `center_of_mass`) or
+ * nothing skinned above it (`root`) is not, which is exactly what those bones should read as.
+ */
+export const fillSkinnedInterior = (parents: number[], skinned: Set<number>): void => {
+  const order: number[] = []           // parents before children
+  const seen = new Set<number>()
+  const visit = (i: number): void => { if (seen.has(i)) return; if (parents[i] >= 0) visit(parents[i]); seen.add(i); order.push(i) }
+  parents.forEach((_, i) => visit(i))
+  const above = new Array(parents.length).fill(false)
+  for (const i of order) above[i] = parents[i] >= 0 && (skinned.has(parents[i]) || above[parents[i]])
+  const below = new Array(parents.length).fill(false)
+  for (let k = order.length - 1; k >= 0; k--) {
+    const i = order[k], p = parents[i]
+    if (p >= 0 && (skinned.has(i) || below[i])) below[p] = true
+  }
+  for (const i of order) if (!skinned.has(i) && above[i] && below[i]) skinned.add(i)
+}
+
+export type UnrealRigInput = {
+  skeleton: UeSkeleton
+  /** When present, only the bones it weights count as "part of the body". */
+  mesh?: UeSkeletalMesh
+  clips?: UeAnimSequence[]
+}
+
+export const rigFromUnrealData = (label: string, input: UnrealRigInput): Rig => {
+  const { skeleton, mesh } = input
+  const names = skeleton.bones.map((b) => b.name)
+  const parents = skeleton.bones.map((b) => b.parent)
+  const local = skeleton.bones.map((b) => ueLocalTransform(b.t, b.q, b.s, b.parent < 0))
+  const rest: Pose = { t: local.map((l) => [ ...l.t ] as Vec3), r: local.map((l) => [ ...l.r ] as Quat), s: local.map((l) => [ ...l.s ] as Vec3) }
+
+  let skinned: Set<number> | null = null
+  if (mesh) {
+    const byName = new Map(names.map((n, i) => [ n, i ]))
+    skinned = new Set<number>()
+    for (const inf of mesh.influences) {
+      if (inf.weight <= 0) continue
+      const bone = mesh.bones[inf.bone]
+      const i = bone ? byName.get(bone.name) : undefined
+      if (i !== undefined) skinned.add(i)
+    }
+    fillSkinnedInterior(parents, skinned)
+  }
+  const ibm = boneInverseBindMatrices(skeleton.bones)
+  const ibmByNode = new Map<number, number[]>()
+  ibm.forEach((m, i) => { if (!skinned || skinned.has(i)) ibmByNode.set(i, m) })
+
+  const makeClips = (base: Pose): Clip[] => (input.clips ?? []).map((clip) => {
+    const { tracks } = unrealClipTracks(skeleton, clip)
+    return {
+      name: clip.name,
+      duration: clip.playLength,
+      sample: (time: number): Pose => {
+        const pose: Pose = { t: base.t.map((v) => [ ...v ] as Vec3), r: base.r.map((v) => [ ...v ] as Quat), s: base.s.map((v) => [ ...v ] as Vec3) }
+        for (const tr of tracks) {
+          const v = sampleTrack(tr, time)
+          if (tr.path === "translation") pose.t[tr.node] = v as Vec3
+          else if (tr.path === "rotation") pose.r[tr.node] = qnorm(v as Quat)
+          else pose.s[tr.node] = v as Vec3
+        }
+        return pose
+      },
+    }
+  })
+
+  return makeRig(label, names, parents, rest, makeClips, ibmByNode)
+}
+
+/** `retarget --from x.uasset` / `--donor-rig x.uasset`: a mesh, a skeleton, or a clip + its skeleton. */
+export const rigFromUnreal = (path: string, opts: LoadUnrealOptions = {}): Rig => {
+  const u = loadUnreal(path, opts)
+  return rigFromUnrealData(path.split(/[\\/]/).pop() ?? path, { skeleton: u.skeleton, mesh: u.mesh, clips: u.anim ? [ u.anim ] : [] })
+}
+
+/** `retarget --anim a.uasset b.uasset`: clips bound BY BONE NAME onto a donor rig loaded elsewhere. */
+export const attachUnrealClips = (rig: Rig, skeleton: UeSkeleton, clips: UeAnimSequence[]): { clips: Clip[], report: { name: string, bound: number, total: number, unbound: string[] }[] } => {
+  const out: Clip[] = []
+  const report: { name: string, bound: number, total: number, unbound: string[] }[] = []
+  const base = rig.bind.local
+  for (const clip of clips) {
+    // convert on the CLIP's own skeleton, then move each track onto the rig's bone of that name
+    const { tracks, unbound } = unrealClipTracks(skeleton, clip)
+    const bound: UnrealTrack[] = []
+    const missing = new Set<string>(unbound)
+    for (const tr of tracks) {
+      const i = rig.index.get(skeleton.bones[tr.node].name)
+      if (i === undefined) { missing.add(skeleton.bones[tr.node].name); continue }
+      bound.push({ ...tr, node: i })
+    }
+    report.push({ name: clip.name, bound: new Set(bound.map((t) => t.node)).size, total: clip.tracks.length, unbound: [ ...missing ] })
+    out.push({
+      name: clip.name,
+      duration: clip.playLength,
+      sample: (time: number): Pose => {
+        const pose: Pose = { t: base.t.map((v) => [ ...v ] as Vec3), r: base.r.map((v) => [ ...v ] as Quat), s: base.s.map((v) => [ ...v ] as Vec3) }
+        for (const tr of bound) {
+          const v = sampleTrack(tr, time)
+          if (tr.path === "translation") pose.t[tr.node] = v as Vec3
+          else if (tr.path === "rotation") pose.r[tr.node] = qnorm(v as Quat)
+          else pose.s[tr.node] = v as Vec3
+        }
+        return pose
+      },
+    })
+  }
+  return { clips: out, report }
+}

package/src/unreal/sequencer.ts

@@ -0,0 +1,193 @@
+// The OTHER data model: `AnimationSequencerDataModel`, what UE 5.2+ writes when a clip is authored
+// or edited in Sequencer through a Control Rig. The motion is not bone tracks but a MovieScene
+// section — `MovieSceneControlRigParameterSection.TransformParameterNamesAndCurves`, one element per
+// FK control (`pelvis_CONTROL`), each holding nine `FMovieSceneFloatChannel`s: 3 translation,
+// 3 rotation (EULER, degrees, `FRotator` order), 3 scale.
+//
+// A control's channels carry the bone's LOCAL transform in UE units, absolutely — not a delta
+// against the reference pose — so once the channels are evaluated on a key grid the result is the
+// same thing `AnimDataModel` hands over, and everything downstream (the coordinate recipe, clip
+// merging, retargeting) is unchanged.
+//
+// `FMovieSceneFloatChannel` is serialized natively (no property tags), verified byte-for-byte
+// against real files — the sizes below account for every byte of all 89 controls of a UE 5.3 clip:
+//
+//   u8 PreInfinityExtrap, u8 PostInfinityExtrap
+//   BulkSerialize<FFrameNumber>          i32 elemSize(4),  i32 count, count × i32   frame numbers
+//   BulkSerialize<FMovieSceneFloatValue> i32 elemSize(28), i32 count, count × 28 B  value + tangents
+//   f32 DefaultValue, i32 bHasDefaultValue, i32 TickNumerator, i32 TickDenominator, i32 (unused)
+//
+// A channel with no keys is a CONSTANT: its `DefaultValue` is the bone's own local component, which
+// is why an unanimated bone still comes out in the right place.
+
+import { BinaryReader, classOf, readObjectProperties, readArrayHeader, readFName, readProperties, propInt, type UePackage } from "./package"
+
+/** `ERichCurveInterpMode`. */
+export const RCIM_LINEAR = 0, RCIM_CONSTANT = 1, RCIM_CUBIC = 2
+
+export type MovieSceneChannel = {
+  /** Frame numbers, in the channel's own tick rate. */
+  times: Int32Array
+  values: Float32Array
+  arriveTangent: Float32Array
+  leaveTangent: Float32Array
+  interp: Uint8Array
+  defaultValue: number
+  hasDefault: boolean
+  tickRate: number
+  /** Bytes the channel actually consumed — the caller checks it against the property's size. */
+  size: number
+}
+
+const VALUE_SIZE = 28
+
+/** One `FMovieSceneFloatChannel` at `at`. */
+export const readFloatChannel = (bytes: Uint8Array, at: number, label = "channel"): MovieSceneChannel => {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  let o = at + 2                                                     // pre/post infinity extrapolation
+  const timeElem = dv.getInt32(o, true), timeCount = dv.getInt32(o + 4, true); o += 8
+  if (timeElem !== 4 || timeCount < 0 || o + timeCount * 4 > bytes.byteLength) {
+    throw new Error(`${label}: bad frame-number array (element ${timeElem}, count ${timeCount})`)
+  }
+  const times = new Int32Array(timeCount)
+  for (let i = 0; i < timeCount; i++) times[i] = dv.getInt32(o + i * 4, true)
+  o += timeCount * 4
+  const valueElem = dv.getInt32(o, true), valueCount = dv.getInt32(o + 4, true); o += 8
+  if (valueElem !== VALUE_SIZE || valueCount !== timeCount) {
+    throw new Error(`${label}: ${valueCount} values of ${valueElem} B for ${timeCount} keys — not a float channel`)
+  }
+  const values = new Float32Array(valueCount)
+  const arriveTangent = new Float32Array(valueCount)
+  const leaveTangent = new Float32Array(valueCount)
+  const interp = new Uint8Array(valueCount)
+  for (let i = 0; i < valueCount; i++) {
+    const b = o + i * VALUE_SIZE
+    values[i] = dv.getFloat32(b, true)
+    arriveTangent[i] = dv.getFloat32(b + 4, true)
+    leaveTangent[i] = dv.getFloat32(b + 8, true)
+    interp[i] = bytes[b + 24]
+  }
+  o += valueCount * VALUE_SIZE
+  const defaultValue = dv.getFloat32(o, true)
+  const hasDefault = dv.getInt32(o + 4, true) !== 0
+  const num = dv.getInt32(o + 8, true), den = dv.getInt32(o + 12, true)
+  o += 20                                                            // + the trailing i32
+  return { times, values, arriveTangent, leaveTangent, interp, defaultValue, hasDefault, tickRate: den ? num / den : 0, size: o - at }
+}
+
+/**
+ * The channel's value at a time in SECONDS. Keys are held before the first and after the last (the
+ * clip's own extrapolation is not applied — a baked grid never leaves the range). Cubic segments are
+ * evaluated as the bezier UE builds from the tangents; weighted tangents are approximated by the
+ * unweighted curve, which is what a baked mocap clip's keys are anyway.
+ */
+export const sampleChannel = (c: MovieSceneChannel, time: number, fallback = 0): number => {
+  const n = c.times.length
+  if (n === 0) return c.hasDefault ? c.defaultValue : fallback
+  const rate = c.tickRate || 1
+  const first = c.times[0] / rate, last = c.times[n - 1] / rate
+  if (time <= first) return c.values[0]
+  if (time >= last) return c.values[n - 1]
+  let i = 0
+  while (i < n - 1 && c.times[i + 1] / rate < time) i++
+  const t0 = c.times[i] / rate, t1 = c.times[i + 1] / rate
+  const span = t1 - t0
+  const u = span > 0 ? (time - t0) / span : 0
+  const v0 = c.values[i], v1 = c.values[i + 1]
+  if (c.interp[i] === RCIM_CONSTANT) return v0
+  if (c.interp[i] !== RCIM_CUBIC) return v0 + (v1 - v0) * u
+  // UE's cubic: control points a third of the interval along each tangent (value per second)
+  const p1 = v0 + (c.leaveTangent[i] * span) / 3
+  const p2 = v1 - (c.arriveTangent[i + 1] * span) / 3
+  const w = 1 - u
+  return w * w * w * v0 + 3 * w * w * u * p1 + 3 * w * u * u * p2 + u * u * u * v1
+}
+
+export type SequencerControl = {
+  /** `pelvis_CONTROL`. */
+  control: string
+  /** …and the bone it drives. */
+  bone: string
+  translation: (MovieSceneChannel | null)[]
+  rotation: (MovieSceneChannel | null)[]
+  scale: (MovieSceneChannel | null)[]
+}
+
+export type SequencerSection = {
+  controls: SequencerControl[]
+  /** Frames per second of the MovieScene's own timeline (`DisplayRate`). */
+  displayRate: number
+  tickRate: number
+}
+
+const frameRate = (r: BinaryReader, pkg: UePackage, props: ReturnType<typeof readProperties>, key: string): number | undefined => {
+  const tag = props.byName.get(key)
+  if (!tag) return undefined
+  r.offset = tag.data
+  const p = readProperties(r, pkg)
+  const num = propInt(r, p.byName.get("Numerator")), den = propInt(r, p.byName.get("Denominator")) ?? 1
+  return num && den ? num / den : undefined
+}
+
+/** The MovieScene's own rates — the frame grid a Sequencer clip is authored on. */
+export const readMovieSceneRates = (pkg: UePackage): { displayRate: number, tickRate: number } => {
+  const idx = pkg.exports.findIndex((e) => classOf(pkg, e) === "MovieScene")
+  if (idx < 0) return { displayRate: 30, tickRate: 0 }
+  const { reader: r, props } = readObjectProperties(pkg, pkg.exports[idx])
+  return {
+    displayRate: frameRate(r, pkg, props, "DisplayRate") ?? 30,
+    tickRate: frameRate(r, pkg, props, "TickResolution") ?? 0,
+  }
+}
+
+/** Every FK control of the package's ControlRig section, with its nine channels. */
+export const readSequencerSection = (pkg: UePackage): SequencerSection => {
+  const idx = pkg.exports.findIndex((e) => classOf(pkg, e) === "MovieSceneControlRigParameterSection")
+  if (idx < 0) throw new Error(`${pkg.label}: no MovieSceneControlRigParameterSection — not a Sequencer clip`)
+  const rates = readMovieSceneRates(pkg)
+  const { reader: r, props } = readObjectProperties(pkg, pkg.exports[idx])
+  const tag = props.byName.get("TransformParameterNamesAndCurves")
+  if (!tag) throw new Error(`${pkg.label}: the ControlRig section holds no transform curves (a curve-only or space-switch section?)`)
+  const { count } = readArrayHeader(r, pkg, tag)
+  const controls: SequencerControl[] = []
+  for (let i = 0; i < count; i++) {
+    const el = readProperties(r, pkg)
+    const after = r.offset
+    let control = ""
+    const nameTag = el.byName.get("ParameterName")
+    if (nameTag) { r.offset = nameTag.data; control = readFName(r, pkg.names) }
+    const slots: Record<string, (MovieSceneChannel | null)[]> = { Translation: [ null, null, null ], Rotation: [ null, null, null ], Scale: [ null, null, null ] }
+    for (const t of el.list) {
+      const slot = slots[t.name]
+      if (!slot || t.type !== "StructProperty" || t.arrayIndex < 0 || t.arrayIndex > 2) continue
+      const ch = readFloatChannel(pkg.bytes, t.data, `${pkg.label}:${control}.${t.name}[${t.arrayIndex}]`)
+      if (ch.size !== t.size) throw new Error(`${pkg.label}: ${control}.${t.name}[${t.arrayIndex}] read ${ch.size} of ${t.size} bytes — channel layout mismatch`)
+      slot[t.arrayIndex] = ch
+    }
+    if (control) {
+      controls.push({
+        control, bone: control.replace(/_CONTROL$/i, ""),
+        translation: slots.Translation, rotation: slots.Rotation, scale: slots.Scale,
+      })
+    }
+    r.offset = after
+  }
+  return { controls, ...rates }
+}
+
+/**
+ * `FRotator` (Roll = X, Pitch = Y, Yaw = Z, degrees) → the quaternion UE builds from it. Straight
+ * out of `FRotator::Quaternion()` — the signs are not a convention to pick, they are that function.
+ */
+export const rotatorToQuat = (roll: number, pitch: number, yaw: number): [ number, number, number, number ] => {
+  const half = Math.PI / 360                      // degrees → radians, halved
+  const sp = Math.sin(pitch * half), cp = Math.cos(pitch * half)
+  const sy = Math.sin(yaw * half), cy = Math.cos(yaw * half)
+  const sr = Math.sin(roll * half), cr = Math.cos(roll * half)
+  return [
+    cr * sp * sy - sr * cp * cy,
+    -cr * sp * cy - sr * cp * sy,
+    cr * cp * sy - sr * sp * cy,
+    cr * cp * cy + sr * sp * sy,
+  ]
+}

package/src/unreal/skeleton.ts

@@ -0,0 +1,74 @@
+// USkeleton → bones. A UE skeleton asset carries the reference skeleton: bone names, parents and
+// the ref pose. In Unreal THE REFERENCE POSE IS THE BIND POSE (skinned meshes are bound to it), so
+// a rig built from one has `bind = rest` and needs no inverse-bind matrices to be meaningful.
+//
+// Layout (§4.1): the tagged part (BoneTree, Sockets, …) is skipped, then the native
+// `FReferenceSkeleton`: bone infos (name, parent, editor export name), then one `FTransform` per
+// bone — LOCAL, UE frame, centimetres, doubles since ue5 1004 (LWC).
+
+import { BinaryReader, findExport, readFName, readObjectProperties, type UePackage } from "./package"
+
+export type UeBone = {
+  name: string
+  parent: number
+  /** LOCAL transform in the UE frame, centimetres. */
+  t: [ number, number, number ]
+  q: [ number, number, number, number ]
+  s: [ number, number, number ]
+}
+
+export type UeSkeleton = {
+  /** The asset's name (`SK_Mannequin`). */
+  name: string
+  bones: UeBone[]
+}
+
+/**
+ * After a UObject's tag list comes an `i32` "has object guid" flag (always 0 in these packages).
+ * Some classes do not write it, so a non-0/1 value is treated as the class's own data and rewound.
+ */
+export const skipObjectGuid = (r: BinaryReader): void => {
+  const at = r.offset
+  const v = r.i32()
+  if (v === 0) return
+  if (v === 1) { r.skip(16); return }
+  r.offset = at
+}
+
+/** `FReferenceSkeleton` (editor build) at the reader's position. */
+export const readReferenceSkeleton = (r: BinaryReader, names: string[], label: string): UeBone[] => {
+  const boneCount = r.i32()
+  if (boneCount < 0 || boneCount > 65536) throw new Error(`${label}: implausible bone count ${boneCount} at ${r.offset - 4}`)
+  const bones: UeBone[] = new Array(boneCount)
+  for (let i = 0; i < boneCount; i++) {
+    const name = readFName(r, names)
+    const parent = r.i32()
+    r.fstring()                                     // exportName (editor only)
+    if (parent < -1 || parent >= boneCount) throw new Error(`${label}: bone ${i} ("${name}") has parent ${parent}`)
+    bones[i] = { name, parent, t: [ 0, 0, 0 ], q: [ 0, 0, 0, 1 ], s: [ 1, 1, 1 ] }
+  }
+  const poseCount = r.i32()
+  if (poseCount !== boneCount) throw new Error(`${label}: reference pose has ${poseCount} transforms for ${boneCount} bones`)
+  for (let i = 0; i < poseCount; i++) {
+    const q = r.doubles(4)                          // FTransform: rotation, translation, scale
+    const t = r.doubles(3)
+    const s = r.doubles(3)
+    bones[i].q = [ q[0], q[1], q[2], q[3] ]
+    bones[i].t = [ t[0], t[1], t[2] ]
+    bones[i].s = [ s[0], s[1], s[2] ]
+  }
+  return bones
+}
+
+/** The `Skeleton` export of a package (a `SK_*.uasset`). */
+export const readSkeleton = (pkg: UePackage): UeSkeleton => {
+  const found = findExport(pkg, "Skeleton")
+  if (!found) throw new Error(`${pkg.label}: no Skeleton export (classes: ${pkg.exports.map((e) => e.objectName).join(", ")})`)
+  const { reader: r } = readObjectProperties(pkg, found.export)   // BoneTree, Sockets, PreviewSkeletalMesh, …
+  skipObjectGuid(r)
+  const bones = readReferenceSkeleton(r, pkg.names, pkg.label)
+  return { name: found.export.objectName, bones }
+}
+
+/** Bones with no parent — `root` for a UE rig, but a skeleton may carry several. */
+export const rootBones = (sk: UeSkeleton): number[] => sk.bones.map((b, i) => (b.parent < 0 ? i : -1)).filter((i) => i >= 0)