lecodes-assets 0.2.0 → 2.4.10

package/src/unity/materials.ts

@@ -0,0 +1,198 @@
+// Unity materials as the texture source of truth for an FBX conversion.
+//
+// An FBX exported for Unity usually references only a base colour (often a legacy file name) and a
+// normal map; the real shading inputs live in the Unity `.mat` next to it — metallic, roughness /
+// smoothness, occlusion (separate maps or an ORM / MaskMap / MetallicGloss pack), emission, and the
+// alpha mode. Textures are referenced by GUID, resolved through a `unity-index.txt` (written by
+// `lecodes assets unpack`) or the `.meta` sidecars of a real Unity project (guid.ts).
+//
+// What this does: for every FBX material, find the `.mat` of the same name (modulo M_/MI_/MAT_
+// prefixes; matFile.ts reads it, a BINARY one through the pack's texture naming convention), and
+// rewrite the glTF material from it (materialWriter.ts). `.mat` files are also looked up across the
+// whole unpacked package through `unity-index.txt`: packs keep shared materials (asphalt, concrete)
+// in a Textures/ tree far from the FBX that uses them. Then the material overrides of the `.prefab`
+// files around the FBX are honoured (prefabs.ts).
+
+import { existsSync } from "node:fs"
+import { basename, dirname, resolve } from "node:path"
+import type { Document, Material, Mesh, Node } from "@gltf-transform/core"
+import { findUnityIndex, guidOfPath, indexedMaterialFiles, resolverFromIndex, resolverFromMeta, type GuidResolver } from "./guid"
+import { collectUnityMaterials, materialKey, type UnityMaterial } from "./matFile"
+import { SLOTS, pick, unityMaterialWriter, type Warn } from "./materialWriter"
+import { collectPrefabOverrides, type PrefabOverride } from "./prefabs"
+
+export type ApplyUnityOptions = {
+  /** Folder(s) to look for `.mat` files in (default: the FBX's folder and its parent, recursively). */
+  materialDirs?: string[]
+  /** `unity-index.txt` to resolve GUIDs with (default: found walking up from the FBX; else `.meta` sidecars). */
+  indexFile?: string
+  /** Honour the material overrides of the `.prefab` files around the FBX (default true) — packs assign
+   *  the real material on the prefab's MeshRenderer and leave the FBX with placeholders. */
+  prefabs?: boolean
+  /** Folders to read `.prefab` files from (default: the FBX's folder and its parent, 3 deep). */
+  prefabDirs?: string[]
+  warn?: Warn
+}
+
+export type ApplyUnityReport = {
+  /** glTF material name → what was applied (slots[0] notes a non-exact match). */
+  applied: { material: string, mat: string, slots: string[] }[]
+  unmatched: string[]
+  binary: string[]
+  /** Binary .mat files whose slots were inferred from their sibling textures. */
+  inferred: string[]
+  /** Nodes re-materialed from a prefab's MeshRenderer (slots listed once per distinct .mat). */
+  overrides: { node: string, mat: string, slots: string[] }[]
+  resolver: string | null
+}
+
+/** Rewrite the Document's materials from the Unity `.mat` files that match them by name. */
+export const applyUnityMaterials = async (doc: Document, fbxPath: string, opts: ApplyUnityOptions = {}): Promise<ApplyUnityReport> => {
+  const warn = opts.warn ?? (() => {})
+  const fbxDir = dirname(resolve(fbxPath))
+  const report: ApplyUnityReport = { applied: [], unmatched: [], binary: [], inferred: [], overrides: [], resolver: null }
+  // Only a Unity CONTEXT makes the .mat scan worthwhile: an unpacked package (unity-index.txt above
+  // the FBX) or a real Unity project (the FBX's own .meta sidecar). Without one the scan of the parent
+  // folder only finds unrelated projects' materials (a Mixamo folder next to a Unity export) and the
+  // .meta resolver would crawl a whole home directory looking for `Assets`.
+  const indexFile = opts.indexFile ?? findUnityIndex(fbxDir)
+  const inProject = existsSync(fbxPath + ".meta")
+  if (!indexFile && !inProject && !opts.materialDirs) return report
+  const dirs = opts.materialDirs ?? [ fbxDir, dirname(fbxDir) ]
+  // the FBX's neighbourhood first (wins on a name clash), then every .mat the package index lists
+  const { byKey, byFile, binary, inferred } = collectUnityMaterials(dirs, 6, indexFile ? indexedMaterialFiles(indexFile) : [])
+  report.binary = binary
+  report.inferred = inferred
+  const mats = doc.getRoot().listMaterials()
+  if (byKey.size === 0) return report
+
+  let resolver: GuidResolver | null = indexFile ? resolverFromIndex(indexFile) : null
+  if (!resolver && (inProject || opts.materialDirs)) resolver = resolverFromMeta(fbxDir)
+  // inferred materials reference files directly — they need no GUID resolver
+  if (!resolver && inferred.length) resolver = { source: "inferred from sibling textures", resolve: () => null }
+  if (!resolver) {
+    warn({ level: "warn", message: `Unity materials found but no way to resolve their texture GUIDs — need a unity-index.txt (lecodes assets unpack) above the FBX or the .meta sidecars of a Unity project` })
+    return report
+  }
+  report.resolver = resolver.source
+
+  // name matching: exact (modulo prefixes) → one key contains the other (MI_Tshirt ↔ M_Shirt) → the
+  // FBX material's base texture and a .mat's base slot point at the same file (MI_Skin ↔ M_Body via
+  // TX_Body_BaseColor) — packs rename materials freely but rarely duplicate a texture
+  const allMats = [ ...new Set(byKey.values()) ]
+  const stemOf = (f: string): string => basename(f).replace(/\.[^.]+$/, "").toLowerCase()
+  const matByStem = new Map<string, UnityMaterial>()
+  for (const um of allMats) {
+    const g = pick(um, SLOTS.base)
+    const f = g ? resolver.resolve(g) : null
+    if (f && !matByStem.has(stemOf(f))) matByStem.set(stemOf(f), um)
+  }
+  const matchMaterial = (gm: Material): { um: UnityMaterial, how: string } | null => {
+    const k = materialKey(gm.getName())
+    const exact = byKey.get(k)
+    if (exact) return { um: exact, how: "name" }
+    if (k.length >= 4) {
+      const part = allMats.find((um) => { const mk = materialKey(um.name); return mk.length >= 4 && (mk.includes(k) || k.includes(mk)) })
+      if (part) return { um: part, how: `name ~ ${part.name}` }
+    }
+    const base = gm.getBaseColorTexture()
+    const stem = base ? stemOf(base.getName() || base.getURI() || "") : ""
+    const byTex = stem ? matByStem.get(stem) : undefined
+    if (byTex) return { um: byTex, how: `base texture ${stem}` }
+    return null
+  }
+
+  const { applyTo } = unityMaterialWriter(doc, resolver, warn)
+
+  const appliedFrom = new Map<Material, string>()
+  for (const gm of mats) {
+    const hit = matchMaterial(gm)
+    if (!hit) { report.unmatched.push(gm.getName()); continue }
+    const slots = await applyTo(gm, hit.um, hit.how)
+    appliedFrom.set(gm, hit.um.file)
+    report.applied.push({ material: gm.getName(), mat: basename(hit.um.file), slots })
+  }
+
+  // prefab overrides: a prefab's MeshRenderer names the real material for a node whose FBX material
+  // is a placeholder ("17 - Default"). Only prefabs showing THIS FBX's mesh count (by GUID, when the
+  // index knows the FBX). The override is applied per primitive; a mesh shared by several nodes
+  // takes the first node's override.
+  if (opts.prefabs !== false && resolver.source !== "inferred from sibling textures") {
+    const fbxGuid = indexFile ? guidOfPath(indexFile, fbxPath) : null
+    const overrides = collectPrefabOverrides(opts.prefabDirs ?? [ fbxDir, dirname(fbxDir) ])
+      .filter((o) => !fbxGuid || !o.meshGuid || o.meshGuid === fbxGuid)
+    const byNode = new Map<string, PrefabOverride>()
+    for (const o of overrides) if (!byNode.has(o.node)) byNode.set(o.node, o)
+    const matCache = new Map<string, Material>()
+    // the FBX importer hangs the mesh on an unnamed child of the named node — take the subtree
+    const meshesUnder = (n: Node): Mesh[] => {
+      const out: Mesh[] = []
+      const walk = (x: Node): void => { const m = x.getMesh(); if (m) out.push(m); x.listChildren().forEach(walk) }
+      walk(n)
+      return out
+    }
+    const targets: [ Node, PrefabOverride ][] = []
+    for (const node of doc.getRoot().listNodes()) { const o = byNode.get(node.getName()); if (o) targets.push([ node, o ]) }
+    // a SINGLE-mesh prop whose prefab GameObject is named after the prefab, not the FBX node
+    // (`P_stone_fence` showing `stone_fence_LP.014`): no name matches, but the prefab names THIS FBX
+    // by GUID and there is only one mesh it could mean. The prefab named like the FBX wins over
+    // its variants (`P_Tent_1` over `P_Tent_1B`).
+    if (!targets.length && fbxGuid) {
+      const meshNodes = doc.getRoot().listNodes().filter((n) => n.getMesh())
+      const mine = overrides.filter((o) => o.meshGuid === fbxGuid)
+      if (meshNodes.length === 1 && mine.length) {
+        const stem = basename(fbxPath).replace(/\.fbx$/i, "").toLowerCase()
+        const o = mine.find((x) => basename(x.prefab, ".prefab").toLowerCase().replace(/^p_/, "") === stem) ?? mine[0]!
+        targets.push([ meshNodes[0]!, o ])
+      }
+    }
+    for (const [ node, o ] of targets) {
+      const prims = meshesUnder(node).flatMap((m) => m.listPrimitives())
+      for (let i = 0; i < prims.length; i++) {
+        const g = o.materials[i]
+        if (!g) continue
+        const matFile = resolver.resolve(g)
+        if (!matFile) continue
+        // by PATH first — the GUID named one exact .mat, and the name key cannot tell
+        // `Materials/M_VP_01.mat` from the FBX's placeholder `Assets/Materials/MI_VP_01.mat`
+        const um = byFile.get(resolve(matFile)) ?? byKey.get(materialKey(basename(matFile, ".mat")))
+        if (!um) continue
+        const current = prims[i].getMaterial()
+        if (current && appliedFrom.get(current) === um.file) continue   // the FBX material already matched this .mat
+        let gm = matCache.get(um.file)
+        if (!gm) {
+          gm = doc.createMaterial(um.name)
+          const slots = await applyTo(gm, um, "name")
+          matCache.set(um.file, gm)
+          appliedFrom.set(gm, um.file)
+          report.overrides.push({ node: node.getName(), mat: basename(um.file), slots })
+        } else report.overrides.push({ node: node.getName(), mat: basename(um.file), slots: [] })
+        prims[i].setMaterial(gm)
+      }
+    }
+  }
+  return report
+}
+
+/** Drop textures no material references any more (the FBX's legacy ones after a .mat rewrite). */
+export const pruneUnusedTextures = (doc: Document): number => {
+  let n = 0
+  for (const t of doc.getRoot().listTextures()) {
+    if (t.listParents().every((p) => p.propertyType === "Root")) { t.dispose(); n++ }
+  }
+  return n
+}
+
+export const describeUnityReport = (r: ApplyUnityReport): string[] => {
+  const lines: string[] = []
+  for (const a of r.applied) lines.push(`🎨 ${a.material} ← ${a.mat}: ${a.slots.join(", ") || "(no changes)"}`)
+  const byMat = new Map<string, { nodes: string[], slots: string[] }>()
+  for (const o of r.overrides) { const e = byMat.get(o.mat) ?? { nodes: [], slots: [] }; e.nodes.push(o.node); if (o.slots.length) e.slots = o.slots; byMat.set(o.mat, e) }
+  for (const [ mat, e ] of byMat) lines.push(`🎨 prefab override ← ${mat}: ${e.slots.join(", ") || "(shared)"} — ${e.nodes.length} node${e.nodes.length === 1 ? "" : "s"} (${e.nodes.slice(0, 4).join(", ")}${e.nodes.length > 4 ? ", …" : ""})`)
+  if (r.unmatched.length && r.applied.length) lines.push(`ℹ no Unity material for: ${r.unmatched.join(", ")} (FBX references kept)`)
+  const skipped = r.binary.filter((b) => !r.inferred.includes(b))
+  if (r.inferred.length) lines.push(`ℹ ${r.inferred.length} binary-serialised .mat file(s) read by texture naming convention (slots inferred from the files next to them)`)
+  if (skipped.length) lines.push(`ℹ ${skipped.length} binary-serialised .mat file(s) skipped — no textures named after them (Unity: Edit ▸ Project Settings ▸ Editor ▸ Asset Serialization = Force Text) — e.g. ${basename(skipped[0])}`)
+  return lines
+}
+

