lecodes-assets 0.2.1 → 2.4.10

package/src/unity/colliderFit.ts

@@ -0,0 +1,287 @@
+// DOES A PACK'S BOX COLLIDER SIT ON THE GEOMETRY IT COVERS?
+//
+// A Unity pack authors its own colliders, and for anything but a crate they are an approximation:
+// the Modular Shooting Range's wall module is flat at ±0.100 m and only its edge trim reaches the
+// ±0.138 m its box collider was fitted to, so the box's face floats 3.8 cm in front of the wall the
+// player sees. Everything that lands ON the hit point then lands in mid-air: a bullet stops short,
+// its impact particles hang off the surface, and a projected decal (fps-demo's bullet holes, box
+// depth ±3 cm) never reaches the wall at all — the hole is simply not there. The same pack's TABLE,
+// by contrast, carries five hand-placed boxes that hug the top, the side panels and the brackets,
+// and swapping those for a mesh would buy nothing.
+//
+// So the verdict is per KIND and it is measured, not guessed: shoot a grid of rays from each box
+// face inward and look at what they meet.
+//
+//   • gap     — the median distance from the face to the first surface under it. The face is a lie
+//               by this much: 0 on a crate, 0.038 on that wall module.
+//   • covered — the share of the face's samples that meet anything at all inside the box. A face
+//               over a void (the ceiling-panel box, 6 m of air under its underside) is the worst
+//               case of the same fault, so it counts as a miss whatever its gap.
+//
+// A kind whose every box passes keeps its boxes (cheap, and a convex box is the better collider for
+// a character to slide along); one box failing sends the whole kind to a mesh collider, since a mix
+// would collide twice. A mesh shape is built once per GLB and shared by every placement
+// (creator-gl physicsBuildMeshFromEntity caches per asset), so the cost is per kind, not per copy.
+
+/** One box as the prefab file will spell it: the node's frame plus the Shape's own half extents and origin. */
+export type FitBox = {
+  /** Shape `box` — half extents along the box's own axes. */
+  half: [number, number, number]
+  /** Shape `origin` — the box's centre in the node's frame. */
+  origin: [number, number, number]
+  /** The collider node's translation in the kind's frame. */
+  t: [number, number, number]
+  /** The collider node's rotation (quaternion xyzw). */
+  rot: [number, number, number, number]
+}
+
+export type FitTriangles = { positions: Float32Array, indices: Uint32Array }
+
+export type FaceFit = {
+  /** "x+", "y-", … — which face of which box (`box` is its index in the kind's list). */
+  face: string
+  box: number
+  /** Metres from the face to the surface under it (median over the samples that met one). */
+  gap: number
+  /** 0…1 share of the face's samples that met a surface inside the box. */
+  covered: number
+}
+
+export type FitVerdict = {
+  /** true = the boxes lie, give the kind a mesh collider. */
+  mesh: boolean
+  /** The face that decided it (the worst one), or null when there was nothing to measure. */
+  worst: FaceFit | null
+  faces: FaceFit[]
+}
+
+export type FitOptions = {
+  /** Metres a box face may stand off the surface under it (default 0.015). */
+  tolerance?: number
+  /** Least share of a face's samples that must meet a surface (default 0.25). */
+  minCovered?: number
+  /** Rays per face edge (default 8 → 64 samples a face). */
+  samples?: number
+}
+
+const EPS = 1e-9
+
+/** Rotate `v` by the quaternion `q` (xyzw). */
+const rotate = (q: readonly number[], v: readonly number[]): [number, number, number] => {
+  const [ x, y, z, w ] = q
+  const tx = 2 * (y * v[2] - z * v[1]), ty = 2 * (z * v[0] - x * v[2]), tz = 2 * (x * v[1] - y * v[0])
+  return [
+    v[0] + w * tx + (y * tz - z * ty),
+    v[1] + w * ty + (z * tx - x * tz),
+    v[2] + w * tz + (x * ty - y * tx),
+  ]
+}
+
+/** …by its inverse. */
+const unrotate = (q: readonly number[], v: readonly number[]): [number, number, number] =>
+  rotate([ -q[0], -q[1], -q[2], q[3] ], v)
+
+/** Möller–Trumbore: the ray's distance to the triangle, or -1. Both sides count — a one-sided test
+ *  would miss a wall whose back face is the one inside the box. */
+const rayTriangle = (
+  ox: number, oy: number, oz: number, dx: number, dy: number, dz: number,
+  ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number,
+): number => {
+  const e1x = bx - ax, e1y = by - ay, e1z = bz - az
+  const e2x = cx - ax, e2y = cy - ay, e2z = cz - az
+  const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x
+  const det = e1x * px + e1y * py + e1z * pz
+  if (det > -EPS && det < EPS) return -1
+  const inv = 1 / det
+  const tx = ox - ax, ty = oy - ay, tz = oz - az
+  const u = (tx * px + ty * py + tz * pz) * inv
+  if (u < -1e-6 || u > 1 + 1e-6) return -1
+  const qx = ty * e1z - tz * e1y, qy = tz * e1x - tx * e1z, qz = tx * e1y - ty * e1x
+  const v = (dx * qx + dy * qy + dz * qz) * inv
+  if (v < -1e-6 || u + v > 1 + 1e-6) return -1
+  return (e2x * qx + e2y * qy + e2z * qz) * inv
+}
+
+/** How well one box covers the geometry: a FaceFit per face, worst first. */
+export const boxFit = (tris: FitTriangles, box: FitBox, opts: FitOptions = {}): FaceFit[] => {
+  const n = Math.max(2, opts.samples ?? 8)
+  const centre: [number, number, number] = [
+    box.t[0] + rotate(box.rot, box.origin)[0],
+    box.t[1] + rotate(box.rot, box.origin)[1],
+    box.t[2] + rotate(box.rot, box.origin)[2],
+  ]
+  // the triangles in the BOX's frame, keeping only those that reach inside it (a 1 cm skin, so a
+  // surface sitting exactly on a face still counts)
+  const h = box.half
+  const keep: number[] = []
+  const P = tris.positions, I = tris.indices
+  const v = new Float32Array(9)
+  for (let i = 0; i + 2 < I.length; i += 3) {
+    let inside = false
+    const lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+    for (let k = 0; k < 3; k++) {
+      const j = I[i + k] * 3
+      const p = unrotate(box.rot, [ P[j] - centre[0], P[j + 1] - centre[1], P[j + 2] - centre[2] ])
+      v[k * 3] = p[0]; v[k * 3 + 1] = p[1]; v[k * 3 + 2] = p[2]
+      for (let a = 0; a < 3; a++) { lo[a] = Math.min(lo[a], p[a]); hi[a] = Math.max(hi[a], p[a]) }
+    }
+    inside = [ 0, 1, 2 ].every((a) => hi[a] >= -h[a] - 0.01 && lo[a] <= h[a] + 0.01)
+    if (inside) for (let k = 0; k < 9; k++) keep.push(v[k])
+  }
+  const T = Float32Array.from(keep)
+
+  const out: FaceFit[] = []
+  for (let axis = 0; axis < 3; axis++) {
+    for (const sign of [ 1, -1 ] as const) {
+      const u = (axis + 1) % 3, w = (axis + 2) % 3
+      const depth = 2 * h[axis]
+      if (depth <= 0) continue
+      const hits: number[] = []
+      let total = 0
+      for (let a = 0; a < n; a++) {
+        for (let b = 0; b < n; b++) {
+          // inset, so a ray does not graze the box's own rim
+          const fu = ((a + 0.5) / n - 0.5) * 2 * 0.9, fw = ((b + 0.5) / n - 0.5) * 2 * 0.9
+          const o = [ 0, 0, 0 ]
+          o[axis] = sign * h[axis]; o[u] = fu * h[u]; o[w] = fw * h[w]
+          const d = [ 0, 0, 0 ]; d[axis] = -sign
+          total++
+          let best = Infinity
+          for (let i = 0; i + 8 < T.length; i += 9) {
+            const t = rayTriangle(o[0], o[1], o[2], d[0], d[1], d[2],
+              T[i], T[i + 1], T[i + 2], T[i + 3], T[i + 4], T[i + 5], T[i + 6], T[i + 7], T[i + 8])
+            if (t >= -1e-4 && t < best && t <= depth + 1e-4) best = Math.max(0, t)
+          }
+          if (best < Infinity) hits.push(best)
+        }
+      }
+      hits.sort((x, y) => x - y)
+      const gap = hits.length ? hits[Math.floor(hits.length / 2)] : depth
+      out.push({ face: "xyz"[axis] + (sign > 0 ? "+" : "-"), box: 0, gap, covered: total ? hits.length / total : 0 })
+    }
+  }
+  return out
+}
+
+/** The kind's verdict over all of its boxes. */
+export const fitVerdict = (tris: FitTriangles | null, boxes: FitBox[], opts: FitOptions = {}): FitVerdict => {
+  const tol = opts.tolerance ?? 0.015
+  const minCovered = opts.minCovered ?? 0.25
+  if (!tris || tris.indices.length === 0 || boxes.length === 0) return { mesh: false, worst: null, faces: [] }
+  const faces: FaceFit[] = []
+  boxes.forEach((b, i) => { for (const f of boxFit(tris, b, opts)) faces.push({ ...f, box: i }) })
+  // the worst face: how badly it fails (a face over a void fails by its whole depth)
+  const bad = (f: FaceFit): boolean => f.covered < minCovered || f.gap > tol
+  const failing = faces.filter(bad)
+  failing.sort((a, b) => b.gap - a.gap)
+  return { mesh: failing.length > 0, worst: failing[0] ?? null, faces }
+}
+
+// ---- reading the geometry back out of a kind's GLB -------------------------------------------------
+
+type GlbJson = {
+  nodes?: { name?: string, mesh?: number, children?: number[], matrix?: number[], translation?: number[], rotation?: number[], scale?: number[] }[]
+  meshes?: { primitives: { attributes: Record<string, number>, indices?: number, mode?: number }[] }[]
+  accessors?: { bufferView?: number, byteOffset?: number, componentType: number, count: number, type: string }[]
+  bufferViews?: { buffer: number, byteOffset?: number, byteLength: number, byteStride?: number }[]
+}
+
+const mul = (A: number[], B: number[]): number[] => {
+  const M = new Array(16).fill(0)
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) {
+    let s = 0
+    for (let k = 0; k < 4; k++) s += A[k * 4 + r] * B[c * 4 + k]
+    M[c * 4 + r] = s
+  }
+  return M
+}
+
+const trsMatrix = (t: number[], q: number[], s: number[]): number[] => {
+  const [ x, y, z, w ] = q
+  const m = [
+    (1 - 2 * (y * y + z * z)) * s[0], (2 * (x * y + z * w)) * s[0], (2 * (x * z - y * w)) * s[0], 0,
+    (2 * (x * y - z * w)) * s[1], (1 - 2 * (x * x + z * z)) * s[1], (2 * (y * z + x * w)) * s[1], 0,
+    (2 * (x * z + y * w)) * s[2], (2 * (y * z - x * w)) * s[2], (1 - 2 * (x * x + y * y)) * s[2], 0,
+    t[0], t[1], t[2], 1,
+  ]
+  return m
+}
+
+/** The LOD0 triangles of a kind's GLB, in the file's own frame.
+ *
+ *  LOD levels are left out (`<base>_LOD<n>`, the engine's own convention — creator-gl src/lod.cpp):
+ *  they are coincident shells of the same surface and only the level 0 one is ever drawn. */
+export const readGlbTriangles = (bytes: Uint8Array): FitTriangles | null => {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  if (dv.getUint32(0, true) !== 0x46546c67) return null                       // "glTF"
+  let off = 12, json: GlbJson | null = null, bin: Uint8Array | null = null
+  while (off + 8 <= bytes.byteLength) {
+    const len = dv.getUint32(off, true), type = dv.getUint32(off + 4, true)
+    const chunk = bytes.subarray(off + 8, off + 8 + len)
+    if (type === 0x4e4f534a) json = JSON.parse(new TextDecoder().decode(chunk)) as GlbJson
+    else if (type === 0x004e4942) bin = chunk
+    off += 8 + len + ((4 - (len % 4)) % 4)
+  }
+  if (!json?.nodes || !json.meshes || !json.accessors || !bin) return null
+  const views = json.bufferViews ?? []
+
+  const read = (index: number, want: number): Float64Array | null => {
+    const a = json!.accessors![index]
+    if (a.bufferView === undefined) return null
+    const bv = views[a.bufferView]
+    const comps = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4 }[a.type] ?? 0
+    if (comps !== want) return null
+    const size = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 }[a.componentType] ?? 0
+    if (!size) return null
+    const stride = bv.byteStride || size * comps
+    const base = (bv.byteOffset ?? 0) + (a.byteOffset ?? 0)
+    const view = new DataView(bin!.buffer, bin!.byteOffset, bin!.byteLength)
+    const out = new Float64Array(a.count * comps)
+    for (let i = 0; i < a.count; i++) {
+      for (let c = 0; c < comps; c++) {
+        const at = base + i * stride + c * size
+        out[i * comps + c] = a.componentType === 5126 ? view.getFloat32(at, true)
+          : a.componentType === 5125 ? view.getUint32(at, true)
+          : a.componentType === 5123 ? view.getUint16(at, true)
+          : a.componentType === 5122 ? view.getInt16(at, true)
+          : view.getUint8(at)
+      }
+    }
+    return out
+  }
+
+  const positions: number[] = []
+  const indices: number[] = []
+  const walk = (ni: number, parent: number[]): void => {
+    const nd = json!.nodes![ni]
+    const local = nd.matrix ?? trsMatrix(nd.translation ?? [ 0, 0, 0 ], nd.rotation ?? [ 0, 0, 0, 1 ], nd.scale ?? [ 1, 1, 1 ])
+    const world = mul(parent, local)
+    const lod = /_LOD(\d+)$/.exec(nd.name ?? "")
+    const skip = lod !== null && Number(lod[1]) > 0
+    if (nd.mesh !== undefined && !skip) {
+      for (const prim of json!.meshes![nd.mesh].primitives) {
+        if (prim.mode !== undefined && prim.mode !== 4) continue
+        const pos = prim.attributes.POSITION !== undefined ? read(prim.attributes.POSITION, 3) : null
+        if (!pos) continue
+        const first = positions.length / 3
+        for (let i = 0; i < pos.length; i += 3) {
+          const x = pos[i], y = pos[i + 1], z = pos[i + 2]
+          positions.push(
+            world[0] * x + world[4] * y + world[8] * z + world[12],
+            world[1] * x + world[5] * y + world[9] * z + world[13],
+            world[2] * x + world[6] * y + world[10] * z + world[14],
+          )
+        }
+        const idx = prim.indices !== undefined ? read(prim.indices, 1) : null
+        if (idx) for (let i = 0; i < idx.length; i++) indices.push(first + idx[i])
+        else for (let i = 0; i < pos.length / 3; i++) indices.push(first + i)
+      }
+    }
+    for (const c of nd.children ?? []) walk(c, world)
+  }
+  const child = new Set<number>()
+  for (const nd of json.nodes) for (const c of nd.children ?? []) child.add(c)
+  const I4 = [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ]
+  json.nodes.forEach((_, i) => { if (!child.has(i)) walk(i, I4) })
+  return { positions: Float32Array.from(positions), indices: Uint32Array.from(indices) }
+}

