lecodes-assets 0.1.2 → 0.2.1

package/src/unity/materials.ts

@@ -0,0 +1,593 @@
+// Unity materials as the texture source of truth.
+//
+// An FBX exported for Unity usually references only a base colour (often a legacy file name) and a
+// normal map; the real shading inputs live in the Unity `.mat` next to it — metallic, roughness /
+// smoothness, occlusion (separate maps or an ORM / MaskMap / MetallicGloss pack), emission, and the
+// alpha mode. Textures are referenced by GUID, resolved through a `unity-index.txt` (written by
+// `lecodes assets unpack`) or the `.meta` sidecars of a real Unity project.
+//
+// What this does: for every FBX material, find the `.mat` of the same name (modulo M_/MI_/MAT_
+// prefixes), read its slots, and rewrite the glTF material — base colour, normal, emissive, alpha
+// mode, and ONE metallic-roughness(+occlusion) texture packed the glTF way (R = AO, G = roughness,
+// B = metallic), re-encoding Unity's layouts (Standard `_MetallicGlossMap` R=metal A=smooth, HDRP/URP
+// `_MaskMap` R=metal G=AO A=smooth, separate Metallic / Roughness / Smoothness / AO maps, or a ready
+// `_ORM`), plus the shader's own SCALE on those maps (`_RoughnessScale` / `_MetallicScale` -> the
+// glTF factors, which multiply the same way). Only YAML-serialised materials are fully readable (Unity ≥ 5 with "Force Text"); a
+// BINARY `.mat` (many asset-store packs ship those) falls back to the pack's naming convention — its
+// slots are inferred from the textures next to it (`<Name>.tga`, `<Name>_NM.tga`, `_MS`, `_AO`,
+// `_E` …, see `inferBinaryMaterial`) and the report says so. `.mat` files are also looked up across
+// the whole unpacked package through `unity-index.txt`: packs keep shared materials (asphalt,
+// concrete) in a Textures/ tree far from the FBX that uses them.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import type { Document, Material, Texture } from "@gltf-transform/core"
+import { sniffMime, decodeTga, decodeBmp, encodePng, type Rgba } from "../textures/resolveImage"
+import { decodePng } from "./png"
+import { collectPrefabOverrides, type PrefabOverride } from "./prefabs"
+
+export type UnityMaterial = {
+  name: string
+  file: string
+  /** Shader asset path (resolved) or the builtin id. */
+  shader: string
+  /** Texture slot → GUID (only slots that reference a texture). */
+  textures: Record<string, string>
+  floats: Record<string, number>
+  colors: Record<string, [number, number, number, number]>
+  keywords: string[]
+}
+
+type Warn = (w: { level: "warn" | "info", message: string }) => void
+
+// ---- .mat parsing (YAML) ------------------------------------------------------------------------
+
+/** Parse a YAML-serialised Unity material. Returns null for binary serialisation / not a material. */
+export const parseUnityMaterial = (text: string, file: string): UnityMaterial | null => {
+  if (!text.startsWith("%YAML") || !/\nMaterial:\n/.test(text)) return null
+  const block = text.slice(text.indexOf("\nMaterial:\n"))
+  const name = /\n\s*m_Name: (.*)/.exec(block)?.[1]?.trim() || basename(file, ".mat")
+  const sh = /m_Shader: \{fileID: (-?\d+)(?:, guid: ([0-9a-f]{32}))?/.exec(text)
+  const shader = sh ? (sh[2] ? `guid:${sh[2]}` : `builtin:${sh[1]}`) : ""
+  const textures: Record<string, string> = {}
+  const texRe = /\n\s+- (\w+):\n\s+m_Texture: \{fileID: -?\d+, guid: ([0-9a-f]{32}), type: \d+\}/g
+  for (let m = texRe.exec(text); m; m = texRe.exec(text)) textures[m[1]] = m[2]
+  const floats: Record<string, number> = {}
+  const floatSection = /m_Floats:\n([\s\S]*?)\n\s+m_Colors:/.exec(text)?.[1] ?? ""
+  const fRe = /- (\w+): (-?[\d.eE+-]+)/g
+  for (let m = fRe.exec(floatSection); m; m = fRe.exec(floatSection)) floats[m[1]] = Number(m[2])
+  const colors: Record<string, [number, number, number, number]> = {}
+  const cRe = /- (\w+): \{r: (-?[\d.eE+-]+), g: (-?[\d.eE+-]+), b: (-?[\d.eE+-]+), a: (-?[\d.eE+-]+)\}/g
+  for (let m = cRe.exec(text); m; m = cRe.exec(text)) colors[m[1]] = [ Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5]) ]
+  const keywords = (/m_ShaderKeywords: (.*)/.exec(text)?.[1] ?? "").trim().split(/\s+/).filter(Boolean)
+  return { name, file, shader, textures, floats, colors, keywords }
+}
+
+export const isBinaryUnityAsset = (bytes: Uint8Array): boolean => !(bytes[0] === 0x25 && bytes[1] === 0x59 && bytes[2] === 0x41)   // "%YA"
+
+// ---- locating materials + resolving GUIDs ----------------------------------------------------------
+
+const walkFiles = (dir: string, depth: number, out: string[], pred: (name: string) => boolean): void => {
+  if (depth < 0 || !existsSync(dir)) return
+  let entries
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+  for (const e of entries) {
+    const p = join(dir, e.name)
+    if (e.isDirectory()) { if (e.name !== "node_modules" && !e.name.startsWith(".")) walkFiles(p, depth - 1, out, pred) }
+    else if (pred(e.name)) out.push(p)
+  }
+}
+
+/** Normalise a material name for matching: case, and the M_/MI_/MAT_ prefixes packs sprinkle. */
+export const materialKey = (n: string): string => n.trim().toLowerCase().replace(/^(mi|m|mat|mtl)_/, "").replace(/\.\d+$/, "")
+
+/** Texture references an inferred material carries: a pseudo-GUID naming the file directly. */
+export const PATH_GUID = "path:"
+const IMAGE_RE = /\.(png|jpe?g|tga|bmp|tiff?|psd|exr)$/i
+/** Suffix conventions (after the material name, case-insensitive) → Unity slot. The base colour is
+ *  the bare name or one of the albedo suffixes. */
+const SUFFIX_SLOTS: [RegExp, string][] = [
+  [ /^$|^_(d|bc|albedo|diffuse|diff|basecolor|base|col|color)$/i, "_MainTex" ],
+  [ /^_(nm|n|nrm|normal|normalmap|norm)$/i, "_BumpMap" ],
+  [ /^_(ms|metallicsmoothness|metallicgloss|mg)$/i, "_MetallicGlossMap" ],
+  [ /^_(m|metallic|metal|met)$/i, "_Metallic" ],
+  [ /^_(r|rough|roughness)$/i, "_Roughness" ],
+  [ /^_(s|smoothness|gloss)$/i, "_Smoothness" ],
+  [ /^_(ao|occlusion|ambientocclusion)$/i, "_OcclusionMap" ],
+  [ /^_(e|em|emission|emissive|emit)$/i, "_EmissionMap" ],
+  [ /^_(orm)$/i, "_ORM" ],
+  [ /^_(mask|maskmap)$/i, "_MaskMap" ],
+]
+
+/**
+ * A binary-serialised `.mat` can't be parsed, but asset-store packs name their textures after the
+ * material: `Seamless_asphalt_v1.mat` next to `Source/Seamless_asphalt_v1.tga` + `…_NM.tga`. Scan the
+ * .mat's folder (and its subfolders, two deep) for images whose stem is the material name plus a
+ * known suffix and build a material whose texture refs point at those files (`path:` pseudo-GUIDs,
+ * resolved without an index). Null when no base colour is found — a wrong guess is worse than none.
+ */
+export const inferBinaryMaterial = (file: string): UnityMaterial | null => {
+  const name = basename(file, ".mat")
+  const dir = dirname(file)
+  const images: string[] = []
+  walkFiles(dir, 2, images, (n) => IMAGE_RE.test(n))
+  const textures: Record<string, string> = {}
+  const lname = name.toLowerCase()
+  for (const img of images.sort()) {
+    const stem = basename(img).replace(/\.[^.]+$/, "")
+    if (!stem.toLowerCase().startsWith(lname)) continue
+    const suffix = stem.slice(name.length)
+    const slot = SUFFIX_SLOTS.find(([ re ]) => re.test(suffix))?.[1]
+    if (slot && !textures[slot]) textures[slot] = PATH_GUID + img
+  }
+  if (!textures._MainTex) return null
+  return { name, file, shader: "binary", textures, floats: {}, colors: {}, keywords: [] }
+}
+
+/** Every readable `.mat` under `dirs` (recursive) plus `extraFiles`, keyed by normalised name.
+ *  Binary ones are listed in `binary`; those whose textures could be inferred from their neighbours
+ *  (`inferBinaryMaterial`) are ALSO used and listed in `inferred`. */
+export const collectUnityMaterials = (dirs: string[], depth = 6, extraFiles: string[] = []): { byKey: Map<string, UnityMaterial>, byFile: Map<string, UnityMaterial>, binary: string[], inferred: string[] } => {
+  const files: string[] = []
+  for (const d of dirs) walkFiles(d, depth, files, (n) => /\.mat$/i.test(n))
+  const seen = new Set(files.map((f) => resolve(f)))
+  for (const f of extraFiles) { const a = resolve(f); if (!seen.has(a) && existsSync(a)) { seen.add(a); files.push(a) } }
+  const byKey = new Map<string, UnityMaterial>()
+  // Keyed by ABSOLUTE PATH as well: `materialKey` strips the M_/MI_ prefix, so a pack that ships a
+  // real `Materials/M_Wall.mat` beside the FBX's placeholder `Assets/Materials/MI_Wall.mat` collapses
+  // both onto one key and whichever was walked first wins. A prefab override names its material by
+  // GUID — an exact file — and must be looked up as one.
+  const byFile = new Map<string, UnityMaterial>()
+  const binary: string[] = []
+  const inferred: string[] = []
+  const put = (m: UnityMaterial, f: string) => {
+    byFile.set(resolve(f), m)
+    const k = materialKey(m.name)
+    if (!byKey.has(k)) byKey.set(k, m)
+    const fk = materialKey(basename(f, ".mat"))
+    if (!byKey.has(fk)) byKey.set(fk, m)
+  }
+  for (const f of files) {
+    const bytes = new Uint8Array(readFileSync(f))
+    if (isBinaryUnityAsset(bytes)) {
+      binary.push(f)
+      const m = inferBinaryMaterial(f)
+      if (m) { inferred.push(f); put(m, f) }
+      continue
+    }
+    const m = parseUnityMaterial(new TextDecoder().decode(bytes), f)
+    if (!m) continue
+    put(m, f)
+  }
+  return { byKey, byFile, binary, inferred }
+}
+
+/** Every `.mat` the index knows (absolute paths) — shared materials live far from the FBX. */
+export const indexedMaterialFiles = (indexFile: string): string[] => {
+  const root = dirname(indexFile)
+  const out: string[] = []
+  for (const line of readFileSync(indexFile, "utf8").split(/\r?\n/)) {
+    const t = line.indexOf("\t")
+    if (t > 0 && /\.mat$/i.test(line)) out.push(join(root, line.slice(t + 1).trim()))
+  }
+  return out
+}
+
+export type GuidResolver = { resolve: (guid: string) => string | null, source: string }
+
+/** Find `unity-index.txt` (written by `lecodes assets unpack`) walking up from `start`. */
+export const findUnityIndex = (start: string): string | null => {
+  let dir = resolve(start)
+  for (let i = 0; i < 12; i++) {
+    const f = join(dir, "unity-index.txt")
+    if (existsSync(f)) return f
+    const up = dirname(dir)
+    if (up === dir) break
+    dir = up
+  }
+  return null
+}
+
+/** The GUID the index lists for an absolute asset path (the FBX itself), or null. */
+export const guidOfPath = (indexFile: string, absPath: string): string | null => {
+  const root = resolve(dirname(indexFile))
+  const want = resolve(absPath).toLowerCase().replace(/\\/g, "/")
+  for (const line of readFileSync(indexFile, "utf8").split(/\r?\n/)) {
+    const t = line.indexOf("\t")
+    if (t < 0) continue
+    if (resolve(root, line.slice(t + 1).trim()).toLowerCase().replace(/\\/g, "/") === want) return line.slice(0, t)
+  }
+  return null
+}
+
+/** GUID → absolute path through an index file (`<guid>\t<path relative to the index's folder>`). */
+export const resolverFromIndex = (indexFile: string): GuidResolver => {
+  const root = dirname(indexFile)
+  const map = new Map<string, string>()
+  for (const line of readFileSync(indexFile, "utf8").split(/\r?\n/)) {
+    const t = line.indexOf("\t")
+    if (t > 0) map.set(line.slice(0, t), line.slice(t + 1).trim())
+  }
+  return { source: indexFile, resolve: (g) => { const p = map.get(g); if (!p) return null; const abs = join(root, p); return existsSync(abs) ? abs : null } }
+}
+
+/** GUID → path through `.meta` sidecars: scans up to the folder that holds `Assets` (or `depthUp` levels). */
+export const resolverFromMeta = (start: string, depthUp = 6): GuidResolver | null => {
+  let root = resolve(start)
+  for (let i = 0; i < depthUp; i++) {
+    if (existsSync(join(root, "Assets")) || basename(root) === "Assets") break
+    const up = dirname(root)
+    if (up === root) break
+    root = up
+  }
+  const metas: string[] = []
+  walkFiles(root, 12, metas, (n) => n.endsWith(".meta"))
+  if (metas.length === 0) return null
+  const map = new Map<string, string>()
+  for (const f of metas) {
+    const head = readFileSync(f, "utf8").slice(0, 300)
+    const g = /\nguid: ([0-9a-f]{32})/.exec(head)?.[1]
+    if (g) map.set(g, f.slice(0, -5))
+  }
+  return { source: `${metas.length} .meta files under ${root}`, resolve: (g) => { const p = map.get(g); return p && existsSync(p) ? p : null } }
+}
+
+// ---- textures: decode / pack / encode -------------------------------------------------------------
+
+export const decodeImage = async (bytes: Uint8Array, hint: string): Promise<Rgba | null> => {
+  const mime = sniffMime(bytes, hint)
+  if (mime === "image/png") { const r = decodePng(bytes); if (r) return r }
+  if (mime === "image/x-tga") return decodeTga(bytes)
+  if (mime === "image/bmp") return decodeBmp(bytes)
+  try {
+    const sharp = (await import("sharp")).default
+    const { data, info } = await sharp(Buffer.from(bytes)).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+    return { width: info.width, height: info.height, data: new Uint8Array(data) }
+  } catch { return null }
+}
+
+/** Nearest-neighbour sample of one channel at (u, v) in 0..1. */
+const sampleCh = (img: Rgba, ch: number, x: number, y: number, w: number, h: number): number => {
+  const sx = Math.min(img.width - 1, Math.floor((x + 0.5) * img.width / w))
+  const sy = Math.min(img.height - 1, Math.floor((y + 0.5) * img.height / h))
+  return img.data[(sy * img.width + sx) * 4 + ch]
+}
+
+export type PackInput = { img: Rgba, channel: number, invert?: boolean }
+/** Pack occlusion / roughness / metallic sources into one RGB image (glTF layout). Missing = constant. */
+export const packOrm = (ao: PackInput | null, rough: PackInput | null, metal: PackInput | null, defaults = { ao: 255, rough: 255, metal: 0 }): Rgba => {
+  const srcs = [ ao, rough, metal ].filter((s): s is PackInput => !!s)
+  const w = Math.max(1, ...srcs.map((s) => s.img.width)), h = Math.max(1, ...srcs.map((s) => s.img.height))
+  const out = new Uint8Array(w * h * 4)
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+    const d = (y * w + x) * 4
+    const get = (s: PackInput | null, dflt: number): number => { if (!s) return dflt; const v = sampleCh(s.img, s.channel, x, y, w, h); return s.invert ? 255 - v : v }
+    out[d] = get(ao, defaults.ao); out[d + 1] = get(rough, defaults.rough); out[d + 2] = get(metal, defaults.metal); out[d + 3] = 255
+  }
+  return { width: w, height: h, data: out }
+}
+
+// ---- slot vocabulary --------------------------------------------------------------------------------
+
+// `_Main*` is the vertex-PAINT convention: a shadergraph that blends a base layer with per-vertex-
+// colour layers (R/G/B channels) names the base one "Main". Nothing here can run the graph, so the
+// main layer IS the material — far better than the white nothing those slot names used to produce.
+const SLOTS = {
+  base: [ "_BaseMap", "_MainTex", "_BaseColor", "_BaseColorMap", "_BC", "_Albedo", "_AlbedoMap", "_Diffuse", "_DiffuseMap", "_Color", "_MainBC" ],
+  normal: [ "_BumpMap", "_NormalMap", "_Normal", "_NormalTex", "_MainNormal" ],
+  orm: [ "_ORM", "_ORMMap", "_OcclusionRoughnessMetallic", "_ORMTex", "_MainORM" ],
+  maskMap: [ "_MaskMap" ],
+  metallicGloss: [ "_MetallicGlossMap" ],
+  metallic: [ "_Metallic", "_MetallicMap", "_MetallicTex", "_MetalMap" ],
+  roughness: [ "_Roughness", "_RoughnessMap", "_RoughnessTex" ],
+  smoothness: [ "_Smoothness", "_SmoothnessMap", "_SmoothnessTex", "_Gloss", "_GlossMap" ],
+  occlusion: [ "_OcclusionMap", "_Occlusion", "_AO", "_AOMap", "_AmbientOcclusion" ],
+  emission: [ "_EmissionMap", "_Emission", "_Emissive", "_EmissiveMap", "_EmissiveColorMap" ],
+  alpha: [ "_Alpha", "_Opacity", "_OpacityMap", "_AlphaMap", "_OpacityMask" ],
+}
+const pick = (m: UnityMaterial, names: string[]): string | null => { for (const n of names) { const g = m.textures[n]; if (g) return g } return null }
+
+export type ApplyUnityOptions = {
+  /** Folder(s) to look for `.mat` files in (default: the FBX's folder and its parent, recursively). */
+  materialDirs?: string[]
+  /** `unity-index.txt` to resolve GUIDs with (default: found walking up from the FBX; else `.meta` sidecars). */
+  indexFile?: string
+  /** Honour the material overrides of the `.prefab` files around the FBX (default true) — packs assign
+   *  the real material on the prefab's MeshRenderer and leave the FBX with placeholders. */
+  prefabs?: boolean
+  /** Folders to read `.prefab` files from (default: the FBX's folder and its parent, 3 deep). */
+  prefabDirs?: string[]
+  warn?: Warn
+}
+
+export type ApplyUnityReport = {
+  /** glTF material name → what was applied (slots[0] notes a non-exact match). */
+  applied: { material: string, mat: string, slots: string[] }[]
+  unmatched: string[]
+  binary: string[]
+  /** Binary .mat files whose slots were inferred from their sibling textures. */
+  inferred: string[]
+  /** Nodes re-materialed from a prefab's MeshRenderer (slots listed once per distinct .mat). */
+  overrides: { node: string, mat: string, slots: string[] }[]
+  resolver: string | null
+}
+
+/** Rewrite the Document's materials from the Unity `.mat` files that match them by name. */
+export const applyUnityMaterials = async (doc: Document, fbxPath: string, opts: ApplyUnityOptions = {}): Promise<ApplyUnityReport> => {
+  const warn = opts.warn ?? (() => {})
+  const fbxDir = dirname(resolve(fbxPath))
+  const report: ApplyUnityReport = { applied: [], unmatched: [], binary: [], inferred: [], overrides: [], resolver: null }
+  // Only a Unity CONTEXT makes the .mat scan worthwhile: an unpacked package (unity-index.txt above
+  // the FBX) or a real Unity project (the FBX's own .meta sidecar). Without one the scan of the parent
+  // folder only finds unrelated projects' materials (a Mixamo folder next to a Unity export) and the
+  // .meta resolver would crawl a whole home directory looking for `Assets`.
+  const indexFile = opts.indexFile ?? findUnityIndex(fbxDir)
+  const inProject = existsSync(fbxPath + ".meta")
+  if (!indexFile && !inProject && !opts.materialDirs) return report
+  const dirs = opts.materialDirs ?? [ fbxDir, dirname(fbxDir) ]
+  // the FBX's neighbourhood first (wins on a name clash), then every .mat the package index lists
+  const { byKey, byFile, binary, inferred } = collectUnityMaterials(dirs, 6, indexFile ? indexedMaterialFiles(indexFile) : [])
+  report.binary = binary
+  report.inferred = inferred
+  const mats = doc.getRoot().listMaterials()
+  if (byKey.size === 0) return report
+
+  let resolver: GuidResolver | null = indexFile ? resolverFromIndex(indexFile) : null
+  if (!resolver && (inProject || opts.materialDirs)) resolver = resolverFromMeta(fbxDir)
+  // inferred materials reference files directly — they need no GUID resolver
+  if (!resolver && inferred.length) resolver = { source: "inferred from sibling textures", resolve: () => null }
+  if (!resolver) {
+    warn({ level: "warn", message: `Unity materials found but no way to resolve their texture GUIDs — need a unity-index.txt (lecodes assets unpack) above the FBX or the .meta sidecars of a Unity project` })
+    return report
+  }
+  report.resolver = resolver.source
+
+  // name matching: exact (modulo prefixes) → one key contains the other (MI_Tshirt ↔ M_Shirt) → the
+  // FBX material's base texture and a .mat's base slot point at the same file (MI_Skin ↔ M_Body via
+  // TX_Body_BaseColor) — packs rename materials freely but rarely duplicate a texture
+  const allMats = [ ...new Set(byKey.values()) ]
+  const stemOf = (f: string): string => basename(f).replace(/\.[^.]+$/, "").toLowerCase()
+  const matByStem = new Map<string, UnityMaterial>()
+  for (const um of allMats) {
+    const g = pick(um, SLOTS.base)
+    const f = g ? resolver.resolve(g) : null
+    if (f && !matByStem.has(stemOf(f))) matByStem.set(stemOf(f), um)
+  }
+  const matchMaterial = (gm: Material): { um: UnityMaterial, how: string } | null => {
+    const k = materialKey(gm.getName())
+    const exact = byKey.get(k)
+    if (exact) return { um: exact, how: "name" }
+    if (k.length >= 4) {
+      const part = allMats.find((um) => { const mk = materialKey(um.name); return mk.length >= 4 && (mk.includes(k) || k.includes(mk)) })
+      if (part) return { um: part, how: `name ~ ${part.name}` }
+    }
+    const base = gm.getBaseColorTexture()
+    const stem = base ? stemOf(base.getName() || base.getURI() || "") : ""
+    const byTex = stem ? matByStem.get(stem) : undefined
+    if (byTex) return { um: byTex, how: `base texture ${stem}` }
+    return null
+  }
+
+  const texCache = new Map<string, Texture | null>()
+  const imgCache = new Map<string, Rgba | null>()
+  const loadBytes = (guid: string): { bytes: Uint8Array, file: string } | null => {
+    const f = guid.startsWith(PATH_GUID) ? guid.slice(PATH_GUID.length) : resolver!.resolve(guid)
+    if (!f) { warn({ level: "warn", message: `texture ${guid}: not in the index / not extracted — skipped` }); return null }
+    return { bytes: new Uint8Array(readFileSync(f)), file: f }
+  }
+  const texFromGuid = async (guid: string): Promise<Texture | null> => {
+    if (texCache.has(guid)) return texCache.get(guid)!
+    const src = loadBytes(guid)
+    let tex: Texture | null = null
+    if (src) {
+      const mime = sniffMime(src.bytes, src.file)
+      let data = src.bytes, outMime: "image/png" | "image/jpeg" = "image/png"
+      if (mime === "image/png" || mime === "image/jpeg") outMime = mime
+      else {
+        const img = await decodeImage(src.bytes, src.file)
+        if (!img) { warn({ level: "warn", message: `texture ${basename(src.file)}: unsupported format (${mime}) — skipped` }); texCache.set(guid, null); return null }
+        data = encodePng(img)
+      }
+      tex = doc.createTexture(basename(src.file).replace(/\.[^.]+$/, "")).setImage(data).setMimeType(outMime)
+    }
+    texCache.set(guid, tex)
+    return tex
+  }
+  const imgFromGuid = async (guid: string): Promise<Rgba | null> => {
+    if (imgCache.has(guid)) return imgCache.get(guid)!
+    const src = loadBytes(guid)
+    const img = src ? await decodeImage(src.bytes, src.file) : null
+    if (src && !img) warn({ level: "warn", message: `texture ${basename(src.file)}: could not decode for packing — skipped` })
+    imgCache.set(guid, img)
+    return img
+  }
+  const nameOf = (guid: string): string => { const f = guid.startsWith(PATH_GUID) ? guid.slice(PATH_GUID.length) : resolver!.resolve(guid); return f ? basename(f) : guid }
+
+  /** Rewrite one glTF material from a Unity material; returns the slot summary. */
+  const applyTo = async (gm: Material, um: UnityMaterial, how: string): Promise<string[]> => {
+    const slots: string[] = how === "name" ? [] : [ `(matched by ${how})` ]
+    if (um.shader === "binary") slots.push("(binary .mat — slots inferred from sibling textures)")
+    // base colour (+ the FBX's base when the .mat has none — keep whatever is there)
+    const baseG = pick(um, SLOTS.base)
+    if (baseG) { const t = await texFromGuid(baseG); if (t) { gm.setBaseColorTexture(t); slots.push(`base=${nameOf(baseG)}`) } }
+    const baseColor = um.colors._BaseColor ?? um.colors._Color
+    if (baseColor) gm.setBaseColorFactor([ baseColor[0], baseColor[1], baseColor[2], gm.getBaseColorFactor()[3] ])
+    const nG = pick(um, SLOTS.normal)
+    if (nG) { const t = await texFromGuid(nG); if (t) { gm.setNormalTexture(t); gm.setNormalScale(um.floats._BumpScale ?? 1); slots.push(`normal=${nameOf(nG)}`) } }
+
+    // metallic / roughness / occlusion
+    const ormG = pick(um, SLOTS.orm), maskG = pick(um, SLOTS.maskMap), mgG = pick(um, SLOTS.metallicGloss)
+    const metG = pick(um, SLOTS.metallic), roughG = pick(um, SLOTS.roughness), smoothG = pick(um, SLOTS.smoothness), aoG = pick(um, SLOTS.occlusion)
+    // A shader's SCALE on top of the maps. glTF's metallicFactor / roughnessFactor multiply their
+    // texture exactly the way these do, so they carry over one-to-one — and dropping them is not a
+    // cosmetic loss: KINEMATION's weapon shader ships `_RoughnessScale: 0.65`, so a gun imported
+    // without it renders 54 % rougher than the artist set it, which reads as plastic instead of
+    // gunmetal. Every weapon in that pack sets 0.6-0.8; only characters leave it at 1.
+    // Names differ per shader, so accept the ones seen in the wild.
+    const scaleOf = (...keys: string[]): number => {
+      for (const k of keys) { const v = um.floats[k]; if (v !== undefined && v >= 0 && v <= 1) return v }
+      return 1
+    }
+    const roughScale = scaleOf("_RoughnessScale", "_RoughnessMultiplier", "_RoughnessStrength")
+    const metalScale = scaleOf("_MetallicScale", "_MetallicMultiplier", "_MetallicStrength")
+    const setMr = (t: Texture, withAo: boolean, label: string): void => {
+      gm.setMetallicRoughnessTexture(t).setMetallicFactor(metalScale).setRoughnessFactor(roughScale)
+      if (withAo) gm.setOcclusionTexture(t).setOcclusionStrength(um.floats._OcclusionStrength ?? 1)
+      if (roughScale !== 1 || metalScale !== 1) {
+        slots.push(`scale metallic=${metalScale} roughness=${roughScale}`)
+      }
+      slots.push(label)
+    }
+    if (ormG) {
+      const t = await texFromGuid(ormG)
+      if (t) setMr(t, true, `orm=${nameOf(ormG)}`)
+    } else if (maskG || mgG || metG || roughG || smoothG || aoG) {
+      // pack: R = AO, G = roughness, B = metallic
+      let ao: PackInput | null = null, rough: PackInput | null = null, metal: PackInput | null = null
+      const parts: string[] = []
+      if (maskG) { const img = await imgFromGuid(maskG); if (img) { metal = { img, channel: 0 }; ao = { img, channel: 1 }; rough = { img, channel: 3, invert: true }; parts.push(`MaskMap ${nameOf(maskG)}`) } }
+      if (mgG) { const img = await imgFromGuid(mgG); if (img) { metal = { img, channel: 0 }; rough = { img, channel: 3, invert: true }; parts.push(`MetallicGloss ${nameOf(mgG)}`) } }
+      if (metG) { const img = await imgFromGuid(metG); if (img) { metal = { img, channel: 0 }; parts.push(`metallic ${nameOf(metG)}`) } }
+      if (roughG) { const img = await imgFromGuid(roughG); if (img) { rough = { img, channel: 0 }; parts.push(`roughness ${nameOf(roughG)}`) } }
+      else if (smoothG) { const img = await imgFromGuid(smoothG); if (img) { rough = { img, channel: 0, invert: true }; parts.push(`smoothness ${nameOf(smoothG)}`) } }
+      if (aoG) { const img = await imgFromGuid(aoG); if (img) { ao = { img, channel: 0 }; parts.push(`ao ${nameOf(aoG)}`) } }
+      if (metal || rough || ao) {
+        // scalar fallbacks for the channels no map covers
+        const smooth = um.floats._Smoothness ?? um.floats._Glossiness
+        const dflt = { ao: 255, rough: Math.round((1 - (smooth ?? 0.5)) * 255), metal: Math.round((um.floats._Metallic ?? 0) * 255) }
+        const packed = packOrm(ao, rough, metal, dflt)
+        const t = doc.createTexture(`${um.name}_ORM`).setImage(encodePng(packed)).setMimeType("image/png")
+        setMr(t, !!ao, `packed ORM ← ${parts.join(" + ")}`)
+      }
+    } else {
+      // no maps: scalar metallic / roughness from the material
+      if (um.floats._Metallic !== undefined) gm.setMetallicFactor(um.floats._Metallic)
+      const smooth = um.floats._Smoothness ?? um.floats._Glossiness
+      if (smooth !== undefined) gm.setRoughnessFactor(1 - smooth)
+      if (um.floats._Metallic !== undefined || smooth !== undefined) slots.push(`metallic=${gm.getMetallicFactor().toFixed(2)} roughness=${gm.getRoughnessFactor().toFixed(2)}`)
+    }
+
+    // emission: only when the material actually emits (keyword or a non-black colour)
+    const emG = pick(um, SLOTS.emission)
+    // `_EmissiveColor` FIRST: HDRP's Lit shader emits by that one and leaves the Standard shader's
+    // `_EmissionColor` sitting in the property block at white, so reading `_EmissionColor` made every
+    // surface of an HDRP pack a self-lit white card — a whole imported level rendered as blank
+    // cardboard. URP / Standard materials carry no `_EmissiveColor`, so they are unaffected.
+    const emC = um.colors._EmissiveColor ?? um.colors._EmissionColor
+    // An explicitly BLACK _EmissionColor is a veto, not a missing value: Unity multiplies the
+    // emission map by that colour, so black means the surface does not emit however many maps are
+    // bound. Without this the "a map and no keywords, so assume it emits" fallback below fires on
+    // custom-shader materials that keep a texture in the slot and switch it off with the colour —
+    // which lit a whole rifle body through a magazine's emission map.
+    const emissionVetoed = emC !== undefined && emC[0] + emC[1] + emC[2] <= 0.01
+    const emits = um.keywords.includes("_EMISSION")
+      || (emC ? emC[0] + emC[1] + emC[2] > 0.01 : false)
+      || (!!emG && !um.keywords.length && !emissionVetoed)
+    if (emG && emits) {
+      const t = await texFromGuid(emG)
+      if (t) { gm.setEmissiveTexture(t).setEmissiveFactor(emC && emC[0] + emC[1] + emC[2] > 0.01 ? [ Math.min(1, emC[0]), Math.min(1, emC[1]), Math.min(1, emC[2]) ] : [ 1, 1, 1 ]); slots.push(`emissive=${nameOf(emG)}`) }
+    } else if (emC && emits && !emG) gm.setEmissiveFactor([ Math.min(1, emC[0]), Math.min(1, emC[1]), Math.min(1, emC[2]) ])
+    else if (!emits) {
+      // The Unity material is the authority and it says this surface does NOT emit — so CLEAR what
+      // the FBX bound (toDocument.ts binds fbx emissiveTex with factor 1,1,1 whenever the mesh file
+      // names one). DCC exports routinely carry an emission slot the Unity material later overrode
+      // to none; leaving it produced a rifle body glowing through a magazine's emission map, which
+      // only became visible once the textures stopped being mushy.
+      if (gm.getEmissiveTexture()) { gm.setEmissiveTexture(null); slots.push("emissive=off") }
+      const ef = gm.getEmissiveFactor()
+      if (ef[0] + ef[1] + ef[2] > 0) gm.setEmissiveFactor([ 0, 0, 0 ])
+    }
+
+    // alpha: URP `_Surface` 1 = transparent, `_AlphaClip` 1 = cutout; Standard `_Mode` 1 cutout, 2/3 blend
+    const mode = um.floats._Mode, surface = um.floats._Surface, clip = um.floats._AlphaClip
+    const cutout = clip === 1 || mode === 1 || um.keywords.includes("_ALPHATEST_ON")
+    const blend = surface === 1 || mode === 2 || mode === 3 || um.keywords.includes("_ALPHABLEND_ON") || um.keywords.includes("_ALPHAPREMULTIPLY_ON")
+    if (cutout) { gm.setAlphaMode("MASK").setAlphaCutoff(um.floats._Cutoff ?? 0.5); slots.push("cutout") }
+    else if (blend) { gm.setAlphaMode("BLEND"); slots.push("blend") }
+    else if (gm.getAlphaMode() !== "OPAQUE" && !pick(um, SLOTS.alpha)) gm.setAlphaMode("OPAQUE")
+    const cull = um.floats._Cull
+    if (cull === 0) gm.setDoubleSided(true)
+
+    return slots
+  }
+
+  const appliedFrom = new Map<Material, string>()
+  for (const gm of mats) {
+    const hit = matchMaterial(gm)
+    if (!hit) { report.unmatched.push(gm.getName()); continue }
+    const slots = await applyTo(gm, hit.um, hit.how)
+    appliedFrom.set(gm, hit.um.file)
+    report.applied.push({ material: gm.getName(), mat: basename(hit.um.file), slots })
+  }
+
+  // prefab overrides: a prefab's MeshRenderer names the real material for a node whose FBX material
+  // is a placeholder ("17 - Default"). Only prefabs showing THIS FBX's mesh count (by GUID, when the
+  // index knows the FBX). The override is applied per primitive; a mesh shared by several nodes
+  // takes the first node's override.
+  if (opts.prefabs !== false && resolver.source !== "inferred from sibling textures") {
+    const fbxGuid = indexFile ? guidOfPath(indexFile, fbxPath) : null
+    const overrides = collectPrefabOverrides(opts.prefabDirs ?? [ fbxDir, dirname(fbxDir) ])
+      .filter((o) => !fbxGuid || !o.meshGuid || o.meshGuid === fbxGuid)
+    const byNode = new Map<string, PrefabOverride>()
+    for (const o of overrides) if (!byNode.has(o.node)) byNode.set(o.node, o)
+    const matCache = new Map<string, Material>()
+    // the FBX importer hangs the mesh on an unnamed child of the named node — take the subtree
+    const meshesUnder = (n: import("@gltf-transform/core").Node): import("@gltf-transform/core").Mesh[] => {
+      const out: import("@gltf-transform/core").Mesh[] = []
+      const walk = (x: import("@gltf-transform/core").Node): void => { const m = x.getMesh(); if (m) out.push(m); x.listChildren().forEach(walk) }
+      walk(n)
+      return out
+    }
+    for (const node of doc.getRoot().listNodes()) {
+      const o = byNode.get(node.getName())
+      if (!o) continue
+      const prims = meshesUnder(node).flatMap((m) => m.listPrimitives())
+      for (let i = 0; i < prims.length; i++) {
+        const g = o.materials[i]
+        if (!g) continue
+        const matFile = resolver.resolve(g)
+        if (!matFile) continue
+        // by PATH first — the GUID named one exact .mat, and the name key cannot tell
+        // `Materials/M_VP_01.mat` from the FBX's placeholder `Assets/Materials/MI_VP_01.mat`
+        const um = byFile.get(resolve(matFile)) ?? byKey.get(materialKey(basename(matFile, ".mat")))
+        if (!um) continue
+        const current = prims[i].getMaterial()
+        if (current && appliedFrom.get(current) === um.file) continue   // the FBX material already matched this .mat
+        let gm = matCache.get(um.file)
+        if (!gm) {
+          gm = doc.createMaterial(um.name)
+          const slots = await applyTo(gm, um, "name")
+          matCache.set(um.file, gm)
+          appliedFrom.set(gm, um.file)
+          report.overrides.push({ node: node.getName(), mat: basename(um.file), slots })
+        } else report.overrides.push({ node: node.getName(), mat: basename(um.file), slots: [] })
+        prims[i].setMaterial(gm)
+      }
+    }
+  }
+  return report
+}
+
+/** Drop textures no material references any more (the FBX's legacy ones after a .mat rewrite). */
+export const pruneUnusedTextures = (doc: Document): number => {
+  let n = 0
+  for (const t of doc.getRoot().listTextures()) {
+    if (t.listParents().every((p) => p.propertyType === "Root")) { t.dispose(); n++ }
+  }
+  return n
+}
+
+export const describeUnityReport = (r: ApplyUnityReport): string[] => {
+  const lines: string[] = []
+  for (const a of r.applied) lines.push(`🎨 ${a.material} ← ${a.mat}: ${a.slots.join(", ") || "(no changes)"}`)
+  const byMat = new Map<string, { nodes: string[], slots: string[] }>()
+  for (const o of r.overrides) { const e = byMat.get(o.mat) ?? { nodes: [], slots: [] }; e.nodes.push(o.node); if (o.slots.length) e.slots = o.slots; byMat.set(o.mat, e) }
+  for (const [ mat, e ] of byMat) lines.push(`🎨 prefab override ← ${mat}: ${e.slots.join(", ") || "(shared)"} — ${e.nodes.length} node${e.nodes.length === 1 ? "" : "s"} (${e.nodes.slice(0, 4).join(", ")}${e.nodes.length > 4 ? ", …" : ""})`)
+  if (r.unmatched.length && r.applied.length) lines.push(`ℹ no Unity material for: ${r.unmatched.join(", ")} (FBX references kept)`)
+  const skipped = r.binary.filter((b) => !r.inferred.includes(b))
+  if (r.inferred.length) lines.push(`ℹ ${r.inferred.length} binary-serialised .mat file(s) read by texture naming convention (slots inferred from the files next to them)`)
+  if (skipped.length) lines.push(`ℹ ${skipped.length} binary-serialised .mat file(s) skipped — no textures named after them (Unity: Edit ▸ Project Settings ▸ Editor ▸ Asset Serialization = Force Text) — e.g. ${basename(skipped[0])}`)
+  return lines
+}
+
+export type { Material }