package/src/unity/math.ts

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

package/src/unity/png.ts

@@ -0,0 +1,75 @@
+// Minimal PNG decoder — 8-bit (and 16-bit, truncated) grey / grey+alpha / RGB / RGBA / palette,
+// non-interlaced, all five scanline filters. Enough for every texture a game asset pack ships, so
+// ORM packing does not need `sharp` (an optional native dependency). Interlaced or <8-bit images
+// return null and the caller falls back to sharp / a warning.
+
+import { inflateSync } from "node:zlib"
+import type { Rgba } from "../textures/resolveImage"
+
+const u32 = (b: Uint8Array, o: number): number => ((b[o] << 24) | (b[o + 1] << 16) | (b[o + 2] << 8) | b[o + 3]) >>> 0
+
+export const decodePng = (b: Uint8Array): Rgba | null => {
+  if (b.length < 33 || b[0] !== 0x89 || b[1] !== 0x50 || b[2] !== 0x4e || b[3] !== 0x47) return null
+  let o = 8
+  let width = 0, height = 0, depth = 0, color = 0, interlace = 0
+  const idat: Uint8Array[] = []
+  let palette: Uint8Array | null = null
+  let trns: Uint8Array | null = null
+  while (o + 8 <= b.length) {
+    const len = u32(b, o)
+    const type = String.fromCharCode(b[o + 4], b[o + 5], b[o + 6], b[o + 7])
+    const data = b.subarray(o + 8, o + 8 + len)
+    if (type === "IHDR") { width = u32(data, 0); height = u32(data, 4); depth = data[8]; color = data[9]; interlace = data[12] }
+    else if (type === "PLTE") palette = data
+    else if (type === "tRNS") trns = data
+    else if (type === "IDAT") idat.push(data)
+    else if (type === "IEND") break
+    o += 12 + len
+  }
+  if (!width || !height || interlace !== 0 || (depth !== 8 && depth !== 16)) return null
+  const channels = color === 0 ? 1 : color === 2 ? 3 : color === 3 ? 1 : color === 4 ? 2 : color === 6 ? 4 : 0
+  if (!channels) return null
+  const bps = depth / 8
+  const bpp = channels * bps                      // bytes per pixel (filter unit)
+  const stride = width * bpp
+  let raw: Uint8Array
+  try {
+    const total = idat.reduce((n, c) => n + c.length, 0)
+    const joined = new Uint8Array(total)
+    let p = 0
+    for (const c of idat) { joined.set(c, p); p += c.length }
+    raw = new Uint8Array(inflateSync(joined))
+  } catch { return null }
+  if (raw.length < (stride + 1) * height) return null
+  const out = new Uint8Array(width * height * 4)
+  const prev = new Uint8Array(stride)
+  const cur = new Uint8Array(stride)
+  for (let y = 0; y < height; y++) {
+    const f = raw[y * (stride + 1)]
+    const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1))
+    for (let x = 0; x < stride; x++) {
+      const a = x >= bpp ? cur[x - bpp] : 0
+      const bb = prev[x]
+      const c = x >= bpp ? prev[x - bpp] : 0
+      let v = line[x]
+      if (f === 1) v += a
+      else if (f === 2) v += bb
+      else if (f === 3) v += (a + bb) >> 1
+      else if (f === 4) { const p = a + bb - c; const pa = Math.abs(p - a), pb = Math.abs(p - bb), pc = Math.abs(p - c); v += pa <= pb && pa <= pc ? a : pb <= pc ? bb : c }
+      cur[x] = v & 0xff
+    }
+    for (let x = 0; x < width; x++) {
+      const s = x * bpp, d = (y * width + x) * 4
+      if (color === 3) {
+        const i = cur[s]
+        out[d] = palette ? palette[i * 3] : i; out[d + 1] = palette ? palette[i * 3 + 1] : i; out[d + 2] = palette ? palette[i * 3 + 2] : i
+        out[d + 3] = trns && i < trns.length ? trns[i] : 255
+      } else if (channels === 1) { out[d] = out[d + 1] = out[d + 2] = cur[s]; out[d + 3] = 255 }
+      else if (channels === 2) { out[d] = out[d + 1] = out[d + 2] = cur[s]; out[d + 3] = cur[s + bps] }
+      else if (channels === 3) { out[d] = cur[s]; out[d + 1] = cur[s + bps]; out[d + 2] = cur[s + 2 * bps]; out[d + 3] = 255 }
+      else { out[d] = cur[s]; out[d + 1] = cur[s + bps]; out[d + 2] = cur[s + 2 * bps]; out[d + 3] = cur[s + 3 * bps] }
+    }
+    prev.set(cur)
+  }
+  return { width, height, data: out }
+}

