lecodes-assets 2.5.1 → 2.8.0

package/src/unity/materialWriter.ts

@@ -6,10 +6,13 @@
 // factors, which multiply the same way).
 
 import { readFileSync } from "node:fs"
+import { cpus } from "node:os"
 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 { sniffMime, encodePngAsync, type Rgba } from "../textures/resolveImage"
+import { ByteLru } from "../textures/byteLru"
+import { knownImageInfo } from "../doctor/imageFacts"
 import type { GuidResolver } from "./guid"
 import { alphaIsKeyed, decodeImage, packOrm, type PackInput } from "./image"
 import { PATH_GUID, declaresNoCutout, isCutoutMaterial, type UnityMaterial } from "./matFile"
@@ -49,52 +52,190 @@ export const SLOTS = {
 }
 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>()
+/** A texture as the glTF image it becomes: a source map (PNG / JPEG kept, anything else re-encoded as PNG) or a
+ *  packed ORM (`parts` = what went into it, `ao` = whether an occlusion source did). */
+type ImageBytes = { name: string, data: Uint8Array, mime: "image/png" | "image/jpeg", parts?: string[], ao?: boolean }
+
+/**
+ * THE TEXTURE BYTES OF ONE IMPORT, shared by every document a writer fills.
+ *
+ * A level import writes every kind as its own GLB, so a wall map shared by a hundred buildings went through
+ * read + TGA decode + PNG encode (+ for a mask map: a second decode and the ORM pack) a hundred times — on
+ * Chernobyl 3554 embedded textures of which 314 are distinct, and a kind's build time scaled with its texture
+ * count, not its parts (Apartment_Door_01_v3, all 9 maps seen before: build 3.2 s, 2026-11-04).
+ *
+ * Only the BYTES are shared — the same `Uint8Array` object to every document (`Texture.setImage` keeps the
+ * reference, and the doctor keys its per-image caches on it: transcodeKtx2.ts `imageInfo`, cardTrim.ts); each
+ * document still makes its own Texture per guid. Decoded RGBA is never kept across kinds (16–64 MB a map).
+ * Bounded by bytes, least recently used out: `LECODES_IMPORT_TEX_CACHE_MB`, default 3072 — the 14-kind sample
+ * held 83 images in 575 MB (~7 MB a map), so the pack's ~314 distinct maps are ~2.2 GB.
+ */
+export class SharedTextures {
+  readonly images: ByteLru<ImageBytes | null>
+  /** guid → does its alpha carry a shape (the custom-shader cutout test): a full decode for one boolean */
+  readonly keyed = new Map<string, Promise<boolean>>()
+  constructor(budget = (Number(process.env.LECODES_IMPORT_TEX_CACHE_MB) || 3072) * 1024 * 1024) {
+    this.images = new ByteLru(budget, (v) => v?.data.byteLength ?? 0)
+  }
+  /** At most this many decodes / encodes at once (a prefetched kind starts all of its maps): what bounds is the
+   *  memory — a 4096² map is 64 MB decoded and as much again as PNG scanlines while it deflates. */
+  private running = 0
+  private waiting: (() => void)[] = []
+  private readonly jobs = Math.max(2, Math.min(8, Math.floor(cpus().length / 2)))
+  async slot<T>(work: () => Promise<T>): Promise<T> {
+    if (this.running >= this.jobs) await new Promise<void>((res) => this.waiting.push(res))
+    else this.running++
+    try { return await work() } finally { const next = this.waiting.shift(); if (next) next(); else this.running-- }
+  }
+}
+
+/** A map as PNG, with what the doctor's analysis would ask sharp about it already known: its size and whether its
+ *  alpha is used are right here in the pixels (imageFacts.ts — sharp's metadata + stats were 0.1–0.25 s a map). */
+const pngOf = async (img: Rgba): Promise<Uint8Array> => {
+  const png = await encodePngAsync(img)
+  knownImageInfo(png, img)
+  return png
+}
+
+/** Writes Unity `.mat` materials into glTF materials of `doc` (one Texture per guid per document; the bytes come
+ *  from `shared`, which a level import hands every kind). `applyTo` rewrites one glTF material from one Unity
+ *  material and returns a slot summary. */
+export const unityMaterialWriter = (doc: Document, resolver: GuidResolver, warn: Warn = () => {}, shared: SharedTextures = new SharedTextures(Infinity)): { applyTo: (gm: Material, um: UnityMaterial, how: string) => Promise<string[]>, prefetch: (um: UnityMaterial) => void } => {
+  const texCache = new Map<string, Promise<Texture | null>>()
+  const imgCache = new Map<string, Promise<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 bytesFromGuid = (guid: string): Promise<ImageBytes | null> => shared.images.get(`tex:${guid}`, async () => {
     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)
+    if (!src) return null
+    const name = basename(src.file).replace(/\.[^.]+$/, "")
+    const mime = sniffMime(src.bytes, src.file)
+    if (mime === "image/png" || mime === "image/jpeg") return { name, data: src.bytes, mime }
+    const data = await shared.slot(async () => { const img = await decodeImage(src.bytes, src.file); return img ? pngOf(img) : null })
+    if (!data) { warn({ level: "warn", message: `texture ${basename(src.file)}: unsupported format (${mime}) — skipped` }); return null }
+    return { name, data, mime: "image/png" }
+  })
+  const texFromGuid = (guid: string): Promise<Texture | null> => {
+    let t = texCache.get(guid)
+    if (!t) {
+      t = bytesFromGuid(guid).then((b) => (b ? doc.createTexture(b.name).setImage(b.data).setMimeType(b.mime) : null))
+      texCache.set(guid, t)
     }
-    texCache.set(guid, tex)
-    return tex
+    return t
   }
