lecodes-assets 0.2.0 → 2.4.10

package/src/unreal/package.ts

@@ -0,0 +1,677 @@
+// Reader for UNCOOKED Unreal Engine 5 editor packages (`.uasset`: one file per asset, everything
+// inline — no `.uexp`/`.ubulk`/`.pak`). What an asset-store pack's Content folder is made of.
+//
+// A package = summary + name table + import table (references to other packages/classes) + export
+// table (the objects in this file) + the exports' serialized bytes + bulk data + a trailing tag.
+// Object references are PACKAGE INDICES: > 0 → export n−1, < 0 → import −n−1, 0 → null.
+//
+// Only the uncooked editor form is handled, for UE 5.0 … 5.7 (`FileVersionUE5` 1004–1018, see
+// `versions.ts`). UE4 packages carry float FTransforms and a different export layout and are refused
+// with a message rather than guessed at, as is anything newer than the last verified version — unless
+// the caller opts in (`{ ue4: true }`): the summary, the tables and the tag list are version-gated
+// field by field and read UE 4.25+ files as they are, so a texture's source image or a sound's WAV
+// comes out of a UE4 pack the same way. Meshes and clips stay UE5-only.
+//
+// See docs/unreal-assets-plan.md §3 — every layout here was verified byte-for-byte against real
+// files from packs saved by 5.0, 5.3, 5.4, 5.5, 5.6 and 5.7.
+
+import { inflateSync } from "node:zlib"
+import { UE4, UE5, LEGACY, UE5_VERSION_MIN, UE5_VERSION_MAX, UE4_VERSION_MIN, releaseOfVersion } from "./versions"
+
+export { UE5_VERSION_MIN, UE5_VERSION_MAX } from "./versions"
+
+export const PACKAGE_FILE_TAG = 0x9e2a83c1
+
+const PKG_FILTER_EDITOR_ONLY = 0x80000000
+
+// ---- binary reader ------------------------------------------------------------------------------
+
+export class BinaryReader {
+  readonly data: Uint8Array
+  readonly view: DataView
+  offset: number
+  /** Named in error messages so a malformed file says WHERE it broke. */
+  label: string
+
+  constructor(data: Uint8Array, offset = 0, label = "package") {
+    this.data = data
+    this.view = new DataView(data.buffer, data.byteOffset, data.byteLength)
+    this.offset = offset
+    this.label = label
+  }
+
+  get remaining(): number { return this.data.byteLength - this.offset }
+
+  private need(n: number): void {
+    if (n < 0 || this.offset + n > this.data.byteLength) {
+      throw new Error(`${this.label}: read of ${n} bytes at offset ${this.offset} runs past the end (${this.data.byteLength})`)
+    }
+  }
+  u8(): number { this.need(1); return this.data[this.offset++] }
+  u16(): number { this.need(2); const v = this.view.getUint16(this.offset, true); this.offset += 2; return v }
+  i32(): number { this.need(4); const v = this.view.getInt32(this.offset, true); this.offset += 4; return v }
+  u32(): number { this.need(4); const v = this.view.getUint32(this.offset, true); this.offset += 4; return v }
+  f32(): number { this.need(4); const v = this.view.getFloat32(this.offset, true); this.offset += 4; return v }
+  f64(): number { this.need(8); const v = this.view.getFloat64(this.offset, true); this.offset += 8; return v }
+  i64(): number {
+    this.need(8)
+    const v = this.view.getBigInt64(this.offset, true)
+    this.offset += 8
+    if (v > 9007199254740991n || v < -9007199254740991n) throw new Error(`${this.label}: 64-bit value ${v} at ${this.offset - 8} is out of the safe integer range`)
+    return Number(v)
+  }
+  raw(n: number): Uint8Array { this.need(n); const v = this.data.subarray(this.offset, this.offset + n); this.offset += n; return v }
+  skip(n: number): void { this.need(n); this.offset += n }
+  /** `f32` × n as a plain array (small fixed-size records: transforms, keys). */
+  floats(n: number): number[] { const out = new Array<number>(n); for (let i = 0; i < n; i++) out[i] = this.f32(); return out }
+  doubles(n: number): number[] { const out = new Array<number>(n); for (let i = 0; i < n; i++) out[i] = this.f64(); return out }
+
+  /** FString: `i32 len`; len > 0 → Latin-1 bytes incl. trailing NUL; len < 0 → UTF-16LE units incl. NUL. */
+  fstring(): string {
+    const n = this.i32()
+    if (n === 0) return ""
+    if (n < 0) {
+      const units = -n
+      if (units > 1 << 22) throw new Error(`${this.label}: implausible UTF-16 string length ${units} at ${this.offset - 4}`)
+      const b = this.raw(units * 2)
+      let s = ""
+      for (let i = 0; i < units; i++) s += String.fromCharCode(b[i * 2] | (b[i * 2 + 1] << 8))
+      return s.replace(/\0+$/, "")
+    }
+    if (n > 1 << 22) throw new Error(`${this.label}: implausible string length ${n} at ${this.offset - 4}`)
+    const b = this.raw(n)
+    let s = ""
+    for (let i = 0; i < n; i++) s += String.fromCharCode(b[i])
+    return s.replace(/\0+$/, "")
+  }
+}
+
+// ---- summary ------------------------------------------------------------------------------------
+
+export type EngineVersion = { major: number, minor: number, patch: number, changelist: number, branch: string }
+
+export type UeSummary = {
+  legacy: number
+  /** `FileVersionUE4` — 522 in every UE5 file seen. */
+  ue4: number
+  /** `FileVersionUE5` — 1004 (5.0) … 1018 (5.7); 0 for UE4 packages. */
+  ue5: number
+  totalHeaderSize: number
+  packageName: string
+  packageFlags: number
+  nameCount: number
+  nameOffset: number
+  exportCount: number
+  exportOffset: number
+  importCount: number
+  importOffset: number
+  /** Base for every bulk payload offset (§3.6). */
+  bulkDataStartOffset: number
+  /** UE 5.2+ package trailer (textures live there); −1 when absent. */
+  payloadTocOffset: number
+  /** UE 5.3+ bulk/data resource table; 0 when the package has none. */
+  dataResourceOffset: number
+  savedBy?: EngineVersion
+}
+
+/**
+ * `FPackageFileSummary`, field by field (versions gate the layout — never a fixed stride).
+ *
+ * Two shapes of head exist: up to UE 5.5 the custom versions come right after the licensee version
+ * and the header size after them; from `PACKAGE_SAVED_HASH` (5.6, which also bumped the legacy
+ * version to −9) a 20-byte saved hash and the header size are written BEFORE the custom versions,
+ * and the guid further down is gone. The UE3 field is still written at −9.
+ */
+export const readSummary = (bytes: Uint8Array, label: string): UeSummary => {
+  const r = new BinaryReader(bytes, 0, label)
+  const tag = r.u32()
+  if (tag !== PACKAGE_FILE_TAG) throw new Error(`${label}: not a .uasset (tag 0x${tag.toString(16)})`)
+  const legacy = r.i32()
+  // The legacy version fixes the shape of everything after it. Guessing past an unknown one reads
+  // garbage (a 5.6 file decoded as an "implausible string length" before −9 was known), so stop here.
+  if (legacy < LEGACY.UE5_6) throw new Error(`${label}: package format ${legacy} is newer than any this reader knows (UE 5.7 = ${LEGACY.UE5_6}) — re-save the asset from UE 5.7 or earlier, or export FBX.`)
+  if (legacy > -6) throw new Error(`${label}: package format ${legacy} predates UE4 — not supported`)
+  if (legacy !== -4) r.i32()                              // legacy UE3 file version
+  const ue4 = r.i32()
+  const ue5 = legacy <= LEGACY.UE5 ? r.i32() : 0
+  r.i32()                                                 // licensee version
+  let totalHeaderSize = 0
+  if (ue5 >= UE5.PACKAGE_SAVED_HASH) { r.skip(20); totalHeaderSize = r.i32() }   // saved hash (FIoHash)
+  const nCustom = r.i32()
+  for (let i = 0; i < nCustom; i++) { r.skip(16); r.i32() }
+  if (ue5 < UE5.PACKAGE_SAVED_HASH) totalHeaderSize = r.i32()
+  const packageName = r.fstring()
+  const packageFlags = r.u32()
+  const editorOnly = (packageFlags & PKG_FILTER_EDITOR_ONLY) !== 0
+  const nameCount = r.i32(), nameOffset = r.i32()
+  if (ue5 >= UE5.ADD_SOFTOBJECTPATH_LIST) { r.i32(); r.i32() }        // soft object paths count/offset
+  if (!editorOnly && ue4 >= UE4.ADDED_PACKAGE_SUMMARY_LOCALIZATION_ID) r.fstring()
+  if (ue4 >= UE4.SERIALIZE_TEXT_IN_PACKAGES) { r.i32(); r.i32() }     // gatherable text count/offset
+  const exportCount = r.i32(), exportOffset = r.i32()
+  const importCount = r.i32(), importOffset = r.i32()
+  if (ue5 >= UE5.VERSE_CELLS) r.skip(16)                              // cell export/import count + offset
+  if (ue5 >= UE5.METADATA_SERIALIZATION_OFFSET) r.i32()               // metadata offset
+  r.i32()                                                             // depends offset
+  if (ue4 >= UE4.ADD_STRING_ASSET_REFERENCES_MAP) { r.i32(); r.i32() }  // soft package references
+  if (ue4 >= UE4.ADDED_SEARCHABLE_NAMES) r.i32()                      // searchable names offset
+  r.i32()                                                             // thumbnail table offset
+  if (ue5 >= UE5.IMPORT_TYPE_HIERARCHIES) { r.i32(); r.i32() }       // import type hierarchies count/offset
+  if (ue5 < UE5.PACKAGE_SAVED_HASH) r.skip(16)                        // guid (replaced by the saved hash)
+  if (!editorOnly) {
+    if (ue4 >= UE4.ADDED_PACKAGE_OWNER) r.skip(16)                    // persistent guid
+    if (ue4 >= UE4.ADDED_PACKAGE_OWNER && ue4 < UE4.NON_OUTER_PACKAGE_IMPORT) r.skip(16)   // owner persistent guid
+  }
+  const nGen = r.i32()
+  if (nGen < 0 || nGen > 1024) throw new Error(`${label}: implausible generation count ${nGen} at ${r.offset - 4} — the summary layout is not the one this reader expects`)
+  for (let i = 0; i < nGen; i++) { r.i32(); r.i32() }
+  const engver = (): EngineVersion => ({ major: r.u16(), minor: r.u16(), patch: r.u16(), changelist: r.u32(), branch: r.fstring() })
+  const savedBy = ue4 >= UE4.ENGINE_VERSION_OBJECT ? engver() : undefined
+  if (ue4 >= UE4.PACKAGE_SUMMARY_HAS_COMPATIBLE_ENGINE_VERSION) engver()
+  r.u32()                                                             // compression flags
+  const nChunks = r.i32()
+  if (nChunks !== 0) throw new Error(`${label}: package-level compression is not supported (${nChunks} chunks)`)
+  r.u32()                                                             // package source
+  const nAdditional = r.i32()
+  for (let i = 0; i < nAdditional; i++) r.fstring()
+  if (legacy > LEGACY.UE4) r.i32()                                    // num texture allocations
+  r.i32()                                                             // asset registry data offset
+  const bulkDataStartOffset = r.i64()
+  r.i32()                                                             // world tile info offset
+  { const n = r.i32(); for (let i = 0; i < n; i++) r.i32() }          // chunk ids
+  if (ue4 >= UE4.PRELOAD_DEPENDENCIES_IN_COOKED_EXPORTS) { r.i32(); r.i32() }
+  if (ue5 >= UE5.NAMES_REFERENCED_FROM_EXPORT_DATA) r.i32()
+  const payloadTocOffset = ue5 >= UE5.PAYLOAD_TOC ? r.i64() : -1
+  const dataResourceOffset = ue5 >= UE5.DATA_RESOURCES ? r.i32() : 0
+  if (r.offset !== nameOffset) {
+    throw new Error(`${label}: the summary ends at ${r.offset} but the name table starts at ${nameOffset} — the summary layout of this ${engineLabel({ ue4, ue5, savedBy } as UeSummary)} file is not the one this reader expects`)
+  }
+
+  return { legacy, ue4, ue5, totalHeaderSize, packageName, packageFlags, nameCount, nameOffset, exportCount, exportOffset, importCount, importOffset, bulkDataStartOffset, payloadTocOffset, dataResourceOffset, savedBy }
+}
+
+/** The engine that saved a package, as "UE 5.0" / "UE 5.4.4" (what the refusals talk about). */
+export const engineLabel = (s: UeSummary): string =>
+  s.savedBy && s.savedBy.major ? `UE ${s.savedBy.major}.${s.savedBy.minor}${s.savedBy.patch ? `.${s.savedBy.patch}` : ""}` : s.ue5 ? `UE ${releaseOfVersion(s.ue5)} (version ${s.ue5})` : `UE? (ue4 ${s.ue4}, ue5 ${s.ue5})`
+
+export type ReadPackageOptions = {
+  /**
+   * Accept a UE4 package (legacy −7, `FileVersionUE4` ≥ `UE4_VERSION_MIN`). The tables and the tag
+   * list read the same way there; what differs is class payloads — float transforms, mesh and clip
+   * layouts — so only readers that do not depend on those opt in (texture sources, sounds).
+   */
+  ue4?: boolean
+}
+
+const checkVersion = (s: UeSummary, label: string, opts: ReadPackageOptions): void => {
+  if (s.legacy > LEGACY.UE5 || s.ue5 === 0) {
+    if (!opts.ue4) throw new Error(`${label}: a UE4 package (legacy ${s.legacy}) — only UE 5.0–5.7 uncooked assets are supported. Export the asset to FBX from the editor instead.`)
+    if (s.ue4 < UE4_VERSION_MIN) throw new Error(`${label}: a UE4 package of version ${s.ue4} — older than any this reader has been verified on (${UE4_VERSION_MIN}, UE 4.25)`)
+    if ((s.packageFlags & PKG_FILTER_EDITOR_ONLY) !== 0) throw new Error(`${label}: a COOKED package (editor data stripped) — this reader needs the uncooked editor asset from a pack's Content folder`)
+    return
+  }
+  if (s.ue5 < UE5_VERSION_MIN) throw new Error(`${label}: package version ${s.ue5} predates UE 5.0 — not supported`)
+  if (s.ue5 > UE5_VERSION_MAX) {
+    throw new Error(`${label}: ${engineLabel(s)} package (version ${s.ue5}) is newer than any this reader has been verified on (UE 5.7 = ${UE5_VERSION_MAX}). Re-save the asset from UE 5.7 or earlier, or export FBX.`)
+  }
+  if ((s.packageFlags & PKG_FILTER_EDITOR_ONLY) !== 0) {
+    throw new Error(`${label}: a COOKED package (editor data stripped) — this reader needs the uncooked editor asset from a pack's Content folder`)
+  }
+}
+
+// ---- name / import / export tables ---------------------------------------------------------------
+
+export type UeImport = { classPackage: string, className: string, outerIndex: number, objectName: string, packageName: string }
+export type UeExport = {
+  classIndex: number, superIndex: number, templateIndex: number, outerIndex: number
+  objectName: string, objectFlags: number
+  serialSize: number, serialOffset: number
+  /** `bIsAsset` — the export the package is named for (the AnimSequence, not its data model). */
+  isAsset: boolean
+  /**
+   * Where the tagged properties sit inside the export's bytes (UE 5.4+, `SCRIPT_SERIALIZATION_OFFSET`),
+   * relative to `serialOffset`; −1 when the file predates them. Some classes write native data
+   * BEFORE their tag list (`UAssetImportData`'s JSON), which is what these offsets are for.
+   */
+  scriptStart: number
+  scriptEnd: number
+}
+
+const readNames = (bytes: Uint8Array, s: UeSummary, label: string): string[] => {
+  const r = new BinaryReader(bytes, s.nameOffset, label)
+  const out: string[] = new Array(s.nameCount)
+  for (let i = 0; i < s.nameCount; i++) {
+    out[i] = r.fstring()
+    if (s.ue4 >= UE4.NAME_HASHES_SERIALIZED) r.u32()          // two u16 hashes
+  }
+  return out
+}
+
+/** FName: `i32 index, i32 number`; number > 0 appends `_${number-1}` (`AnimationDataModel_0`). */
+export const readFName = (r: BinaryReader, names: string[]): string => {
+  const i = r.i32(), n = r.i32()
+  if (i < 0 || i >= names.length) throw new Error(`${r.label}: name index ${i} out of range (${names.length}) at offset ${r.offset - 8}`)
+  return n > 0 ? `${names[i]}_${n - 1}` : names[i]
+}
+
+const readImports = (bytes: Uint8Array, s: UeSummary, names: string[], label: string): UeImport[] => {
+  const r = new BinaryReader(bytes, s.importOffset, label)
+  const editorOnly = (s.packageFlags & PKG_FILTER_EDITOR_ONLY) !== 0
+  const out: UeImport[] = []
+  for (let i = 0; i < s.importCount; i++) {
+    const classPackage = readFName(r, names)
+    const className = readFName(r, names)
+    const outerIndex = r.i32()
+    const objectName = readFName(r, names)
+    const packageName = s.ue4 >= UE4.NON_OUTER_PACKAGE_IMPORT && !editorOnly ? readFName(r, names) : ""
+    if (s.ue5 >= UE5.OPTIONAL_RESOURCES) r.i32()         // bImportOptional
+    out.push({ classPackage, className, outerIndex, objectName, packageName })
+  }
+  if (r.offset !== s.exportOffset) throw new Error(`${label}: the import table ends at ${r.offset}, the export table starts at ${s.exportOffset} — import layout mismatch`)
+  return out
+}
+
+const readExports = (bytes: Uint8Array, s: UeSummary, names: string[], label: string): UeExport[] => {
+  const r = new BinaryReader(bytes, s.exportOffset, label)
+  const out: UeExport[] = []
+  for (let i = 0; i < s.exportCount; i++) {
+    const classIndex = r.i32(), superIndex = r.i32()
+    const templateIndex = s.ue4 >= UE4.TEMPLATE_INDEX_IN_COOKED_EXPORTS ? r.i32() : 0
+    const outerIndex = r.i32()
+    const objectName = readFName(r, names)
+    const objectFlags = r.u32()
+    const serialSize = s.ue4 >= UE4.BIG_EXPORT_SIZE_FIXES ? r.i64() : r.i32()
+    const serialOffset = s.ue4 >= UE4.BIG_EXPORT_SIZE_FIXES ? r.i64() : r.i32()
+    r.i32(); r.i32(); r.i32()                                          // bForcedExport / bNotForClient / bNotForServer
+    if (s.ue5 < UE5.REMOVE_OBJECT_EXPORT_PACKAGE_GUID) r.skip(16)      // package guid
+    if (s.ue5 >= UE5.TRACK_OBJECT_EXPORT_IS_INHERITED) r.i32()         // bIsInheritedInstance
+    r.u32()                                                            // package flags
+    r.i32()                                                            // bNotAlwaysLoadedForEditorGame
+    const isAsset = s.ue4 >= UE4.COOKED_ASSETS_IN_EDITOR_SUPPORT ? r.i32() !== 0 : false
+    if (s.ue5 >= UE5.OPTIONAL_RESOURCES) r.i32()                       // bGeneratePublicHash
+    if (s.ue4 >= UE4.PRELOAD_DEPENDENCIES_IN_COOKED_EXPORTS) r.skip(20)  // 5 × dependency index/count
+    let scriptStart = -1, scriptEnd = -1
+    if (s.ue5 >= UE5.SCRIPT_SERIALIZATION_OFFSET) { scriptStart = r.i64(); scriptEnd = r.i64() }
+    if (serialOffset < 0 || serialSize < 0 || serialOffset + serialSize > bytes.byteLength) {
+      throw new Error(`${label}: export ${i} ("${objectName}") claims bytes [${serialOffset}, ${serialOffset + serialSize}) outside the file (${bytes.byteLength})`)
+    }
+    if (scriptStart >= 0 && (scriptStart > scriptEnd || scriptEnd > serialSize)) {
+      throw new Error(`${label}: export ${i} ("${objectName}") puts its properties at [${scriptStart}, ${scriptEnd}) of ${serialSize} bytes — export layout mismatch`)
+    }
+    out.push({ classIndex, superIndex, templateIndex, outerIndex, objectName, objectFlags, serialSize, serialOffset, isAsset, scriptStart, scriptEnd })
+  }
+  return out
+}
+
+// ---- the package --------------------------------------------------------------------------------
+
+export type UePackage = {
+  label: string
+  bytes: Uint8Array
+  summary: UeSummary
+  names: string[]
+  imports: UeImport[]
+  exports: UeExport[]
+}
+
+export const readPackage = (bytes: Uint8Array, label = "package", opts: ReadPackageOptions = {}): UePackage => {
+  const summary = readSummary(bytes, label)
+  checkVersion(summary, label, opts)
+  const names = readNames(bytes, summary, label)
+  const imports = readImports(bytes, summary, names, label)
+  const exports = readExports(bytes, summary, names, label)
+  return { label, bytes, summary, names, imports, exports }
+}
+
+/** Class name of an export ("AnimSequence", "SkeletalMesh", "AnimDataModel", …). */
+export const classOf = (pkg: UePackage, e: UeExport): string => {
+  if (e.classIndex < 0) return pkg.imports[-e.classIndex - 1]?.objectName ?? "?"
+  if (e.classIndex > 0) return pkg.exports[e.classIndex - 1]?.objectName ?? "?"
+  return "Class"
+}
+
+/** The first export of a class, or undefined. */
+export const findExport = (pkg: UePackage, className: string): { index: number, export: UeExport } | undefined => {
+  for (let i = 0; i < pkg.exports.length; i++) if (classOf(pkg, pkg.exports[i]) === className) return { index: i, export: pkg.exports[i] }
+  return undefined
+}
+
+/**
+ * The export the package IS — the one flagged as the asset (an AnimMontage, not the AnimDataModel
+ * sitting next to it); falls back to the first export that is not the metadata object.
+ */
+export const assetExport = (pkg: UePackage): UeExport | undefined =>
+  pkg.exports.find((e) => e.isAsset) ?? pkg.exports.find((e) => classOf(pkg, e) !== "MetaData") ?? pkg.exports[0]
+
+/** A reader over one export's serialized bytes. Offsets stay FILE-absolute so bulk offsets line up. */
+export const exportReader = (pkg: UePackage, e: UeExport): BinaryReader =>
+  new BinaryReader(pkg.bytes.subarray(0, e.serialOffset + e.serialSize), e.serialOffset, `${pkg.label}:${e.objectName}`)
+
+export type UeObjectRef = { kind: "import" | "export", index: number, name: string, className: string, packagePath: string }
+
+/** Resolve a package index (what an ObjectProperty carries) to what it points at. */
+export const resolveObject = (pkg: UePackage, packageIndex: number): UeObjectRef | null => {
+  if (packageIndex === 0) return null
+  if (packageIndex > 0) {
+    const i = packageIndex - 1
+    const e = pkg.exports[i]
+    if (!e) return null
+    return { kind: "export", index: i, name: e.objectName, className: classOf(pkg, e), packagePath: pkg.summary.packageName }
+  }
+  const i = -packageIndex - 1
+  const imp = pkg.imports[i]
+  if (!imp) return null
+  return { kind: "import", index: i, name: imp.objectName, className: imp.className, packagePath: importPackagePath(pkg, i) }
+}
+
+/** Walk an import's outer chain to the `/Game/...` package it lives in. */
+export const importPackagePath = (pkg: UePackage, index: number): string => {
+  let cur: UeImport | undefined = pkg.imports[index]
+  const seen = new Set<number>([ index ])
+  while (cur) {
+    if (cur.className === "Package" && cur.objectName.startsWith("/")) return cur.objectName
+    if (cur.packageName.startsWith("/")) return cur.packageName
+    if (cur.outerIndex >= 0) break
+    const next: number = -cur.outerIndex - 1
+    if (seen.has(next)) break
+    seen.add(next)
+    cur = pkg.imports[next]
+  }
+  return ""
+}
+
+// ---- tagged properties (§3.5) ---------------------------------------------------------------------
+
+/**
+ * A property's type as the UE 5.4+ tag writes it: a tree of names — `StructProperty` with the struct
+ * (`Vector3f`, itself carrying its package `/Script/CoreUObject`) as its parameter, `ArrayProperty`
+ * with its element type, `EnumProperty` with the enum and the underlying type. Older files are lifted
+ * into the same shape from their per-type extras, so readers see one representation.
+ */
+export type PropertyTypeName = { name: string, params: PropertyTypeName[] }
+
+export type PropertyTag = {
+  name: string
+  /** Root of the type tree: `IntProperty`, `StructProperty`, `ArrayProperty`, … */
+  type: string
+  typeName: PropertyTypeName
+  size: number
+  arrayIndex: number
+  /** File offset of the payload (`size` bytes). */
+  data: number
+  /** StructProperty: the struct's name; Array/Set/OptionalProperty: the element type; Byte/EnumProperty: the enum. */
+  struct?: string
+  inner?: string
+  enumName?: string
+  keyType?: string
+  valueType?: string
+  /** BoolProperty carries its value in the tag itself. */
+  bool?: boolean
+  /** UE 5.4+ flags say the struct payload is native bytes rather than a tag list; undefined before. */
+  native?: boolean
+}
+
+// EPropertyTagFlags (UE 5.4+, `PROPERTY_TAG_COMPLETE_TYPE_NAME`)
+const TAG_HAS_ARRAY_INDEX = 0x01
+const TAG_HAS_PROPERTY_GUID = 0x02
+const TAG_HAS_PROPERTY_EXTENSIONS = 0x04
+const TAG_HAS_BINARY_OR_NATIVE_SERIALIZE = 0x08
+const TAG_BOOL_TRUE = 0x10
+// EPropertyTagExtension
+const TAG_EXT_OVERRIDABLE_INFORMATION = 0x02
+// EClassSerializationControlExtension (the byte that opens an object's tag list, UE 5.4+)
+const CLASS_EXT_OVERRIDABLE_INFORMATION = 0x02
+
+/** `FPropertyTypeName`: nodes in pre-order, each an FName and how many parameters follow it. */
+const readTypeName = (r: BinaryReader, names: string[], depth = 0): PropertyTypeName => {
+  const name = readFName(r, names)
+  const n = r.i32()
+  if (n < 0 || n > 16 || depth > 16) throw new Error(`${r.label}: property type "${name}" claims ${n} parameters at ${r.offset - 4} — not a type name`)
+  const params: PropertyTypeName[] = []
+  for (let i = 0; i < n; i++) params.push(readTypeName(r, names, depth + 1))
+  return { name, params }
+}
+
+/** The old per-type extras (struct name, inner type, enum) as the same tree the new files write. */
+const liftTypeName = (type: string, extras: { struct?: string, inner?: string, enumName?: string, keyType?: string, valueType?: string }): PropertyTypeName => {
+  const leaf = (name?: string): PropertyTypeName[] => (name && name !== "None" ? [ { name, params: [] } ] : [])
+  if (type === "StructProperty") return { name: type, params: leaf(extras.struct) }
+  if (type === "ArrayProperty" || type === "SetProperty" || type === "OptionalProperty") return { name: type, params: leaf(extras.inner) }
+  if (type === "ByteProperty" || type === "EnumProperty") return { name: type, params: leaf(extras.enumName) }
+  if (type === "MapProperty") return { name: type, params: [ ...leaf(extras.keyType), ...leaf(extras.valueType) ] }
+  return { name: type, params: [] }
+}
+
+/** Fill the convenience fields (`struct`, `inner`, …) from the tree. */
+const deriveTypeFields = (tag: PropertyTag): void => {
+  const t = tag.typeName
+  const p0 = t.params[0]?.name
+  if (t.name === "StructProperty") tag.struct = p0
+  else if (t.name === "ArrayProperty" || t.name === "SetProperty" || t.name === "OptionalProperty") tag.inner = p0
+  else if (t.name === "ByteProperty" || t.name === "EnumProperty") tag.enumName = p0
+  else if (t.name === "MapProperty") { tag.keyType = p0; tag.valueType = t.params[1]?.name }
+}
+
+/** The extension byte both layouts may end with (UE 5.4+): overridable-serialization bookkeeping. */
+const skipTagExtension = (r: BinaryReader): void => {
+  const ext = r.u8()
+  if (ext & TAG_EXT_OVERRIDABLE_INFORMATION) { r.u8(); r.u8() }      // override operation + experimental flag
+}
+
+/**
+ * One `FPropertyTag`; null at the `None` that ends a list. Leaves the reader AT the payload.
+ *
+ * Two layouts. Up to UE 5.3 (and 5.4's early `1011`): type name, size, array index, per-type extras
+ * (struct name + guid, bool value, enum, inner types), an optional property guid. From `1012`: the
+ * type TREE, size, one flags byte that says which of array index / guid / extensions follow and
+ * carries the bool value itself.
+ */
+export const readPropertyTag = (r: BinaryReader, pkg: { names: string[], summary: { ue4?: number, ue5: number } }): PropertyTag | null => {
+  const { names } = pkg
+  const ue5 = pkg.summary.ue5
+  const ue4 = pkg.summary.ue4 ?? UE4.FROZEN
+  const name = readFName(r, names)
+  if (name === "None") return null
+  let tag: PropertyTag
+  if (ue5 >= UE5.PROPERTY_TAG_COMPLETE_TYPE_NAME) {
+    const typeName = readTypeName(r, names)
+    const size = r.i32()
+    const flags = r.u8()
+    tag = { name, type: typeName.name, typeName, size, arrayIndex: 0, data: 0, native: (flags & TAG_HAS_BINARY_OR_NATIVE_SERIALIZE) !== 0 }
+    if (flags & TAG_HAS_ARRAY_INDEX) tag.arrayIndex = r.i32()
+    if (flags & TAG_HAS_PROPERTY_GUID) r.skip(16)
+    if (flags & TAG_HAS_PROPERTY_EXTENSIONS) skipTagExtension(r)
+    if (typeName.name === "BoolProperty") tag.bool = (flags & TAG_BOOL_TRUE) !== 0
+    deriveTypeFields(tag)
+  } else {
+    const type = readFName(r, names)
+    const size = r.i32()
+    const arrayIndex = r.i32()
+    const extras: { struct?: string, inner?: string, enumName?: string, keyType?: string, valueType?: string } = {}
+    let bool: boolean | undefined
+    if (type === "StructProperty") { extras.struct = readFName(r, names); r.skip(16) }
+    else if (type === "BoolProperty") bool = r.u8() !== 0
+    else if (type === "ByteProperty" || type === "EnumProperty") extras.enumName = readFName(r, names)
+    else if (type === "ArrayProperty" || type === "SetProperty" || type === "OptionalProperty") extras.inner = readFName(r, names)
+    else if (type === "MapProperty") { extras.keyType = readFName(r, names); extras.valueType = readFName(r, names) }
+    if (ue4 >= UE4.PROPERTY_GUID_IN_PROPERTY_TAG && r.u8()) r.skip(16)  // optional property guid
+    if (ue5 >= UE5.PROPERTY_TAG_EXTENSION_AND_OVERRIDABLE_SERIALIZATION) skipTagExtension(r)
+    tag = { name, type, typeName: liftTypeName(type, extras), size, arrayIndex, data: 0, ...extras }
+    if (bool !== undefined) tag.bool = bool
+  }
+  tag.data = r.offset
+  if (tag.size < 0 || tag.data + tag.size > r.data.byteLength) {
+    throw new Error(`${r.label}: property "${name}" (${tag.type}) claims ${tag.size} bytes at ${tag.data} — past the end (${r.data.byteLength})`)
+  }
+  return tag
+}
+
+export type Properties = {
+  list: PropertyTag[]
+  byName: Map<string, PropertyTag>
+  /** Offset just past the terminating `None`. */
+  end: number
+}
+
+/**
+ * A whole tag list (a UObject's script properties, or a tagged struct's). Properties equal to their
+ * class default are OMITTED by the serializer — absent is not zero, so every reader below treats a
+ * missing tag as "the engine's default", never as 0.
+ */
+export const readProperties = (r: BinaryReader, pkg: { names: string[], summary: { ue4?: number, ue5: number } }): Properties => {
+  const list: PropertyTag[] = []
+  for (;;) {
+    const tag = readPropertyTag(r, pkg)
+    if (!tag) break
+    list.push(tag)
+    r.offset = tag.data + tag.size
+  }
+  const byName = new Map<string, PropertyTag>()
+  for (const t of list) if (!byName.has(t.name)) byName.set(t.name, t)
+  return { list, byName, end: r.offset }
+}
+
+/**
+ * An OBJECT's tag list — the entry point every class reader uses. Differs from a struct's list in
+ * two ways a caller should not have to know: since UE 5.4 the export table says where the properties
+ * start (a class may write native data first), and the list opens with a class-serialization-control
+ * byte. The reader is left just past the terminating `None`, on the object's native data.
+ */
+export const readObjectProperties = (pkg: UePackage, e: UeExport): { reader: BinaryReader, props: Properties } => {
+  const r = exportReader(pkg, e)
+  if (e.scriptStart >= 0) r.offset = e.serialOffset + e.scriptStart
+  if (pkg.summary.ue5 >= UE5.PROPERTY_TAG_EXTENSION_AND_OVERRIDABLE_SERIALIZATION) {
+    const control = r.u8()
+    if (control & CLASS_EXT_OVERRIDABLE_INFORMATION) r.u8()           // overridable operation
+  }
+  const props = readProperties(r, pkg)
+  return { reader: r, props }
+}
+
+// scalar payload helpers — each seeks to the tag's payload itself
+export const propInt = (r: BinaryReader, t: PropertyTag | undefined): number | undefined => { if (!t) return undefined; r.offset = t.data; return r.i32() }
+export const propFloat = (r: BinaryReader, t: PropertyTag | undefined): number | undefined => { if (!t) return undefined; r.offset = t.data; return r.f32() }
+export const propName = (r: BinaryReader, names: string[], t: PropertyTag | undefined): string | undefined => { if (!t) return undefined; r.offset = t.data; return readFName(r, names) }
+export const propString = (r: BinaryReader, t: PropertyTag | undefined): string | undefined => { if (!t) return undefined; r.offset = t.data; return r.fstring() }
+export const propObject = (r: BinaryReader, t: PropertyTag | undefined): number | undefined => { if (!t) return undefined; r.offset = t.data; return r.i32() }
+/** ByteProperty is an FName when it names an enum, a raw byte otherwise; EnumProperty is always an FName. */
+export const propEnum = (r: BinaryReader, names: string[], t: PropertyTag | undefined): string | undefined => {
+  if (!t) return undefined
+  r.offset = t.data
+  if (t.type === "EnumProperty" || (t.enumName && t.enumName !== "None")) return readFName(r, names)
+  return String(r.u8())
+}
+
+/** Structs serialized as fixed bytes (no tag list inside). Only what this pipeline meets. */
+export const NATIVE_STRUCT_SIZE: Record<string, number> = {
+  Vector3f: 12, Quat4f: 16, Vector2f: 8, Vector4f: 16, Color: 4, LinearColor: 16, Guid: 16,
+  IntPoint: 8, IntVector: 12, Vector: 24, Vector2D: 16, Vector4: 32, Quat: 32, Rotator: 24, Transform: 80,
+}
+
+/**
+ * `ArrayProperty` header: the element count, then — for struct elements in files up to UE 5.3 — an
+ * INNER TAG naming the struct. From `PROPERTY_TAG_COMPLETE_TYPE_NAME` the outer tag's type tree
+ * already carries the element type and the inner tag is gone: the elements follow the count directly.
+ * `elementStruct` is the struct's name either way.
+ */
+export const readArrayHeader = (r: BinaryReader, pkg: { names: string[], summary: { ue4?: number, ue5: number } }, tag: PropertyTag): { count: number, inner: PropertyTag | null, elementStruct: string } => {
+  r.offset = tag.data
+  const count = r.i32()
+  // a struct array's payload opens with an inner tag only from `INNER_ARRAY_TAG_INFO` (UE 4.12)
+  const innerTag = pkg.summary.ue5 < UE5.PROPERTY_TAG_COMPLETE_TYPE_NAME && (pkg.summary.ue4 ?? UE4.FROZEN) >= UE4.INNER_ARRAY_TAG_INFO
+  const inner = tag.inner === "StructProperty" && innerTag ? readPropertyTag(r, pkg) : null
+  const elementStruct = inner?.struct ?? tag.typeName.params[0]?.params[0]?.name ?? ""
+  return { count, inner, elementStruct }
+}
+
+/** `n` float triples/quads straight out of an `ArrayProperty<Vector3f | Quat4f>` payload. */
+export const readFloatArray = (r: BinaryReader, pkg: { names: string[], summary: { ue4?: number, ue5: number } }, tag: PropertyTag): { comps: number, values: Float32Array } => {
+  const { count, elementStruct } = readArrayHeader(r, pkg, tag)
+  const struct = elementStruct || tag.inner || ""
+  const comps = struct === "Quat4f" || struct === "Quat" || struct === "Vector4f" ? 4 : struct === "Vector2f" ? 2 : 3
+  const values = new Float32Array(count * comps)
+  for (let i = 0; i < values.length; i++) values[i] = r.f32()
+  return { comps, values }
+}
+
+// ---- bulk data (§3.6) ------------------------------------------------------------------------------
+
+const BULKDATA_SERIALIZE_COMPRESSED = 0x2
+const BULKDATA_PAYLOAD_IN_SEPARATE_FILE = 0x100
+const BULKDATA_SIZE_64BIT = 0x2000
+const BULKDATA_DUPLICATE_NON_OPTIONAL = 0x4000
+const BULKDATA_BAD_DATA_VERSION = 0x8000
+const BULKDATA_NO_OFFSET_FIX_UP = 0x10000
+
+export type BulkDataHeader = { flags: number, elementCount: number, sizeOnDisk: number, offsetInFile: number }
+
+/** `FByteBulkData`'s header, wherever a class embeds one. Leaves the reader past it. */
+export const readBulkHeader = (r: BinaryReader): BulkDataHeader => {
+  const flags = r.u32()
+  const wide = (flags & BULKDATA_SIZE_64BIT) !== 0
+  const elementCount = wide ? r.i64() : r.i32()
+  const sizeOnDisk = wide ? r.i64() : r.i32()
+  const offsetInFile = r.i64()
+  if (flags & BULKDATA_BAD_DATA_VERSION) r.u16()
+  if (flags & BULKDATA_DUPLICATE_NON_OPTIONAL) { r.u32(); r.i64(); r.i64() }
+  return { flags, elementCount, sizeOnDisk, offsetInFile }
+}
+
+export const bulkIsCompressed = (h: BulkDataHeader): boolean => (h.flags & BULKDATA_SERIALIZE_COMPRESSED) !== 0
+
+/**
+ * The payload a bulk header points at, decompressed when it needs to be.
+ *
+ * The compressed container names its codec with a byte whose table is not reliably known, so the
+ * first chunk is SNIFFED instead: 0x78 = zlib (every UE 5.0 mesh bulk seen); anything else is
+ * reported by name rather than fed to the wrong decoder.
+ */
+export const readBulkPayload = (pkg: UePackage, h: BulkDataHeader): Uint8Array => {
+  if (h.flags & BULKDATA_PAYLOAD_IN_SEPARATE_FILE) {
+    throw new Error(`${pkg.label}: bulk payload lives in a separate .ubulk file — only fully inline (uncooked) packages are supported`)
+  }
+  const base = (h.flags & BULKDATA_NO_OFFSET_FIX_UP) ? 0 : pkg.summary.bulkDataStartOffset
+  const start = base + h.offsetInFile
+  if (start < 0 || start + h.sizeOnDisk > pkg.bytes.byteLength) {
+    throw new Error(`${pkg.label}: bulk payload [${start}, ${start + h.sizeOnDisk}) is outside the file (${pkg.bytes.byteLength})`)
+  }
+  const raw = pkg.bytes.subarray(start, start + h.sizeOnDisk)
+  if (!bulkIsCompressed(h)) return raw
+  return inflateChunked(raw, pkg.label)
+}
+
+/** UE's chunked compressed container (`FArchive::SerializeCompressed`). */
+export const inflateChunked = (raw: Uint8Array, label: string): Uint8Array => {
+  const r = new BinaryReader(raw, 0, `${label} bulk`)
+  const lo = r.u32(), hi = r.u32()
+  if (lo !== PACKAGE_FILE_TAG) throw new Error(`${label}: compressed bulk header tag 0x${lo.toString(16)} is not a package tag — unknown container`)
+  const v2 = hi === 0x22222222
+  const chunkSize = r.i64()
+  let codecName = "zlib"
+  if (v2) {
+    const codec = r.u8()
+    codecName = codec === 0 ? r.fstring() : `codec ${codec}`
+  }
+  const totalCompressed = r.i64(), totalUncompressed = r.i64()
+  if (chunkSize <= 0 || totalUncompressed < 0) throw new Error(`${label}: nonsense compressed bulk header (chunk ${chunkSize}, total ${totalUncompressed})`)
+  const n = Math.ceil(totalUncompressed / chunkSize)
+  const chunks: { c: number, u: number }[] = []
+  for (let i = 0; i < n; i++) chunks.push({ c: r.i64(), u: r.i64() })
+  const out = new Uint8Array(totalUncompressed)
+  let written = 0
+  for (let i = 0; i < n; i++) {
+    const { c, u } = chunks[i]
+    const data = r.raw(c)
+    if (c === u) { out.set(data, written); written += u; continue }
+    const magic = data[0]
+    if (magic !== 0x78) {
+      throw new Error(`${label}: bulk chunk ${i} is ${magic === 0x8c ? "Oodle-compressed" : `compressed with an unsupported codec (${codecName}, first byte 0x${magic.toString(16)})`} — not supported. Export the asset to FBX from the editor instead.`)
+    }
+    const inflated = inflateSync(data)
+    if (inflated.byteLength !== u) throw new Error(`${label}: bulk chunk ${i} inflated to ${inflated.byteLength} bytes, expected ${u}`)
+    out.set(inflated, written)
+    written += inflated.byteLength
+  }
+  if (written !== totalUncompressed) throw new Error(`${label}: bulk payload came to ${written} bytes, header says ${totalUncompressed}`)
+  void totalCompressed
+  return out
+}