lecodes-assets 0.2.0 → 2.4.10

package/src/unity/guid.ts

@@ -0,0 +1,104 @@
+// GUID → file. Every reference inside a Unity project is a GUID; the path behind it comes from a
+// `unity-index.txt` (written by `lecodes assets unpack`) or the `.meta` sidecars of a real project.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+
+export 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)
+  }
+}
+
+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 => {
+  // THE PROJECT'S `Assets` HAS NO `.meta` OF ITS OWN — every folder inside it does. Without that test
+  // the first folder called `assets` on the way up won (a case-insensitive disk makes `Assets` match it
+  // too): Peremena's `Models/assets/` (a Sketchfab download) cut the index down to Models/, and the
+  // walls and ceiling lost their materials — `Materials/` was never scanned.
+  const isProjectAssets = (dir: string): boolean => /^assets$/i.test(basename(dir)) && !existsSync(`${dir}.meta`)
+  const holdsProjectAssets = (dir: string): boolean => {
+    try { return readdirSync(dir).some((n) => /^assets$/i.test(n) && isProjectAssets(join(dir, n))) } catch { return false }
+  }
+  let root = resolve(start)
+  for (let i = 0; i < depthUp; i++) {
+    if (isProjectAssets(root) || holdsProjectAssets(root)) 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 } }
+}
+
+/** 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
+}
+
+/** The resolver for a scene / prefab file: the index found walking up from it (or the one given),
+ *  else the Unity project's `.meta` sidecars. */
+export const resolverFor = (file: string, indexFile?: string | null): GuidResolver => {
+  const idx = indexFile === undefined ? findUnityIndex(dirname(resolve(file))) : indexFile
+  if (idx && existsSync(idx)) return resolverFromIndex(idx)
+  const r = resolverFromMeta(dirname(resolve(file)), 12)
+  if (!r) throw new Error(`no unity-index.txt above ${file} and no .meta sidecars — cannot resolve GUIDs`)
+  return r
+}

package/src/unity/image.ts

@@ -0,0 +1,58 @@
+// Texture pixels for the material pass: decode whatever a pack ships, pack glTF's ORM layout.
+
+import { sniffMime, decodeTga, decodeBmp, type Rgba } from "../textures/resolveImage"
+import { decodePng } from "./png"
+
+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 }
+}
+
+/** Does this image's ALPHA channel carry a shape, or is it the flat 255 a decoder invents? Sampled —
+ *  a leaf card is ~87 % clear, so a coarse stride sees it instantly and a false positive needs a
+ *  meaningful part of the image to be see-through. */
+export const alphaIsKeyed = (img: Rgba): boolean => {
+  const n = img.width * img.height
+  const step = Math.max(1, Math.floor(n / 4096))
+  let clear = 0, seen = 0
+  for (let i = 0; i < n; i += step) { seen++; if (img.data[i * 4 + 3] < 250) clear++ }
+  return seen > 0 && clear / seen > 0.02
+}
+
+/** The mean alpha of an image (0..1), sampled on a coarse grid — what a mask map says as one number. Null when undecodable. */
+export const meanAlpha = async (bytes: Uint8Array, hint: string): Promise<number | null> => {
+  const img = await decodeImage(bytes, hint)
+  if (!img) return null
+  const step = Math.max(1, Math.floor(Math.sqrt((img.width * img.height) / 4096)))
+  let sum = 0, n = 0
+  for (let y = 0; y < img.height; y += step) for (let x = 0; x < img.width; x += step) { sum += img.data[(y * img.width + x) * 4 + 3]; n++ }
+  return n ? sum / n / 255 : null
+}

package/src/unity/kindGlb.ts

