lecodes-assets 0.1.2 → 0.2.1

package/src/unreal/list.ts

@@ -0,0 +1,113 @@
+// `unreal ls <dir>` — what a pack holds, before converting anything. Reads only the summary, the
+// name table and the tables (no bulk data, no tracks), so a 796-package pack lists in well under a
+// second; a clip's skeleton comes from its imports, which is enough to group clips by rig.
+//
+// Assets the reader cannot handle are listed with their reason instead of being skipped — the point
+// of listing a pack is to find out what is usable.
+
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { dirname, join, relative, resolve } from "node:path"
+import { resolveObjectFile } from "./resolve"
+import { readPackage, engineLabel, classOf, assetExport } from "./package"
+import { skeletonPathOf } from "./index"
+import { dataModelKind, packageKind } from "./anim"
+
+export type UnrealAssetRow = {
+  file: string
+  kind: ReturnType<typeof packageKind>
+  engine: string
+  /** The `/Game/...` path of the skeleton a clip or mesh names. */
+  skeleton: string
+  dataModel: string
+  note: string
+}
+
+export const listUassets = (dir: string): string[] => {
+  const out: string[] = []
+  const walk = (d: string): void => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (/\.uasset$/i.test(e.name)) out.push(p)
+    }
+  }
+  if (statSync(dir).isDirectory()) walk(dir)
+  else out.push(dir)
+  return out.sort()
+}
+
+/**
+ * A pack's assets, grouped by the skeleton they belong to. A `Skeleton` asset does not know its own
+ * `/Game/...` path in UE 5.0 files (`packageName` is "None" there), so it is matched to the path its
+ * clips name by resolving that path back to a file — the same walk-up `--clips` uses.
+ */
+export const scanUnreal = (dir: string): UnrealAssetRow[] => {
+  const rows = scanPackages(dir)
+  const byFile = new Map(rows.map((r) => [ resolve(r.file), r ]))
+  // one referencing file per skeleton path, captured before anything is re-keyed below
+  const referrer = new Map<string, string>()
+  for (const r of rows) if (r.skeleton.startsWith("/") && !referrer.has(r.skeleton)) referrer.set(r.skeleton, r.file)
+  for (const [ path, from ] of referrer) {
+    const found = resolveObjectFile(path, dirname(from))
+    const row = found ? byFile.get(resolve(found.file)) : undefined
+    if (row) row.skeleton = path
+  }
+  return rows
+}
+
+const scanPackages = (dir: string): UnrealAssetRow[] =>
+  listUassets(dir).map((file): UnrealAssetRow => {
+    try {
+      const pkg = readPackage(new Uint8Array(readFileSync(file)), file)
+      const kind = packageKind(pkg)
+      const model = dataModelKind(pkg)
+      return {
+        file, kind, engine: engineLabel(pkg.summary),
+        // a UE 5.0 package does not carry its own path ("None") — `scanUnreal` fills it in
+        skeleton: kind === "Skeleton" ? (pkg.summary.packageName.startsWith("/") ? pkg.summary.packageName : "") : skeletonPathOf(pkg),
+        dataModel: model === "none" ? "" : model,
+        // the class of the export the package IS (an AnimMontage, not the AnimDataModel beside it)
+        note: kind === "other" ? (() => { const a = assetExport(pkg); return a ? classOf(pkg, a) : "?" })() : "",
+      }
+    } catch (e) {
+      return { file, kind: "other", engine: "?", skeleton: "", dataModel: "", note: (e as Error).message.replace(/^.*?: /, "") }
+    }
+  })
+
+export const formatUnrealListing = (dir: string, rows: UnrealAssetRow[], opts: { all?: boolean } = {}): string => {
+  const lines: string[] = []
+  const usable = rows.filter((r) => r.kind !== "other" && r.kind !== "Texture2D")
+  lines.push(`${dir}: ${rows.length} package(s) — ${usable.length} readable by this pipeline`)
+  const engines = new Map<string, number>()
+  for (const r of rows) engines.set(r.engine, (engines.get(r.engine) ?? 0) + 1)
+  lines.push(`  engines: ${[ ...engines ].map(([ e, n ]) => `${e} ×${n}`).join(", ")}`)
+
+  // grouped by skeleton, so a pack's rigs and the clips on them read as a unit
+  const bySkeleton = new Map<string, UnrealAssetRow[]>()
+  for (const r of usable) {
+    const key = r.skeleton || "(no skeleton named)"
+    const list = bySkeleton.get(key) ?? []
+    list.push(r)
+    bySkeleton.set(key, list)
+  }
+  for (const [ skel, list ] of [ ...bySkeleton ].sort((a, b) => b[1].length - a[1].length)) {
+    const counts = { AnimSequence: 0, SkeletalMesh: 0, Skeleton: 0, Texture2D: 0 } as Record<string, number>
+    for (const r of list) counts[r.kind]++
+    const blocked = list.filter((r) => r.note)
+    lines.push(`  ${skel}: ${counts.Skeleton} skeleton(s), ${counts.SkeletalMesh} mesh(es), ${counts.AnimSequence} clip(s)${blocked.length ? `  ⚠ ${blocked.length} not readable (${blocked[0].note})` : ""}`)
+    for (const r of list) {
+      if (!opts.all && r.kind === "AnimSequence" && !r.note && list.length > 12) continue
+      lines.push(`     ${r.kind.padEnd(13)} ${relative(dir, r.file).replace(/\\/g, "/")}${r.note ? `  ⚠ ${r.note}` : ""}`)
+    }
+    if (!opts.all && counts.AnimSequence > 0 && list.length > 12) lines.push(`     (${counts.AnimSequence} clip(s) not listed — pass --all)`)
+  }
+  const textures = rows.filter((r) => r.kind === "Texture2D")
+  if (textures.length) lines.push(`  textures: ${textures.length} Texture2D asset(s)`)
+  const other = rows.filter((r) => r.kind === "other")
+  if (other.length) {
+    const kinds = new Map<string, number>()
+    for (const r of other) kinds.set(r.note || "?", (kinds.get(r.note || "?") ?? 0) + 1)
+    lines.push(`  other: ${[ ...kinds ].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([ k, n ]) => `${k} ×${n}`).join(", ")}`)
+  }
+  return lines.join("\n")
+}

