lecodes-assets 0.2.1 → 2.4.10

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 }
+  }
+}

package/src/unity/prefabs.ts

@@ -6,9 +6,9 @@
 // renders a mesh, which FBX mesh it shows and which material GUIDs its renderer carries, so the
 // converter can re-material the matching glTF node (`applyUnityMaterials`).
 
-import { existsSync, readFileSync, readdirSync } from "node:fs"
-import { join } from "node:path"
-import { parseUnityYaml } from "./scene"
+import { readFileSync } from "node:fs"
+import { walkFiles } from "./guid"
+import { isMap, readUnityObjects, ref } from "./yaml"
 
 export type PrefabOverride = {
   /** The .prefab file. */
@@ -21,11 +21,6 @@ export type PrefabOverride = {
   materials: (string | undefined)[]
 }
 
-type Y = string | Y[] | { [k: string]: Y }
-const isMap = (v: Y | undefined): v is { [k: string]: Y } => typeof v === "object" && v !== null && !Array.isArray(v)
-const guidOf = (v: Y | undefined): string | undefined => (isMap(v) && typeof v.guid === "string" ? v.guid : undefined)
-const idOf = (v: Y | undefined): string => (isMap(v) ? String(v.fileID ?? "0") : "0")
-
 /** Material overrides declared by one text-serialised prefab (empty for binary / non-prefab files). */
 export const readPrefabOverrides = (file: string): PrefabOverride[] => {
   const text = readFileSync(file, "utf8")
@@ -33,22 +28,13 @@ export const readPrefabOverrides = (file: string): PrefabOverride[] => {
   const names = new Map<string, string>()                  // GameObject id → name
   const meshes = new Map<string, string | undefined>()      // GameObject id → mesh guid
   const renderers = new Map<string, (string | undefined)[]>()   // GameObject id → material guids
-  const re = /^--- !u!(\d+) &(-?\d+)( stripped)?\s*$/gm
-  const starts: { idx: number, end: number }[] = []
-  for (let m = re.exec(text); m; m = re.exec(text)) starts.push({ idx: m.index, end: m.index + m[0].length })
-  for (let i = 0; i < starts.length; i++) {
-    const chunk = text.slice(starts[i].end, i + 1 < starts.length ? starts[i + 1].idx : text.length)
-    const doc = parseUnityYaml(chunk)
-    const cls = Object.keys(doc)[0] ?? ""
-    const body = doc[cls]
-    if (!isMap(body)) continue
-    const id = /&(-?\d+)/.exec(text.slice(starts[i].idx, starts[i].end))?.[1] ?? ""
+  for (const { cls, id, body } of readUnityObjects(text)) {
+    const go = ref(body.m_GameObject).fileID
     if (cls === "GameObject" && typeof body.m_Name === "string") names.set(id, body.m_Name)
-    else if (cls === "MeshFilter") meshes.set(idOf(body.m_GameObject), guidOf(body.m_Mesh))
+    else if (cls === "MeshFilter") meshes.set(go, ref(body.m_Mesh).guid)
     else if (cls === "MeshRenderer" || cls === "SkinnedMeshRenderer") {
-      const mats = Array.isArray(body.m_Materials) ? body.m_Materials.map((m) => guidOf(m)) : []
-      renderers.set(idOf(body.m_GameObject), mats)
-      if (cls === "SkinnedMeshRenderer") meshes.set(idOf(body.m_GameObject), guidOf(body.m_Mesh))
+      renderers.set(go, Array.isArray(body.m_Materials) ? body.m_Materials.map((m) => (isMap(m) && typeof m.guid === "string" ? m.guid : undefined)) : [])
+      if (cls === "SkinnedMeshRenderer") meshes.set(go, ref(body.m_Mesh).guid)
     }
   }
   const out: PrefabOverride[] = []
@@ -63,18 +49,6 @@ export const readPrefabOverrides = (file: string): PrefabOverride[] => {
 /** Every `.prefab` under `dirs` (recursive to `depth`), read for overrides. */
 export const collectPrefabOverrides = (dirs: string[], depth = 3): PrefabOverride[] => {
   const files: string[] = []
-  const walk = (dir: string, d: number): void => {
-    if (d < 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.startsWith(".")) walk(p, d - 1) }
-      else if (/\.prefab$/i.test(e.name)) files.push(p)
-    }
-  }
-  for (const d of dirs) walk(d, depth)
-  const out: PrefabOverride[] = []
-  for (const f of [ ...new Set(files) ]) out.push(...readPrefabOverrides(f))
-  return out
+  for (const d of dirs) walkFiles(d, depth, files, (n) => /\.prefab$/i.test(n))
+  return [ ...new Set(files) ].flatMap(readPrefabOverrides)
 }

package/src/unity/propertyPath.ts

@@ -0,0 +1,43 @@
+// Unity's serialized property paths (`m_LocalPosition.x`, `m_Materials.Array.data[1]`) on a raw
+// YAML body — what a PrefabInstance's `m_Modifications` are written in.
+
+import { isMap, num, type Y, type YMap } from "./yaml"
+
+/** Read what a dotted property path currently holds (the mirror of `setPath`), so an override can be
+ *  compared with what it would replace. Undefined when any step is missing. */
+export const readPath = (body: YMap, path: string): Y | undefined => {
+  let cur: Y | undefined = body
+  for (const p of path.split(".")) {
+    if (!isMap(cur)) return undefined
+    cur = cur[p]
+  }
+  return cur
+}
+
+/** `m_LocalPosition.x`, `m_Materials.Array.data[1]`, `m_Materials.Array.size`, `m_Size.y` … */
+export const setPath = (body: YMap, path: string, value: Y | undefined): void => {
+  if (!path || value === undefined) return
+  const parts = path.split(".")
+  let cur: Y = body
+  for (let i = 0; i < parts.length; i++) {
+    const p = parts[i]
+    const last = i === parts.length - 1
+    if (p === "Array" && Array.isArray(cur)) continue
+    const arr = /^data\[(\d+)\]$/.exec(p)
+    if (arr && Array.isArray(cur)) {
+      const k = +arr[1]
+      if (last) { cur[k] = value; return }
+      if (cur[k] === undefined || typeof cur[k] !== "object") cur[k] = {}
+      cur = cur[k]
+      continue
+    }
+    if (p === "size" && Array.isArray(cur) && last) { cur.length = Math.max(0, num(value as Y, cur.length)); return }
+    if (!isMap(cur)) return
+    if (last) { cur[p] = value; return }
+    let next: Y | undefined = cur[p]
+    // an array field addressed as `field.Array.…` — make sure it is one
+    if (parts[i + 1] === "Array" && !Array.isArray(next)) { next = []; cur[p] = next }
+    else if (next === undefined || typeof next !== "object") { next = {}; cur[p] = next }
+    cur = next
+  }
+}