lecodes-assets 0.2.1 → 2.4.10

package/src/unity/matFile.ts

@@ -0,0 +1,179 @@
+// A Unity `.mat` file read into its slots. 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.
+
+import { existsSync, readFileSync } from "node:fs"
+import { basename, dirname, resolve } from "node:path"
+import { walkFiles } from "./guid"
+
+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[]
+  /** Texture slot → `[scaleX, scaleY, offsetX, offsetY]` (Unity `m_Scale` / `m_Offset`) for the slots that are not (1, 1, 0, 0). */
+  tiling?: Record<string, [number, number, number, number]>
+  /** `m_LightmapFlags`: bit 4 = EmissiveIsBlack - Unity's own "this material does not emit", whatever the colours say;
+   *  bit 2 = BakedEmissive, bit 1 = RealtimeEmissive - the inspector's "Global Illumination" (neither = None: the glow
+   *  lights nothing; materialWriter writes it as the glTF extras `lecodes.emissiveBake: false`). */
+  lightmapFlags?: number
+}
+
+// ---- .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)
+  // Unity's built-in shaders live in two pseudo-assets whose GUIDs are all zeros but one digit
+  // (`…f000…` = builtin_extra: Standard 46, Standard (Specular) 45, Autodesk Interactive 47); the fileID
+  // is then the shader's identity, so those read as `builtin:<fileID>` like a GUID-less reference does.
+  const builtin = !sh?.[2] || /^0{16}[ef]0{15}$/.test(sh[2])
+  const shader = sh ? (builtin ? `builtin:${sh[1]}` : `guid:${sh[2]}`) : ""
+  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]
+  // a slot's tiling — a detail layer's bark repeats 3× along the trunk (NatureManufacture `_DetailAlbedoMap` (1, 3))
+  const tiling: Record<string, [number, number, number, number]> = {}
+  const stRe = /\n\s+- (\w+):\n\s+m_Texture: \{fileID: -?\d+, guid: [0-9a-f]{32}, type: \d+\}\n\s+m_Scale: \{x: (-?[\d.eE+-]+), y: (-?[\d.eE+-]+)\}\n\s+m_Offset: \{x: (-?[\d.eE+-]+), y: (-?[\d.eE+-]+)\}/g
+  for (let m = stRe.exec(text); m; m = stRe.exec(text)) { const st: [number, number, number, number] = [ Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5]) ]; if (st[0] !== 1 || st[1] !== 1 || st[2] !== 0 || st[3] !== 0) tiling[m[1]] = st }
+  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]) ]
+  // keywords: one space-separated line before Unity 2021, a `m_ValidKeywords:` list since
+  const keywords = (/m_ShaderKeywords: (.*)/.exec(text)?.[1] ?? "").trim().split(/\s+/).filter(Boolean)
+  const valid = /\n\s*m_ValidKeywords:\n((?:\s*- .*\n)*)/.exec(text)?.[1]
+  if (valid) for (const k of valid.split("\n")) { const m = /^\s*- (\S+)/.exec(k); if (m && !keywords.includes(m[1])) keywords.push(m[1]) }
+  const lightmapFlags = Number(/m_LightmapFlags: (\d+)/.exec(text)?.[1] ?? NaN)
+  return { name, file, shader, textures, floats, colors, keywords, tiling: Object.keys(tiling).length ? tiling : undefined, lightmapFlags: Number.isFinite(lightmapFlags) ? lightmapFlags : undefined }
+}
+
+export const isBinaryUnityAsset = (bytes: Uint8Array): boolean => !(bytes[0] === 0x25 && bytes[1] === 0x59 && bytes[2] === 0x41)   // "%YA"
+
+// ---- what a material says about itself ------------------------------------------------------------
+
+/** Unity's alpha-cutout switch across pipelines: URP `_AlphaClip`, HDRP `_AlphaCutoffEnable`, Standard `_Mode` 1,
+ *  or the keyword — what becomes glTF MASK (and marks a kind as foliage for the level writer). */
+export const isCutoutMaterial = (um: UnityMaterial): boolean => {
+  const clip = um.floats._AlphaClip ?? um.floats._AlphaCutoffEnable
+  return clip === 1 || um.floats._Mode === 1 || um.keywords.includes("_ALPHATEST_ON")
+}
+
+/**
+ * The material carries its pipeline's own cutout SWITCH and that switch is OFF — i.e. it has said,
+ * in the field its shader actually reads, that it is not a cutout. Only `_AlphaClip` (URP) and
+ * `_AlphaCutoffEnable` (HDRP) count: `_Mode` is the Standard shader's field and packs leave a stale
+ * `_Mode: 0` on materials whose custom shader never looks at it, which is the whole reason the
+ * texture heuristic below exists.
+ */
+export const declaresNoCutout = (um: UnityMaterial): boolean =>
+  um.floats._AlphaClip === 0 || um.floats._AlphaCutoffEnable === 0
+
+/** The material's WIND PROFILE — Unity HDRP's Wind.hlsl properties, which NatureManufacture's vegetation shaders carry
+ *  per material: `_Drag` (how much of the wind the plant takes: trees 0.1, grass 1-2), `_Stiffness` (the bend's growth
+ *  along the plant), `_InitialBend` (a permanent lean downwind), `_ShiverDrag` (the leaves' own motion: needles 0.02,
+ *  grass 0.1-0.2, bark ~0) and `_ShiverDirectionality` (0 = along the normal, 1 = along the wind). Goes into the glTF
+ *  material extras as `lecodes.wind`, which creator-gl's foliage tier reads (glb.cpp foliageProfileFromExtras); a
+ *  material without the two defining floats has no profile and the engine picks one by the plant's size. */
+export const windProfile = (um: UnityMaterial): [number, number, number, number, number] | null => {
+  const f = um.floats
+  if (f._Drag === undefined || f._Stiffness === undefined) return null
+  return [ f._Drag, f._Stiffness, f._InitialBend ?? 0, f._ShiverDrag ?? 0, f._ShiverDirectionality ?? 0.5 ]
+}
+
+/** 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+$/, "")
+
+// ---- binary materials, collecting ------------------------------------------------------------------
+
+/** 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|ormh)$/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 }
+}

package/src/unity/materialSlots.ts

@@ -0,0 +1,53 @@
+// WHICH MATERIAL SLOT BELONGS TO WHICH PRIMITIVE.
+//
+// A MeshRenderer's `m_Materials` is indexed by UNITY's submesh order, and that is NOT always the
+// order ufbx hands us the primitives in: for Chernobyl's `Balcony_13` the two orders agree on LOD0
+// and disagree on LOD1, so assigning the list by POSITION put the trim's material on the wall, the
+// balcony panel's on the trim and the wall's on the glass — on the far level only. On screen that is
+// a building whose textures rearrange themselves as you walk up to it, and it is invisible in any
+// check that compares the SET of materials per level, because the set is identical.
+//
+// The pairing is recoverable because both sides name the same FBX material: a slot holds either
+// `name:<fbx material>` or the GUID that this model's `.meta` remaps that name to — and when the
+// `.meta` remaps nothing (a pack that assigns materials in its PREFABS ships an empty one), the slot
+// still has a name: the `.mat`'s own. Packs name those after the FBX slot they fill.
+
+import { materialKey } from "./matFile"
+
+/**
+ * For each primitive (by its FBX material name) the index of the slot it takes, −1 for none.
+ * `slotNames[k]` is what slot k is known as (null when nothing names it).
+ *
+ *  1. equal names;
+ *  2. equal KEYS (M_/MI_ prefixes aside), then one key containing the other — taken only when exactly
+ *     one slot fits. ORDER IS NOT A PAIRING: what was left over used to be handed out in primitive
+ *     order, and `SM_Wall_Door_04`'s wall reads as [Wall, Wall_Exterior] here while the prefab
+ *     assigns [Brick_Wall, Wall], so the brick ended up on the INSIDE face. By name `Wall` ↔
+ *     `Wall.mat` and `Metal` ↔ `Metal_01.mat` pair, which leaves `Wall_Exterior` ↔ `Brick_Wall.mat`
+ *     as the only way round for the rest;
+ *  3. what is left over to what is left over, in order — which is exactly how an OVERRIDDEN slot
+ *     finds its primitive, since an override's GUID matches no FBX name.
+ */
+export const pairSlots = (fbxNames: string[], slotNames: (string | null)[]): number[] => {
+  const slotFor = new Array<number>(fbxNames.length).fill(-1)
+  const used = new Set<number>()
+  const take = (i: number, k: number): void => { slotFor[i] = k; used.add(k) }
+  for (let i = 0; i < fbxNames.length; i++) {
+    const j = slotNames.findIndex((n, k) => n !== null && n === fbxNames[i] && !used.has(k))
+    if (j >= 0) take(i, j)
+  }
+  for (let i = 0; i < fbxNames.length; i++) {
+    if (slotFor[i] >= 0 || !fbxNames[i]) continue
+    const a = materialKey(fbxNames[i])
+    const free = slotNames.map((n, k) => ({ n, k })).filter((x) => x.n !== null && !used.has(x.k))
+    let hit = free.find((x) => materialKey(x.n!) === a)
+    if (!hit && a.length >= 3) {
+      const near = free.filter((x) => { const b = materialKey(x.n!); return b.length >= 3 && (b.includes(a) || a.includes(b)) })
+      if (near.length === 1) hit = near[0]
+    }
+    if (hit) take(i, hit.k)
+  }
+  const spare = slotNames.map((_, k) => k).filter((k) => !used.has(k))
+  for (let i = 0; i < fbxNames.length; i++) if (slotFor[i] < 0 && spare.length) slotFor[i] = spare.shift()!
+  return slotFor
+}