package/src/unreal/materials.ts

@@ -0,0 +1,291 @@
+// Material slots → glTF materials with their textures.
+//
+// The route is exact, not guessed: a mesh's slot names come from its import data, the material
+// assets it uses come from its IMPORT TABLE, and a `MaterialInstanceConstant` lists its textures as
+// `TextureParameterValues` — a parameter name plus the Texture2D asset it points at. What is NOT
+// knowable without evaluating the material graph is what each parameter DOES, so a texture's role
+// is read from three agreeing signals: the parameter's name (`BaseColor Map`, `Normal`), the
+// asset's suffix (`_D`, `_N`, `_ORM`) and the texture's own compression setting (`TC_Normalmap`,
+// `TC_Masks`). Anything that does not land in glTF's five slots (masks, tangent maps, detail
+// layers) is reported and left out rather than wired somewhere plausible.
+//
+// Scalar/vector parameters (tints, roughness powers) are NOT applied: whether `SkinTone` multiplies
+// the base colour or drives something else is a property of the master material's graph. Gear comes
+// out in its neutral colours, as it did in the predecessor Python exporter.
+
+import { basename, dirname } from "node:path"
+import type { Document, Material, Texture } from "@gltf-transform/core"
+import type { ConvertWarning } from "../fbx/toDocument"
+import { findExport, readArrayHeader, readFName, readProperties, readObjectProperties, resolveObject, classOf, type UePackage } from "./package"
+import { readPackageFile } from "./index"
+import { resolveObjectFile } from "./resolve"
+import { extractTexture, readTexture2D, type UeTexture } from "./texture"
+import { findOodle } from "./oodle"
+
+export type TextureRole = "base" | "normal" | "orm" | "other"
+
+export type UeTextureParam = {
+  /** The material parameter's name (`BaseColor Map`, `Base Texture`, `Normal`). */
+  param: string
+  /** `/Game/…/T_F_Arms_D` — the Texture2D asset. */
+  path: string
+  asset: string
+  role: TextureRole
+}
+
+// A material names more textures than glTF has slots for, and several of them look like the one you
+// want: the UE5 mannequin's material has BOTH `Normal` (the normal map) and `BNormal` (a bent
+// normal), and picking whichever came first put the wrong one on the mesh. So candidates are SCORED
+// and the best one wins — an exact parameter name beats an asset suffix, which beats the texture's
+// compression setting, and a parameter that names something glTF has no slot for scores nothing.
+const NOT_A_MAP = /bent|bnormal|detail|aniso|tangent|mask|msk|paint|emis|opacity|packed|_msr|specular|subsurface|scatter|fuzz|sheen|clear ?coat|cccc|ccr/i
+
+const SCORES: Record<Exclude<TextureRole, "other">, { re: RegExp, on: "param" | "asset" | "compression", score: number }[]> = {
+  base: [
+    { re: /^(base ?colou?r|base ?tex(ture)?|albedo|diffuse|colou?r ?map)( map)?$/i, on: "param", score: 100 },
+    { re: /_(d|bc|albedo|basecolor|diff)$/i, on: "asset", score: 90 },
+    { re: /base ?colou?r|albedo|diffuse/i, on: "param", score: 80 },
+  ],
+  normal: [
+    { re: /^(normal|normal ?map|nrm)$/i, on: "param", score: 100 },
+    { re: /_n$/i, on: "asset", score: 90 },
+    { re: /^normal/i, on: "param", score: 85 },
+    { re: /^TC_Normalmap$/i, on: "compression", score: 50 },
+  ],
+  orm: [
+    { re: /orm|occlusion.?roughness.?metallic/i, on: "param", score: 100 },
+    { re: /_orm$/i, on: "asset", score: 90 },
+  ],
+}
+
+/** How well a texture fits a glTF slot: 0 = not a candidate. */
+export const scoreTexture = (role: Exclude<TextureRole, "other">, param: string, asset: string, compression = ""): number => {
+  if (NOT_A_MAP.test(param) || NOT_A_MAP.test(asset)) return 0
+  let best = 0
+  for (const rule of SCORES[role]) {
+    const subject = rule.on === "param" ? param : rule.on === "asset" ? asset : compression
+    if (subject && rule.re.test(subject)) best = Math.max(best, rule.score)
+  }
+  // a mask texture never becomes a normal map, whatever its name suggests
+  if (role === "normal" && compression === "TC_Masks") return 0
+  return best
+}
+
+/** The slot a texture fits best — what the report prints; the wiring uses `scoreTexture` directly. */
+export const classifyTexture = (param: string, asset: string, compression?: string): TextureRole => {
+  let role: TextureRole = "other", best = 0
+  for (const r of [ "base", "normal", "orm" ] as const) {
+    const score = scoreTexture(r, param, asset, compression)
+    if (score > best) { best = score; role = r }
+  }
+  return role
+}
+
+/** A material asset's `TextureParameterValues`, classified. */
+export const readMaterialTextures = (pkg: UePackage): UeTextureParam[] => {
+  const found = findExport(pkg, "MaterialInstanceConstant") ?? findExport(pkg, "Material")
+  if (!found) return []
+  const { reader: r, props } = readObjectProperties(pkg, found.export)
+  const tag = props.byName.get("TextureParameterValues")
+  if (!tag) return []
+  const out: UeTextureParam[] = []
+  const { count } = readArrayHeader(r, pkg, tag)
+  for (let i = 0; i < count; i++) {
+    const el = readProperties(r, pkg)
+    const after = r.offset
+    let param = ""
+    let path = "", asset = ""
+    const info = el.byName.get("ParameterInfo")
+    if (info) {
+      r.offset = info.data
+      const inner = readProperties(r, pkg)
+      const n = inner.byName.get("Name")
+      if (n) { r.offset = n.data; param = readFName(r, pkg.names) }
+    }
+    const value = el.byName.get("ParameterValue")
+    if (value) {
+      r.offset = value.data
+      const ref = resolveObject(pkg, r.i32())
+      if (ref) { path = ref.packagePath; asset = ref.name }
+    }
+    if (path) out.push({ param, path, asset, role: classifyTexture(param, asset) })
+    r.offset = after
+  }
+  return out
+}
+
+const normalize = (s: string): string => s.toLowerCase().replace(/[^a-z0-9]/g, "")
+
+/**
+ * Which material asset each mesh slot uses. The mesh's import table names the materials it
+ * references; slots are matched to them by name — exact, then normalised, then (when the counts
+ * agree and nothing else did) in order, which is how the assets line up in practice.
+ */
+export const resolveSlotMaterials = (pkg: UePackage, slots: string[]): (string | null)[] => {
+  const refs: { name: string, path: string }[] = []
+  for (let i = 0; i < pkg.imports.length; i++) {
+    const imp = pkg.imports[i]
+    if (imp.className !== "MaterialInstanceConstant" && imp.className !== "Material") continue
+    const path = resolveObject(pkg, -i - 1)?.packagePath ?? ""
+    if (path && !refs.some((r) => r.path === path)) refs.push({ name: imp.objectName, path })
+  }
+  const out: (string | null)[] = slots.map<string | null>(() => null)
+  const left = [ ...refs ]
+  const take = (i: number, r: { name: string, path: string }): void => { out[i] = r.path; left.splice(left.indexOf(r), 1) }
+  slots.forEach((s, i) => { const hit = left.find((r) => r.name.toLowerCase() === s.toLowerCase()); if (hit) take(i, hit) })
+  slots.forEach((s, i) => { if (!out[i]) { const hit = left.find((r) => normalize(r.name) === normalize(s)); if (hit) take(i, hit) } })
+  slots.forEach((s, i) => {
+    if (out[i] || !left.length) return
+    const n = normalize(s)
+    const hit = left.find((r) => normalize(r.name).includes(n) || n.includes(normalize(r.name)))
+    if (hit) take(i, hit)
+  })
+  const anyMatched = out.some((v) => v !== null)
+  if (!anyMatched && refs.length === slots.length) refs.forEach((r, i) => { out[i] = r.path })
+  return out
+}
+
+export type TextureOptions = {
+  /** Last-resort lookup for an object path, for hosts with no pack on disk (the studio's flat
+   *  upload store): `/Game/…/MI_Manny_01` → whichever uploaded file carries that asset. */
+  resolveAsset?: (objectPath: string) => string | null
+  /** Longest edge kept; larger sources are downscaled (needs `sharp`). Default 2048, 0 = no cap. */
+  maxSize?: number
+  /** UE authors normal maps DirectX-style (green down); glTF wants OpenGL (green up). */
+  flipNormalGreen?: boolean
+  contentRoot?: string
+  warn?: (w: ConvertWarning) => void
+}
+
+export type AppliedTextures = {
+  /** Per slot: which roles were wired. */
+  slots: { slot: string, material: string | null, roles: string[], skipped: string[] }[]
+  textures: number
+  /** Set when nothing could be read because the Oodle library is missing. */
+  oodleMissing: boolean
+}
+
+/** Decode → fix channels → re-encode. Uses `sharp` when it is installed, else the package's own
+ *  PNG codec (correct, just slower and without the resize). */
+export const fixChannels = async (data: Uint8Array, mime: string, opts: { swapRb: boolean, flipGreen: boolean, maxSize: number }): Promise<{ data: Uint8Array, mimeType: string }> => {
+  const { swapRb, flipGreen, maxSize } = opts
+  if (!swapRb && !flipGreen && !maxSize) return { data, mimeType: mime }
+  try {
+    const sharp = (await import("sharp")).default
+    let img = sharp(Buffer.from(data), { limitInputPixels: false, unlimited: true })
+    const meta = await img.metadata()
+    if (maxSize && Math.max(meta.width ?? 0, meta.height ?? 0) > maxSize) img = img.resize(maxSize, maxSize, { fit: "inside" })
+    const { data: raw, info } = await img.raw().toBuffer({ resolveWithObject: true })
+    const ch = info.channels
+    for (let i = 0; i < raw.length; i += ch) {
+      if (swapRb) { const t = raw[i]; raw[i] = raw[i + 2]; raw[i + 2] = t }
+      if (flipGreen && ch > 1) raw[i + 1] = 255 - raw[i + 1]
+    }
+    let usesAlpha = false
+    if (ch === 4) for (let i = 3; i < raw.length; i += 4) if (raw[i] !== 255) { usesAlpha = true; break }
+    const out = sharp(raw, { raw: { width: info.width, height: info.height, channels: ch } })
+    const encoded = usesAlpha
+      ? await out.png({ compressionLevel: 9 }).toBuffer()
+      : await out.removeAlpha().jpeg({ quality: 92, chromaSubsampling: "4:4:4" }).toBuffer()
+    return { data: new Uint8Array(encoded), mimeType: usesAlpha ? "image/png" : "image/jpeg" }
+  } catch {
+    // no sharp: the channel fix still has to happen, so do it on the package's own PNG codec
+    const { decodePng } = await import("../unity/png")
+    const { encodePng } = await import("../textures/resolveImage")
+    const img = mime === "image/png" ? decodePng(data) : null
+    if (!img) return { data, mimeType: mime }
+    for (let i = 0; i < img.data.length; i += 4) {
+      if (swapRb) { const t = img.data[i]; img.data[i] = img.data[i + 2]; img.data[i + 2] = t }
+      if (flipGreen) img.data[i + 1] = 255 - img.data[i + 1]
+    }
+    return { data: encodePng(img), mimeType: "image/png" }
+  }
+}
+
+/**
+ * Put the pack's textures on a document's materials. The document must already carry one material
+ * per mesh slot, named after the slot (that is what `unrealToDocument` builds).
+ */
+export const applyUnrealTextures = async (doc: Document, meshPath: string, slots: string[], opts: TextureOptions = {}): Promise<AppliedTextures> => {
+  const warn = opts.warn ?? (() => {})
+  const maxSize = opts.maxSize ?? 2048
+  const flipNormals = opts.flipNormalGreen ?? true
+  const report: AppliedTextures = { slots: [], textures: 0, oodleMissing: false }
+  const meshPkg = readPackageFile(meshPath)
+  /** An object path → a file: the pack's own layout first, then whatever the host can offer. */
+  const find = (objectPath: string, from = dirname(meshPath)): string | null =>
+    resolveObjectFile(objectPath, from, opts.contentRoot)?.file ?? opts.resolveAsset?.(objectPath) ?? null
+  const materials = doc.getRoot().listMaterials()
+  const assets = resolveSlotMaterials(meshPkg, slots)
+  const cache = new Map<string, Texture | null>()
+
+  const loadTexture = async (path: string, role: TextureRole, texAsset: UeTexture | null, file: string): Promise<Texture | null> => {
+    const key = `${path}|${role}`
+    const hit = cache.get(key)
+    if (hit !== undefined) return hit
+    let tex: Texture | null = null
+    try {
+      const img = await extractTexture(readPackageFile(file))
+      const prepared = await fixChannels(img.data, img.mimeType, {
+        swapRb: img.swapRb,
+        flipGreen: role === "normal" && flipNormals,
+        maxSize,
+      })
+      tex = doc.createTexture(img.texture.name).setImage(prepared.data).setMimeType(prepared.mimeType)
+      report.textures++
+    } catch (e) {
+      const msg = (e as Error).message
+      if (/Oodle/i.test(msg)) { report.oodleMissing = true; tex = null } else warn({ level: "warn", message: `texture ${basename(file)}: ${msg}` })
+    }
+    void texAsset
+    cache.set(key, tex)
+    return tex
+  }
+
+  for (let i = 0; i < slots.length; i++) {
+    const slot = slots[i]
+    const assetPath = assets[i]
+    const material: Material | undefined = materials[i]
+    const row = { slot, material: assetPath ? assetPath.split("/").pop() ?? null : null, roles: [] as string[], skipped: [] as string[] }
+    report.slots.push(row)
+    if (!assetPath || !material) continue
+    const matFile = find(assetPath)
+    if (!matFile) { warn({ level: "info", message: `material ${row.material}: asset not found next to the mesh — slot '${slot}' keeps its default` }); continue }
+
+    let params: UeTextureParam[]
+    try { params = readMaterialTextures(readPackageFile(matFile)) } catch (e) { warn({ level: "warn", message: `material ${row.material}: ${(e as Error).message}` }); continue }
+
+    // the texture asset's own compression setting is the third vote on what a parameter is for
+    const resolved = params.map((p) => {
+      const file = find(p.path, dirname(matFile))
+      let texture: UeTexture | null = null
+      if (file) { try { texture = readTexture2D(readPackageFile(file)) } catch { texture = null } }
+      return { ...p, file, texture, role: classifyTexture(p.param, p.asset, texture?.compressionSettings) }
+    })
+
+    for (const role of [ "base", "normal", "orm" ] as const) {
+      const pick = resolved
+        .filter((p) => p.file)
+        .map((p) => ({ p, score: scoreTexture(role, p.param, p.asset, p.texture?.compressionSettings) }))
+        .filter((c) => c.score > 0)
+        .sort((a, b) => b.score - a.score)[0]?.p
+      if (!pick) continue
+      const tex = await loadTexture(pick.path, role, pick.texture, pick.file!)
+      if (!tex) continue
+      if (role === "base") {
+        material.setBaseColorTexture(tex).setBaseColorFactor([ 1, 1, 1, 1 ])
+        material.getBaseColorTexture()?.setName(pick.asset)
+      } else if (role === "normal") {
+        material.setNormalTexture(tex)
+      } else {
+        // UE packs occlusion/roughness/metallic into R/G/B — glTF reads exactly the same channels
+        material.setMetallicRoughnessTexture(tex).setOcclusionTexture(tex).setMetallicFactor(1).setRoughnessFactor(1)
+      }
+      row.roles.push(role)
+    }
+    row.skipped = resolved.filter((p) => p.role === "other").map((p) => `${p.param || p.asset}`)
+  }
+  if (report.oodleMissing) warn({ level: "info", message: `textures skipped — no Oodle decoder (${findOodle() ? "found the library but could not call it" : "set LECODES_OODLE"})` })
+  void classOf
+  return report
+}

