lecodes-assets 0.2.0 → 2.4.10

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

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