lecodes-assets 0.2.0 → 2.4.10

package/src/unreal/oodle.ts

@@ -0,0 +1,153 @@
+// Oodle: the codec Unreal compresses editor payloads (texture sources) with. It is proprietary —
+// RAD Game Tools', licensed by Epic — so nothing is shipped here. The decoder is loaded from a
+// library the machine ALREADY has: any `oo2core_*_win64.dll` (an Unreal install has one under
+// `Engine/Binaries/ThirdParty/Oodle/`, and so does most every UE game), or the Linux/macOS twin.
+// Only `OodleLZ_Decompress` is called, and only on bytes that came out of a `.uasset`.
+//
+// Two runtimes matter: the monorepo and the studio run on Bun (`bun:ffi`), while the `lecodes` CLI
+// is a Node binary (`koffi`, an optional dependency). Whichever is present is used; when neither is,
+// the message says exactly what to install or point at, and the caller carries on without textures.
+
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+export type OodleDecoder = {
+  path: string
+  runtime: "bun:ffi" | "koffi"
+  /** Decompress one block. `rawSize` is exact — Oodle needs to be told the output size. */
+  decompress: (src: Uint8Array, rawSize: number) => Uint8Array
+}
+
+const LIB_NAMES = process.platform === "win32" ? [ /^oo2core_\d+_win64\.dll$/i ]
+  : process.platform === "darwin" ? [ /^liboo2coremac64\..*$/i, /^liboo2core.*\.dylib$/i ]
+  : [ /^liboo2corelinux64\.so.*$/i, /^liboo2core.*\.so.*$/i ]
+
+const isLib = (name: string): boolean => LIB_NAMES.some((re) => re.test(name))
+
+/** Files matching an Oodle library name in `dir` (not recursive), newest SDK first. */
+const libsIn = (dir: string): string[] => {
+  try {
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) return []
+    return readdirSync(dir).filter(isLib).sort().reverse().map((n) => join(dir, n))
+  } catch { return [] }
+}
+
+/** Directories an Unreal install keeps the redistributable in (a few layouts across 5.x). */
+const unrealDirs = (): string[] => {
+  const roots: string[] = []
+  const bases = process.platform === "win32"
+    ? [ "C:/Program Files/Epic Games", "C:/Program Files (x86)/Epic Games", "D:/Epic Games", "D:/Program Files/Epic Games" ]
+    : [ join(homedir(), "UnrealEngine"), "/opt/UnrealEngine", "/Users/Shared/Epic Games" ]
+  for (const base of bases) {
+    try {
+      if (!existsSync(base)) continue
+      for (const entry of readdirSync(base)) {
+        if (!/^UE_?5/i.test(entry) && !/^Unreal/i.test(entry)) continue
+        const engine = join(base, entry, "Engine", "Binaries", "ThirdParty", "Oodle")
+        if (!existsSync(engine)) continue
+        roots.push(engine)
+        for (const sub of readdirSync(engine)) {                    // Win64 / Linux / Mac, or an SDK folder
+          const p = join(engine, sub)
+          if (statSync(p).isDirectory()) {
+            roots.push(p)
+            for (const sub2 of readdirSync(p)) { const q = join(p, sub2); if (statSync(q).isDirectory()) roots.push(q) }
+          }
+        }
+      }
+    } catch { /* an unreadable install is not an error */ }
+  }
+  return roots
+}
+
+/** Where the library was looked for, in order — what the "not found" message lists. */
+export const oodleSearchPath = (): string[] => [
+  ...[ process.env.LECODES_OODLE, process.env.UE_OODLE_DLL ].filter((v): v is string => !!v),
+  join(homedir(), ".lecodes", "oodle"),
+  ...unrealDirs(),
+]
+
+/** The library file, or null. An env var may name the file itself or the folder holding it. */
+export const findOodle = (): string | null => {
+  for (const entry of oodleSearchPath()) {
+    if (existsSync(entry) && statSync(entry).isFile()) return entry
+    const hit = libsIn(entry)[0]
+    if (hit) return hit
+  }
+  return null
+}
+
+export const OODLE_MISSING_MESSAGE =
+  "Unreal compresses texture sources with Oodle, which is proprietary and cannot be shipped here. " +
+  "Point LECODES_OODLE at an oo2core library — every Unreal install has one under " +
+  "Engine/Binaries/ThirdParty/Oodle/, and so does most any UE game — or drop the file into ~/.lecodes/oodle/. " +
+  "Everything else in the asset (geometry, skin, animation) reads without it."
+
+let cached: OodleDecoder | null | undefined
+
+/** The decoder, or null when no library/runtime is available. Loaded once per process. */
+export const getOodle = async (): Promise<OodleDecoder | null> => {
+  if (cached !== undefined) return cached
+  const path = findOodle()
+  if (!path) return (cached = null)
+  cached = (await loadBunFfi(path)) ?? (await loadKoffi(path))
+  return cached
+}
+
+/** Reset for tests (a decoder is otherwise loaded once and kept). */
+export const resetOodle = (): void => { cached = undefined }
+
+// OodleLZ_Decompress(src, srcLen, dst, dstLen, fuzzSafe=1, checkCRC=0, verbosity=0,
+//                    decBufBase, decBufSize, cb, cbUser, decoderMem, decoderMemSize, threadPhase=3)
+// The trailing arguments are the "no scratch buffer, no callback, decode in one go" defaults.
+
+const loadBunFfi = async (path: string): Promise<OodleDecoder | null> => {
+  if (typeof (globalThis as { Bun?: unknown }).Bun === "undefined") return null
+  try {
+    const { dlopen, FFIType, ptr } = await import("bun:ffi")
+    const lib = dlopen(path, {
+      OodleLZ_Decompress: {
+        args: [ FFIType.ptr, FFIType.i64, FFIType.ptr, FFIType.i64, FFIType.i32, FFIType.i32, FFIType.i32,
+                FFIType.ptr, FFIType.i64, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.i64, FFIType.i32 ],
+        returns: FFIType.i64,
+      },
+    })
+    return {
+      path, runtime: "bun:ffi",
+      decompress: (src, rawSize) => {
+        // Oodle may read a little past the end of the output buffer; the pad is what UE allocates too.
+        const dst = new Uint8Array(rawSize + 64)
+        const n = Number(lib.symbols.OodleLZ_Decompress(ptr(src), BigInt(src.byteLength), ptr(dst), BigInt(rawSize),
+          1, 0, 0, null, 0n, null, null, null, 0n, 3))
+        if (n !== rawSize) throw new Error(`Oodle decompressed ${n} bytes, expected ${rawSize} (${path})`)
+        return dst.subarray(0, rawSize)
+      },
+    }
+  } catch { return null }
+}
+
+const loadKoffi = async (path: string): Promise<OodleDecoder | null> => {
+  try {
+    // @ts-ignore — an optional peer: present only when the Node build needs it
+    const koffi = (await import("koffi")).default as {
+      load: (p: string) => { func: (signature: string) => (...args: unknown[]) => number }
+    }
+    const lib = koffi.load(path)
+    const fn = lib.func("int64_t OodleLZ_Decompress(const void *src, int64_t srcLen, void *dst, int64_t dstLen, "
+      + "int fuzz, int crc, int verbosity, void *decBufBase, int64_t decBufSize, void *cb, void *cbUser, "
+      + "void *decoderMem, int64_t decoderMemSize, int threadPhase)")
+    return {
+      path, runtime: "koffi",
+      decompress: (src, rawSize) => {
+        const dst = Buffer.alloc(rawSize + 64)
+        const n = Number(fn(src, src.byteLength, dst, rawSize, 1, 0, 0, null, 0, null, null, null, 0, 3))
+        if (n !== rawSize) throw new Error(`Oodle decompressed ${n} bytes, expected ${rawSize} (${path})`)
+        return new Uint8Array(dst.buffer, dst.byteOffset, rawSize)
+      },
+    }
+  } catch { return null }
+}
+
+export const OODLE_NO_RUNTIME_MESSAGE =
+  "an Oodle library was found but no way to call it: run the pipeline under Bun, or `npm i koffi` "
+  + "next to lecodes-assets so the Node build can load it"