package/src/unreal/mesh.ts

@@ -0,0 +1,205 @@
+// SkeletalMesh → geometry + skin + bones, out of the EDITOR IMPORT DATA (`FSkeletalMeshImportData`
+// — what the FBX importer saw), which a `SkeletalMeshEditorData` child export keeps as bulk data.
+// That is the same source the render data is built from, and the only one that still carries the
+// skin influences and the source bone list.
+//
+// A mesh whose LODs were generated in-engine has no import data at all (an 84-byte payload, header
+// only); the UE4 mannequin of the Stairs pack is one. Such a mesh cannot be exported by this path —
+// `lodCount` reports which LODs have a source (§8).
+//
+// The vertex model is UE's: POINTS carry position and skin weights, WEDGES are per-corner
+// (point + UV + colour), FACES name three wedges plus a per-corner normal. glTF wants one array of
+// vertices, so `toDocument` de-duplicates wedges per material slot.
+
+import {
+  BinaryReader, findExport, classOf, readObjectProperties, readBulkHeader, readBulkPayload,
+  bulkIsCompressed, propObject, resolveObject, type UePackage, type BulkDataHeader,
+} from "./package"
+import { skipObjectGuid } from "./skeleton"
+
+export type UeMeshBone = {
+  name: string
+  parent: number
+  /** LOCAL transform, UE frame, centimetres (floats here, unlike the USkeleton's doubles). */
+  t: [ number, number, number ]
+  q: [ number, number, number, number ]
+  s: [ number, number, number ]
+}
+
+export type UeInfluence = { weight: number, point: number, bone: number }
+
+export type UeSkeletalMesh = {
+  name: string
+  /** Skeleton asset this mesh is bound to (`/Game/…/SK_Mannequin`), when it names one. */
+  skeletonPath: string
+  skeletonName: string
+  /** Which LOD was read, and what the file holds. */
+  lod: number
+  lods: { index: number, bytes: number, compressed: boolean, hasSource: boolean }[]
+  /** version of the import-data blob (3 = UE 5.0, 5 = UE 5.3). */
+  version: number
+  /** n × 3 floats, UE frame, cm — the skeleton's bind (= reference) space. */
+  points: Float32Array
+  /** per wedge: point index, uv0, uv1 (NaN-free zeros when absent), material slot. */
+  wedgePoint: Uint32Array
+  wedgeUv0: Float32Array
+  wedgeUv1: Float32Array
+  hasUv1: boolean
+  /** per face: 3 wedge indices, material slot, 3 corner normals (UE frame). */
+  faceWedges: Uint32Array
+  faceMaterial: Uint8Array
+  faceNormals: Float32Array
+  influences: UeInfluence[]
+  materials: string[]
+  bones: UeMeshBone[]
+}
+
+const BULK_EMPTY_MAX = 100          // a generated LOD's "import data" is a header and nothing else
+
+/** `FRawSkeletalMeshBulkData` list of the `SkeletalMeshEditorData` export. */
+const readEditorDataLods = (pkg: UePackage, editorExportIndex: number): { header: BulkDataHeader }[] => {
+  const e = pkg.exports[editorExportIndex]
+  const { reader: r } = readObjectProperties(pkg, e)  // empty tag list (just `None`)
+  skipObjectGuid(r)
+  const lodCount = r.i32()
+  if (lodCount < 0 || lodCount > 64) throw new Error(`${pkg.label}: ${lodCount} LODs in ${e.objectName} — not a mesh editor-data export`)
+  const out: { header: BulkDataHeader }[] = []
+  for (let i = 0; i < lodCount; i++) {
+    r.u8(); r.u8()                                    // geo / skinning import versions
+    const header = readBulkHeader(r)
+    r.skip(16)                                        // guid
+    r.i32()                                           // bGuidIsHash
+    out.push({ header })
+  }
+  return out
+}
+
+/** `FSkeletalMeshImportData` — the arrays sit back to back with an i32 count in front of each. */
+const parseImportData = (blob: Uint8Array, label: string): Omit<UeSkeletalMesh, "name" | "skeletonPath" | "skeletonName" | "lod" | "lods"> => {
+  const r = new BinaryReader(blob, 0, `${label} import data`)
+  const version = r.i32()
+  r.skip(32)                                          // 8 more header ints (flags: normals, tangents, …)
+
+  const faceCount = r.i32()
+  const faceWedges = new Uint32Array(faceCount * 3)
+  const faceMaterial = new Uint8Array(faceCount)
+  const faceNormals = new Float32Array(faceCount * 9)
+  {
+    const base = r.offset
+    if (faceCount < 0 || base + faceCount * 127 > blob.byteLength) throw new Error(`${label}: ${faceCount} faces do not fit the import data (${blob.byteLength} B)`)
+    const v = r.view
+    for (let i = 0; i < faceCount; i++) {
+      const o = base + i * 127
+      faceMaterial[i] = blob[o]
+      faceWedges[i * 3] = v.getUint32(o + 7, true)
+      faceWedges[i * 3 + 1] = v.getUint32(o + 11, true)
+      faceWedges[i * 3 + 2] = v.getUint32(o + 15, true)
+      for (let k = 0; k < 9; k++) faceNormals[i * 9 + k] = v.getFloat32(o + 91 + k * 4, true)   // TangentZ per corner
+    }
+    r.offset = base + faceCount * 127
+  }
+
+  const influenceCount = r.i32()
+  const influences: UeInfluence[] = new Array(influenceCount)
+  {
+    const base = r.offset
+    if (influenceCount < 0 || base + influenceCount * 12 > blob.byteLength) throw new Error(`${label}: ${influenceCount} influences do not fit the import data`)
+    const v = r.view
+    for (let i = 0; i < influenceCount; i++) {
+      const o = base + i * 12
+      influences[i] = { weight: v.getFloat32(o, true), point: v.getInt32(o + 4, true), bone: v.getInt32(o + 8, true) }
+    }
+    r.offset = base + influenceCount * 12
+  }
+
+  const materialCount = r.i32()
+  const materials: string[] = []
+  for (let i = 0; i < materialCount; i++) materials.push(r.fstring())
+
+  const pointCount = r.i32()
+  const points = new Float32Array(pointCount * 3)
+  for (let i = 0; i < points.length; i++) points[i] = r.f32()
+
+  const mapCount = r.i32()
+  r.skip(mapCount * 4)                                // PointToRawMap
+
+  const boneCount = r.i32()
+  const bones: UeMeshBone[] = new Array(boneCount)
+  for (let i = 0; i < boneCount; i++) {
+    const name = r.fstring()
+    r.u32()                                           // flags
+    r.i32()                                           // numChildren
+    const parent = r.i32()
+    const q = r.floats(4), t = r.floats(3), s = r.floats(3)
+    bones[i] = { name, parent, t: [ t[0], t[1], t[2] ], q: [ q[0], q[1], q[2], q[3] ], s: [ s[0], s[1], s[2] ] }
+  }
+
+  const wedgeCount = r.i32()
+  const wedgePoint = new Uint32Array(wedgeCount)
+  const wedgeUv0 = new Float32Array(wedgeCount * 2)
+  const wedgeUv1 = new Float32Array(wedgeCount * 2)
+  let hasUv1 = false
+  {
+    const base = r.offset
+    if (wedgeCount < 0 || base + wedgeCount * 42 > blob.byteLength) throw new Error(`${label}: ${wedgeCount} wedges do not fit the import data`)
+    const v = r.view
+    for (let i = 0; i < wedgeCount; i++) {
+      const o = base + i * 42
+      wedgePoint[i] = v.getUint32(o, true)
+      wedgeUv0[i * 2] = v.getFloat32(o + 10, true)
+      wedgeUv0[i * 2 + 1] = v.getFloat32(o + 14, true)
+      const u1 = v.getFloat32(o + 18, true), v1 = v.getFloat32(o + 22, true)
+      wedgeUv1[i * 2] = u1; wedgeUv1[i * 2 + 1] = v1
+      if (!hasUv1 && (u1 !== 0 || v1 !== 0)) hasUv1 = true
+    }
+    r.offset = base + wedgeCount * 42
+  }
+
+  for (const [ i, w ] of faceWedges.entries()) {
+    if (w >= wedgeCount) throw new Error(`${label}: face ${Math.floor(i / 3)} names wedge ${w} of ${wedgeCount}`)
+  }
+  return { version, points, wedgePoint, wedgeUv0, wedgeUv1, hasUv1, faceWedges, faceMaterial, faceNormals, influences, materials, bones }
+}
+
+export type ReadMeshOptions = { lod?: number }
+
+/** The `SkeletalMesh` export of a package (an `SKM_*.uasset`), at one LOD (default 0). */
+export const readSkeletalMesh = (pkg: UePackage, opts: ReadMeshOptions = {}): UeSkeletalMesh => {
+  const found = findExport(pkg, "SkeletalMesh")
+  if (!found) throw new Error(`${pkg.label}: no SkeletalMesh export (exports: ${pkg.exports.map((e) => `${e.objectName}:${classOf(pkg, e)}`).join(", ")})`)
+  const { reader: r, props } = readObjectProperties(pkg, found.export)
+  const skelRef = resolveObject(pkg, propObject(r, props.byName.get("Skeleton")) ?? 0)
+
+  const editorRef = resolveObject(pkg, propObject(r, props.byName.get("MeshEditorDataObject")) ?? 0)
+  const editorIndex = editorRef?.kind === "export" ? editorRef.index : pkg.exports.findIndex((e) => classOf(pkg, e) === "SkeletalMeshEditorData")
+  if (editorIndex < 0) {
+    throw new Error(`${pkg.label}: the mesh keeps no editor import data (a cooked or engine-generated mesh) — only its skeleton can be read`)
+  }
+  const lodsRaw = readEditorDataLods(pkg, editorIndex)
+  const lods = lodsRaw.map((l, i) => ({ index: i, bytes: l.header.elementCount, compressed: bulkIsCompressed(l.header), hasSource: l.header.elementCount > BULK_EMPTY_MAX }))
+  const want = opts.lod ?? 0
+  const chosen = lods[want]
+  if (!chosen) throw new Error(`${pkg.label}: no LOD ${want} (the mesh has ${lods.length})`)
+  if (!chosen.hasSource) {
+    const alt = lods.filter((l) => l.hasSource).map((l) => l.index)
+    throw new Error(`${pkg.label}: LOD ${want} has no source geometry (${chosen.bytes} B — an engine-generated LOD)${alt.length ? `; LOD ${alt.join("/")} do${alt.length > 1 ? "" : "es"}` : " and neither does any other LOD, so this mesh cannot be exported"}`)
+  }
+  const blob = readBulkPayload(pkg, lodsRaw[want].header)
+  const data = parseImportData(blob, pkg.label)
+  return {
+    name: found.export.objectName,
+    skeletonPath: skelRef?.packagePath ?? "",
+    skeletonName: skelRef?.name ?? "",
+    lod: want, lods,
+    ...data,
+  }
+}
+
+/** Bounding box of the points, UE frame, centimetres. */
+export const meshBounds = (m: UeSkeletalMesh): { min: number[], max: number[] } => {
+  const min = [ Infinity, Infinity, Infinity ], max = [ -Infinity, -Infinity, -Infinity ]
+  for (let i = 0; i < m.points.length; i += 3) {
+    for (let k = 0; k < 3; k++) { min[k] = Math.min(min[k], m.points[i + k]); max[k] = Math.max(max[k], m.points[i + k]) }
+  }
+  return { min, max }
+}