-  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 imgFromGuid = (guid: string): Promise<Rgba | null> => {
+    let p = imgCache.get(guid)
+    if (!p) {
+      p = (async () => {
+        const src = loadBytes(guid)
+        const img = src ? await shared.slot(() => decodeImage(src.bytes, src.file)) : null
+        if (src && !img) warn({ level: "warn", message: `texture ${basename(src.file)}: could not decode for packing — skipped` })
+        return img
+      })()
+      imgCache.set(guid, p)
+    }
+    return p
   }
   const nameOf = (guid: string): string => { const f = guid.startsWith(PATH_GUID) ? guid.slice(PATH_GUID.length) : resolver.resolve(guid); return f ? basename(f) : guid }
 
+  /** The texture guids `applyTo` reads off a Unity material, by role, and the numbers that decide them — picked
+   *  once, for `applyTo` and for `prefetch` alike. */
+  const sourcesOf = (um: UnityMaterial) => {
+    // EVERY slot is picked the same way: 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
+    // 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 = live(SLOTS.base)
+    const nG = live(SLOTS.normal)
+    // 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)
+    const smoothness = autodesk ? (um.floats._Glossiness !== undefined ? 1 - um.floats._Glossiness : undefined) : um.floats._Smoothness ?? um.floats._Glossiness
+    // 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))
+    return { baseG, nG, ormG, maskG, mgG, metG, roughG, smoothG, aoG, smoothness, emG, emC, emits }
+  }
+  type Sources = ReturnType<typeof sourcesOf>
+
+  /** The packed ORM of a material (R = AO, G = roughness, B = metallic; scalar fallbacks for the channels no map
+   *  covers), null when none of its sources decodes. The recipe is the key: the same maps and fallbacks pack to
+   *  the same pixels in every kind. */
+  const packedOrm = (um: UnityMaterial, { maskG, mgG, metG, roughG, smoothG, aoG, smoothness }: Sources): Promise<ImageBytes | null> => {
+    const dflt = { ao: 255, rough: Math.round((1 - (smoothness ?? 0.5)) * 255), metal: Math.round((um.floats._Metallic ?? 0) * 255) }
+    return shared.images.get(`orm:${JSON.stringify([ maskG, mgG, metG, roughG, roughG ? null : smoothG, aoG, dflt ])}`, async () => {
+      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) return null
+      const data = await shared.slot(() => pngOf(packOrm(ao, rough, metal, dflt)))
+      return { name: "", data, mime: "image/png", parts, ao: !!ao }
+    })
+  }
+  const packs = (s: Sources): boolean => !s.ormG && !!(s.maskG || s.mgG || s.metG || s.roughG || s.smoothG || s.aoG)
+
+  /** Start making every image `applyTo(um)` will read, without touching the document: the bytes land in `shared`
+   *  (one prepare per guid, deduplicated in flight) and `applyTo` then waits on them in its own order — the
+   *  Textures are still created in that order, so the file does not change. Run for a kind's materials up front,
+   *  the deflates of its maps overlap on the thread pool instead of queueing behind one another. */
+  const prefetch = (um: UnityMaterial): void => {
+    const s = sourcesOf(um)
+    const guids = [ s.baseG, s.nG, s.ormG, s.emits ? s.emG : null ]
+    for (const g of guids) if (g) void bytesFromGuid(g)
+    if (packs(s)) void packedOrm(um, s)
+  }
+
   /** 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)")
+    const src = sourcesOf(um)
+    const { baseG, nG, ormG, smoothness, emG, emC, emits } = src
     // 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)}`) } }
     let baseColor = um.colors._BaseColor ?? um.colors._Color
     // An Amplify leaf graph's albedo is `_Color × tex + _Color_Tilling × tex × noise` (Chernobyl's Leaves.shader: a
@@ -108,25 +249,9 @@ export const unityMaterialWriter = (doc: Document, resolver: GuidResolver, warn:
       slots.push(`base×(_Color + _Color_Tilling/2)`)
     }
     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
@@ -144,7 +269,6 @@ export const unityMaterialWriter = (doc: Document, resolver: GuidResolver, warn:
       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
@@ -168,53 +292,14 @@ export const unityMaterialWriter = (doc: Document, resolver: GuidResolver, warn:
     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 if (packs(src)) {
+      const packed = await packedOrm(um, src)
+      if (packed) {
+        const t = doc.createTexture(`${um.name}_ORM`).setImage(packed.data).setMimeType("image/png")
+        setMr(t, !!packed.ao, `packed ORM ← ${packed.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 => {
@@ -296,9 +381,10 @@ export const unityMaterialWriter = (doc: Document, resolver: GuidResolver, warn:
     // (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)
+    else if (um.shader.startsWith("guid:") && baseG && !declaresNoCutout(um) && await (() => {
+      let k = shared.keyed.get(baseG)
+      if (!k) { k = imgFromGuid(baseG).then((img) => !!img && alphaIsKeyed(img)); shared.keyed.set(baseG, k) }
+      return k
     })()) {
       gm.setAlphaMode("MASK").setAlphaCutoff(um.floats._AlphaCutoff ?? um.floats._Cutoff ?? 0.5)
       slots.push(`cutout (custom shader, keyed base map)`)
@@ -312,5 +398,5 @@ export const unityMaterialWriter = (doc: Document, resolver: GuidResolver, warn:
 
     return slots
   }
-  return { applyTo }
+  return { applyTo, prefetch }
 }

package/src/unity/prefabTree.ts

@@ -197,6 +197,9 @@ export class PrefabLoader {
     // it is kept and the loss is counted rather than the wall disappearing.
     const objRef = m.objectReference && ref(m.objectReference).fileID !== "0" ? m.objectReference : undefined
     if (objRef && !ref(objRef).guid && ref(readPath(target.body, path)).guid) { this.stats.sceneLocalRefs++; return }
+    // the slot list BEFORE the first override (`m_MaterialsSource`, ours): an overridden slot's material names nothing in
+    // the FBX, and which submesh the slot stands for is told only by what it held in the source prefab (kindGlb pairs by it)
+    if (materialSlot(path) !== null && Array.isArray(target.body.m_Materials) && target.body.m_MaterialsSource === undefined) target.body.m_MaterialsSource = structuredClone(target.body.m_Materials)
     setPath(target.body, path, objRef ?? m.value)
   }
 

package/src/unity/scene.ts

@@ -18,7 +18,7 @@ import { resolverFor } from "./guid"
 import { I4, decompose, mirrorX, mmul, r6, trsMatrix, type Mat4 } from "./math"
 import { PrefabLoader, newStats } from "./prefabTree"
 import { readUnityTerrain, type UnityTerrain } from "./terrain"
-import { color, isMap, num, ref, vec3, type Quat, type Vec3 } from "./yaml"
+import { color, isMap, num, ref, vec3, type Quat, type Vec3, type Y } from "./yaml"
 
 export type Handedness = "x" | "none"
 
@@ -32,6 +32,9 @@ export type KindPart = {
   mesh: { guid: string, fileID: string }
   /** `.mat` GUIDs, one per submesh (Unity's order). */
   materials: string[]
