lecodes-assets 0.2.0 → 2.4.10

package/src/unreal/materials.ts

@@ -0,0 +1,399 @@
+// 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 { BinaryReader, 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 { evaluateConstant, readMaterialGraph, type MaterialGraph } from "./materialGraph"
+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)$/i, on: "asset", score: 85 },
+    { 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
+}
+
+/** One entry of a `SkeletalMesh`'s own material array: which asset the SLOT actually uses. */
+export type UeSkeletalMaterial = { slot: string, imported: string, path: string, name: string }
+
+/**
+ * The mesh's OWN per-slot material assignment (`TArray<FSkeletalMaterial>` from
+ * `USkeletalMesh::Serialize`, right after the tagged properties). This is the only exact answer:
+ * a slot's NAME is what the FBX import left behind (`MI_Pants_ColorA`), while the material the
+ * artist later put in that slot can be a different asset entirely (`MI_Pants_CamoA`) — matching by
+ * name alone leaves those slots grey.
+ *
+ * The array's offset is not fixed (the header between the properties and it has changed across 5.x),
+ * so the start is FOUND rather than assumed: a candidate offset must parse into a whole array whose
+ * every entry resolves to a Material object and whose flags are booleans. Nothing is returned unless
+ * that holds, and the caller falls back to matching by name.
+ */
+export const readSkeletalMaterials = (pkg: UePackage): UeSkeletalMaterial[] => {
+  const found = findExport(pkg, "SkeletalMesh")
+  if (!found) return []
+  let start: number
+  let data: Uint8Array
+  try {
+    const { reader } = readObjectProperties(pkg, found.export)
+    start = reader.offset
+    data = reader.data
+  } catch { return [] }
+  const end = found.export.serialOffset + found.export.serialSize
+  for (let off = start; off < start + 128; off++) {
+    const r = new BinaryReader(data, off, pkg.label)
+    try {
+      const count = r.i32()
+      if (count < 1 || count > 256) continue
+      const rows: UeSkeletalMaterial[] = []
+      for (let i = 0; i < count; i++) {
+        // a slot may hold NO material (index 0 — UE draws its default there); that is still a row
+        const index = r.i32()
+        const ref = index === 0 ? { packagePath: "", name: "", className: "Material" } : resolveObject(pkg, index)
+        if (!ref || !/Material/.test(ref.className)) throw new Error("not a material")
+        const slot = readFName(r, pkg.names)
+        const hasImported = r.i32()
+        if (hasImported !== 0 && hasImported !== 1) throw new Error("not a bool")
+        const imported = hasImported ? readFName(r, pkg.names) : ""
+        // FMeshUVChannelInfo: bInitialized, bOverrideDensities, LocalUVDensities[4]
+        const init = r.i32(), override = r.i32()
+        if (init > 1 || init < 0 || override > 1 || override < 0) throw new Error("not a UV channel info")
+        r.skip(16)
+        rows.push({ slot, imported, path: ref.packagePath, name: ref.name })
+      }
+      if (r.offset > end) continue
+      return rows
+    } catch { /* not the array — keep scanning */ }
+  }
+  return []
+}
+
+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 out: (string | null)[] = slots.map<string | null>(() => null)
+
+  // exact first: the mesh's own slot → material array, matched by slot name (a mesh can carry more
+  // entries than the import data has slots — an unused section — so index order is not enough)
+  const own = readSkeletalMaterials(pkg)
+  if (own.length) {
+    const byName = new Map<string, string>()
+    // an EMPTY slot (no material assigned) is left for the name match below rather than taken as ""
+    for (const m of own) {
+      if (m.path) for (const key of [ m.imported, m.slot ]) if (key) byName.set(normalize(key), m.path)
+    }
+    slots.forEach((s, i) => { out[i] = byName.get(normalize(s)) ?? null })
+    const matched = out.filter((v) => v !== null).length
+    // no name agreed at all (an import whose slots were renamed) — the array IS the slot order
+    if (!matched && own.length === slots.length) own.forEach((m, i) => { out[i] = m.path })
+    if (out.every((v) => v !== null)) return out
+  }
+
+  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 left = refs.filter((r) => !out.includes(r.path))
+  const take = (i: number, r: { name: string, path: string }): void => { out[i] = r.path; left.splice(left.indexOf(r), 1) }
+  slots.forEach((s, i) => { if (out[i]) return; 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, png?: boolean }): 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 }
+    // An opaque image goes to JPEG (what a GLB wants to embed) unless the caller asked for a
+    // lossless file — `unreal tex`, where the image is a SOURCE for further work (a normal map
+    // headed for an atlas has no business picking up JPEG blocks on the way).
+    const lossless = usesAlpha || opts.png === true
+    const out = sharp(raw, { raw: { width: info.width, height: info.height, channels: ch } })
+    const encoded = lossless
+      ? await (usesAlpha ? out : out.removeAlpha()).png({ compressionLevel: 9 }).toBuffer()
+      : await out.removeAlpha().jpeg({ quality: 92, chromaSubsampling: "4:4:4" }).toBuffer()
+    return { data: new Uint8Array(encoded), mimeType: lossless ? "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" }
+  }
+}
+
+/** The constant-valued pins of a plain Material (null for an instance or an unreadable package). */
+const constantPins = (file: string): { base?: number[], metallic?: number, roughness?: number, emissive?: number[] } | null => {
+  let graph: MaterialGraph
+  try { graph = readMaterialGraph(readPackageFile(file)) } catch { return null }
+  const pin = (name: string): number[] | undefined => evaluateConstant(graph, graph.outputs[name]) ?? undefined
+  // an UNCONNECTED pin is the engine's default (Metallic 0, Roughness 0.5), not "unknown" — but a
+  // pin wired to something this cannot evaluate (a texture) stays undecided
+  const or = (name: string, dflt: number): number | undefined => (graph.outputs[name] ? pin(name)?.[0] : dflt)
+  return { base: pin("BaseColor"), metallic: or("Metallic", 0), roughness: or("Roughness", 0.5), emissive: pin("EmissiveColor") }
+}
+
+/**
+ * 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) }
+    })
+
+    // a material whose ONLY texture says nothing about its role (`Param`, `Texture` — this pack's
+    // eyes and eyelashes) is a base colour: there is nothing else it could be, and the alternative
+    // is a grey slot. A name that reads as a mask or a map glTF has no slot for is still left out.
+    const lone = resolved.filter((p) => p.file && !NOT_A_MAP.test(p.param) && !NOT_A_MAP.test(p.asset))
+    const onlyBase = lone.length === 1 && lone[0].role === "other" ? lone[0] : null
+
+    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
+        ?? (role === "base" ? onlyBase : null)
+      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)
+    }
+    // A pin no texture reached gets what the graph computes when it is all NUMBERS — a pack whose
+    // materials carry no textures at all (KINEMATION's FPS Animation Pack weapons: `M_Finish` is a
+    // VectorParameter colour, a Constant metallic and a Constant roughness) otherwise came out as 14
+    // identical grey slots. Only a plain Material has a graph; an instance keeps its defaults.
+    const pins = constantPins(matFile)
+    if (pins) {
+      if (pins.base && !row.roles.includes("base")) { material.setBaseColorFactor([ pins.base[0], pins.base[1] ?? pins.base[0], pins.base[2] ?? pins.base[0], 1 ]); row.roles.push("base=const") }
+      if (!row.roles.includes("orm")) {
+        if (pins.metallic !== undefined) { material.setMetallicFactor(Math.min(1, Math.max(0, pins.metallic))); row.roles.push("metallic=const") }
+        if (pins.roughness !== undefined) { material.setRoughnessFactor(Math.min(1, Math.max(0, pins.roughness))); row.roles.push("roughness=const") }
+      }
+      if (pins.emissive && pins.emissive.some((c) => c > 0)) { material.setEmissiveFactor([ pins.emissive[0], pins.emissive[1] ?? pins.emissive[0], pins.emissive[2] ?? pins.emissive[0] ].map((c) => Math.min(1, c)) as [ number, number, number ]); row.roles.push("emissive=const") }
+    }
+    row.skipped = resolved.filter((p) => p.role === "other" && p !== onlyBase).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 }
+}