lecodes-assets 0.2.1 → 2.5.0

package/src/unity/materials.ts

@@ -1,292 +1,26 @@
-// Unity materials as the texture source of truth.
+// Unity materials as the texture source of truth for an FBX conversion.
 //
 // 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.
+// `lecodes assets unpack`) or the `.meta` sidecars of a real Unity project (guid.ts).
 //
 // 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"
+// prefixes; matFile.ts reads it, a BINARY one through the pack's texture naming convention), and
+// rewrite the glTF material from it (materialWriter.ts). `.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. Then the material overrides of the `.prefab`
+// files around the FBX are honoured (prefabs.ts).
+
+import { existsSync } from "node:fs"
+import { basename, dirname, resolve } from "node:path"
+import type { Document, Material, Mesh, Node } from "@gltf-transform/core"
+import { findUnityIndex, guidOfPath, indexedMaterialFiles, resolverFromIndex, resolverFromMeta, type GuidResolver } from "./guid"
+import { collectUnityMaterials, materialKey, type UnityMaterial } from "./matFile"
+import { SLOTS, pick, unityMaterialWriter, type Warn } from "./materialWriter"
 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[]
@@ -368,148 +102,7 @@ export const applyUnityMaterials = async (doc: Document, fbxPath: string, opts:
     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 { applyTo } = unityMaterialWriter(doc, resolver, warn)
 
   const appliedFrom = new Map<Material, string>()
   for (const gm of mats) {
@@ -532,15 +125,28 @@ export const applyUnityMaterials = async (doc: Document, fbxPath: string, opts:
     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) }
+    const meshesUnder = (n: Node): Mesh[] => {
+      const out: Mesh[] = []
+      const walk = (x: 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 targets: [ Node, PrefabOverride ][] = []
+    for (const node of doc.getRoot().listNodes()) { const o = byNode.get(node.getName()); if (o) targets.push([ node, o ]) }
+    // a SINGLE-mesh prop whose prefab GameObject is named after the prefab, not the FBX node
+    // (`P_stone_fence` showing `stone_fence_LP.014`): no name matches, but the prefab names THIS FBX
+    // by GUID and there is only one mesh it could mean. The prefab named like the FBX wins over
+    // its variants (`P_Tent_1` over `P_Tent_1B`).
+    if (!targets.length && fbxGuid) {
+      const meshNodes = doc.getRoot().listNodes().filter((n) => n.getMesh())
+      const mine = overrides.filter((o) => o.meshGuid === fbxGuid)
+      if (meshNodes.length === 1 && mine.length) {
+        const stem = basename(fbxPath).replace(/\.fbx$/i, "").toLowerCase()
+        const o = mine.find((x) => basename(x.prefab, ".prefab").toLowerCase().replace(/^p_/, "") === stem) ?? mine[0]!
+        targets.push([ meshNodes[0]!, o ])
+      }
+    }
+    for (const [ node, o ] of targets) {
       const prims = meshesUnder(node).flatMap((m) => m.listPrimitives())
       for (let i = 0; i < prims.length; i++) {
         const g = o.materials[i]
@@ -590,4 +196,3 @@ export const describeUnityReport = (r: ApplyUnityReport): string[] => {
   return lines
 }
 
-export type { Material }

package/src/unity/math.ts

@@ -0,0 +1,82 @@
+// The Unity importer's linear algebra: column-major 4×4 matrices, (x, y, z, w) quaternions, and the
+// ONE frame conversion everything here shares.
+//
+// Frame: Unity is left-handed (+Z forward); glTF / LeCodes are right-handed. Unity's FBX importer
+// mirrors X, so undoing it is a conjugation by S = diag(−1, 1, 1): position (−x, y, z), quaternion
+// (x, −y, −z, w), scale unchanged. It is applied to placements AND inside kinds (part matrices), so a
+// kind's meshes — the FBX's own geometry, which is Unity's mesh mirrored back — land where Unity
+// drew them.
+
+import type { Quat, Vec3 } from "./yaml"
+
+export type Mat4 = number[]            // column-major
+export type TRS = { t: Vec3, r: Quat, s: Vec3 }
+
+export const I4 = (): Mat4 => [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ]
+
+export const mmul = (a: Mat4, b: Mat4): Mat4 => {
+  const o = new Array(16).fill(0)
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) o[c * 4 + r] = a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + a[12 + r] * b[c * 4 + 3]
+  return o
+}
+
+export const scaleMatrix = (s: number): Mat4 => [ s, 0, 0, 0, 0, s, 0, 0, 0, 0, s, 0, 0, 0, 0, 1 ]
+
+export const trsMatrix = (t: Vec3, q: Quat, s: Vec3): Mat4 => {
+  const [ x, y, z, w ] = q
+  const xx = x * x, yy = y * y, zz = z * z, xy = x * y, xz = x * z, yz = y * z, wx = w * x, wy = w * y, wz = w * z
+  return [
+    (1 - 2 * (yy + zz)) * s[0], 2 * (xy + wz) * s[0], 2 * (xz - wy) * s[0], 0,
+    2 * (xy - wz) * s[1], (1 - 2 * (xx + zz)) * s[1], 2 * (yz + wx) * s[1], 0,
+    2 * (xz + wy) * s[2], 2 * (yz - wx) * s[2], (1 - 2 * (xx + yy)) * s[2], 0,
+    t[0], t[1], t[2], 1,
+  ]
+}
+
+/** Conjugate by the X mirror: S·M·S with S = diag(−1, 1, 1). */
+export const mirrorX = (m: Mat4): Mat4 => m.map((v, i) => ((Math.floor(i / 4) === 0) !== (i % 4 === 0) ? -v : v))
+
+/** The same conjugation on a quaternion and on a position. */
+export const mirrorQuat = (q: number[]): Quat => [ q[0], -q[1], -q[2], q[3] ]
+export const mirrorPos = (p: number[]): Vec3 => [ -p[0], p[1], p[2] ]
+
+export const decompose = (m: Mat4): TRS => {
+  const sx = Math.hypot(m[0], m[1], m[2]), sy = Math.hypot(m[4], m[5], m[6]), sz0 = Math.hypot(m[8], m[9], m[10])
+  const det = m[0] * (m[5] * m[10] - m[6] * m[9]) - m[4] * (m[1] * m[10] - m[2] * m[9]) + m[8] * (m[1] * m[6] - m[2] * m[5])
+  const sz = det < 0 ? -sz0 : sz0
+  const r00 = m[0] / sx, r10 = m[1] / sx, r20 = m[2] / sx, r01 = m[4] / sy, r11 = m[5] / sy, r21 = m[6] / sy, r02 = m[8] / sz, r12 = m[9] / sz, r22 = m[10] / sz
+  const tr = r00 + r11 + r22
+  let q: Quat
+  if (tr > 0) { const s = Math.sqrt(tr + 1) * 2; q = [ (r21 - r12) / s, (r02 - r20) / s, (r10 - r01) / s, s / 4 ] }
+  else if (r00 > r11 && r00 > r22) { const s = Math.sqrt(1 + r00 - r11 - r22) * 2; q = [ s / 4, (r01 + r10) / s, (r02 + r20) / s, (r21 - r12) / s ] }
+  else if (r11 > r22) { const s = Math.sqrt(1 + r11 - r00 - r22) * 2; q = [ (r01 + r10) / s, s / 4, (r12 + r21) / s, (r02 - r20) / s ] }
+  else { const s = Math.sqrt(1 + r22 - r00 - r11) * 2; q = [ (r02 + r20) / s, (r12 + r21) / s, s / 4, (r10 - r01) / s ] }
+  const l = Math.hypot(...q) || 1
+  return { t: [ m[12], m[13], m[14] ], r: q.map((v) => v / l) as Quat, s: [ sx, sy, sz ] }
+}
+
+/** Hamilton product a · b (apply b, then a). */
+export const qmul = (a: number[], b: number[]): Quat => [
+  a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+  a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+  a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+  a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+]
+
+const DEG = 180 / Math.PI
+/** YXZ euler angles (DEGREES) from a unit quaternion — the SDK's `Node.eulerAngles` convention. */
+export const eulerYXZ = (q: number[]): [number, number, number] => {
+  const [ x, y, z, w ] = q
+  const x2 = x + x, y2 = y + y, z2 = z + z
+  const xx = x * x2, xy = x * y2, xz = x * z2, yy = y * y2, yz = y * z2, zz = z * z2, wx = w * x2, wy = w * y2, wz = w * z2
+  const m13 = xz + wy, m21 = xy + wz, m22 = 1 - (xx + zz), m23 = yz - wx, m31 = xz - wy, m33 = 1 - (xx + yy), m11 = 1 - (yy + zz)
+  const ex = Math.asin(-Math.max(-1, Math.min(1, m23)))
+  let ey: number, ez: number
+  if (Math.abs(m23) < 0.9999999) { ey = Math.atan2(m13, m33); ez = Math.atan2(m21, m22) } else { ey = Math.atan2(-m31, m11); ez = 0 }
+  return [ ex * DEG, ey * DEG, ez * DEG ]
+}
+
+/** Rounded for output (and `+ 0` so a −0 never reaches a file). */
+export const r6 = (v: number): number => Math.round(v * 1e6) / 1e6 + 0
+export const r3 = (v: number): number => Math.round(v * 1000) / 1000 + 0
+export const r2 = (v: number): number => Math.round(v * 100) / 100 + 0