+  /** What each slot held in the SOURCE prefab, before an instance overrode it (`""` = nothing there); absent when no
+   *  slot was overridden. Only for pairing slots with primitives — never in the kind key, so no kind splits on it. */
+  sourceMaterials?: string[]
   /** The level this part is drawn at. THE ENGINE'S LOD GROUP IS THE WHOLE GLB (creator-gl lod.cpp): at level n it draws
    *  the `_LOD<n>` nodes and nothing else, so a renderer Unity draws at several levels (listed under each, or in a
    *  cull-only LODGroup, or in none while the kind has levels) is written once per level — the same mesh under a
@@ -240,7 +243,8 @@ export const importUnityScene = async (scenePath: string, opts: ImportSceneOptio
           // in no LODGroup: a loose renderer named like its node (`…_LOD1`) keeps that level; a plain one is drawn at every level
           const suffix = lodSuffix(goName(g))
           const levels = lods.get(mr) ?? (suffix > 0 ? [ suffix ] : [])
-          drawn.push({ part: { path: p, matrix: M, mesh: { guid: mesh.guid, fileID: mesh.fileID }, materials: mats, castShadows: num(mr.body.m_CastShadows, 1) !== 0 }, levels })
+          const source = Array.isArray(mr.body.m_MaterialsSource) ? mats.map((_, k) => ref((mr.body.m_MaterialsSource as Y[])[k]).guid ?? "") : undefined
+          drawn.push({ part: { path: p, matrix: M, mesh: { guid: mesh.guid, fileID: mesh.fileID }, materials: mats, ...(source ? { sourceMaterials: source } : {}), castShadows: num(mr.body.m_CastShadows, 1) !== 0 }, levels })
         }
       }
       for (const c of g.comps) {

package/src/unity/triBudget.ts

@@ -5,11 +5,11 @@
 // renderer's physics down with an out-of-bounds abort before the first frame.
 //
 // So a kind over the budget is simplified at import (meshoptimizer, the same weld + simplify the doctor's
-// LOD pass runs), all of its primitives by one ratio. A scan's look lives in its normal map, which the
+// LOD pass runs), each LOD level over the budget by its own ratio. A scan's look lives in its normal map, which the
 // simplified surface keeps (the UVs are preserved), and the collider shrinks with it. Skinned meshes are
 // left alone: collapsing vertices under a skin moves weights the budget knows nothing about.
 
-import { PropertyType, type Document, type Primitive } from "@gltf-transform/core"
+import { PropertyType, type Document, type Mesh, type Primitive } from "@gltf-transform/core"
 import { prune, simplifyPrimitive, weldPrimitive } from "@gltf-transform/functions"
 import { MeshoptSimplifier } from "meshoptimizer"
 
@@ -17,15 +17,47 @@ export const DEFAULT_MAX_TRIS = 50_000
 
 const trisOf = (p: Primitive): number => p.getMode() !== 4 ? 0 : Math.floor((p.getIndices()?.getCount() ?? p.getAttribute("POSITION")?.getCount() ?? 0) / 3)
 
-/** Simplify the document's meshes down to about `maxTris` triangles in total. Null when it already fits. */
+/** The primitives drawn at each LOD level (`_LOD<n>` node names, none = level 0): kindGlb writes a node per level a
+ *  part is drawn at, so a primitive shared by twins counts at every one of their levels. A mesh on no node is level 0. */
+const primsByLevel = (doc: Document): Map<number, Set<Primitive>> => {
+  const out = new Map<number, Set<Primitive>>()
+  const add = (level: number, mesh: Mesh): void => {
+    let set = out.get(level)
+    if (!set) out.set(level, set = new Set())
+    for (const p of mesh.listPrimitives()) if (p.getMode() === 4 && !p.getAttribute("JOINTS_0")) set.add(p)
+  }
+  const placed = new Set<Mesh>()
+  for (const n of doc.getRoot().listNodes()) {
+    const mesh = n.getMesh()
+    if (!mesh) continue
+    placed.add(mesh)
+    add(Number(/_LOD(\d+)$/i.exec(n.getName())?.[1] ?? 0), mesh)
+  }
+  for (const m of doc.getRoot().listMeshes()) if (!placed.has(m)) add(0, m)
+  return out
+}
+
+/** Simplify the document's meshes until no LOD level draws more than about `maxTris` triangles. Null when it already fits.
+ *
+ *  THE BUDGET IS PER LEVEL, never the kind's sum: one level is drawn at a time and the collider is level 0. Summed,
+ *  Chernobyl's Ferris_Wheel (110 k + 44 k + 20 k + 10 k over four levels) went down to 0.27 of itself on EVERY level,
+ *  the coarsest included, and at that ratio the 5 % error ceiling (a metre on a 22 m wheel) collapsed the rim and the
+ *  outer half of the spokes: the cabins hung in the air around a stump of a wheel (2026-11-04). Now only a level over
+ *  the budget is simplified, by its own ratio. */
 export const fitTriangleBudget = async (doc: Document, maxTris: number): Promise<{ before: number, after: number } | null> => {
-  // a Set: a kind's parts that share a mesh share its primitives (kindGlb clones meshes shallowly)
-  const prims = [ ...new Set(doc.getRoot().listMeshes().flatMap((m) => m.listPrimitives())) ].filter((p) => p.getMode() === 4 && !p.getAttribute("JOINTS_0"))
-  const before = prims.reduce((n, p) => n + trisOf(p), 0)
+  const levels = primsByLevel(doc)
+  const levelTris = (set: Set<Primitive>): number => [ ...set ].reduce((n, p) => n + trisOf(p), 0)
+  const heaviest = (): number => Math.max(0, ...[ ...levels.values() ].map(levelTris))
+  const before = heaviest()
   if (maxTris <= 0 || before <= maxTris) return null
+  // a primitive drawn at several levels takes the strictest of their ratios
+  const ratioOf = new Map<Primitive, number>()
+  for (const set of levels.values()) {
+    const r = maxTris / Math.max(1, levelTris(set))
+    if (r < 1) for (const p of set) ratioOf.set(p, Math.min(r, ratioOf.get(p) ?? 1))
+  }
   await MeshoptSimplifier.ready
-  const ratio = maxTris / before
-  for (const p of prims) {
+  for (const [ p, ratio ] of ratioOf) {
     const want = trisOf(p) * ratio
     weldPrimitive(p)
     // `error` is the ceiling on how far the surface may move, relative to the mesh's size: a scan has
@@ -46,7 +78,7 @@ export const fitTriangleBudget = async (doc: Document, maxTris: number): Promise
   // weld and simplify write NEW accessors: the million-triangle originals stay in the file until pruned
   // (the herbarium was 27 MB at 50 000 triangles without this)
   await doc.transform(prune({ propertyTypes: [ PropertyType.ACCESSOR ] }))
-  return { before, after: prims.reduce((n, p) => n + trisOf(p), 0) }
+  return { before, after: heaviest() }
 }
 
 /** Area-weighted vertex normals, summed per POSITION so a UV seam (two vertices, one point) shades as one. */