lecodes-assets 0.2.1 → 2.5.0

package/src/unity/unityMesh.ts

@@ -0,0 +1,151 @@
+// A Unity MESH ASSET (`!u!43` in a text-serialised `.asset`) as a glTF mesh — the geometry a pack
+// authored INSIDE Unity rather than in a modelling tool: NatureManufacture's tree LOD3 is a hand-made
+// cross of quads saved as `<Tree>_Mesh_s.asset` and referenced by the prefab's last LODGroup level,
+// so a kind built from FBX sources alone silently loses its far level and the forest pops out at
+// 0.026 screen heights. Only what such a mesh carries is read: positions, normals, tangents, colours,
+// up to four UV sets, 16/32-bit indices, triangles. Skins, blend shapes and compressed meshes are not
+// (a `.asset` mesh with bones is not something a pack ships).
+//
+// FRAME. The importer's FBX sources hold Unity's mesh MIRRORED BACK on X (ufbx reads the file in its
+// own right-handed frame; Unity's import negated X), and every part of a kind goes through the same
+// mirror later. A mesh saved by Unity is already in Unity's frame, so it is negated on X here —
+// positions, normals, tangent xyz — with the tangent sign and the triangle winding flipped, which is
+// what a reflection does to a handedness. After that it is indistinguishable from an FBX mesh.
+
+import { Document, type Mesh } from "@gltf-transform/core"
+import { readFileSync } from "node:fs"
+import { isMap, num, readUnityObjects, str, type Y, type YMap } from "./yaml"
+
+/** Unity's VertexFormat: bytes per component and how to read one. */
+const FORMATS: Record<number, { size: number, read: (v: DataView, o: number) => number }> = {
+  0: { size: 4, read: (v, o) => v.getFloat32(o, true) },
+  1: { size: 2, read: (v, o) => half(v.getUint16(o, true)) },
+  2: { size: 1, read: (v, o) => v.getUint8(o) / 255 },
+  3: { size: 1, read: (v, o) => Math.max(-1, v.getInt8(o) / 127) },
+  4: { size: 2, read: (v, o) => v.getUint16(o, true) / 65535 },
+  5: { size: 2, read: (v, o) => Math.max(-1, v.getInt16(o, true) / 32767) },
+  6: { size: 1, read: (v, o) => v.getUint8(o) },
+  7: { size: 1, read: (v, o) => v.getInt8(o) },
+  8: { size: 2, read: (v, o) => v.getUint16(o, true) },
+  9: { size: 2, read: (v, o) => v.getInt16(o, true) },
+  10: { size: 4, read: (v, o) => v.getUint32(o, true) },
+  11: { size: 4, read: (v, o) => v.getInt32(o, true) },
+}
+
+const half = (h: number): number => {
+  const s = h >> 15 ? -1 : 1, e = (h >> 10) & 0x1f, m = h & 0x3ff
+  if (e === 0) return s * m * 2 ** -24
+  if (e === 31) return m ? NaN : s * Infinity
+  return s * (1 + m / 1024) * 2 ** (e - 15)
+}
+
+/** Unity's vertex channel order → the glTF attribute it is (blend weights / indices are not read). */
+const CHANNELS: (string | null)[] = [ "POSITION", "NORMAL", "TANGENT", "COLOR_0", "TEXCOORD_0", "TEXCOORD_1", "TEXCOORD_2", "TEXCOORD_3", null, null, null, null, null, null ]
+
+const hex = (s: string): Uint8Array => {
+  const out = new Uint8Array(s.length >> 1)
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(s.substr(i * 2, 2), 16)
+  return out
+}
+
+export type UnityMeshAsset = { name: string, mesh: Mesh, doc: Document }
+
+/** Is this text a Unity mesh asset at all? Cheap: the class tag, before any parsing. */
+export const isUnityMeshAsset = (text: string): boolean => /^--- !u!43 /m.test(text)
+
+/**
+ * Read the mesh object of a text-serialised `.asset`. Null when the file holds no readable mesh
+ * (binary, compressed, external stream data, no vertices, no triangles).
+ */
+export const readUnityMeshAsset = (path: string): UnityMeshAsset | null => {
+  const text = readFileSync(path, "utf8")
+  if (!isUnityMeshAsset(text)) return null
+  const obj = readUnityObjects(text).find((o) => o.classID === 43)
+  if (!obj) return null
+  const b = obj.body
+  const vd = isMap(b.m_VertexData) ? b.m_VertexData : null
+  if (!vd) return null
+  const vcount = num(vd.m_VertexCount)
+  const data = hex(str(vd._typelessdata))
+  if (!vcount || data.length === 0) return null
+  if (isMap(b.m_StreamData) && num(b.m_StreamData.size) > 0) return null
+  if (num(b.m_MeshCompression) !== 0) return null
+
+  // channels → streams: a stream's stride is the end of its last channel rounded up to 4, streams
+  // follow one another 16-aligned
+  type Ch = { stream: number, offset: number, format: number, dim: number, attr: string | null }
+  const channels: Ch[] = (Array.isArray(vd.m_Channels) ? vd.m_Channels : []).map((c: Y, i: number): Ch => {
+    const m = isMap(c) ? c : ({} as YMap)
+    return { stream: num(m.stream), offset: num(m.offset), format: num(m.format), dim: num(m.dimension) & 0xf, attr: CHANNELS[i] ?? null }
+  })
+  const streams = Math.max(0, ...channels.map((c) => c.stream)) + 1
+  const stride: number[] = [], base: number[] = []
+  let cursor = 0
+  for (let s = 0; s < streams; s++) {
+    let end = 0
+    for (const c of channels) if (c.stream === s && c.dim > 0) end = Math.max(end, c.offset + c.dim * (FORMATS[c.format]?.size ?? 4))
+    stride[s] = (end + 3) & ~3
+    base[s] = cursor
+    cursor += stride[s] * vcount
+    cursor = (cursor + 15) & ~15
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
+
+  const doc = new Document()
+  const buffer = doc.createBuffer()
+  const mesh = doc.createMesh(str(b.m_Name))
+  const attrs = new Map<string, { data: Float32Array<ArrayBuffer>, dim: number }>()
+  for (const c of channels) {
+    if (!c.attr || c.dim === 0) continue
+    const fmt = FORMATS[c.format]
+    if (!fmt) continue
+    // glTF wants TANGENT as vec4 (w = sign), UVs as vec2; colours keep their width (3 or 4)
+    const dim = c.attr === "TANGENT" ? 4 : c.attr.startsWith("TEXCOORD") ? 2 : c.dim
+    const out = new Float32Array(new ArrayBuffer(vcount * dim * 4))
+    for (let i = 0; i < vcount; i++) {
+      const at = base[c.stream] + i * stride[c.stream] + c.offset
+      for (let k = 0; k < dim; k++) out[i * dim + k] = k < c.dim ? fmt.read(view, at + k * fmt.size) : (k === 3 ? 1 : 0)
+    }
+    attrs.set(c.attr, { data: out, dim })
+  }
+  const pos = attrs.get("POSITION")
+  if (!pos || pos.dim !== 3) return null
+
+  // THE MIRROR (see the header): x negated on positions / normals / tangents, the tangent sign
+  // flipped; Unity's UV origin is bottom-left where glTF's is top-left
+  for (const key of [ "POSITION", "NORMAL", "TANGENT" ]) {
+    const a = attrs.get(key)
+    if (!a) continue
+    for (let i = 0; i < vcount; i++) {
+      a.data[i * a.dim] = -a.data[i * a.dim]
+      if (key === "TANGENT") a.data[i * 4 + 3] = -a.data[i * 4 + 3]
+    }
+  }
+  for (const [ key, a ] of attrs) if (key.startsWith("TEXCOORD")) for (let i = 0; i < vcount; i++) a.data[i * 2 + 1] = 1 - a.data[i * 2 + 1]
+
+  const idxHex = hex(str(b.m_IndexBuffer))
+  const wide = num(b.m_IndexFormat) === 1
+  const iv = new DataView(idxHex.buffer, idxHex.byteOffset, idxHex.byteLength)
+  const subs = Array.isArray(b.m_SubMeshes) ? b.m_SubMeshes : []
+  for (const s of subs) {
+    if (!isMap(s)) continue
+    if (num(s.topology) !== 0) continue // triangles only
+    const first = num(s.firstByte), count = num(s.indexCount), baseVertex = num(s.baseVertex)
+    if (count < 3 || first + count * (wide ? 4 : 2) > idxHex.length) continue
+    const idx = new Uint32Array(new ArrayBuffer(count * 4))
+    for (let i = 0; i < count; i++) idx[i] = (wide ? iv.getUint32(first + i * 4, true) : iv.getUint16(first + i * 2, true)) + baseVertex
+    // winding: a reflection turns every triangle inside out
+    for (let i = 0; i + 2 < count; i += 3) { const t = idx[i + 1]; idx[i + 1] = idx[i + 2]; idx[i + 2] = t }
+    const prim = doc.createPrimitive().setMode(4)
+    for (const [ key, a ] of attrs) {
+      const type = a.dim === 2 ? "VEC2" : a.dim === 3 ? "VEC3" : "VEC4"
+      prim.setAttribute(key, doc.createAccessor().setType(type).setArray(a.data).setBuffer(buffer))
+    }
+    prim.setIndices(doc.createAccessor().setType("SCALAR").setArray(idx).setBuffer(buffer))
+    mesh.addPrimitive(prim)
+  }
+  if (!mesh.listPrimitives().length) return null
+  const node = doc.createNode(str(b.m_Name)).setMesh(mesh)
+  doc.createScene(str(b.m_Name)).addChild(node)
+  return { name: str(b.m_Name), mesh, doc }
+}

package/src/unity/unpack.ts

@@ -1,19 +1,26 @@
 // `.unitypackage` reader. The file is a gzip'd tar of one folder per asset GUID holding `asset`
-// (the bytes), `asset.meta` and `pathname` (its path under Assets/). Two streaming passes keep
+// (the bytes), `asset.meta` and `pathname` (its path under Assets/) — gzip'd or, from some publishers,
+// a plain tar under the same extension (sniffed by the magic). Two streaming passes keep
 // memory flat on multi-GB packs: pass 1 indexes GUID → path (written as `unity-index.txt` at the
 // output root — `convert` resolves Unity material textures through it), pass 2 writes the files
 // that match the requested patterns (everything by default), `.meta` sidecars included so the
 // result is also a valid Unity project fragment.
 
-import { createReadStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { closeSync, createReadStream, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync, writeSync } from "node:fs"
 import { dirname, join } from "node:path"
 import { createGunzip } from "node:zlib"
 
 type Entry = { name: string, size: number }
 
+/** gzip's magic — some publishers ship the tar UNCOMPRESSED under the same extension. */
+const isGzip = (file: string): boolean => {
+  const fd = openSync(file, "r")
+  try { const h = Buffer.alloc(2); return readSync(fd, h, 0, 2, 0) === 2 && h[0] === 0x1f && h[1] === 0x8b } finally { closeSync(fd) }
+}
+
 const tarStream = (file: string, onEntry: (e: Entry, data: Uint8Array) => void): Promise<void> => new Promise((resolveP, rejectP) => {
-  const gunzip = createGunzip()
-  createReadStream(file, { highWaterMark: 1 << 22 }).on("error", rejectP).pipe(gunzip)
+  const raw = createReadStream(file, { highWaterMark: 1 << 22 }).on("error", rejectP)
+  const gunzip: NodeJS.ReadableStream = isGzip(file) ? raw.pipe(createGunzip().on("error", rejectP)) : raw
   let buf: Buffer = Buffer.alloc(0)
   let state: "header" | "body" | "pad" = "header"
   let entry: Entry | null = null
@@ -94,6 +101,18 @@ export const readUnityIndex = (file: string): Map<string, string> => {
   return map
 }
 
+/** Node's fs cannot write more than 2 GiB - 1 in one call, and a .unitypackage can carry a single
+ *  asset over that (Chernobyl v1.0 ships a 2.46 GB one). `writeFileSync` throws ERR_OUT_OF_RANGE
+ *  from deep inside the gunzip callback, which reads as a corrupt archive rather than as a limit —
+ *  the extraction simply stops a few hundred files in, with the index already written and no clue
+ *  which asset did it. Slice the write instead. */
+const WRITE_CAP = 0x7fffffff
+const writeWhole = (dest: string, data: Uint8Array): void => {
+  if (data.length <= WRITE_CAP) { writeFileSync(dest, data); return }
+  const fd = openSync(dest, "w")
+  try { for (let o = 0; o < data.length; o += WRITE_CAP) writeSync(fd, data, o, Math.min(WRITE_CAP, data.length - o)) } finally { closeSync(fd) }
+}
+
 export type ExtractOptions = {
   /** Regexes (case-insensitive) a path must match; none = everything. */
   only?: RegExp[]
@@ -122,7 +141,7 @@ export const extractUnityPackage = async (pkg: string, index: Map<string, string
       try { if (statSync(dest).size === data.length) return } catch { /* fall through */ }
     }
     mkdirSync(dirname(dest), { recursive: true })
-    writeFileSync(dest, data)
+    writeWhole(dest, data)
     if (isAsset) { files++; bytes += data.length }
     if (files % 50 === 0) opts.progress?.(files, bytes)
   })

package/src/unity/yaml.ts

@@ -0,0 +1,131 @@
+// Unity's text serialisation: a YAML subset parser (what Unity writes — block maps/sequences, flow
+// maps, scalars) and the split of a `.unity` / `.prefab` / `.mat` file into its objects
+// (`--- !u!<classID> &<fileID>[ stripped]`), plus the small readers every consumer of those bodies
+// needs (refs, numbers, vectors).
+
+export type Y = string | Y[] | { [k: string]: Y }
+export type YMap = { [k: string]: Y }
+type Line = { indent: number, text: string }
+
+const splitLines = (text: string): Line[] => {
+  const raw = text.split(/\r?\n/)
+  const out: Line[] = []
+  for (let i = 0; i < raw.length; i++) {
+    let l = raw[i]
+    if (!l.trim() || l.startsWith("%")) continue
+    // wrapped flow maps: `{fileID: 1, guid: abc,` ⏎ `  type: 3}`
+    let open = (l.match(/\{/g) ?? []).length - (l.match(/\}/g) ?? []).length
+    while (open > 0 && i + 1 < raw.length) {
+      const nx = raw[++i]
+      l += " " + nx.trim()
+      open += (nx.match(/\{/g) ?? []).length - (nx.match(/\}/g) ?? []).length
+    }
+    // wrapped plain / quoted scalars (long `propertyPath` or `value` strings): a deeper line that is
+    // neither a key nor a list item continues the previous one
+    const indent = l.length - l.trimStart().length
+    const prev = out[out.length - 1]
+    if (prev && indent > prev.indent && !/^- |^-$/.test(l.trim()) && l.trim().search(/:( |$)/) < 0 && !l.trim().startsWith("{") && /: \S/.test(prev.text)) {
+      prev.text += " " + l.trim()
+      continue
+    }
+    out.push({ indent, text: l.trim() })
+  }
+  return out
+}
+
+const scalar = (s: string): Y => {
+  s = s.trim()
+  if (s === "" || s === "~" || s === "null") return ""
+  if (s === "[]") return []
+  if (s === "{}") return {}
+  if (s.startsWith("{") && s.endsWith("}")) {
+    const obj: YMap = {}
+    for (const part of s.slice(1, -1).split(",")) {
+      const c = part.indexOf(":")
+      if (c < 0) continue
+      obj[part.slice(0, c).trim()] = scalar(part.slice(c + 1))
+    }
+    return obj
+  }
+  if (s.startsWith("[") && s.endsWith("]")) return s.slice(1, -1).split(",").map((x) => scalar(x))
+  if ((s.startsWith("'") && s.endsWith("'")) || (s.startsWith("\"") && s.endsWith("\""))) return s.slice(1, -1).replace(/''/g, "'")
+  return s
+}
+
+export const parseUnityYaml = (text: string): YMap => {
+  const lines = splitLines(text)
+  let pos = 0
+  const parseValue = (minIndent: number): Y => {
+    if (pos >= lines.length || lines[pos].indent < minIndent) return ""
+    return lines[pos].text.startsWith("- ") || lines[pos].text === "-" ? parseSeq(lines[pos].indent) : parseMap(lines[pos].indent)
+  }
+  const parseMap = (indent: number): YMap => {
+    const obj: YMap = {}
+    while (pos < lines.length && lines[pos].indent === indent && !lines[pos].text.startsWith("- ")) {
+      const t = lines[pos].text
+      const c = t.search(/:( |$)/)
+      if (c < 0) { pos++; continue }
+      const key = t.slice(0, c).trim()
+      const rest = t.slice(c + 1).trim()
+      pos++
+      if (rest === "") obj[key] = pos < lines.length && lines[pos].indent > indent ? parseValue(indent + 1) : (pos < lines.length && lines[pos].indent === indent && lines[pos].text.startsWith("- ") ? parseSeq(indent) : "")
+      else obj[key] = scalar(rest)
+    }
+    return obj
+  }
+  const parseSeq = (indent: number): Y[] => {
+    const arr: Y[] = []
+    while (pos < lines.length && lines[pos].indent === indent && (lines[pos].text.startsWith("- ") || lines[pos].text === "-")) {
+      const rest = lines[pos].text.slice(1).trim()
+      if (rest === "") { pos++; arr.push(parseValue(indent + 1)); continue }
+      // a flow map / flow list / plain scalar item (`- {fileID: 0, guid: …}`) is one value, not a key
+      if (rest.startsWith("{") || rest.startsWith("[") || rest.search(/:( |$)/) < 0) { pos++; arr.push(scalar(rest)); continue }
+      // the item's first key shares the dash line; the rest of its keys sit two deeper
+      lines[pos] = { indent: indent + 2, text: rest }
+      arr.push(parseValue(indent + 2))
+    }
+    return arr
+  }
+  return parseMap(lines[0]?.indent ?? 0)
+}
+
+// ---- objects --------------------------------------------------------------------------------------
+
+export type UnityObject = { classID: number, id: string, stripped: boolean, cls: string, body: YMap }
+
+/** Split a text-serialised Unity file into its objects, each body parsed. */
+export const readUnityObjects = (text: string): UnityObject[] => {
+  const re = /^--- !u!(\d+) &(-?\d+)( stripped)?\s*$/gm
+  const starts: { idx: number, classID: number, id: string, stripped: boolean, end: number }[] = []
+  for (let m = re.exec(text); m; m = re.exec(text)) starts.push({ idx: m.index, classID: +m[1], id: m[2], stripped: !!m[3], end: m.index + m[0].length })
+  const out: UnityObject[] = []
+  for (let i = 0; i < starts.length; i++) {
+    const s = starts[i]
+    const body = parseUnityYaml(text.slice(s.end, i + 1 < starts.length ? starts[i + 1].idx : text.length))
+    const cls = Object.keys(body)[0] ?? ""
+    out.push({ classID: s.classID, id: s.id, stripped: s.stripped, cls, body: (body[cls] as YMap) ?? {} })
+  }
+  return out
+}
+
+// ---- value readers --------------------------------------------------------------------------------
+
+export type Ref = { fileID: string, guid?: string }
+export const isMap = (v: Y | undefined): v is YMap => typeof v === "object" && v !== null && !Array.isArray(v)
+export const ref = (v: Y | undefined): Ref => (isMap(v) ? { fileID: String(v.fileID ?? "0"), guid: typeof v.guid === "string" && v.guid ? v.guid : undefined } : { fileID: "0" })
+export const num = (v: Y | undefined, d = 0): number => { const n = typeof v === "string" ? Number(v) : NaN; return Number.isFinite(n) ? n : d }
+export const str = (v: Y | undefined): string => (typeof v === "string" ? v : "")
+export type Vec3 = [number, number, number]
+export type Quat = [number, number, number, number]
+export const vec3 = (v: Y | undefined, d: Vec3 = [ 0, 0, 0 ]): Vec3 => {
+  const o = isMap(v) ? v : {}
+  return [ num(o.x, d[0]), num(o.y, d[1]), num(o.z, d[2]) ]
+}
+export const quat = (v: Y | undefined): Quat => {
+  const o = isMap(v) ? v : {}
+  return [ num(o.x, 0), num(o.y, 0), num(o.z, 0), num(o.w, 1) ]
+}
+export const color = (v: Y | undefined): [number, number, number, number] => {
+  const o = isMap(v) ? v : {}
+  return [ num(o.r, 1), num(o.g, 1), num(o.b, 1), num(o.a, 1) ]
+}

package/src/unreal/index.ts

@@ -4,7 +4,7 @@
 
 import { readFileSync } from "node:fs"
 import { basename, dirname } from "node:path"
-import { readPackage, engineLabel, classOf, importPackagePath, type UePackage } from "./package"
+import { readPackage, engineLabel, classOf, importPackagePath, type UePackage, type ReadPackageOptions } from "./package"
 import { readSkeleton, type UeSkeleton } from "./skeleton"
 import { readAnimSequence, dataModelKind, packageKind, type UeAnimSequence, type DataModelKind } from "./anim"
 import { readSkeletalMesh, type UeSkeletalMesh } from "./mesh"
@@ -38,11 +38,12 @@ export type LoadedUnreal = {
 const packageCache = new Map<string, UePackage>()
 const skeletonCache = new Map<string, UeSkeleton>()
 
-export const readPackageFile = (path: string): UePackage => {
-  const hit = packageCache.get(path)
+export const readPackageFile = (path: string, opts: ReadPackageOptions = {}): UePackage => {
+  const key = opts.ue4 ? `${path}\0ue4` : path
+  const hit = packageCache.get(key)
   if (hit) return hit
-  const pkg = readPackage(new Uint8Array(readFileSync(path)), basename(path))
-  packageCache.set(path, pkg)
+  const pkg = readPackage(new Uint8Array(readFileSync(path)), basename(path), opts)
+  packageCache.set(key, pkg)
   return pkg
 }
 

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
+}