@@ -0,0 +1,364 @@
+// One scene KIND (scene.ts: a fully expanded prefab — mesh parts, materials per submesh, LOD levels)
+// → one glTF Document: the meshes pulled out of their FBX files, each on a node carrying the part's
+// kind-local transform, the FBX importer's `globalScale` and the FBX's own geometric-transform helper,
+// materials written from the Unity `.mat` files the MeshRenderer names (by GUID — no name guessing),
+// LOD parts named `<part>_LOD<n>` so creator-gl's LOD pass groups them.
+//
+// Mesh identity: a MeshFilter names `{fileID, guid}` — the FBX's GUID and the Unity object id the FBX
+// `.meta` names after the NODE that holds the mesh. That node's geometry in ufbx's frame (metres,
+// right-handed Y-up) is Unity's mesh mirrored back on X, i.e. exactly what the X-mirrored kind frame
+// expects; `globalScale` is the only factor left.
+
+import { basename, dirname } from "node:path"
+import { readFileSync } from "node:fs"
+import { Document, type Material, type Mesh, type Node } from "@gltf-transform/core"
+import { mergeDocuments, prune } from "@gltf-transform/functions"
+import { readFbx } from "../fbx/read"
+import { toDocument } from "../fbx/toDocument"
+import { quiet } from "../props"
+import { readFbxMeta, type FbxMeta } from "./fbxModel"
+import { readUnityMeshAsset } from "./unityMesh"
+import type { GuidResolver } from "./guid"
+import { I4, mmul, scaleMatrix, type Mat4 } from "./math"
+import { collectUnityMaterials, materialKey, parseUnityMaterial, windProfile, type UnityMaterial } from "./matFile"
+import { pairSlots } from "./materialSlots"
+import { unityMaterialWriter } from "./materialWriter"
+import { projectTriplanar, triplanarOf } from "./triplanar"
+import type { KindPart, SceneKind } from "./scene"
+
+type FbxSource = { doc: Document, meta: FbxMeta, byName: Map<string, Node>, path: string, sole?: Node | null }
+
+/** The file's ONLY mesh-bearing node, or null when it has none or more than one (cached per file). */
+const soleMeshNode = (src: FbxSource): Node | undefined => {
+  if (src.sole === undefined) {
+    const hit: Node[] = []
+    for (const n of src.doc.getRoot().listNodes()) {
+      if (n.getMesh()) { hit.push(n); continue }
+      const kid = n.listChildren().find((c) => c.getMesh())
+      if (kid && !n.getMesh()) hit.push(n)
+    }
+    // the MESH either way: a parent counts by its child's mesh, not by the child node — mixing the two
+    // made every file whose mesh node has a parent (a Sketchfab export: root/…/Plane_0/Object_4) "two meshes"
+    const meshes = new Set(hit.map((n) => n.getMesh() ?? n.listChildren().find((c) => c.getMesh())?.getMesh()))
+    src.sole = meshes.size === 1 ? hit[0] : null
+  }
+  return src.sole ?? undefined
+}
+
+export type KindGlbContext = {
+  resolver: GuidResolver
+  /** The folders whose `.mat` files answer `name:<material>` refs (FBX materials not remapped). */
+  materialDirs: string[]
+  warn: (msg: string) => void
+}
+
+/** One kind's document under construction, with what is shared between its parts. */
+type KindDoc = {
+  doc: Document
+  writer: ReturnType<typeof unityMaterialWriter>
+  /** per source FBX: its document merged in (source property → copy) */
+  merged: Map<string, Map<unknown, unknown>>
+  /** the FBX nodes that came along, dropped at the end */
+  imported: Set<Node>
+  materials: Map<string, Material>
+  meshes: Map<string, Mesh>
+}
+
+/** THE LOD CHAIN IS GROUPED BY BASE NAME, so every level of one mesh must share it — and a vegetation
+ *  pack breaks that by convention: Unity's tree exporter calls the last level `Billboard_<Tree>` beside
+ *  `<Tree>`, `<Tree>_LOD1`, `<Tree>_LOD2`. Left alone the billboard becomes a chain of ITS OWN whose
+ *  only member is level 3, so it is selected at every distance and drawn OVER the tree it is supposed
+ *  to replace: Chernobyl's forest wore flat white cards at point-blank range. The prefix goes when the
+ *  part is a LOD member. */
+/**
+ * The node names a renderer's GameObject could be standing for when the FBX `.meta` id table is empty
+ * (a pack routinely ships `internalIDToNameTable: []`), most literal first. Unity names a DUPLICATED
+ * object `Book (17)` while the node in the file is still `Book`; a renderer that sits on the prefab
+ * ROOT has no path of its own, and the prefab is named after the model with a pack's decoration —
+ * NatureManufacture's terrain-detail prefabs are `Prefab_heath_A_01_Unity_Terrain` over
+ * `heath_A_01.fbx`, whose meshes are `heath_A_01_LOD0` / `_LOD1`; a scene's loose renderer IS named
+ * like its node (`mountain_background_02_LOD1`), only the kind name carries it.
+ */
+export const meshNameCandidates = (hint?: string, kindName?: string): string[] => {
+  const out: string[] = []
+  const add = (s: string | undefined): void => { if (s && !out.includes(s)) out.push(s) }
+  for (const raw of [ hint, kindName ]) {
+    if (!raw) continue
+    add(raw)
+    const bare = raw.replace(/ \(\d+\)$/, "")
+    add(bare)
+    const plain = bare.replace(/^(Prefab|P|PF|PREFAB|SM|PRB)_/i, "").replace(/_(Unity_Terrain|Terrain|Prefab|VS)$/i, "")
+    add(plain)
+    add(`${plain}_LOD0`)
+  }
+  return out
+}
+
+const partNodeName = (part: KindPart, kindName: string): string => {
+  const raw = (part.path.split("/").pop() || kindName).replace(/_LOD\d+$/i, "")
+  return part.lod > 0 ? `${raw.replace(/^Billboard_/i, "")}_LOD${part.lod}` : raw
+}
+
+export class KindGlbBuilder {
+  private fbx = new Map<string, Promise<FbxSource | null>>()
+  private mats = new Map<string, UnityMaterial | null>()
+  private byKey: Map<string, UnityMaterial> | null = null
+  constructor(readonly ctx: KindGlbContext) {}
+
+  private source(guid: string): Promise<FbxSource | null> {
+    let p = this.fbx.get(guid)
+    if (!p) {
+      p = (async () => {
+        const path = this.ctx.resolver.resolve(guid)
+        if (!path) { this.ctx.warn(`mesh source ${guid}: not found`); return null }
+        // A MESH SAVED BY UNITY (`<Tree>_Mesh_s.asset`, the hand-made LOD3 cross of NatureManufacture's
+        // trees) is a one-node source of its own: `4300000` is the fileID Unity gives the mesh in a
+        // mesh asset, and the node carries the asset's name for the name / sole-mesh fallbacks.
+        if (/\.asset$/i.test(path)) {
+          try {
+            const um = readUnityMeshAsset(path)
+            if (!um) { this.ctx.warn(`${basename(path)}: not a readable mesh asset (binary, compressed or empty)`); return null }
+            const node = um.doc.getRoot().listNodes()[0]
+            const meta: FbxMeta = { globalScale: 1, names: new Map([ [ "4300000", um.name ] ]), ids: new Map([ [ `43:${um.name}`, "4300000" ] ]), materials: new Map(), addColliders: false, bakeAxisConversion: false }
+            return { doc: um.doc, meta, byName: new Map([ [ um.name, node ] ]), path, sole: node }
+          } catch (e) { this.ctx.warn(`${basename(path)}: ${(e as Error).message}`); return null }
+        }
+        try {
+          const scene = await readFbx(new Uint8Array(readFileSync(path)))
+          const { doc } = await toDocument(scene, { baseDir: dirname(path), defaultClipName: basename(path), warn: () => {}, extraUvSets: true })
+          for (const a of doc.getRoot().listAnimations()) a.dispose()
+          const byName = new Map<string, Node>()
+          for (const n of doc.getRoot().listNodes()) if (!byName.has(n.getName())) byName.set(n.getName(), n)
+          return { doc, meta: readFbxMeta(path + ".meta"), byName, path }
+        } catch (e) { this.ctx.warn(`${basename(path)}: ${(e as Error).message}`); return null }
+      })()
+      this.fbx.set(guid, p)
+    }
+    return p
+  }
+
+  private material(ref: string): UnityMaterial | null {
+    if (this.mats.has(ref)) return this.mats.get(ref)!
+    let um: UnityMaterial | null = null
+    if (ref.startsWith("name:")) {
+      this.byKey ??= collectUnityMaterials(this.ctx.materialDirs, 8).byKey
+      um = this.byKey.get(materialKey(ref.slice(5))) ?? null
+    } else if (ref) {
+      const path = this.ctx.resolver.resolve(ref)
+      if (path) { try { um = parseUnityMaterial(readFileSync(path, "utf8"), path) } catch { um = null } }
+      if (!um && path) this.ctx.warn(`material ${basename(path)}: unreadable (binary?) — the FBX's own kept`)
+    }
+    // A miss here is SILENT and expensive: the primitive keeps no material at all (the FBX's own is
+    // pruned with the rest of its document), so the kind renders as glTF's default white metal.
+    if (!um) this.ctx.warn(`material ${ref}: no .mat found — the part keeps no material`)
+    this.mats.set(ref, um)
+    return um
+  }
+
+  /** Every material of every part, in part order (null = unreadable) — what the level writer's foliage
+   *  verdict reads (`unity/foliage.ts`: the material's folder and name, never its alpha mode). */
+  materialsOf(kind: SceneKind): (UnityMaterial | null)[] {
+    const out: (UnityMaterial | null)[] = []
+    for (const part of kind.parts) for (const ref of part.materials) out.push(this.material(ref))
+    return out
+  }
+
+  /** The mesh node of an FBX for a Unity mesh ref, with the transform from that node to its mesh
+   *  (a geometric-transform helper child when ufbx made one).
+   *
+   *  A MeshFilter names its mesh `{fileID, guid}`, and turning that NUMBER into a node name needs the
+   *  FBX `.meta`'s own id table — which a pack routinely ships EMPTY (`internalIDToNameTable: []`;
+   *  Chernobyl's every model does, and not one of its 648 kinds could be built). So when the id says
+   *  nothing, fall back to the part's own NODE NAME: Unity names the GameObject it instantiates after
+   *  the FBX node it came from, so `Pine_01_LOD0` in the prefab is `Pine_01_LOD0` in the file. It is a
+   *  strict improvement — the id is tried first and a renamed node just fails the way it did before. */
+  private meshFor(src: FbxSource, fileID: string, hint?: string, kindName?: string): { mesh: Mesh, local: Mat4 } | null {
+    const name = fileID.startsWith("name:") ? fileID.slice(5) : src.meta.names.get(fileID)
+    // ...and when the part has no path either — the renderer sits on the prefab ROOT, which is how
+    // every single-mesh prop in a kit is built — there is still one unambiguous answer if the file
+    // holds exactly ONE mesh: that mesh.
+    let node = name !== undefined ? src.byName.get(name) : undefined
+    for (const c of meshNameCandidates(hint, kindName)) { if (node) break; node = src.byName.get(c) }
+    // the file's LOD chain of that base name — a detail prefab's one renderer means "the plant", and
+    // the plant is `heath_A_01_LOD0` (the finest level; the coarser ones are the same plant)
+    if (!node) {
+      for (const c of meshNameCandidates(hint, kindName)) {
+        const chain = [ ...src.byName.entries() ].filter(([ n ]) => n.replace(/_LOD\d+$/i, "") === c && /_LOD\d+$/i.test(n)).sort(([ a ], [ b ]) => a.localeCompare(b))
+        if (chain.length) { node = chain[0][1]; break }
+      }
+    }
+    node ??= soleMeshNode(src)
+    if (!node) return null
+    if (node.getMesh()) return { mesh: node.getMesh()!, local: I4() }
+    for (const c of node.listChildren()) if (c.getMesh()) return { mesh: c.getMesh()!, local: Array.from(c.getMatrix()) }
+    return null
+  }
+
+  /** The materials of one mesh: each primitive takes the slot that names it (materialSlots.ts) — by
+   *  NAME, never by position. A slot is known by the FBX material it names, the one this model's
+   *  `.meta` remaps its GUID from, or — when the `.meta` remaps nothing — the `.mat`'s own name. */
+  private async assignMaterials(mesh: Mesh, part: KindPart, src: FbxSource, out: KindDoc): Promise<void> {
+    const prims = mesh.listPrimitives()
+    const byGuid = new Map<string, string>()
+    for (const [ n, g ] of src.meta.materials) if (!byGuid.has(g)) byGuid.set(g, n)
+    const slotName = part.materials.map((r) => (r.startsWith("name:") ? r.slice(5) : byGuid.get(r) ?? this.material(r)?.name ?? null))
+    const slotFor = pairSlots(prims.map((pr) => pr.getMaterial()?.getName() ?? ""), slotName)
+    for (let i = 0; i < prims.length; i++) {
+      const ref = part.materials[slotFor[i] >= 0 ? slotFor[i] : Math.min(i, part.materials.length - 1)]
+      if (!ref) continue
+      const um = this.material(ref)
+      // THE DETAIL LAYER ON ANOTHER UV SET (NatureManufacture's bark shader): albedo / normal / ORM are
+      // `lerp(main(uv0), detail(uv3 × tiling), mask.a)`, and the pines' mask is white everywhere — uv0 covers the
+      // roots alone, the whole trunk is the detail bark on the third UV set. glTF has one UV per texture slot,
+      // so the primitive takes the detail textures on TEXCOORD_0 = that set × tiling.
+      const detail = um ? await this.detailLayer(um) : null
+      const set = detail ? prims[i].getAttribute(`TEXCOORD_${detail.set}`) : null
+      const useDetail = detail !== null && set !== null
+      const key = useDetail ? `${ref}\u0000detail` : ref
+      let gm = out.materials.get(key)
+      if (!gm && um) {
+        gm = out.doc.createMaterial(um.name)
+        await out.writer.applyTo(gm, useDetail ? detail!.um : um, "name")
+        const wind = windProfile(um)
+        if (wind) {
+          // merged: applyTo may have put the GI switch (`emissiveBake`) there already
+          const extras = (gm.getExtras() ?? {}) as Record<string, unknown>
+          gm.setExtras({ ...extras, lecodes: { ...((extras.lecodes as Record<string, unknown> | undefined) ?? {}), wind } })
+        }
+        out.materials.set(key, gm)
+      }
+      if (!gm) continue
+      if (useDetail) {
+        const [ sx, sy, ox, oy ] = detail!.st
+        const src = set!, n = src.getCount(), uv = new Float32Array(new ArrayBuffer(n * 8)), v: number[] = []
+        // glTF v runs top-down (the reader flipped it): Unity's v' = v·sy + oy on the un-flipped value
+        for (let k = 0; k < n; k++) { src.getElement(k, v); uv[k * 2] = v[0] * sx + ox; uv[k * 2 + 1] = 1 - ((1 - v[1]) * sy + oy) }
+        prims[i].setAttribute("TEXCOORD_0", out.doc.createAccessor().setType("VEC2").setArray(uv).setBuffer(out.doc.getRoot().listBuffers()[0]))
+      }
+      prims[i].setMaterial(gm)
+    }
+  }
+
+  private detailCache = new Map<string, Promise<{ set: number, st: [number, number, number, number], um: UnityMaterial } | null>>()
+
+  /** A material whose surface IS its detail layer: `_DETALUSEUV3_ON` (the detail sampled on Unity's uv3 = set 2)
+   *  with a `_DetailAlbedoMap`, under a `_DetailMask` whose alpha is white (a black or missing mask = the
+   *  main layer alone, Unity's default; a mixed mask is logged and the main layer kept). */
+  private detailLayer(um: UnityMaterial): Promise<{ set: number, st: [number, number, number, number], um: UnityMaterial } | null> {
+    let p = this.detailCache.get(um.file)
+    if (!p) {
+      p = (async () => {
+        if (!um.keywords.includes("_DETALUSEUV3_ON") || !um.textures._DetailAlbedoMap) return null
+        const maskGuid = um.textures._DetailMask
+        const maskPath = maskGuid ? this.ctx.resolver.resolve(maskGuid) : null
+        if (!maskPath) return null
+        const { meanAlpha } = await import("./image")
+        const a = await meanAlpha(new Uint8Array(readFileSync(maskPath)), maskPath)
+        if (a === null) return null
+        if (a < 0.97) { if (a > 0.03) this.ctx.warn(`${um.name}: detail mask ${basename(maskPath)} is mixed (${a.toFixed(2)}) — main layer kept`); return null }
+        const textures: Record<string, string> = { ...um.textures, _MainTex: um.textures._DetailAlbedoMap }
+        for (const k of Object.keys(textures)) if (/^_(MaskMap|BaseColorMap|NormalMap|BumpMap|MetalicRAOGSmothnessA)\d*$/.test(k)) delete textures[k]
+        if (um.textures._DetailNormalMap) textures._BumpMap = um.textures._DetailNormalMap
+        if (um.textures._DetailMetalicRAOGSmothnessA) textures._MetalicRAOGSmothnessA = um.textures._DetailMetalicRAOGSmothnessA
+        const floats = { ...um.floats, _BumpScale: um.floats._DetailNormalMapScale ?? um.floats._BumpScale ?? 1 }
+        return { set: 2, st: um.tiling?._DetailAlbedoMap ?? [ 1, 1, 0, 0 ], um: { ...um, textures, floats } }
+      })()
+      this.detailCache.set(um.file, p)
+    }
+    return p
+  }
+
+  /** The part's mesh inside the kind's document, wearing the part's materials: one Mesh per (mesh,
+   *  material list) — parts sharing a mesh with other materials get a clone. */
+  private async partMesh(part: KindPart, src: FbxSource, found: Mesh, out: KindDoc): Promise<Mesh> {
+    let map = out.merged.get(part.mesh.guid)
+    if (!map) {
+      map = mergeDocuments(out.doc, src.doc) as Map<unknown, unknown>
+      out.merged.set(part.mesh.guid, map)
+      for (const n of src.doc.getRoot().listNodes()) { const t = map.get(n) as Node | undefined; if (t) out.imported.add(t) }
+    }
+    const meshId = `${part.mesh.guid}:${part.mesh.fileID}:`
+    const key = meshId + part.materials.join(",")
+    let mesh = out.meshes.get(key)
+    if (!mesh) {
+      const base = map.get(found) as Mesh
+      mesh = [ ...out.meshes.keys() ].some((k) => k.startsWith(meshId)) ? base.clone() : base
+      await this.assignMaterials(mesh, part, src, out)
+      out.meshes.set(key, mesh)
+    }
+    return mesh
+  }
+
+  /** Primitives whose material samples TRIPLANAR (a Shader Graph, triplanar.ts) get the projection baked
+   *  into their UVs. The UVs depend on the part's matrix, so such a mesh becomes this part's own copy. */
+  private triplanarUVs(mesh: Mesh, matrix: Mat4, out: KindDoc): Mesh {
+    const refOf = new Map<Material, string>()
+    for (const [ ref, gm ] of out.materials) refOf.set(gm, ref)
+    const plan = mesh.listPrimitives().map((p) => {
+      // the cache key may carry the detail-layer suffix (assignMaterials) — the .mat is the ref before it
+      const ref = p.getMaterial() ? refOf.get(p.getMaterial()!)?.split("\u0000")[0] : undefined
+      const um = ref ? this.material(ref) : null
+      return um ? triplanarOf(um, this.ctx.resolver) : null
+    })
+    if (!plan.some(Boolean)) return mesh
+    const own = out.doc.createMesh(mesh.getName())
+    mesh.listPrimitives().forEach((p, i) => {
+      const t = plan[i]
+      const q = t ? p.clone() : p
+      if (t) projectTriplanar(out.doc, q, t.space === "object" ? I4() : matrix, t.tile)
+      own.addPrimitive(q)
+    })
+    return own
+  }
+
+  async build(kind: SceneKind): Promise<{ doc: Document, parts: number, missing: string[] }> {
+    const doc = quiet(new Document())
+    doc.createBuffer()
+    const scene = doc.createScene(kind.name)
+    const root = doc.createNode(kind.name)
+    scene.addChild(root)
+    const out: KindDoc = { doc, writer: unityMaterialWriter(doc, this.ctx.resolver), merged: new Map(), imported: new Set(), materials: new Map(), meshes: new Map() }
+    const missing: string[] = []
+    let parts = 0
+    for (const part of kind.parts) {
+      const where = part.path || kind.name
+      const src = await this.source(part.mesh.guid)
+      if (!src) { missing.push(`${where}: mesh file ${part.mesh.guid}`); continue }
+      const hit = this.meshFor(src, part.mesh.fileID, part.path.split("/").pop() || undefined, kind.name)
+      if (!hit) { missing.push(`${where}: mesh ${src.meta.names.get(part.mesh.fileID) ?? part.mesh.fileID} not in ${basename(src.path)}`); continue }
+      // A MESH WITH NO VERTICES IS NOT A MESH. Packs ship them — the Modular Shooting Range's floor
+      // stripes carry five LOD levels of which the last is empty — and writing one out is not merely
+      // wasteful: filament's gltfio walks the primitive in `ResourceLoader::loadResources` and takes
+      // the whole host down with an access violation, before a single frame. Skipped like a missing
+      // mesh, and reported, because a silently thinner LOD chain is its own bug.
+      if (!hit.mesh.listPrimitives().some((p) => (p.getAttribute("POSITION")?.getCount() ?? 0) > 0)) {
+        missing.push(`${where}: mesh "${hit.mesh.getName() || "?"}" has no vertices — skipped`)
+        continue
+      }
+      let mesh = await this.partMesh(part, src, hit.mesh, out)
+      // Unity bakes the geometric transform into the mesh, THEN scales it: part · S(globalScale) · helper
+      const m = mmul(mmul(part.matrix, scaleMatrix(src.meta.globalScale)), hit.local)
+      mesh = this.triplanarUVs(mesh, m, out)
+      root.addChild(doc.createNode(partNodeName(part, kind.name)).setMesh(mesh).setMatrix(m as never))
+      parts++
+    }
+    // the FBX's further UV sets were shader inputs (read for the detail layer above); TEXCOORD_1 is the lightmap set
+    for (const m of doc.getRoot().listMeshes()) for (const p of m.listPrimitives()) for (const k of [ 1, 2, 3 ]) { const a = p.getAttribute(`TEXCOORD_${k}`); if (a) { p.setAttribute(`TEXCOORD_${k}`, null); if (a.listParents().length <= 1) a.dispose() } }
+    // drop everything the FBX documents brought besides the meshes / materials we used
+    for (const s of doc.getRoot().listScenes()) if (s !== scene) s.dispose()
+    for (const n of out.imported) n.dispose()
+    await doc.transform(prune({ keepLeaves: false }))
+    // ONE BUFFER. `mergeDocuments` brings each source FBX's own buffer along, so a kind whose parts
+    // come from SEVERAL model files ends up with several — and a GLB may hold at most one, which
+    // glTF-Transform reports as "GLB must have 0-1 buffers" from inside writeBinary. The school's
+    // kinds each drew from a single FBX and never hit it; Chernobyl assembles prefabs out of parts
+    // from different models and dies partway through the level.
+    const buffers = doc.getRoot().listBuffers()
+    if (buffers.length > 1) {
+      const keep = buffers[0]
+      for (const a of doc.getRoot().listAccessors()) a.setBuffer(keep)
+      for (const b of buffers.slice(1)) b.dispose()
+    }
+    return { doc, parts, missing }
+  }
+}