lecodes-assets 0.2.0 → 2.4.10

package/src/unreal/list.ts

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

package/src/unreal/materialGraph.ts

@@ -0,0 +1,224 @@
+// A Material's EXPRESSION GRAPH — the nodes the artist wired in the material editor, as data.
+//
+// `materials.ts` places textures by what their names suggest, because what a parameter DOES is a
+// property of the graph. This reads the graph itself: every `MaterialExpression*` export with its
+// scalar settings (a Constant's `R`, a ScalarParameter's name and default, a TextureSample's asset)
+// and its inputs as edges (`{ node, output, mask }`), plus the material's own outputs (BaseColor,
+// Opacity, Normal, …) as edges into it. A tool can then EVALUATE the graph — e.g. bake what a decal
+// material computes into a texture a renderer without that shader can use.
+//
+// An input (`FExpressionInput` and its Color/Scalar/Vector subclasses) is a StructProperty whose
+// payload is native, not a tag list: the expression (package index), the output index, the input's
+// name, the mask flag and the four channel masks, then the subclass's own constant. Only the common
+// head is read. Output indices follow each class's own output list — a TextureSample's are RGB, R,
+// G, B, A, RGBA — and `mask` spells the channels the edge takes ("rgb", "a", "" = all).
+//
+// Verified on UE 4.25 packages (the "Bullet Impact VFX" pack's decal materials, read with
+// `{ ue4: true }`). UE5 writes the same input head, but its editor-only data moved to
+// `MaterialEditorOnlyData` — a UE5 Material's outputs are read from that export when present.
+
+import { classOf, readFName, readObjectProperties, readProperties, propInt, resolveObject, type PropertyTag, type UePackage, type BinaryReader } from "./package"
+
+export type MaterialEdge = {
+  /** The expression the edge comes from (its object name, e.g. `MaterialExpressionMultiply_21`). */
+  node: string
+  /** Which of that expression's outputs. */
+  output: number
+  /** The channels taken: `"rgb"`, `"a"`, `"r"` … or `""` for the output as it is. */
+  mask: string
+}
+
+export type MaterialExpression = {
+  /** `Multiply`, `LinearInterpolate`, `TextureSample`, … (the class without `MaterialExpression`). */
+  kind: string
+  /** Connected inputs by their property name (`A`, `B`, `Alpha`, `Input`, `Coordinates`, …). */
+  inputs: Record<string, MaterialEdge>
+  /** Everything scalar the expression carries: numbers, names, enums, booleans, colours, and
+   *  object references as the referenced asset's path (`Texture` → `/Game/…/T_x`). */
+  values: Record<string, number | string | boolean | number[]>
+}
+
+export type MaterialGraph = {
+  name: string
+  /** `MD_Surface`, `MD_DeferredDecal`, …; `BLEND_Opaque`, `BLEND_Translucent`, …; `MSM_DefaultLit`, …. */
+  domain: string
+  blendMode: string
+  shadingModel: string
+  /** The material's own pins (`BaseColor`, `Opacity`, `Normal`, `Metallic`, `Roughness`, `EmissiveColor`, …). */
+  outputs: Record<string, MaterialEdge>
+  /** Every other scalar setting on the material (two-sided, tangent-space normal, …). */
+  settings: Record<string, number | string | boolean | number[]>
+  expressions: Record<string, MaterialExpression>
+}
+
+/** Struct types that are an expression input (`FExpressionInput` and its subclasses). */
+const isInputStruct = (s: string | undefined): boolean => !!s && /(^ExpressionInput$|MaterialInput$)/.test(s)
+
+const MASK = [ "r", "g", "b", "a" ]
+
+/** The native head of an `FExpressionInput`: expression, output index, input name, mask, r/g/b/a. */
+const readEdge = (pkg: UePackage, r: BinaryReader, tag: PropertyTag): MaterialEdge | null => {
+  if (isTaggedEdge(pkg, r, tag)) return readTaggedEdge(pkg, r, tag)
+  if (tag.size < 36) return null
+  r.offset = tag.data
+  const expr = r.i32(), output = r.i32()
+  readFName(r, pkg.names)                                             // the input's display name
+  const masked = r.i32() !== 0
+  const channels = [ r.i32(), r.i32(), r.i32(), r.i32() ]
+  return edgeTo(pkg, expr, output, masked, channels)
+}
+
+const EDGE_FIELDS = new Set([ "Expression", "OutputIndex", "InputName", "Mask", "MaskR", "MaskG", "MaskB", "MaskA", "ExpressionName", "None" ])
+
+/**
+ * Old UE4 (seen on 4.10, file version 482) writes an input as an ordinary TAG LIST — `Expression`
+ * (ObjectProperty), `OutputIndex`, `Mask`, `MaskR`… each only when it is not the default — instead of
+ * the native head. Told apart by its first two names: a field of the struct, then a property type.
+ */
+const isTaggedEdge = (pkg: UePackage, r: BinaryReader, tag: PropertyTag): boolean => {
+  if (tag.size < 8 || pkg.summary.ue5 !== 0) return false
+  r.offset = tag.data
+  const n0 = r.i32()
+  if (n0 < 0 || n0 >= pkg.names.length || !EDGE_FIELDS.has(pkg.names[n0])) return false
+  if (pkg.names[n0] === "None") return tag.size === 8
+  r.i32()
+  const n2 = r.i32()
+  return n2 >= 0 && n2 < pkg.names.length && pkg.names[n2].endsWith("Property")
+}
+
+const readTaggedEdge = (pkg: UePackage, r: BinaryReader, tag: PropertyTag): MaterialEdge | null => {
+  r.offset = tag.data
+  const p = readProperties(r, pkg)
+  const int = (n: string): number => propInt(r, p.byName.get(n)) ?? 0
+  return edgeTo(pkg, int("Expression"), int("OutputIndex"), int("Mask") !== 0, [ int("MaskR"), int("MaskG"), int("MaskB"), int("MaskA") ])
+}
+
+const edgeTo = (pkg: UePackage, expr: number, output: number, masked: boolean, channels: number[]): MaterialEdge | null => {
+  if (expr === 0) return null
+  const target = resolveObject(pkg, expr)
+  if (!target) return null
+  return { node: target.name, output, mask: masked ? channels.map((c, i) => (c ? MASK[i] : "")).join("") : "" }
+}
+
+/** A tag's value when it is a plain setting; undefined for what this reader does not model. */
+const readValue = (pkg: UePackage, r: BinaryReader, t: PropertyTag): number | string | boolean | number[] | undefined => {
+  r.offset = t.data
+  switch (t.type) {
+    case "FloatProperty": return r.f32()
+    case "DoubleProperty": return r.f64()
+    case "IntProperty": return r.i32()
+    case "BoolProperty": return t.bool ?? false
+    case "NameProperty": return readFName(r, pkg.names)
+    case "StrProperty": return r.fstring()
+    case "EnumProperty": return readFName(r, pkg.names)
+    case "ByteProperty": return t.enumName && t.enumName !== "None" ? readFName(r, pkg.names) : r.u8()
+    case "ObjectProperty": {
+      const o = resolveObject(pkg, r.i32())
+      if (!o) return undefined
+      return o.kind === "import" && o.packagePath ? o.packagePath : o.name
+    }
+    case "StructProperty":
+      if (t.struct === "LinearColor") return [ r.f32(), r.f32(), r.f32(), r.f32() ]
+      if (t.struct === "Color") { const b = r.raw(4); return [ b[2] / 255, b[1] / 255, b[0] / 255, b[3] / 255 ] }   // BGRA in memory
+      return undefined
+    default: return undefined
+  }
+}
+
+// Bookkeeping every expression carries that says nothing about what it computes.
+const NOISE = /^(MaterialExpressionEditor[XY]|MaterialExpressionGuid|ExpressionGUID|Material|Function|Desc|bCollapsed|bRealtimePreview|bHidePreviewWindow|bShowOutputNameOnPin|bNeedToUpdatePreview|Outputs|SortPriority|Group)$/
+
+/** What an edge evaluates to when everything upstream of it is a number — `null` as soon as anything
+ *  is not (a texture, a vertex colour, UVs, an expression this does not model). Output 0 is the whole
+ *  value, output k the k-th channel (a VectorParameter's RGB / R / G / B / A); the edge's mask then
+ *  takes its channels. Properties left at their class default are not serialised, so the defaults
+ *  are UE's: a Constant's R 0, a Multiply's ConstB 1, a Lerp's ConstAlpha 0.5. */
+export const evaluateConstant = (graph: MaterialGraph, edge: MaterialEdge | undefined, depth = 0): number[] | null => {
+  if (!edge || depth > 64) return null
+  const ex = graph.expressions[edge.node]
+  if (!ex) return null
+  const num = (k: string, d = 0): number => (typeof ex.values[k] === "number" ? ex.values[k] as number : d)
+  const vec = (k: string, d: number[]): number[] => (Array.isArray(ex.values[k]) ? [ ...(ex.values[k] as number[]) ] : d)
+  const arg = (pin: string, constKey: string, d: number): number[] | null =>
+    ex.inputs[pin] ? evaluateConstant(graph, ex.inputs[pin], depth + 1) : [ num(constKey, d) ]
+  const zip = (a: number[], b: number[], f: (x: number, y: number) => number): number[] => {
+    const n = Math.max(a.length, b.length)
+    return Array.from({ length: n }, (_, i) => f(a.length === 1 ? a[0] : a[i] ?? 0, b.length === 1 ? b[0] : b[i] ?? 0))
+  }
+  let v: number[] | null
+  switch (ex.kind) {
+    case "Constant": v = [ num("R") ]; break
+    case "Constant2Vector": v = [ num("R"), num("G") ]; break
+    case "Constant3Vector": v = vec("Constant", [ 0, 0, 0, 0 ]).slice(0, 3); break
+    case "Constant4Vector": v = vec("Constant", [ 0, 0, 0, 0 ]); break
+    case "ScalarParameter": case "StaticBoolParameter": v = [ num("DefaultValue") ]; break
+    case "VectorParameter": v = vec("DefaultValue", [ 0, 0, 0, 1 ]); break
+    case "Multiply": case "Add": case "Subtract": case "Divide": case "Max": case "Min": {
+      const a = arg("A", "ConstA", ex.kind === "Multiply" || ex.kind === "Divide" ? 1 : 0)
+      const b = arg("B", "ConstB", ex.kind === "Multiply" || ex.kind === "Add" || ex.kind === "Divide" ? 1 : 0)
+      if (!a || !b) return null
+      const op = { Multiply: (x: number, y: number) => x * y, Add: (x: number, y: number) => x + y, Subtract: (x: number, y: number) => x - y,
+        Divide: (x: number, y: number) => (y ? x / y : 0), Max: Math.max, Min: Math.min }[ex.kind]
+      v = zip(a, b, op)
+      break
+    }
+    case "OneMinus": { const a = arg("Input", "", 0); v = a && a.map((x) => 1 - x); break }
+    case "LinearInterpolate": {
+      const a = arg("A", "ConstA", 0), b = arg("B", "ConstB", 1), t = arg("Alpha", "ConstAlpha", 0.5)
+      if (!a || !b || !t) return null
+      v = zip(zip(a, b, (x, y) => y - x), t, (d, s) => d * s).map((d, i) => (a.length === 1 ? a[0] : a[i] ?? 0) + d)
+      break
+    }
+    default: return null
+  }
+  if (!v) return null
+  if (edge.output > 0) v = [ v[edge.output - 1] ?? 0 ]
+  if (edge.mask) v = [ ...edge.mask ].map((c) => v![MASK.indexOf(c)] ?? v![0] ?? 0)
+  return v
+}
+
+/** The expression graph of the package's Material (throws when it holds none). */
+export const readMaterialGraph = (pkg: UePackage): MaterialGraph => {
+  const exports = pkg.exports.map((e, i) => ({ e, i, cls: classOf(pkg, e) }))
+  const mat = exports.find((x) => x.cls === "Material")
+  if (!mat) throw new Error(`${pkg.label}: no Material export (${[ ...new Set(exports.map((x) => x.cls)) ].join(", ")})`)
+  const graph: MaterialGraph = { name: mat.e.objectName, domain: "MD_Surface", blendMode: "BLEND_Opaque", shadingModel: "MSM_DefaultLit", outputs: {}, settings: {}, expressions: {} }
+
+  // the material's own pins: on the Material in UE4, on its MaterialEditorOnlyData in UE5
+  const pinsFrom = [ mat, ...exports.filter((x) => x.cls === "MaterialEditorOnlyData") ]
+  for (const src of pinsFrom) {
+    const { reader: r, props } = readObjectProperties(pkg, src.e)
+    for (const t of props.list) {
+      if (t.type === "StructProperty" && isInputStruct(t.struct)) {
+        const edge = readEdge(pkg, r, t)
+        if (edge) graph.outputs[t.name] = edge
+        continue
+      }
+      if (src !== mat || NOISE.test(t.name)) continue
+      const v = readValue(pkg, r, t)
+      if (v === undefined) continue
+      if (t.name === "MaterialDomain") graph.domain = String(v)
+      else if (t.name === "BlendMode") graph.blendMode = String(v)
+      else if (t.name === "ShadingModel") graph.shadingModel = String(v)
+      else graph.settings[t.name] = v
+    }
+  }
+
+  for (const x of exports) {
+    if (!x.cls.startsWith("MaterialExpression") || x.cls === "MaterialExpressionComment") continue
+    const { reader: r, props } = readObjectProperties(pkg, x.e)
+    const ex: MaterialExpression = { kind: x.cls.slice("MaterialExpression".length), inputs: {}, values: {} }
+    for (const t of props.list) {
+      if (NOISE.test(t.name)) continue
+      if (t.type === "StructProperty" && isInputStruct(t.struct)) {
+        const edge = readEdge(pkg, r, t)
+        if (edge) ex.inputs[t.name] = edge
+        continue
+      }
+      const v = readValue(pkg, r, t)
+      if (v !== undefined) ex.values[t.name] = v
+    }
+    graph.expressions[x.e.objectName] = ex
+  }
+  return graph
+}