lecodes-assets 0.2.0 → 0.2.1

package/src/unreal/texture.ts

@@ -0,0 +1,202 @@
+// Texture2D → the SOURCE image the artist imported. An uncooked asset keeps it whole (not the
+// compressed BCn mips a cooked build ships), wrapped in an `FCompressedBuffer`: a big-endian header
+// followed by fixed-size blocks, Oodle-compressed (`oodle.ts` loads the decoder).
+//
+// What comes out is usually a PNG or JPEG file, ready to embed in a GLB as it is. One catch: UE
+// writes a `TSF_BGRA8` source into that PNG straight from BGRA memory, so its red and blue channels
+// are swapped — `FTextureSource.Format` says when, and the swap needs a decode/encode round trip
+// (`../textures/resolveImage`).
+//
+// Verified on UE 5.0 (buffer right after the exports, `payloadTocOffset = -1`) and UE 5.3 (inside
+// the package trailer): same container either way, so it is found by its magic at or after the
+// bulk-data start rather than through the trailer's own table of contents.
+
+import { BinaryReader, findExport, readProperties, readObjectProperties, propInt, propEnum, propString, type UePackage } from "./package"
+import { getOodle, OODLE_MISSING_MESSAGE, findOodle, OODLE_NO_RUNTIME_MESSAGE } from "./oodle"
+
+/** `b7 75 63 62` — `FCompressedBuffer`'s magic, big-endian like the rest of its header. */
+const COMPRESSED_BUFFER_MAGIC = [ 0xb7, 0x75, 0x63, 0x62 ]
+const HEADER_SIZE = 64            // magic + crc + 4 bytes + blockCount + rawSize + compSize + a 32-byte hash
+
+export type CompressedBuffer = {
+  offset: number
+  /** 0 = stored, 3 = Oodle (the only two seen); anything else is refused by name. */
+  method: number
+  compressor: number
+  blockSize: number
+  rawSize: number
+  compressedSize: number
+  blocks: { offset: number, size: number, rawSize: number }[]
+}
+
+/** The header at `offset`, or null when the bytes there are not one. */
+export const readCompressedBuffer = (bytes: Uint8Array, offset: number): CompressedBuffer | null => {
+  if (offset + HEADER_SIZE > bytes.byteLength) return null
+  for (let i = 0; i < 4; i++) if (bytes[offset + i] !== COMPRESSED_BUFFER_MAGIC[i]) return null
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const method = bytes[offset + 8], compressor = bytes[offset + 9], blockExp = bytes[offset + 11]
+  const blockCount = dv.getUint32(offset + 12)
+  const rawSize = Number(dv.getBigUint64(offset + 16))
+  const compressedSize = Number(dv.getBigUint64(offset + 24))
+  if (blockExp < 8 || blockExp > 30 || blockCount > 1 << 20 || rawSize < 0) return null
+  const blockSize = 1 << blockExp
+  if (method !== 0 && blockCount !== Math.ceil(rawSize / blockSize)) return null
+  const blocks: CompressedBuffer["blocks"] = []
+  let o = offset + HEADER_SIZE + (method === 0 ? 0 : blockCount * 4)
+  if (method === 0) {
+    blocks.push({ offset: offset + HEADER_SIZE, size: rawSize, rawSize })
+  } else {
+    let written = 0
+    for (let i = 0; i < blockCount; i++) {
+      const size = dv.getUint32(offset + HEADER_SIZE + i * 4)
+      const want = Math.min(blockSize, rawSize - written)
+      blocks.push({ offset: o, size, rawSize: want })
+      o += size
+      written += want
+    }
+  }
+  if (o > bytes.byteLength) return null
+  return { offset, method, compressor, blockSize, rawSize, compressedSize, blocks }
+}
+
+/** The first `FCompressedBuffer` at or after `from` (default: where a package's bulk data starts). */
+export const findCompressedBuffer = (pkg: UePackage, from = pkg.summary.bulkDataStartOffset): CompressedBuffer | null => {
+  const bytes = pkg.bytes
+  const start = Math.max(0, Math.min(from, bytes.byteLength))
+  for (let i = start; i + HEADER_SIZE <= bytes.byteLength; i++) {
+    if (bytes[i] !== COMPRESSED_BUFFER_MAGIC[0]) continue
+    const buf = readCompressedBuffer(bytes, i)
+    if (buf) return buf
+  }
+  return null
+}
+
+/** Decompress a buffer's blocks. Needs the Oodle decoder unless every block is stored. */
+export const decodeCompressedBuffer = async (pkg: UePackage, buf: CompressedBuffer): Promise<Uint8Array> => {
+  const out = new Uint8Array(buf.rawSize)
+  const needsOodle = buf.method !== 0 && buf.blocks.some((b) => b.size !== b.rawSize)
+  const oodle = needsOodle ? await getOodle() : null
+  if (needsOodle && !oodle) throw new Error(findOodle() ? OODLE_NO_RUNTIME_MESSAGE : OODLE_MISSING_MESSAGE)
+  if (buf.method !== 0 && buf.method !== 3) throw new Error(`${pkg.label}: compressed buffer method ${buf.method} is not supported (0 = stored, 3 = Oodle)`)
+  let written = 0
+  for (const b of buf.blocks) {
+    const src = pkg.bytes.subarray(b.offset, b.offset + b.size)
+    if (src.byteLength !== b.size) throw new Error(`${pkg.label}: compressed block at ${b.offset} runs past the file`)
+    out.set(b.size === b.rawSize ? src : oodle!.decompress(src, b.rawSize), written)
+    written += b.rawSize
+  }
+  return out
+}
+
+// ---- the texture asset ---------------------------------------------------------------------------
+
+/** `ETextureSourceFormat` values that matter here; anything else is reported, not guessed at. */
+export type UeTextureSource = {
+  width: number
+  height: number
+  mips: number
+  slices: number
+  /** `TSF_BGRA8`, `TSF_G8`, `TSF_RGBA16F`, … (absent in a few 5.0 assets → ""). */
+  format: string
+  /** `TSCF_PNG` / `TSCF_JPEG` / `TSCF_None`; UE 5.0 says the same thing with `bPNGCompressed`. */
+  compression: string
+}
+
+export type UeTexture = {
+  name: string
+  source: UeTextureSource
+  /** `TC_Default`, `TC_Normalmap`, `TC_Masks`, … — what the material does with it. */
+  compressionSettings: string
+  srgb: boolean
+  /** The imported file's own path, when the asset still remembers it. */
+  sourceFile: string
+}
+
+/** The `Texture2D` export's own facts (no payload work). */
+export const readTexture2D = (pkg: UePackage): UeTexture => {
+  const found = findExport(pkg, "Texture2D")
+  if (!found) throw new Error(`${pkg.label}: no Texture2D export`)
+  const { reader: r, props } = readObjectProperties(pkg, found.export)
+  const srcTag = props.byName.get("Source")
+  const source: UeTextureSource = { width: 0, height: 0, mips: 1, slices: 1, format: "", compression: "" }
+  if (srcTag) {
+    r.offset = srcTag.data
+    const s = readProperties(r, pkg)
+    source.width = propInt(r, s.byName.get("SizeX")) ?? 0
+    source.height = propInt(r, s.byName.get("SizeY")) ?? 0
+    source.mips = propInt(r, s.byName.get("NumMips")) ?? 1
+    source.slices = propInt(r, s.byName.get("NumSlices")) ?? 1
+    source.format = propEnum(r, pkg.names, s.byName.get("Format")) ?? ""
+    source.compression = propEnum(r, pkg.names, s.byName.get("CompressionFormat"))
+      ?? (s.byName.get("bPNGCompressed")?.bool ? "TSCF_PNG" : "")
+  }
+  return {
+    name: found.export.objectName,
+    source,
+    compressionSettings: propEnum(r, pkg.names, props.byName.get("CompressionSettings")) ?? "TC_Default",
+    srgb: props.byName.get("SRGB")?.bool ?? true,
+    sourceFile: sourceFileOf(pkg, r, props),
+  }
+}
+
+/** `AssetImportData`'s JSON blob keeps the file the texture was imported from; nice for reports. */
+const sourceFileOf = (pkg: UePackage, r: BinaryReader, props: ReturnType<typeof readProperties>): string => {
+  try {
+    const tag = props.byName.get("AssetImportData")
+    if (!tag) return ""
+    const idx = propInt(r, tag) ?? 0
+    if (idx <= 0) return ""
+    const e = pkg.exports[idx - 1]
+    if (!e) return ""
+    const { reader: er, props: p } = readObjectProperties(pkg, e)
+    const json = propString(er, p.byName.get("SourceData")) ?? ""
+    const m = /"RelativeFilename"\s*:\s*"([^"]+)"/.exec(json)
+    return m ? m[1] : ""
+  } catch { return "" }
+}
+
+export type ExtractedImage = {
+  /** The source file as it sits in the asset (PNG/JPEG bytes), plus what it is. */
+  data: Uint8Array
+  mimeType: string
+  /** True when the channels are B,G,R and a red/blue swap is owed (`TSF_BGRA8`). */
+  swapRb: boolean
+  texture: UeTexture
+}
+
+const startsWith = (b: Uint8Array, at: number, sig: number[]): boolean => sig.every((v, i) => b[at + i] === v)
+const PNG_SIG = [ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a ]
+const JPEG_SIG = [ 0xff, 0xd8, 0xff ]
+
+/** Where the image file starts inside a decompressed payload (UE writes it verbatim). */
+const imageAt = (payload: Uint8Array): { at: number, mimeType: string } | null => {
+  const limit = Math.min(payload.byteLength, 4096)
+  for (let i = 0; i < limit; i++) {
+    if (startsWith(payload, i, PNG_SIG)) return { at: i, mimeType: "image/png" }
+    if (startsWith(payload, i, JPEG_SIG)) return { at: i, mimeType: "image/jpeg" }
+  }
+  return null
+}
+
+/**
+ * The image inside a texture asset. Throws with the Oodle message when the decoder is missing —
+ * callers that can live without textures should catch it and say so once.
+ */
+export const extractTexture = async (pkg: UePackage): Promise<ExtractedImage> => {
+  const texture = readTexture2D(pkg)
+  const buf = findCompressedBuffer(pkg)
+  if (!buf) throw new Error(`${pkg.label}: no source image payload (a texture with its source stripped?)`)
+  const payload = await decodeCompressedBuffer(pkg, buf)
+  const img = imageAt(payload)
+  if (!img) {
+    throw new Error(`${pkg.label}: the payload is raw ${texture.source.format || "pixels"} (${texture.source.width}×${texture.source.height}), not a PNG/JPEG — not supported yet`)
+  }
+  return {
+    data: payload.subarray(img.at),
+    mimeType: img.mimeType,
+    // UE fills a TSF_BGRA8 source straight from BGRA memory, so the file's R and B are the other
+    // way round. Formats that name their order (RGBA8, G8, …) need no swap.
+    swapRb: /^TSF_BGRA8/i.test(texture.source.format),
+    texture,
+  }
+}

package/src/unreal/toDocument.ts

@@ -0,0 +1,360 @@
+// 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
+
+  // ---- 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
+      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
+      })
+    }
+
+    // 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,100 @@
+// 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,
+  INNER_ARRAY_TAG_INFO: 500,
+  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 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"
+}