lecodes-assets 0.2.1 → 2.4.10

package/src/unreal/materials.ts

@@ -16,10 +16,11 @@
 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 { 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"
@@ -44,6 +45,7 @@ const SCORES: Record<Exclude<TextureRole, "other">, { re: RegExp, on: "param" |
   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: [
@@ -114,6 +116,60 @@ export const readMaterialTextures = (pkg: UePackage): UeTextureParam[] => {
   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, "")
 
 /**
@@ -122,6 +178,24 @@ const normalize = (s: string): string => s.toLowerCase().replace(/[^a-z0-9]/g, "
  * 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]
@@ -129,10 +203,9 @@ export const resolveSlotMaterials = (pkg: UePackage, slots: string[]): (string |
     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 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) => { const hit = left.find((r) => r.name.toLowerCase() === s.toLowerCase()); if (hit) take(i, hit) })
+  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
@@ -167,7 +240,7 @@ export type AppliedTextures = {
 
 /** 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 }> => {
+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 {
@@ -183,11 +256,15 @@ export const fixChannels = async (data: Uint8Array, mime: string, opts: { swapRb
     }
     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 = usesAlpha
-      ? await out.png({ compressionLevel: 9 }).toBuffer()
+    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: usesAlpha ? "image/png" : "image/jpeg" }
+    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")
@@ -202,6 +279,17 @@ export const fixChannels = async (data: Uint8Array, mime: string, opts: { swapRb
   }
 }
 
+/** 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).
@@ -263,12 +351,19 @@ export const applyUnrealTextures = async (doc: Document, meshPath: string, slots
       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
@@ -283,7 +378,20 @@ export const applyUnrealTextures = async (doc: Document, meshPath: string, slots
       }
       row.roles.push(role)
     }
-    row.skipped = resolved.filter((p) => p.role === "other").map((p) => `${p.param || p.asset}`)
+    // 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

package/src/unreal/package.ts

@@ -7,13 +7,16 @@
 //
 // 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.
+// 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, releaseOfVersion } from "./versions"
+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"
 
@@ -190,9 +193,21 @@ export const readSummary = (bytes: Uint8Array, label: string): UeSummary => {
 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})`
 
-const checkVersion = (s: UeSummary, label: string): void => {
+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) {
-    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 (!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) {
@@ -298,9 +313,9 @@ export type UePackage = {
   exports: UeExport[]
 }
 
-export const readPackage = (bytes: Uint8Array, label = "package"): UePackage => {
+export const readPackage = (bytes: Uint8Array, label = "package", opts: ReadPackageOptions = {}): UePackage => {
   const summary = readSummary(bytes, label)
-  checkVersion(summary, 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)
@@ -450,9 +465,10 @@ const skipTagExtension = (r: BinaryReader): void => {
  * 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: { ue5: number } }): PropertyTag | null => {
+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
@@ -477,7 +493,7 @@ export const readPropertyTag = (r: BinaryReader, pkg: { names: string[], summary
     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 (r.u8()) r.skip(16)                                            // optional property guid
+    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
@@ -501,7 +517,7 @@ export type Properties = {
  * 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: { ue5: number } }): Properties => {
+export const readProperties = (r: BinaryReader, pkg: { names: string[], summary: { ue4?: number, ue5: number } }): Properties => {
   const list: PropertyTag[] = []
   for (;;) {
     const tag = readPropertyTag(r, pkg)
@@ -557,16 +573,18 @@ export const NATIVE_STRUCT_SIZE: Record<string, number> = {
  * 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: { ue5: number } }, tag: PropertyTag): { count: number, inner: PropertyTag | null, elementStruct: string } => {
+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()
-  const inner = tag.inner === "StructProperty" && pkg.summary.ue5 < UE5.PROPERTY_TAG_COMPLETE_TYPE_NAME ? readPropertyTag(r, pkg) : null
+  // 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: { ue5: number } }, tag: PropertyTag): { comps: number, values: Float32Array } => {
+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

package/src/unreal/resolve.ts

@@ -8,11 +8,13 @@ import { dirname, join, resolve, sep } from "node:path"
 
 export const GAME_PREFIX = "/Game/"
 
-/** `/Game/A/B/Name` → `A/B/Name.uasset`. */
+/** `/Game/A/B/Name` → `A/B/Name.uasset`. A PLUGIN's content mounts at `/<PluginName>/` instead of
+ *  `/Game/` (KINEMATION's FPS Animation Pack: `/FPSAnimationPack/Meshes/…/SK_Mannequin`), and its
+ *  Content folder on disk is just as unmarked — so any mount point is stripped the same way. */
 export const objectPathToFile = (objectPath: string): string | null => {
-  if (!objectPath.startsWith(GAME_PREFIX)) return null
-  const rel = objectPath.slice(GAME_PREFIX.length)
-  return rel ? `${rel.replace(/\//g, sep)}.uasset` : null
+  const m = /^\/[^/]+\/(.+)$/.exec(objectPath)
+  if (!m) return null
+  return `${m[1].replace(/\//g, sep)}.uasset`
 }
 
 export type ResolveResult = { file: string, contentRoot: string } | null

package/src/unreal/sound.ts

@@ -0,0 +1,128 @@
+// SoundWave → the WAV the artist imported. An uncooked `SoundWave` keeps its source audio whole
+// (`RawData`, an editor bulk payload — not the platform-cooked Vorbis/ADPCM a packaged game
+// ships), wrapped in the same Oodle `FCompressedBuffer` a texture's source image lives in, so it
+// is found and decoded the same way (`texture.ts`). What comes out is a complete RIFF/WAVE file,
+// PCM, exactly as imported — 48 kHz 16-bit mono for the engine packs seen; stereo where the pack
+// author kept it.
+//
+// `--ogg` hands the WAV to ffmpeg (on PATH, or `LECODES_FFMPEG`) for a mono Vorbis file, which is
+// what a game clip wants: `Sound.load` decodes mono by default anyway, and Vorbis is a tenth of
+// the size. Loop points are not touched — the packs' loops are cut to the sample already.
+
+import { basename, join } from "node:path"
+import { writeFileSync, mkdirSync, unlinkSync } from "node:fs"
+import { spawnSync } from "node:child_process"
+import { classOf, findExport, readObjectProperties, propInt, propFloat, propName, type UePackage } from "./package"
+import { findCompressedBuffer, decodeCompressedBuffer } from "./texture"
+
+export type UeSoundWave = {
+  name: string
+  /** `NumChannels`, `SampleRate`, `Duration` as the asset declares them (0 when absent). */
+  channels: number
+  sampleRate: number
+  duration: number
+  /** `SoundGroup` / `bLooping` when present. */
+  looping: boolean
+}
+
+/** The `SoundWave` export's own facts (no payload work). */
+export const readSoundWave = (pkg: UePackage): UeSoundWave => {
+  const found = findExport(pkg, "SoundWave")
+  if (!found) throw new Error(`${pkg.label}: no SoundWave export (${pkg.exports.map((e) => classOf(pkg, e)).join(", ")})`)
+  const { reader: r, props } = readObjectProperties(pkg, found.export)
+  const one = (k: string) => props.byName.get(k)
+  return {
+    name: found.export.objectName,
+    channels: propInt(r, one("NumChannels")) ?? 0,
+    sampleRate: propInt(r, one("SampleRate")) ?? 0,
+    duration: propFloat(r, one("Duration")) ?? 0,
+    looping: one("bLooping")?.bool ?? false,
+  }
+}
+
+export type WavInfo = { channels: number, sampleRate: number, bits: number, frames: number, duration: number }
+
+/** The fmt/data facts of a RIFF/WAVE file — a sanity check on what came out of the buffer. */
+export const readWavInfo = (wav: Uint8Array): WavInfo => {
+  const tag = String.fromCharCode(...wav.subarray(0, 4)), wave = String.fromCharCode(...wav.subarray(8, 12))
+  if (tag !== "RIFF" || wave !== "WAVE") throw new Error(`payload is not a RIFF/WAVE file (${tag} ${wave})`)
+  const dv = new DataView(wav.buffer, wav.byteOffset, wav.byteLength)
+  let o = 12, fmt: { channels: number, sampleRate: number, bits: number } | null = null, data = 0
+  while (o + 8 <= wav.byteLength) {
+    const id = String.fromCharCode(...wav.subarray(o, o + 4)), size = dv.getUint32(o + 4, true)
+    if (id === "fmt ") fmt = { channels: dv.getUint16(o + 10, true), sampleRate: dv.getUint32(o + 12, true), bits: dv.getUint16(o + 22, true) }
+    if (id === "data") data = size
+    o += 8 + size + (size & 1)
+  }
+  if (!fmt) throw new Error("WAV has no fmt chunk")
+  const frames = data / Math.max(1, fmt.channels * (fmt.bits / 8))
+  return { ...fmt, frames, duration: frames / fmt.sampleRate }
+}
+
+/** The imported WAV out of a SoundWave asset. Needs Oodle unless the buffer is stored plain. */
+export const extractSound = async (pkg: UePackage): Promise<{ wave: UeSoundWave, wav: Uint8Array, info: WavInfo }> => {
+  const wave = readSoundWave(pkg)
+  const buf = findCompressedBuffer(pkg)
+  if (!buf) throw new Error(`${pkg.label}: no FCompressedBuffer after the exports — a cooked package, or the audio lives in a .ubulk`)
+  const wav = await decodeCompressedBuffer(pkg, buf)
+  return { wave, wav, info: readWavInfo(wav) }
+}
+
+/** Where ffmpeg is: `LECODES_FFMPEG`, else PATH. null when it cannot be run. */
+export const findFfmpeg = (): string | null => {
+  const exe = process.env.LECODES_FFMPEG || "ffmpeg"
+  const p = spawnSync(exe, [ "-version" ], { encoding: "utf8" })
+  return p.status === 0 ? exe : null
+}
+
+export type OggOptions = {
+  /** Downmix to one channel (default true — what a game clip wants; `Sound.load` is mono anyway). */
+  mono?: boolean
+  /** libvorbis quality −1..10 (default 5 ≈ 160 kb/s stereo, ~80 mono). */
+  quality?: number
+}
+
+/** WAV bytes → an OGG Vorbis file on disk through ffmpeg. Returns the written size. */
+export const wavToOgg = (ffmpeg: string, wav: Uint8Array, outPath: string, o: OggOptions = {}): number => {
+  const tmp = outPath + ".tmp.wav"
+  writeFileSync(tmp, wav)
+  try {
+    const args = [ "-hide_banner", "-loglevel", "error", "-y", "-i", tmp ]
+    if (o.mono !== false) args.push("-ac", "1")
+    args.push("-c:a", "libvorbis", "-q:a", String(o.quality ?? 5), outPath)
+    const p = spawnSync(ffmpeg, args, { encoding: "utf8" })
+    if (p.status !== 0) throw new Error(`ffmpeg failed on ${basename(outPath)}: ${(p.stderr || p.stdout || "").trim()}`)
+  } finally {
+    try { unlinkSync(tmp) } catch { /* nothing to clean */ }
+  }
+  return Bun.file(outPath).size
+}
+
+export type SoundExportRow = { name: string, out: string, info: WavInfo, bytes: number }
+
+/**
+ * Every SoundWave under `inputs` (files or folders) → `outDir/<name>.wav` (or `.ogg`). Non-sound
+ * packages (SoundCue, MetaSound…) are skipped silently — a pack's `Cue` folder sits next to its
+ * `Sound` folder. Throws on the first sound that cannot be decoded.
+ */
+export const exportSounds = async (
+  files: string[], outDir: string,
+  opts: { ogg?: OggOptions | false, readPackage: (path: string) => UePackage, log?: (s: string) => void },
+): Promise<SoundExportRow[]> => {
+  mkdirSync(outDir, { recursive: true })
+  const ffmpeg = opts.ogg ? findFfmpeg() : null
+  if (opts.ogg && !ffmpeg) throw new Error("--ogg needs ffmpeg on PATH (or LECODES_FFMPEG=<path to ffmpeg>)")
+  const rows: SoundExportRow[] = []
+  for (const f of files) {
+    const pkg = opts.readPackage(f)
+    if (!findExport(pkg, "SoundWave")) continue
+    const { wave, wav, info } = await extractSound(pkg)
+    const out = join(outDir, wave.name + (ffmpeg ? ".ogg" : ".wav"))
+    let bytes = wav.byteLength
+    if (ffmpeg) bytes = wavToOgg(ffmpeg, wav, out, opts.ogg || {})
+    else writeFileSync(out, wav)
+    rows.push({ name: wave.name, out, info, bytes })
+    opts.log?.(`  ${wave.name.padEnd(28)} ${info.channels}ch ${info.sampleRate} Hz ${info.bits}-bit  ${info.duration.toFixed(3)} s → ${(bytes / 1024).toFixed(0)} KB`)
+  }
+  return rows
+}

package/src/unreal/texture.ts

@@ -11,7 +11,7 @@
 // the package trailer): same container either way, so it is found by its magic at or after the
 // bulk-data start rather than through the trailer's own table of contents.
 
-import { BinaryReader, findExport, readProperties, readObjectProperties, propInt, propEnum, propString, type UePackage } from "./package"
+import { BinaryReader, findExport, readProperties, readObjectProperties, readBulkHeader, readBulkPayload, propInt, propEnum, propString, type UePackage } from "./package"
 import { getOodle, OODLE_MISSING_MESSAGE, findOodle, OODLE_NO_RUNTIME_MESSAGE } from "./oodle"
 
 /** `b7 75 63 62` — `FCompressedBuffer`'s magic, big-endian like the rest of its header. */
@@ -178,14 +178,81 @@ const imageAt = (payload: Uint8Array): { at: number, mimeType: string } | null =
   return null
 }
 
+/** The image's own size, so a signature found in the bulk region can be checked against the asset. */
+const pngHeader = (b: Uint8Array, at: number): { width: number, height: number } | null => {
+  const dv = new DataView(b.buffer, b.byteOffset, b.byteLength)
+  if (at + 24 > b.byteLength) return null
+  if (String.fromCharCode(b[at + 12], b[at + 13], b[at + 14], b[at + 15]) !== "IHDR") return null
+  return { width: dv.getUint32(at + 16), height: dv.getUint32(at + 20) }
+}
+
+/** `IEND` + its CRC ends a PNG; bytes after it (the trailer's own tail) are not part of the image. */
+const pngEnd = (b: Uint8Array, at: number): number => {
+  for (let i = at; i + 8 <= b.byteLength; i++) {
+    if (b[i] === 0x49 && b[i + 1] === 0x45 && b[i + 2] === 0x4e && b[i + 3] === 0x44) return i + 8
+  }
+  return b.byteLength
+}
+
+/**
+ * Some assets keep the source image in the package trailer WITHOUT the `FCompressedBuffer` wrapper —
+ * the payload is stored, so what sits there is the PNG file itself (this pack's gloves, eyes and a
+ * few masks). Found by its signature in the bulk region and only accepted when its IHDR agrees with
+ * the size the asset reports, so a stray signature cannot be mistaken for the source.
+ */
+const findRawSource = (pkg: UePackage, texture: UeTexture): ExtractedImage | null => {
+  const b = pkg.bytes
+  const start = Math.max(0, Math.min(pkg.summary.bulkDataStartOffset, b.byteLength))
+  for (let i = start; i + 24 <= b.byteLength; i++) {
+    if (!startsWith(b, i, PNG_SIG)) continue
+    const head = pngHeader(b, i)
+    if (!head) continue
+    if (texture.source.width && (head.width !== texture.source.width || head.height !== texture.source.height)) continue
+    return {
+      data: b.subarray(i, pngEnd(b, i)),
+      mimeType: "image/png",
+      swapRb: /^TSF_BGRA8/i.test(texture.source.format),
+      texture,
+    }
+  }
+  return null
+}
+
+/**
+ * UE4 keeps the source in a plain `FByteBulkData` that `UTexture::Serialize` writes right after the
+ * object's tag list — UObject's has-guid flag (a 4-byte bool, + the guid), `FStripDataFlags` (two
+ * bytes), then the bulk header. The payload is UE's zlib-chunked container (`inflateChunked`), and
+ * what it holds is the PNG/JPEG the artist imported, like the UE5 buffer's.
+ */
+const ue4Source = (pkg: UePackage, texture: UeTexture): ExtractedImage => {
+  const found = findExport(pkg, "Texture2D")!
+  const { reader: r, props } = readObjectProperties(pkg, found.export)
+  r.offset = props.end
+  if (r.i32()) r.skip(16)                                             // UObject: its guid, when it has one
+  const strip = r.u8(); r.u8()                                        // FStripDataFlags: global, class
+  if (strip & 0x1) throw new Error(`${pkg.label}: the editor data is stripped (a cooked texture) — no source image to read`)
+  const payload = readBulkPayload(pkg, readBulkHeader(r))
+  const img = imageAt(payload)
+  if (!img) {
+    throw new Error(`${pkg.label}: the UE4 source is raw ${texture.source.format || "pixels"} (${texture.source.width}×${texture.source.height}), not a PNG/JPEG — not supported yet`)
+  }
+  return { data: payload.subarray(img.at), mimeType: img.mimeType, swapRb: /^TSF_BGRA8/i.test(texture.source.format), texture }
+}
+
 /**
  * The image inside a texture asset. Throws with the Oodle message when the decoder is missing —
- * callers that can live without textures should catch it and say so once.
+ * callers that can live without textures should catch it and say so once. A UE4 package (read with
+ * `{ ue4: true }`) takes the plain bulk-data path instead.
  */
 export const extractTexture = async (pkg: UePackage): Promise<ExtractedImage> => {
   const texture = readTexture2D(pkg)
+  if (pkg.summary.ue5 === 0) return ue4Source(pkg, texture)
   const buf = findCompressedBuffer(pkg)
-  if (!buf) throw new Error(`${pkg.label}: no source image payload (a texture with its source stripped?)`)
+  if (!buf) {
+    const raw = findRawSource(pkg, texture)
+    if (raw) return raw
+    throw new Error(`${pkg.label}: no source image payload (a texture with its source stripped?)`)
+  }
   const payload = await decodeCompressedBuffer(pkg, buf)
   const img = imageAt(payload)
   if (!img) {

package/src/unreal/toDocument.ts

@@ -193,6 +193,7 @@ export const unrealToDocument = (input: UnrealDocumentInput, opts: UnrealDocumen
 
   let flippedWinding = false
   let droppedWeight = 0
+  let unweighted = 0
 
   // ---- mesh + skin ----
   if (mesh) {
@@ -218,12 +219,18 @@ export const unrealToDocument = (input: UnrealDocumentInput, opts: UnrealDocumen
       const total = list.reduce((n, i) => n + i.weight, 0)
       const kept = keep.reduce((n, i) => n + i.weight, 0)
       if (total > 0) droppedWeight += total - kept
+      // A point with NO influence is bound to the ROOT bone — what UE's importer does with every
+      // unweighted vertex. Left at weight 0 it skins to the origin: the FPS Animation Pack's MX16A4
+      // keeps its whole barrel and handguard unweighted (14 088 of 15 696 points in one section),
+      // and those collapsed triangles took the desktop host down inside the next UI draw.
+      if (kept <= 0) { pointJoints[p * MAX_JOINTS_PER_VERTEX] = 0; pointWeights[p * MAX_JOINTS_PER_VERTEX] = 1; unweighted++; continue }
       const norm = kept > 0 ? 1 / kept : 0
       keep.forEach((inf, k) => {
         pointJoints[p * MAX_JOINTS_PER_VERTEX + k] = inf.bone >= 0 && inf.bone < joints.length ? inf.bone : 0
         pointWeights[p * MAX_JOINTS_PER_VERTEX + k] = inf.weight * norm
       })
     }
+    if (unweighted) warn({ level: "info", message: `mesh '${mesh.name}': ${unweighted} of ${perPoint.length} points carry no skin weight — bound to the root bone '${mesh.bones[0]?.name ?? "?"}', as UE's importer does` })
 
     // normals: the per-corner TangentZ of every face using a wedge, accumulated
     const wedgeCount = mesh.wedgePoint.length

package/src/unreal/versions.ts

@@ -60,7 +60,10 @@ export const UE4 = {
   PACKAGE_SUMMARY_HAS_COMPATIBLE_ENGINE_VERSION: 444,
   SERIALIZE_TEXT_IN_PACKAGES: 459,
   COOKED_ASSETS_IN_EDITOR_SUPPORT: 485,
+  /** A struct array's payload opens with an inner tag naming the struct. */
   INNER_ARRAY_TAG_INFO: 500,
+  /** A property tag may carry a property guid (a has-guid byte after the extras). */
+  PROPERTY_GUID_IN_PROPERTY_TAG: 503,
   NAME_HASHES_SERIALIZED: 504,
   PRELOAD_DEPENDENCIES_IN_COOKED_EXPORTS: 507,
   TEMPLATE_INDEX_IN_COOKED_EXPORTS: 508,
@@ -83,6 +86,11 @@ export const LEGACY = {
   UE5_6: -9,
 } as const
 
+/** The oldest `FileVersionUE4` a UE4 package may carry when a reader opts in (`{ ue4: true }`):
+ *  `ADDED_PACKAGE_OWNER`, UE 4.25 — the "Bullet Impact VFX" pack, whose "UE_5.0" download is 4.25
+ *  packages throughout. */
+export const UE4_VERSION_MIN = 459
+
 /** The newest `FileVersionUE5` this reader has verified against real files. */
 export const UE5_VERSION_MAX = UE5.IMPORT_TYPE_HIERARCHIES
 /** The oldest — UE 5.0. Earlier UE5 previews are refused. */