package/src/unity/materialWriter.ts

@@ -0,0 +1,306 @@
+// One Unity material → one 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).
+
+import { readFileSync } from "node:fs"
+import { basename } from "node:path"
+import type { Document, Material, Texture } from "@gltf-transform/core"
+import { KHRMaterialsEmissiveStrength } from "@gltf-transform/extensions"
+import { sniffMime, encodePng, type Rgba } from "../textures/resolveImage"
+import type { GuidResolver } from "./guid"
+import { alphaIsKeyed, decodeImage, packOrm, type PackInput } from "./image"
+import { PATH_GUID, declaresNoCutout, isCutoutMaterial, type UnityMaterial } from "./matFile"
+
+export type Warn = (w: { level: "warn" | "info", message: string }) => void
+
+// ---- 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.
+// `_Base_Color` / `_Base_Map` / `_Normal_Map` are the UNDERSCORED spellings a hand-written shader
+// graph produces from a property display name ("Base Color" -> `_Base_Color`), and they are common:
+// Chernobyl's vegetation shader names its albedo ONLY `_Base_Color`, which left 1400+ of its trees
+// untextured, and the school pack has three `_Base_Map` materials of its own. Missing a base slot is
+// the quietest failure in this file — the material still carries a colour, so it reads as flat art
+// rather than as a lost texture.
+export const SLOTS = {
+  base: [ "_BaseMap", "_Base_Map", "_MainTex", "_BaseColor", "_Base_Color", "_BaseColorMap", "_BC", "_Albedo", "_AlbedoMap", "_Diffuse", "_DiffuseMap", "_Color", "_MainBC", "_MainTex1", "_Diffuse_Tex", "_Albedo_Tex", "_Base_Tex" ],
+  normal: [ "_BumpMap", "_NormalMap", "_Normal_Map", "_Normal", "_NormalTex", "_MainNormal", "_Normal_Tex" ],
+  // `_ORMH` = Occlusion / Roughness / Metallic / Height — the same RGB as an ORM with the height in
+  // alpha (glTF's MR sampler ignores alpha, so it reads as an ORM). MISSING IT IS EXPENSIVE: the
+  // Modular Shooting Range's materials carry their whole shading in `_ORMH` and ALSO point
+  // `_OcclusionMap` at the same file, so the pass took the AO channel alone and filled the other two
+  // from the floats — `_Metallic: 1` — and every sign, locker and pipe in the level came out a bare
+  // mirror (2026-09-17: measured B = 1.000 in the import against 0.009 in T_Signs_ORM.png).
+  orm: [ "_ORM", "_ORMMap", "_ORMH", "_ORMHMap", "_OcclusionRoughnessMetallic", "_ORMTex", "_MainORM" ],
+  // `_MetalicRAOGSmothnessA` = NatureManufacture's own shaders: the HDRP layout under another name
+  maskMap: [ "_MaskMap", "_MetalicRAOGSmothnessA" ],
+  metallicGloss: [ "_MetallicGlossMap" ],
+  metallic: [ "_Metallic", "_MetallicMap", "_MetallicTex", "_MetalMap" ],
+  roughness: [ "_Roughness", "_RoughnessMap", "_RoughnessTex", "_Roughness_Tex" ],
+  smoothness: [ "_Smoothness", "_SmoothnessMap", "_SmoothnessTex", "_Gloss", "_GlossMap" ],
+  occlusion: [ "_OcclusionMap", "_Occlusion", "_AO", "_AOMap", "_AmbientOcclusion" ],
+  emission: [ "_EmissionMap", "_Emission", "_Emissive", "_EmissiveMap", "_EmissiveColorMap" ],
+  alpha: [ "_Alpha", "_Opacity", "_OpacityMap", "_AlphaMap", "_OpacityMask" ],
+}
+export const pick = (m: UnityMaterial, names: string[]): string | null => { for (const n of names) { const g = m.textures[n]; if (g) return g } return null }
+
+/** Writes Unity `.mat` materials into glTF materials of `doc` (textures decoded / packed once per
+ *  document). `applyTo` rewrites one glTF material from one Unity material and returns a slot summary. */
+export const unityMaterialWriter = (doc: Document, resolver: GuidResolver, warn: Warn = () => {}): { applyTo: (gm: Material, um: UnityMaterial, how: string) => Promise<string[]> } => {
+  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)
+    // the first base slot whose texture EXISTS: custom shaders keep stale refs in the usual slots (a
+    // tree-billboard shader's `_BaseColor` names a deleted file, its atlas sits in `_MainTex1`)
+    const baseG = SLOTS.base.map((n) => um.textures[n]).find((g) => g && (g.startsWith(PATH_GUID) || resolver.resolve(g))) ?? null
+    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] ])
+    // EVERY slot is picked the way the base is: the first candidate whose texture EXISTS. A `.mat` keeps the
+    // property block of every shader it ever wore, so a NatureManufacture bark that moved from HDRP Lit to
+    // the pack's own shader still names a deleted `_MaskMap` beside the live `_MetalicRAOGSmothnessA` — and
+    // taking the dead one first left the trunk with no pack at all, i.e. `_Smoothness: 1` = a mirror.
+    const live = (names: string[]): string | null => names.map((n) => um.textures[n]).find((g) => g && (g.startsWith(PATH_GUID) || resolver.resolve(g))) ?? null
+    const nG = live(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
+    // Unity's built-in "Autodesk Interactive" shader (builtin fileID 47 — what a Maya / 3ds Max PBR
+    // material imports as) reuses the Standard shader's slot NAMES with other meanings: `_SpecGlossMap`
+    // is a ROUGHNESS map, `_MetallicGlossMap` a plain metallic map (its alpha is NOT smoothness — it
+    // ships opaque, and reading it as smoothness 1 turned a cloth glove into a mirror), and
+    // `_Glossiness` is the roughness slider.
+    const autodesk = um.shader === "builtin:47"
+    const ormG = live(SLOTS.orm), maskG = live(SLOTS.maskMap), mgG = autodesk ? null : live(SLOTS.metallicGloss)
+    const metG = live(SLOTS.metallic) ?? (autodesk ? live(SLOTS.metallicGloss) : null)
+    const roughG = live(SLOTS.roughness) ?? (autodesk ? um.textures._SpecGlossMap ?? null : null)
+    const smoothG = live(SLOTS.smoothness), aoG = live(SLOTS.occlusion)
+    /** Metallic / roughness as plain NUMBERS off the material.
+     *
+     *  This runs when no map covers them — including when the material NAMES metal-ish slots that
+     *  then fail to resolve or decode, which used to fall through and set nothing at all. glTF's
+     *  default metallicFactor is 1 and Unity's `_Metallic` default is 0, so "set nothing" means
+     *  EVERY SUCH MATERIAL BECOMES A MIRROR: `Maple_Leaves` says `_Metallic: 0` in the .mat, names a
+     *  `_Mask` and a `_Smoothness` texture that are not in the pack, and arrived at metallic 1.00 —
+     *  a rough metal has no diffuse, so Chernobyl's maples reflected the sky and read as silver. */
+    const scalarMr = (): void => {
+      // ALWAYS a number (2026-10-18): a shader with no `_Metallic` at all — NatureManufacture's Cross Model
+      // Shader (the trees' LOD3 billboard cross, a specular shader with `_Specular` 0) — left the glTF default
+      // of 1 standing, and every far tree in the forest was a black cut-out: a metal has no diffuse. Unity's
+      // default is 0, so the absence means 0
+      gm.setMetallicFactor(um.floats._Metallic ?? 0)
+      if (smoothness !== undefined) gm.setRoughnessFactor(1 - smoothness)
+      slots.push(`metallic=${gm.getMetallicFactor().toFixed(2)} roughness=${gm.getRoughnessFactor().toFixed(2)}`)
+    }
+    const smoothness = autodesk ? (um.floats._Glossiness !== undefined ? 1 - um.floats._Glossiness : undefined) : um.floats._Smoothness ?? um.floats._Glossiness
+    // 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 dflt = { ao: 255, rough: Math.round((1 - (smoothness ?? 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 scalarMr()
+    } else scalarMr()
+
+    // emission: only when the material actually emits (keyword or a non-black colour)
+    const emG = live(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.
+    // ... EXCEPT a material whose `_EMISSION` keyword is on: that is URP / Standard speaking, and there `_EmissionColor`
+    // is the live one. A URP pack upgraded from HDRP keeps dead `_EmissiveColor` / `_EmissiveIntensity` fields (the
+    // school, 2026-09-18: Ceiling_02 emits at `_EmissionColor` 10 while its `_EmissiveColor` says 1200 nits).
+    const emC = um.keywords.includes("_EMISSION") ? um.colors._EmissionColor ?? um.colors._EmissiveColor : 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.
+    // `m_LightmapFlags` bit 4 (EmissiveIsBlack) is Unity's own veto, in every pipeline: the inspector sets it when the
+    // emission is switched off. The school's Ceiling_03 has no `_EMISSION`, this flag, and a dead HDRP `_EmissiveColor`
+    // of 0.125 - it was imported as a dim emitter.
+    // ... but ONLY for the Standard / URP Lit family, where the inspector couples the flag with the `_EMISSION` keyword.
+    // HDRP (and the shadergraphs of HDRP packs) leaves the flag at 4 on materials that glow by `_EmissiveColor` - there it
+    // only says "no contribution to baked GI" (the range's M_Lamp_long: `_EmissiveColor` 4, flags 4, and it emits).
+    const keywordShader = um.shader === "builtin:45" || um.shader === "builtin:46"
+      || um.shader === "guid:933532a4fcc9baf4fa0491de14d08ed7" || um.shader === "guid:8d2bb70cbf9db8d4da26e15b26e74248"   // URP Lit, Simple Lit
+    const flagVeto = keywordShader && ((um.lightmapFlags ?? 0) & 4) !== 0 && !um.keywords.includes("_EMISSION")
+    const emissionVetoed = (emC !== undefined && emC[0] + emC[1] + emC[2] <= 0.01) || flagVeto
+    const emits = !emissionVetoed && (um.keywords.includes("_EMISSION")
+      || (emC ? emC[0] + emC[1] + emC[2] > 0.01 : false)
+      || (!!emG && !um.keywords.length))
+    // an HDR emission colour (Unity's intensity is in it): glTF's factor stops at 1, the rest is
+    // KHR_materials_emissive_strength - the factor keeps the hue, the strength the brightest channel
+    const setEmission = (c: readonly number[] | undefined): void => {
+      const lit = c && c[0] + c[1] + c[2] > 0.01 ? c : [ 1, 1, 1 ]
+      const peak = Math.max(lit[0], lit[1], lit[2], 1)
+      gm.setEmissiveFactor([ lit[0] / peak, lit[1] / peak, lit[2] / peak ])
+      if (peak > 1.001) {
+        gm.setExtension("KHR_materials_emissive_strength", doc.createExtension(KHRMaterialsEmissiveStrength).createEmissiveStrength().setEmissiveStrength(peak))
+        slots.push(`emissiveStrength=${peak.toFixed(2)}`)
+      }
+    }
+    if (emG && emits) {
+      const t = await texFromGuid(emG)
+      if (t) { gm.setEmissiveTexture(t); setEmission(emC); slots.push(`emissive=${nameOf(emG)}`) }
+    } else if (emC && emits && !emG) setEmission(emC)
+    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 ])
+    }
+    // THE GI SWITCH: does the glow light the level in a lightmap bake? Unity says it per material in `m_LightmapFlags`
+    // (the inspector's "Global Illumination"): bit 2 BakedEmissive = Baked, bit 1 RealtimeEmissive = Realtime (which a
+    // project without realtime GI bakes as well), neither = None — drawn, lighting nothing; the pack lights the room
+    // with lamps instead (the range's M_Lamp_long: `_EmissiveColor` 4, flags 4 = EmissiveIsBlack alone). The engine's
+    // bake reads the glTF extras {"lecodes":{"emissiveBake":false}} (creator-gl lightmap_bake.cpp). A material with no
+    // `m_LightmapFlags` at all keeps the default: it bakes. MERGED into the extras (the foliage `wind` profile lives there).
+    const giNone = emits && um.lightmapFlags !== undefined && (um.lightmapFlags & 3) === 0
+    const extras = (gm.getExtras() ?? {}) as Record<string, unknown>
+    const lecodes = extras.lecodes as Record<string, unknown> | undefined
+    if (giNone) {
+      gm.setExtras({ ...extras, lecodes: { ...(lecodes ?? {}), emissiveBake: false } })
+      slots.push("emissiveBake=false (Unity GI: None)")
+    } else if (lecodes && "emissiveBake" in lecodes) {
+      // a re-import of a material whose flags changed: the switch goes
+      const { emissiveBake: _off, ...rest } = lecodes
+      const { lecodes: _l, ...others } = extras
+      gm.setExtras(Object.keys(rest).length ? { ...others, lecodes: rest } : others)
+    }
+
+    // alpha: URP `_Surface` 1 = transparent, `_AlphaClip` 1 = cutout; Standard `_Mode` 1 cutout, 2/3 blend;
+    // HDRP `_SurfaceType` 1 = transparent, `_AlphaCutoffEnable` 1 = cutout at `_AlphaCutoff` (a foliage
+    // pack's leaves are all cutout — missed, the texture's clear pixels draw as black cards)
+    const mode = um.floats._Mode, surface = um.floats._Surface ?? um.floats._SurfaceType
+    const cutout = isCutoutMaterial(um)
+    // THE AUTHORED SURFACE TYPE BEATS THE CLIP FLAG. URP writes `_AlphaClip: 1` beside `_Surface: 1`
+    // for a pane that is transparent AND clipped (a window's glass is the ordinary case: clip the
+    // fully-clear texels, blend the rest), and read as CUTOUT such a pane comes out fully OPAQUE —
+    // the test passes everywhere once the base alpha is 1, so the glass turns to stone and nothing
+    // in the conversion looks wrong. Keywords stay weaker evidence than the surface float: a stale
+    // `_ALPHABLEND_ON` left on an opaque foliage material must not beat its clip.
+    const transparentSurface = surface === 1 || mode === 2 || mode === 3
+    const blend = transparentSurface || um.keywords.includes("_ALPHABLEND_ON") || um.keywords.includes("_ALPHAPREMULTIPLY_ON") || um.keywords.includes("_SURFACE_TYPE_TRANSPARENT")
+    if (transparentSurface || (blend && !cutout)) {
+      gm.setAlphaMode("BLEND")
+      // ...and on a transparent material Unity's base-colour ALPHA is the opacity — the one number
+      // that says how much glass this is (0.18 on this school's window panes). Everywhere else the
+      // FBX's own alpha is deliberately left alone; see the base colour written above.
+      const a = (um.colors._BaseColor ?? um.colors._Color)?.[3]
+      if (a !== undefined && a < 1) { const c = gm.getBaseColorFactor(); gm.setBaseColorFactor([ c[0], c[1], c[2], a ]) }
+      slots.push(`blend${a !== undefined && a < 1 ? ` a=${a.toFixed(2)}` : ""}`)
+    }
+    else if (cutout) { gm.setAlphaMode("MASK").setAlphaCutoff(um.floats._AlphaCutoff ?? um.floats._Cutoff ?? 0.5); slots.push("cutout") }
+    // A CUSTOM shader's `_Mode` / `_Surface` MEAN NOTHING. Those floats belong to Unity's own lit
+    // shaders; a hand-written one keys its opacity however it likes and routinely leaves them at 0.
+    // Chernobyl's vegetation shader clips at `_Cutoff` internally while `Birch_Leaves` and
+    // `Small_Tree` say `_Mode: 0` with no keywords at all — imported opaque, which drew every leaf
+    // CARD as a solid quad and turned a forest of 9326 trees into white blobs seen from the air.
+    // So when the shader is one we cannot read, the TEXTURE is the evidence: a base map whose alpha
+    // channel actually carries a shape is a cutout, whatever the material's floats claim.
+    // ...but NEVER against a material that declared itself opaque in the field its own pipeline
+    // reads. HDRP addresses every shader by GUID, so `guid:` alone says nothing there, and the
+    // Modular Shooting Range's linoleum — `_AlphaCutoffEnable: 0`, `_SurfaceType: 0` — ships a base
+    // map whose alpha channel this heuristic read as a shape. The whole FLOOR was then clipped away
+    // (you saw the placeholder ground box through it) and so was the 12 cm skirting at the foot of
+    // every wall, which is the same linoleum material on the wall mesh. `_Mode: 0` still does not
+    // count as a declaration — see `declaresNoCutout`.
+    else if (um.shader.startsWith("guid:") && baseG && !declaresNoCutout(um) && await (async () => {
+      const img = await imgFromGuid(baseG)
+      return !!img && alphaIsKeyed(img)
+    })()) {
+      gm.setAlphaMode("MASK").setAlphaCutoff(um.floats._AlphaCutoff ?? um.floats._Cutoff ?? 0.5)
+      slots.push(`cutout (custom shader, keyed base map)`)
+    }
+    else if (gm.getAlphaMode() !== "OPAQUE" && !pick(um, SLOTS.alpha)) gm.setAlphaMode("OPAQUE")
+    // two-sided: Standard/URP `_Cull` 0, HDRP `_DoubleSidedEnable` 1 / `_CullMode` 0
+    if (um.floats._Cull === 0 || um.floats._CullMode === 0 || um.floats._DoubleSidedEnable === 1 || um.keywords.includes("_DOUBLESIDED_ON")) {
+      gm.setDoubleSided(true)
+      slots.push("double-sided")
+    }
+
+    return slots
+  }
+  return { applyTo }
+}