package/src/unity/fbxModel.ts

@@ -0,0 +1,194 @@
+// A MODEL FILE AS A PREFAB. Prefabs and scenes instance an FBX directly (`m_SourcePrefab` = the
+// FBX's GUID) and override its objects by fileID, so the importer needs the GameObject tree Unity's
+// own model importer would have built from that file — shape, ids and transforms.
+
+import { existsSync, readFileSync } from "node:fs"
+import { basename, extname } from "node:path"
+import { readFbx, type FbxNode } from "../fbx/read"
+import type { Tree, UComp, UGO } from "./gameObjects"
+import { mirrorQuat } from "./math"
+import { isMap, num, parseUnityYaml, ref, str, type YMap } from "./yaml"
+
+// Unity names a model's objects in the FBX's `.meta` (`fileIDToRecycleName` — classID·100000 + 2n —
+// or, since 2020, `internalIDToNameTable`), after the FBX nodes. The tree is rebuilt from the file's
+// own nodes the way Unity's importer shapes it: the root takes the file's name and the //RootNode
+// ids, a single top-level GROUP collapses into it, transforms are mirrored into Unity's frame with
+// the importer's `globalScale` on positions.
+
+export type FbxMeta = {
+  globalScale: number
+  /** fileID → object name (`//RootNode`, a node name, a mesh name). */
+  names: Map<string, string>
+  /** `<classID>:<name>` → fileID. */
+  ids: Map<string, string>
+  /** FBX material name → the remapped `.mat` (externalObjects). */
+  materials: Map<string, string>
+  /** The importer's `addColliders`: Unity puts a MeshCollider on every mesh of this model at IMPORT,
+   *  so the collider is in neither the prefab nor the scene and there is nothing to read but this. */
+  addColliders: boolean
+  /** The importer's `bakeAxisConversion`: the Z-up→Y-up correction a Blender export keeps on its top
+   *  nodes is baked into the meshes, so it survives a placement that overwrites the root's rotation. */
+  bakeAxisConversion: boolean
+}
+
+export const readFbxMeta = (metaPath: string): FbxMeta => {
+  const out: FbxMeta = { globalScale: 1, names: new Map(), ids: new Map(), materials: new Map(), addColliders: false, bakeAxisConversion: false }
+  if (!existsSync(metaPath)) return out
+  const doc = parseUnityYaml(readFileSync(metaPath, "utf8"))
+  const mi = isMap(doc.ModelImporter) ? doc.ModelImporter : {}
+  const meshes = isMap(mi.meshes) ? mi.meshes : {}
+  out.globalScale = num(meshes.globalScale, 1)
+  out.addColliders = num(meshes.addColliders, 0) !== 0
+  out.bakeAxisConversion = num(meshes.bakeAxisConversion, 0) !== 0
+  const add = (cls: number, id: string, name: string): void => {
+    out.names.set(id, name)
+    const k = `${cls}:${name}`
+    if (!out.ids.has(k)) out.ids.set(k, id)
+  }
+  if (isMap(mi.fileIDToRecycleName)) for (const [ id, name ] of Object.entries(mi.fileIDToRecycleName)) add(Math.floor(Number(id) / 100000), id, str(name))
+  if (Array.isArray(mi.internalIDToNameTable)) for (const e of mi.internalIDToNameTable) {
+    if (!isMap(e) || !isMap(e.first)) continue
+    for (const [ cls, id ] of Object.entries(e.first)) add(Number(cls), str(id), str(e.second))
+  }
+  if (Array.isArray(mi.externalObjects)) for (const e of mi.externalObjects) {
+    if (!isMap(e) || !isMap(e.first)) continue
+    if (!/Material$/.test(str(e.first.type))) continue
+    const g = ref(e.second).guid
+    if (g) out.materials.set(str(e.first.name), g)
+  }
+  return out
+}
+
+export type ModelInfo = { stem: string, nodes: FbxNode[], materials: string[][], meta: FbxMeta }
+export const MODEL_EXT = /\.(fbx|obj|dae|blend)$/i
+
+export const readModel = async (path: string): Promise<ModelInfo | null> => {
+  try {
+    const scene = await readFbx(new Uint8Array(readFileSync(path)))
+    // per node: the FBX material names its primitives use, in primitive order (= Unity's submeshes)
+    const materials = scene.nodes.map((n) => {
+      const mesh = n.mesh >= 0 ? scene.meshes[n.mesh] : null
+      const names: string[] = []
+      for (const p of mesh?.primitives ?? []) { const nm = scene.materials[p.material]?.name ?? ""; if (!names.includes(nm)) names.push(nm) }
+      return names
+    })
+    return { stem: basename(path, extname(path)), nodes: scene.nodes, materials, meta: readFbxMeta(path + ".meta") }
+  } catch { return null }
+}
+
+/** The name the FBX importer gives a model's MESH object: the node's (for the collapsed root too). */
+export const MODEL_ROOT = "//RootNode"
+
+// UNITY'S OWN fileIDs FOR AN IMPORTED MODEL'S ROOT OBJECTS, by class id.
+//
+// A model `.meta` usually ships NO id table at all (`internalIDToNameTable: []`), so there is
+// nothing to read the root's ids out of - and yet every prefab that wraps that FBX, and every scene
+// that places such a prefab, addresses them. They are not hashes of anything in the file: these four
+// numbers are the same in every pack (measured across seven vendors' packs here - tactical, gunvfx,
+// both blood packs, mc-core, the school), because Unity assigns a model prefab's ROOT a fixed id set
+// and only its CHILDREN get per-name ids.
+//
+// Getting this wrong is silent and total. A kit whose prefabs are bare wrappers around an FBX keeps
+// every placement's position, rotation and material override on the ROOT, addressed as
+// `xor(thatPrefabInstance, thisId)`; invent the root's id instead and not one override in the level
+// resolves, so the whole thing loads with every piece stacked on the origin.
+const MODEL_ROOT_IDS: Record<number, string> = {
+  1: "919132149155446097",       // GameObject
+  4: "-8679921383154817045",     // Transform
+  23: "-7511558181221131132",    // MeshRenderer
+  205: "4742473837712756890",    // LODGroup
+}
+
+/** `bakeAxisConversion`'s half turn about the up axis in front of a rotation: RotY(180°) · q. */
+const bakedAxis = (q: number[]): number[] => [ q[2], q[3], -q[0], -q[1] ]
+
+/** How much of an FBX node's own transform its GameObject takes:
+ *  `full` — all of it (an ordinary child);
+ *  `none` — none (the model's root, which Unity authors at the origin);
+ *  `axis` — what the ROOT's mesh takes when the FBX's single top node IS the mesh. In Unity that
+ *  node is the prefab's root, and a root's position and rotation are never the model's: every
+ *  PrefabInstance overrides them (`SM_Door_01.prefab` writes 0 / identity over the node's −2 m and
+ *  its 180°), so neither may be applied here. What survives is the importer's `bakeAxisConversion`:
+ *  it turns the file half a turn about the up axis (FBX front → Unity forward) and bakes the top
+ *  node's rotation INTO THE MESH, where no override reaches it: mesh' = RotY(180°) · R · mesh.
+ *  Without the flag nothing is baked and the placement's own rotation stands the mesh up.
+ *  Measured on the school, whose four flagged models are the only ones this touches:
+ *  `SM_Door_01` (R = RotY 180° · RotX −90°, so the half turns cancel) stands in its wall's opening,
+ *  x −2.66..−1.34 — the whole R flipped it to +1.34..+2.66, R with the position put it at ±0.66,
+ *  nothing laid it down; `SM_Door_02` (R = identity, mesh authored upright at x 0.78..3.22, nested
+ *  at −2 in `SM_Wall_Door_03`) lands in ITS opening, −5.16..−2.84, only with the half turn —
+ *  without it the double door stood 4 m off, which is how it shipped before.
+ *  The node's SCALE is the root's too (`rootScale` below, `axis` keeps none of it): a Blender export
+ *  without "Apply Unit" puts ×100 on that node, Unity shows it as the ROOT's scale, and a placement
+ *  that writes `m_LocalScale` REPLACES it. Peremena's desks (×100 in the file, 85 in the scene) came out
+ *  8500× their mesh — 130 m across — while they were a child's scale multiplied by the placement's. */
+type TransformShare = "full" | "none" | "axis" | "rootScale"
+
+const xyz = (v: number[]): YMap => ({ x: String(v[0]), y: String(v[1]), z: String(v[2]) })
+const xyzw = (q: number[]): YMap => ({ x: String(q[0]), y: String(q[1]), z: String(q[2]), w: String(q[3]) })
+
+/** A node's local transform as a Unity Transform body: X mirrored, positions × the importer's scale. */
+const transformBody = (n: FbxNode | null, share: TransformShare, meta: FbxMeta): YMap => {
+  const gs = meta.globalScale
+  const t = n && share === "full" ? [ -n.t[0] * gs, n.t[1] * gs, n.t[2] * gs ] : [ 0, 0, 0 ]
+  const q = !n || share === "none" || share === "rootScale" ? [ 0, 0, 0, 1 ] : share === "full" ? n.r : meta.bakeAxisConversion ? bakedAxis(n.r) : [ 0, 0, 0, 1 ]
+  const s = n && (share === "full" || share === "rootScale") ? n.s : [ 1, 1, 1 ]
+  return { m_LocalPosition: xyz(t), m_LocalRotation: xyzw(mirrorQuat(q)), m_LocalScale: xyz(s) }
+}
+
+/** The GameObject tree Unity's importer makes of a model file, under the ids its `.meta` publishes. */
+export const modelTree = (info: ModelInfo, guid: string): Tree => {
+  const { nodes, meta } = info
+  const ids = new Map<string, UGO | UComp>()
+  const kids = new Map<number, number[]>()
+  nodes.forEach((n, i) => { if (n.parent >= 0) { const a = kids.get(n.parent) ?? []; a.push(i); kids.set(n.parent, a) } })
+  // helper nodes (geometric transform / scale inheritance) are not GameObjects: skip through them
+  const realChildren = (i: number): number[] => (kids.get(i) ?? []).flatMap((c) => (nodes[c].helper ? realChildren(c) : [ c ]))
+  const meshOf = (i: number): number => nodes[i].mesh >= 0 ? i : (kids.get(i) ?? []).find((c) => nodes[c].helper && meshOf(c) >= 0) ?? -1
+  const sceneRoot = nodes.findIndex((n) => n.isRoot)
+  const tops = sceneRoot >= 0 ? realChildren(sceneRoot) : nodes.map((_, i) => i).filter((i) => nodes[i].parent < 0)
+  // ONE top-level node collapses into the root — but only a BARE GROUP. A node that carries the MESH
+  // has to stay a child, because the root's transform never reaches the GLB (kindGlb builds the kind
+  // from its parts) and its `axis` share is the thing that stands a Blender export up.
+  const topMesh = tops.length === 1 && meshOf(tops[0]) >= 0 ? tops[0] : -1
+  const collapse = tops.length === 1 && topMesh < 0
+
+  // ids: the `.meta`'s own, Unity's fixed set for the root, else a placeholder nothing can address
+  let placeholders = 0
+  const idFor = (cls: number, name: string): string => meta.ids.get(`${cls}:${name}`)
+    ?? (name === MODEL_ROOT ? MODEL_ROOT_IDS[cls] : undefined)
+    ?? `-${cls}${String(++placeholders).padStart(6, "0")}`
+  const add = (go: UGO, cls: string, classId: number, key: string, body: YMap): UComp => {
+    const c: UComp = { cls, id: idFor(classId, key), body, go }
+    go.comps.push(c)
+    ids.set(c.id, c)
+    return c
+  }
+
+  const make = (i: number | null, key: string, name: string, parent: UGO | null, share: TransformShare): UGO => {
+    const go: UGO = { id: idFor(1, key), body: { m_Name: name, m_IsActive: "1" }, comps: [], children: [], parent }
+    ids.set(go.id, go)
+    // the root of a model whose single top node is the mesh takes that node's scale (TransformShare)
+    const tn = i === null ? (parent === null && topMesh >= 0 ? topMesh : null) : i
+    add(go, "Transform", 4, key, transformBody(tn === null ? null : nodes[tn], i === null && tn !== null ? "rootScale" : share, meta))
+    const mi = i === null ? -1 : meshOf(i)
+    if (mi >= 0) {
+      const meshName = nodes[i!].name
+      const mesh = { fileID: meta.ids.get(`43:${meshName}`) ?? `name:${meshName}`, guid }
+      const mats = info.materials[mi].map((m) => { const g = meta.materials.get(m); return g ? { fileID: "2100000", guid: g } : { fileID: "0", guid: `name:${m}` } })
+      add(go, "MeshFilter", 33, key, { m_Mesh: mesh })
+      add(go, "MeshRenderer", 23, key, { m_Enabled: "1", m_CastShadows: "1", m_Materials: mats })
+      // `addColliders` is the importer generating a MeshCollider per mesh — the only trace of it is
+      // this flag, so a kit that leans on it (here: the interior floor, the ceiling and four walls)
+      // otherwise imports with nothing to stand on and the player falls through the level.
+      if (meta.addColliders) add(go, "MeshCollider", 64, key, { m_Enabled: "1", m_Convex: "0", m_Mesh: mesh })
+    }
+    for (const c of i === null ? tops : realChildren(i)) go.children.push(make(c, nodes[c].name, nodes[c].name, go, c === topMesh ? "axis" : "full"))
+    return go
+  }
+  const root = make(collapse ? tops[0] : null, MODEL_ROOT, info.stem, null, "none")
+  // every id here came from the FBX .meta's own tables, i.e. it IS the id this asset publishes
+  const bySource = new Map<string, UGO | UComp>()
+  for (const [ k, v ] of ids) bySource.set(`${guid}:${k}`, v)
+  return { roots: [ root ], ids, bySource }
+}