package/src/unity/prefabTree.ts

@@ -0,0 +1,285 @@
+// Unity GameObject trees out of text-serialised `.prefab` / `.unity` files, with NESTED prefab
+// instances expanded and their modifications applied — what the Unity editor shows in its hierarchy.
+//
+// A file's objects are GameObjects + components (Transform, MeshFilter, MeshRenderer, LODGroup,
+// colliders, Light …) wired by fileID, plus `PrefabInstance` objects that stand for a whole other
+// prefab. Expanding an instance = a CLONE of the source prefab's tree, its `m_Modifications` applied
+// to the cloned objects (a property path on the object the target fileID names in the source
+// prefab), parented under `m_TransformParent`. Objects of the outer file that hang on the instance
+// (a child GameObject parented to one of its transforms, a component added to one of its objects)
+// reference it through STRIPPED stubs: `m_PrefabInstance` + `m_CorrespondingSourceObject` name the
+// object inside the expansion.
+//
+// Ids: inside a prefab ASSET the objects of a nested instance are also addressable under
+// `(instanceFileID XOR sourceFileID) & 0x7FFF…` — how an outer file's modifications reach an object
+// two levels down. Scenes use their own stub ids, resolved through the stub fields.
+//
+// A model file is a prefab too (fbxModel.ts builds its tree).
+
+import { readFileSync } from "node:fs"
+import { MODEL_EXT, modelTree, readModel, type FbxMeta, type ModelInfo } from "./fbxModel"
+import { cloneTree, type Tree, type UComp, type UGO } from "./gameObjects"
+import type { GuidResolver } from "./guid"
+import { readPath, setPath } from "./propertyPath"
+import { isMap, readUnityObjects, ref, str, type Y, type YMap } from "./yaml"
+
+const MASK = (1n << 63n) - 1n
+const xorId = (a: string, b: string): string => ((BigInt(a) ^ BigInt(b)) & MASK).toString()
+
+export type TreeStats = { instances: number, unresolvedMods: number, sceneLocalRefs: number, guessedTransforms: number, missingPrefabs: Set<string>, binaryPrefabs: Set<string> }
+export const newStats = (): TreeStats => ({ instances: 0, unresolvedMods: 0, sceneLocalRefs: 0, guessedTransforms: 0, missingPrefabs: new Set(), binaryPrefabs: new Set() })
+
+const isComp = (o: UGO | UComp): o is UComp => "cls" in o
+const materialSlot = (path: string): number | null => { const m = /^m_Materials\.Array\.data\[(\d+)\]$/.exec(path); return m ? Number(m[1]) : null }
+
+/**
+ * The renderers of an instance whose ids nobody published.
+ *
+ * A MODEL prefab whose `.meta` ships an empty `internalIDToNameTable` publishes no ids for anything
+ * below its root, so our synthesised components get placeholder ones and a prefab that assigns the
+ * MATERIAL — which is how a pack with material-less FBX files does it — cannot address them. Everton
+ * High School is that pack: 56 of its 97 kinds imported with no material at all, silently, because
+ * these modifications found no target.
+ *
+ * The choice is made by SLOT COUNT first: a door's four renderers want 2, 3, 3 and 1 material, and
+ * the two that want 3 carry the same list, so the only choice that matters is unambiguous. Without
+ * a fit, a lone free renderer is taken (one renderer, one target); anything else stays unresolved.
+ */
+class RendererGuess {
+  private guessed = new Map<string, UComp>()
+  /** How many material slots each target wants: the highest `m_Materials.Array.data[N]` it carries, plus one. */
+  private slotsWanted = new Map<string, number>()
+  constructor(private tree: Tree, mods: Y[]) {
+    for (const m of mods) {
+      if (!isMap(m)) continue
+      const slot = materialSlot(str(m.propertyPath))
+      if (slot === null) continue
+      const id = ref(m.target).fileID
+      this.slotsWanted.set(id, Math.max(this.slotsWanted.get(id) ?? 0, slot + 1))
+    }
+  }
+
+  /** The renderer chosen for this unresolvable target — the same one for all its slots. */
+  pick(targetId: string): UComp | undefined {
+    const already = this.guessed.get(targetId)
+    if (already) return already
+    const taken = new Set(this.guessed.values())
+    const free: UComp[] = []
+    for (const v of this.tree.ids.values()) if (isComp(v) && v.cls === "MeshRenderer" && !taken.has(v)) free.push(v)
+    const want = this.slotsWanted.get(targetId) ?? 0
+    const fit = free.filter((r) => (Array.isArray(r.body.m_Materials) ? r.body.m_Materials.length : 0) === want)
+    const pick = fit[0] ?? (free.length === 1 ? free[0] : undefined)
+    if (pick) this.guessed.set(targetId, pick)
+    return pick
+  }
+}
+
+/**
+ * The transforms of an instance whose ids nobody published — matched BY POSITION.
+ *
+ * The same gap as RendererGuess, on the other component: a MODEL prefab whose `.meta` ships an empty
+ * `internalIDToNameTable` publishes no ids below its root, so a placement that nudges one of the
+ * model's CHILDREN (`m_LocalPosition.z` on a node inside the FBX) names an id we cannot address.
+ * Peremena's door frames are one FBX of eight frames, seven of them moved by 5 to 16 cm in the scene
+ * to meet the doors, and without the moves every sideways door stood 15 cm out of its opening.
+ *
+ * An override writes the NEW value of the components it changes, and a nudge keeps the object close
+ * to where the file put it — so each unresolved target is matched to the free Transform whose file
+ * position is nearest over exactly those components. Only when it is unambiguous: within MAX_M, clearly
+ * nearer than the runner-up, and one target per transform. Rotation / scale overrides ride along on a
+ * target the position matched; a target with no position component is left unresolved.
+ */
+export class TransformGuess {
+  private static MAX_M = 0.5
+  private matched = new Map<string, UComp>()
+  constructor(tree: Tree, mods: Y[], resolvable: (id: string, guid: string) => boolean) {
+    const wanted = new Map<string, Record<string, number>>()
+    for (const m of mods) {
+      if (!isMap(m)) continue
+      const t = ref(m.target), hit = /^m_LocalPosition\.([xyz])$/.exec(str(m.propertyPath))
+      if (!hit || resolvable(t.fileID, t.guid ?? "")) continue
+      const v = Number(str(m.value))
+      if (!Number.isFinite(v)) continue
+      const w = wanted.get(t.fileID) ?? {}
+      w[hit[1]] = v
+      wanted.set(t.fileID, w)
+    }
+    if (!wanted.size) return
+    const roots = new Set(tree.roots)
+    const free: { c: UComp, p: Record<string, number> }[] = []
+    for (const v of tree.ids.values()) {
+      if (!isComp(v) || v.cls !== "Transform" || roots.has(v.go)) continue
+      const lp = isMap(v.body.m_LocalPosition) ? v.body.m_LocalPosition : {}
+      free.push({ c: v, p: { x: Number(str(lp.x)) || 0, y: Number(str(lp.y)) || 0, z: Number(str(lp.z)) || 0 } })
+    }
+    const cands: { id: string, c: UComp, d: number }[] = []
+    for (const [ id, w ] of wanted) {
+      const ds = free.map((f) => ({ c: f.c, d: Math.hypot(...Object.entries(w).map(([ k, v ]) => v - f.p[k])) })).sort((a, b) => a.d - b.d)
+      const [ best, next ] = ds
+      if (best && best.d <= TransformGuess.MAX_M && (!next || next.d > best.d * 2 + 0.05)) cands.push({ id, c: best.c, d: best.d })
+    }
+    const taken = new Set<UComp>()
+    for (const k of cands.sort((a, b) => a.d - b.d)) if (!taken.has(k.c)) { taken.add(k.c); this.matched.set(k.id, k.c) }
+  }
+  pick(targetId: string): UComp | undefined { return this.matched.get(targetId) }
+  get count(): number { return this.matched.size }
+}
+
+export class PrefabLoader {
+  private cache = new Map<string, Tree | null>()
+  private models = new Map<string, ModelInfo | null>()
+  constructor(readonly resolver: GuidResolver, readonly stats: TreeStats = newStats()) {}
+
+  /** Read every model file the texts instance (transitively through the prefabs they instance) —
+   *  FBX parsing is async, tree building is not. */
+  async preload(texts: string[], guids: string[] = []): Promise<void> {
+    const seen = new Set<string>()
+    const queue = [ ...guids ]
+    const scan = (t: string): void => { for (const m of t.matchAll(/m_SourcePrefab: \{fileID: \d+, guid: ([0-9a-f]{32})/g)) queue.push(m[1]) }
+    texts.forEach(scan)
+    while (queue.length) {
+      const g = queue.pop()!
+      if (seen.has(g)) continue
+      seen.add(g)
+      const path = this.resolver.resolve(g)
+      if (!path) continue
+      if (MODEL_EXT.test(path)) { if (!this.models.has(g)) this.models.set(g, await readModel(path)); continue }
+      if (/\.prefab$/i.test(path)) { const t = readFileSync(path, "utf8"); if (t.startsWith("%YAML")) scan(t) }
+    }
+  }
+
+  modelMeta(guid: string): FbxMeta | null { return this.models.get(guid)?.meta ?? null }
+
+  /** A fresh (cloned) tree of the prefab asset, or null when it cannot be read. */
+  prefab(guid: string, depth = 0): Tree | null {
+    if (depth > 16) return null
+    let t = this.cache.get(guid)
+    if (t === undefined) {
+      t = this.read(guid, depth)
+      this.cache.set(guid, t)
+    }
+    return t ? cloneTree(t) : null
+  }
+
+  private read(guid: string, depth: number): Tree | null {
+    const path = this.resolver.resolve(guid)
+    if (!path) { this.stats.missingPrefabs.add(guid); return null }
+    if (MODEL_EXT.test(path)) {
+      const info = this.models.get(guid)
+      if (!info) { this.stats.missingPrefabs.add(guid); return null }
+      return modelTree(info, guid)
+    }
+    const text = readFileSync(path, "utf8")
+    if (!text.startsWith("%YAML")) { this.stats.binaryPrefabs.add(path); return null }
+    return this.buildText(text, guid, depth + 1)
+  }
+
+  /** One `m_Modifications` entry onto the cloned tree of the instance it belongs to. */
+  private applyModification(tree: Tree, m: YMap, guess: RendererGuess, placed: TransformGuess): void {
+    const tgt = ref(m.target)
+    const path = str(m.propertyPath)
+    // An override names its target as (guid, fileID) - "object N of THAT asset". Once a prefab is
+    // nested the tree's own ids are XOR-composed, so an override reaching PAST one prefab into
+    // another's object misses by id: a kit whose prefabs are bare wrappers around an FBX puts
+    // EVERY placement's transform there, and the whole level then collapses onto the origin.
+    const target = tree.ids.get(tgt.fileID)
+      ?? (tgt.guid ? tree.bySource.get(`${tgt.guid}:${tgt.fileID}`) : undefined)
+      ?? (path.startsWith("m_Materials") ? guess.pick(tgt.fileID) : undefined)
+      ?? (path.startsWith("m_Local") ? placed.pick(tgt.fileID) : undefined)
+    if (!target) { this.stats.unresolvedMods++; return }
+    // AN OVERRIDE POINTING AT AN OBJECT INSIDE THE SCENE, not at an asset, has nothing an
+    // importer can follow: no GUID, so no file. Mesh painters write exactly that — Polybrush
+    // stores the painted copy of a mesh as a scene-local `!u!43` (`PolybrushMesh…`) and rewrites
+    // the MeshFilter's `m_Mesh` to it. Taking that at face value replaced a real mesh reference
+    // with a dangling one and the part was then dropped in silence: the shooting range's walls
+    // lost 257 of them and nine wall kinds came out of the import with no geometry at all.
+    // The asset reference underneath is the same geometry minus the painted vertex colours, so
+    // 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 }
+    setPath(target.body, path, objRef ?? m.value)
+  }
+
+  /** A `PrefabInstance` object → the source prefab's tree, cloned, with this instance's overrides on it. */
+  private expandInstance(body: YMap, depth: number): { tree: Tree, source: string, parent: string } | null {
+    const source = ref(body.m_SourcePrefab).guid
+    const tree = source ? this.prefab(source, depth) : null
+    if (!source || !tree) return null
+    this.stats.instances++
+    const mod = isMap(body.m_Modification) ? body.m_Modification : {}
+    const mods = Array.isArray(mod.m_Modifications) ? mod.m_Modifications : []
+    const guess = new RendererGuess(tree, mods)
+    const placed = new TransformGuess(tree, mods, (id, guid) => tree.ids.has(id) || (!!guid && tree.bySource.has(`${guid}:${id}`)))
+    this.stats.guessedTransforms += placed.count
+    for (const m of mods) if (isMap(m)) this.applyModification(tree, m, guess, placed)
+    for (const rc of Array.isArray(mod.m_RemovedComponents) ? mod.m_RemovedComponents : []) {
+      const c = tree.ids.get(ref(rc).fileID)
+      if (c && isComp(c)) c.go.comps = c.go.comps.filter((x) => x !== c)
+    }
+    for (const r of tree.roots) r.prefab = source
+    return { tree, source, parent: ref(mod.m_TransformParent).fileID }
+  }
+
+  /** Build the trees of a text-serialised file (a prefab asset or a scene). */
+  buildText(text: string, fileGuid: string | null, depth = 0): Tree {
+    const objs = readUnityObjects(text)
+    const ids = new Map<string, UGO | UComp>()
+    const bySource = new Map<string, UGO | UComp>()
+    /** This file's own objects, to be published under its own GUID once it is known to be an asset. */
+    const own = new Map<string, UGO | UComp>()
+    const reg = (id: string, o: UGO | UComp): void => { ids.set(id, o); own.set(id, o) }
+    const instances = new Map<string, Tree>()
+    const instanceParent = new Map<string, string>()
+
+    // 1. nested prefab instances: clone the source, apply the modifications, expose its objects
+    for (const o of objs) {
+      if (o.cls !== "PrefabInstance" || o.stripped) continue
+      const inst = this.expandInstance(o.body, depth)
+      if (!inst) continue
+      instances.set(o.id, inst.tree)
+      instanceParent.set(o.id, inst.parent)
+      // this file publishes a nested object under Unity's composed id, and an override that
+      // reaches it from further out names exactly that (with THIS file's guid)
+      for (const [ k, v ] of inst.tree.ids) reg(xorId(o.id, k), v)
+      // ...while by SOURCE it stays whatever asset defined it, however deep it now sits
+      for (const [ k, v ] of inst.tree.bySource) if (!bySource.has(k)) bySource.set(k, v)
+    }
+
+    // 2. stripped stubs → the object inside the expansion
+    for (const o of objs) {
+      if (!o.stripped) continue
+      const tree = instances.get(ref(o.body.m_PrefabInstance).fileID)
+      const hit = tree?.ids.get(ref(o.body.m_CorrespondingSourceObject).fileID)
+      if (hit) reg(o.id, hit)
+    }
+
+    // 3. the file's own GameObjects and components
+    for (const o of objs) {
+      if (o.stripped || o.cls !== "GameObject") continue
+      reg(o.id, { id: o.id, body: o.body, comps: [], children: [], parent: null })
+    }
+    const transforms: UComp[] = []
+    for (const o of objs) {
+      if (o.stripped || o.cls === "GameObject" || o.cls === "PrefabInstance") continue
+      const owner = ids.get(ref(o.body.m_GameObject).fileID)
+      if (!owner || isComp(owner)) continue
+      const c: UComp = { cls: o.cls, id: o.id, body: o.body, go: owner }
+      owner.comps.push(c)
+      reg(o.id, c)
+      if (o.cls === "Transform" || o.cls === "RectTransform") transforms.push(c)
+    }
+
+    // 4. parenting: own transforms by m_Father, instance roots by m_TransformParent
+    const roots: UGO[] = []
+    const attach = (child: UGO, parentTransformId: string): void => {
+      const p = parentTransformId !== "0" ? ids.get(parentTransformId) : undefined
+      const pgo = p ? (isComp(p) ? p.go : p) : null
+      if (pgo) { child.parent = pgo; pgo.children.push(child) } else roots.push(child)
+    }
+    for (const t of transforms) attach(t.go, ref(t.body.m_Father).fileID)
+    for (const [ id, tree ] of instances) for (const r of tree.roots) attach(r, instanceParent.get(id) ?? "0")
+    // Unity's child order (m_Children) is cosmetic here; file order is stable enough
+    if (fileGuid) for (const [ k, v ] of own) bySource.set(`${fileGuid}:${k}`, v)
+    return { roots, ids, bySource }
+  }
+}