package/src/unity/foliage.ts

@@ -0,0 +1,63 @@
+// WHAT IS A PLANT on an imported level — the kinds the level writer marks `foliage: true` (the SDK's
+// vegetation tier: wind, touch bending, per-copy tint).
+//
+// The first rule was "any part wears an alpha-cutout material", and that is too broad by a mile: a
+// poster is cutout, so is a road marking, a door's grille, a window frame — and the tier SWAYS them.
+// On Chernobyl it caught 77 kinds of which 27 were plants; on the school it took two doors.
+//
+// So the evidence is the MATERIAL'S OWN NAME AND FOLDER, never its alpha mode: a pack sorts its
+// materials by what they are (`Materials/Vegetation/…` against `Materials/Decals/`) or names them
+// so (`M_Grass_Tall`, `Grass_01`), and that is the author telling us directly. The kind's name is
+// weaker (`Fencing_Flowerbed_01` is a railing) and is consulted only when NO material of the kind
+// could be read (binary .mat, a missing .meta). And because every rule is a guess about someone
+// else's naming, the import takes an explicit list: `--foliage <re>` marks exactly the kinds whose
+// name matches (the rules are then OFF), `--no-foliage` marks none.
+import { basename } from "node:path"
+import type { SceneKind } from "./scene"
+import type { UnityMaterial } from "./matFile"
+
+export type FoliageOptions = {
+  /** Explicit: exactly the kinds whose NAME matches wear the tier; the material rules are off. */
+  foliage?: RegExp
+  /** Nothing wears the tier. */
+  noFoliage?: boolean
+}
+
+/** A material FOLDER that says "this is a plant" — one path segment, whole. */
+const VEGETATION_DIR = /(^|[\\/])(vegetation|foliage|plants?|shrubs?|grass|trees?|bushes|flowers?)([\\/]|$)/i
+/** A material NAME that says so — a whole word of it (`M_Grass_Tall`, `Grass_01`, `Leaves_Birch`). */
+const VEGETATION_WORD = /(^|[^a-z])(grass|bush|bushes|shrub|leaf|leaves|foliage|vegetation|fern|ivy|vine|reed|clover|weed|moss|hedge|plant|flower|spruce|pine|birch|oak|palm|tree)(e?s)?([^a-z]|$)/i
+/** …unless the same name says it is the WOODY part or the debris: a trunk, a stump, a fallen log. */
+const NOT_VEGETATION_WORD = /(^|[^a-z])(trunk|bark|stump|log|logs|fallen|cut|root|roots|rock|stone|mushroom)([^a-z]|$)/i
+
+/** Does the material's file say vegetation — by the folder it sits in, or by its own name? */
+export const isVegetationMaterial = (um: UnityMaterial): boolean => {
+  if (!um.file) return false
+  const norm = um.file.replace(/\\/g, "/")
+  const dir = norm.slice(0, norm.lastIndexOf("/") + 1)
+  if (VEGETATION_DIR.test(dir)) return true
+  const name = basename(norm).replace(/\.mat$/i, "")
+  return VEGETATION_WORD.test(name) && !NOT_VEGETATION_WORD.test(name)
+}
+
+// Vegetation by kind name — the fallback for a kind none of whose materials could be read.
+const FOLIAGE_NAME = /grass|bush|shrub|flower|plant|reed|clover|fern|ivy|vine|leaf|leaves|tree|spruce|pine|birch|oak|palm|weed|moss|hedge|foliage/i
+const NOT_FOLIAGE = /stump|log|branch|trunk_cut|rock|stone|mushroom|fenc|rail/i
+
+/** Should this kind wear the foliage tier? `materials` = every material of every part the builder
+ *  could read (null = unreadable), in part order. */
+export const decideFoliage = (kind: SceneKind, materials: (UnityMaterial | null)[], opts: FoliageOptions = {}): boolean => {
+  if (opts.noFoliage) return false
+  if (opts.foliage) return opts.foliage.test(kind.name)
+  const read = materials.filter((m): m is UnityMaterial => !!m)
+  if (read.length > 0) return read.some(isVegetationMaterial)
+  return FOLIAGE_NAME.test(kind.name) && !NOT_FOLIAGE.test(kind.name)
+}
+
+/** The import log's one line about the verdict — so a wrong guess is seen, not found in the wind. */
+export const describeFoliage = (names: string[], opts: FoliageOptions = {}): string => {
+  const how = opts.noFoliage ? "--no-foliage" : opts.foliage ? `--foliage ${opts.foliage.source}` : "by material folder / name"
+  if (names.length === 0) return `🌿 foliage tier: none (${how}; --foliage <re> marks kinds by name)`
+  const shown = names.slice(0, 12).join(", ") + (names.length > 12 ? `, … +${names.length - 12}` : "")
+  return `🌿 foliage tier: ${names.length} kind(s) ${how} — ${shown}${opts.foliage || opts.noFoliage ? "" : " (--foliage <re> overrides, --no-foliage none)"}`
+}

package/src/unity/gameObjects.ts

@@ -0,0 +1,81 @@
+// A Unity file's objects as a tree: GameObjects with their components (raw YAML bodies) and
+// children. prefabTree.ts builds these out of `.prefab` / `.unity` text, fbxModel.ts out of a model
+// file; scene.ts reads the finished tree through the accessors at the bottom.
+//
+// Raw bodies stay raw (YAML maps) until a reader asks, so a prefab modification is just "set this
+// path on that body" whatever the component.
+
+import { isMap, num, quat, ref, str, vec3, type Quat, type Vec3, type YMap } from "./yaml"
+import type { TRS } from "./math"
+
+export type UComp = { cls: string, id: string, body: YMap, go: UGO }
+export type UGO = {
+  id: string
+  body: YMap
+  comps: UComp[]
+  children: UGO[]
+  parent: UGO | null
+  /** Set on the root GameObject of a prefab instance: the source prefab's GUID. */
+  prefab?: string
+}
+// `ids` addresses an object the way the CURRENT file does (a nested prefab's are XOR-composed,
+// Unity's own scheme); `bySource` addresses it the way an OVERRIDE does - by the asset the object
+// is defined in plus its id THERE, which survives any amount of nesting. See the lookup below.
+export type Tree = { roots: UGO[], ids: Map<string, UGO | UComp>, bySource: Map<string, UGO | UComp> }
+
+/** A deep copy: every instance of a prefab gets its own bodies to apply modifications to. */
+export const cloneTree = (t: Tree): Tree => {
+  const map = new Map<UGO | UComp, UGO | UComp>()
+  const cloneGo = (g: UGO, parent: UGO | null): UGO => {
+    const n: UGO = { id: g.id, body: structuredClone(g.body), comps: [], children: [], parent, prefab: g.prefab }
+    map.set(g, n)
+    for (const c of g.comps) { const nc: UComp = { cls: c.cls, id: c.id, body: structuredClone(c.body), go: n }; n.comps.push(nc); map.set(c, nc) }
+    for (const ch of g.children) n.children.push(cloneGo(ch, n))
+    return n
+  }
+  const roots = t.roots.map((r) => cloneGo(r, null))
+  const ids = new Map<string, UGO | UComp>()
+  for (const [ k, v ] of t.ids) { const n = map.get(v); if (n) ids.set(k, n) }
+  const bySource = new Map<string, UGO | UComp>()
+  for (const [ k, v ] of t.bySource) { const n = map.get(v); if (n) bySource.set(k, n) }
+  return { roots, ids, bySource }
+}
+
+// ---- reading the finished tree --------------------------------------------------------------------
+
+export const comp = (go: UGO, cls: string): UComp | undefined => go.comps.find((c) => c.cls === cls)
+export const goName = (go: UGO): string => str(go.body.m_Name)
+export const goActive = (go: UGO): boolean => num(go.body.m_IsActive, 1) !== 0
+export const localTRS = (go: UGO): TRS => {
+  const t = comp(go, "Transform") ?? comp(go, "RectTransform")
+  if (!t) return { t: [ 0, 0, 0 ], r: [ 0, 0, 0, 1 ], s: [ 1, 1, 1 ] }
+  const r = quat(t.body.m_LocalRotation)
+  const l = Math.hypot(r[0], r[1], r[2], r[3]) || 1
+  return { t: vec3(t.body.m_LocalPosition), r: [ r[0] / l, r[1] / l, r[2] / l, r[3] / l ], s: vec3(t.body.m_LocalScale, [ 1, 1, 1 ]) }
+}
+export const enabled = (c: UComp): boolean => num(c.body.m_Enabled, 1) !== 0
+
+/** LOD level per renderer component (from every LODGroup in the tree): renderer → level. */
+export const lodLevels = (roots: UGO[], ids?: Map<string, UGO | UComp>): Map<UComp, number> => {
+  const out = new Map<UComp, number>()
+  const walk = (g: UGO): void => {
+    for (const c of g.comps) {
+      if (c.cls !== "LODGroup" || !Array.isArray(c.body.m_LODs)) continue
+      // renderer refs are ids in the file the LODGroup came from — resolve among the group's own subtree
+      const byId = new Map<string, UComp>()
+      const collect = (x: UGO): void => { for (const k of x.comps) byId.set(k.id, k); x.children.forEach(collect) }
+      collect(g)
+      c.body.m_LODs.forEach((lod, level) => {
+        if (!isMap(lod) || !Array.isArray(lod.renderers)) return
+        for (const r of lod.renderers) {
+          const id = ref(isMap(r) ? r.renderer : undefined).fileID
+          const rc = byId.get(id) ?? (ids?.get(id) as UComp | undefined)
+          if (rc && "go" in rc && !out.has(rc)) out.set(rc, level)
+        }
+      })
+    }
+    g.children.forEach(walk)
+  }
+  roots.forEach(walk)
+  return out
+}