lecodes-assets 0.2.1 → 2.5.0

package/src/unity/scene.ts

@@ -1,363 +1,398 @@
-// Unity scene (`.unity`, text-serialised YAML) → a level description: every placed prefab instance
-// and mesh object with its world transform, already in LeCodes' frame, plus a table of the prefabs
-// used (and a best guess at the FBX + node each one renders). The vendor's demo map becomes a JSON
-// a `level.ts` can walk: one `Model.load` per prefab, one `clone()` per instance.
+// Unity scene (`.unity`, text-serialised) → a level description in LeCodes' frame: every placed
+// prefab instance as a KIND (a distinct fully-expanded GameObject tree: meshes + materials + LOD
+// levels + colliders, relative to its root) plus one placement per instance, the terrain (heights,
+// splat layers) with its painted trees and detail meshes as more placements, and the lights.
 //
-// What is read: `PrefabInstance` (source prefab GUID, the m_LocalPosition/Rotation/Scale + m_Name +
-// m_IsActive overrides, the transform it is parented to), `Transform` / `GameObject` (the scene's
-// own hierarchy: groups like "Static/Roads", plain mesh objects via `MeshFilter`). Parents that are
-// themselves inside a prefab instance ("stripped" transforms) resolve to that instance's transform —
-// the prefab's internal offsets live in the prefab file, which the big packs ship binary-serialised,
-// so a child parented deep inside a prefab lands at the prefab's root (counted in `approximate`).
+// Kinds are keyed by CONTENT, not by prefab: two instances of one prefab share a kind unless the
+// scene overrode something inside one of them (a moved child, another material) — then that one gets
+// a variant kind. Nested prefabs, variants and modifications are resolved by prefabTree.ts; the
+// scene's own loose mesh objects become kinds too.
 //
-// Frame: Unity is left-handed (+Z forward); glTF/LeCodes right-handed. Unity's FBX importer mirrors
-// X, so undoing it is: position (−x, y, z), quaternion (x, −y, −z, w), scale unchanged — the
-// UnityGLTF convention. `handedness: "z"` mirrors Z instead (for content authored in Unity itself),
-// `"none"` keeps Unity's numbers.
+// Frame: every transform is conjugated by the X mirror (math.ts) — placements AND the part matrices
+// inside kinds.
 
-import { existsSync, readFileSync } from "node:fs"
-import { basename, dirname, resolve } from "node:path"
-import { findUnityIndex } from "./materials"
+import { readFileSync } from "node:fs"
+import { basename } from "node:path"
+import { comp, enabled, goActive, goName, localTRS, lodLevels, type UComp, type UGO } from "./gameObjects"
+import { resolverFor } from "./guid"
+import { I4, decompose, mirrorX, mmul, r6, trsMatrix, type Mat4 } from "./math"
+import { PrefabLoader, newStats } from "./prefabTree"
+import { readUnityTerrain, type UnityTerrain } from "./terrain"
+import { color, isMap, num, ref, vec3, type Quat, type Vec3 } from "./yaml"
 
-// ---- a YAML subset parser (what Unity writes: block maps/sequences, flow maps, scalars) ----------
+export type Handedness = "x" | "none"
 
-export type Y = string | Y[] | { [k: string]: Y }
-type Line = { indent: number, text: string }
+// ---- output types -------------------------------------------------------------------------------------
 
-const splitLines = (text: string): Line[] => {
-  const raw = text.split(/\r?\n/)
-  const out: Line[] = []
-  for (let i = 0; i < raw.length; i++) {
-    let l = raw[i]
-    if (!l.trim() || l.startsWith("%")) continue
-    // wrapped flow maps: `{fileID: 1, guid: abc,` ⏎ `  type: 3}`
-    let open = (l.match(/\{/g) ?? []).length - (l.match(/\}/g) ?? []).length
-    while (open > 0 && i + 1 < raw.length) {
-      const nx = raw[++i]
-      l += " " + nx.trim()
-      open += (nx.match(/\{/g) ?? []).length - (nx.match(/\}/g) ?? []).length
-    }
-    const indent = l.length - l.trimStart().length
-    out.push({ indent, text: l.trim() })
-  }
-  return out
-}
-
-const scalar = (s: string): Y => {
-  s = s.trim()
-  if (s === "" || s === "~" || s === "null") return ""
-  if (s === "[]") return []
-  if (s === "{}") return {}
-  if (s.startsWith("{") && s.endsWith("}")) {
-    const obj: { [k: string]: Y } = {}
-    for (const part of s.slice(1, -1).split(",")) {
-      const c = part.indexOf(":")
-      if (c < 0) continue
-      obj[part.slice(0, c).trim()] = scalar(part.slice(c + 1))
-    }
-    return obj
-  }
-  if (s.startsWith("[") && s.endsWith("]")) return s.slice(1, -1).split(",").map((x) => scalar(x))
-  if ((s.startsWith("'") && s.endsWith("'")) || (s.startsWith("\"") && s.endsWith("\""))) return s.slice(1, -1).replace(/''/g, "'")
-  return s
-}
-
-export const parseUnityYaml = (text: string): { [k: string]: Y } => {
-  const lines = splitLines(text)
-  let pos = 0
-  const parseValue = (minIndent: number): Y => {
-    if (pos >= lines.length || lines[pos].indent < minIndent) return ""
-    return lines[pos].text.startsWith("- ") || lines[pos].text === "-" ? parseSeq(lines[pos].indent) : parseMap(lines[pos].indent)
-  }
-  const parseMap = (indent: number): { [k: string]: Y } => {
-    const obj: { [k: string]: Y } = {}
-    while (pos < lines.length && lines[pos].indent === indent && !lines[pos].text.startsWith("- ")) {
-      const t = lines[pos].text
-      const c = t.search(/:( |$)/)
-      if (c < 0) { pos++; continue }
-      const key = t.slice(0, c).trim()
-      const rest = t.slice(c + 1).trim()
-      pos++
-      if (rest === "") obj[key] = pos < lines.length && lines[pos].indent > indent ? parseValue(indent + 1) : (pos < lines.length && lines[pos].indent === indent && lines[pos].text.startsWith("- ") ? parseSeq(indent) : "")
-      else obj[key] = scalar(rest)
-    }
-    return obj
-  }
-  const parseSeq = (indent: number): Y[] => {
-    const arr: Y[] = []
-    while (pos < lines.length && lines[pos].indent === indent && (lines[pos].text.startsWith("- ") || lines[pos].text === "-")) {
-      const rest = lines[pos].text.slice(1).trim()
-      if (rest === "") { pos++; arr.push(parseValue(indent + 1)); continue }
-      // a flow map / flow list / plain scalar item (`- {fileID: 0, guid: …}`) is one value, not a key
-      if (rest.startsWith("{") || rest.startsWith("[") || rest.search(/:( |$)/) < 0) { pos++; arr.push(scalar(rest)); continue }
-      // the item's first key shares the dash line; the rest of its keys sit two deeper
-      lines[pos] = { indent: indent + 2, text: rest }
-      arr.push(parseValue(indent + 2))
-    }
-    return arr
-  }
-  return parseMap(lines[0]?.indent ?? 0)
-}
-
-// ---- the scene -----------------------------------------------------------------------------------
-
-type Ref = { fileID: string, guid?: string }
-const ref = (v: Y | undefined): Ref => (typeof v === "object" && !Array.isArray(v) && v ? { fileID: String(v.fileID ?? "0"), guid: typeof v.guid === "string" ? v.guid : undefined } : { fileID: "0" })
-const num = (v: Y | undefined, d = 0): number => { const n = typeof v === "string" ? Number(v) : NaN; return Number.isFinite(n) ? n : d }
-const str = (v: Y | undefined): string => (typeof v === "string" ? v : "")
-const vec3 = (v: Y | undefined, d: [number, number, number]): [number, number, number] => {
-  const o = typeof v === "object" && !Array.isArray(v) && v ? v : {}
-  return [ num(o.x, d[0]), num(o.y, d[1]), num(o.z, d[2]) ]
+export type KindPart = {
+  /** GameObject path inside the kind (`Spruce_3/Spruce_3_LOD1`). */
+  path: string
+  /** Kind-local transform, LeCodes frame (column-major). */
+  matrix: Mat4
+  mesh: { guid: string, fileID: string }
+  /** `.mat` GUIDs, one per submesh (Unity's order). */
+  materials: string[]
+  /** The level this part is drawn at. THE ENGINE'S LOD GROUP IS THE WHOLE GLB (creator-gl lod.cpp): at level n it draws
+   *  the `_LOD<n>` nodes and nothing else, so a renderer Unity draws at several levels (listed under each, or in a
+   *  cull-only LODGroup, or in none while the kind has levels) is written once per level — the same mesh under a
+   *  node per level. One part here is one node. */
+  lod: number
+  castShadows: boolean
 }
-const quat = (v: Y | undefined): [number, number, number, number] => {
-  const o = typeof v === "object" && !Array.isArray(v) && v ? v : {}
-  return [ num(o.x, 0), num(o.y, 0), num(o.z, 0), num(o.w, 1) ]
-}
-
-type Vec3 = [number, number, number]
-type Quat = [number, number, number, number]
-type TRS = { t: Vec3, r: Quat, s: Vec3 }
-const ID: TRS = { t: [ 0, 0, 0 ], r: [ 0, 0, 0, 1 ], s: [ 1, 1, 1 ] }
-const qmul = (a: Quat, b: Quat): 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 qnorm = (q: Quat): Quat => { const l = Math.hypot(q[0], q[1], q[2], q[3]) || 1; return [ q[0] / l, q[1] / l, q[2] / l, q[3] / l ] }
-const qrot = (q: Quat, v: Vec3): Vec3 => {
-  const [ x, y, z, w ] = q
-  const ix = w * v[0] + y * v[2] - z * v[1], iy = w * v[1] + z * v[0] - x * v[2], iz = w * v[2] + x * v[1] - y * v[0], iw = -x * v[0] - y * v[1] - z * v[2]
-  return [ ix * w + iw * -x + iy * -z - iz * -y, iy * w + iw * -y + iz * -x - ix * -z, iz * w + iw * -z + ix * -y - iy * -x ]
-}
-const compose = (p: TRS, l: TRS): TRS => {
-  const st: Vec3 = [ p.s[0] * l.t[0], p.s[1] * l.t[1], p.s[2] * l.t[2] ]
-  const rt = qrot(p.r, st)
-  return { t: [ p.t[0] + rt[0], p.t[1] + rt[1], p.t[2] + rt[2] ], r: qnorm(qmul(p.r, l.r)), s: [ p.s[0] * l.s[0], p.s[1] * l.s[1], p.s[2] * l.s[2] ] }
-}
-
-export type Handedness = "x" | "z" | "none"
-const toLeCodes = (w: TRS, h: Handedness): TRS => {
-  if (h === "x") return { t: [ -w.t[0], w.t[1], w.t[2] ], r: [ w.r[0], -w.r[1], -w.r[2], w.r[3] ], s: w.s }
-  if (h === "z") return { t: [ w.t[0], w.t[1], -w.t[2] ], r: [ -w.r[0], -w.r[1], w.r[2], w.r[3] ], s: w.s }
-  return w
+export type KindCollider = {
+  path: string
+  matrix: Mat4
+  trigger: boolean
+} & (
+  | { shape: "box", center: Vec3, size: Vec3 }
+  | { shape: "sphere", center: Vec3, radius: number }
+  | { shape: "capsule", center: Vec3, radius: number, height: number, direction: number }
+  | { shape: "mesh", convex: boolean, mesh: { guid: string, fileID: string } | null }
+)
+export type KindLight = { path: string, matrix: Mat4, type: number, color: [number, number, number, number], intensity: number, range: number, area?: LightArea, unit?: string }
+export type SceneKind = {
+  key: string
+  /** File-safe unique name (`P_Bush_3`, `P_Bush_3_v2`). */
+  name: string
+  prefab: string | null
+  prefabPath: string | null
+  parts: KindPart[]
+  colliders: KindCollider[]
+  lights: KindLight[]
+  particles: number
+  count: number
 }
-
 export type SceneInstance = {
+  kind: string
   name: string
-  /** prefab GUID (key into `prefabs`), or null for a plain mesh object */
-  prefab: string | null
-  /** `Static/Roads` — the scene's grouping GameObjects above the instance */
+  /** `Vegetation/Grass` — the scene groups above the instance; `Terrain/Trees`, `Terrain/Details`. */
   group: string
   position: Vec3
   rotation: Quat
   scale: Vec3
-  /** true when a parent sat inside a binary prefab — placed at that prefab's root, not its inner child */
-  approximate?: boolean
 }
-export type ScenePrefab = { path: string | null, name: string, fbx: string | null, node: string | null, count: number }
+/** An AREA light's emitter (Unity rectangle / disc lights, HDRP rectangle / tube / disc): `width` runs along the light's
+ *  local X (`along`), `height` along its local Y (`up`; 0 for a tube), and it emits along `direction` (local +Z). The
+ *  lightmap bake takes such a lamp as a rectangle (`Light.point({ bakeArea })`) - a fixture lights from its length, not
+ *  from a point. */
+export type LightArea = { shape: "rect" | "tube" | "disc", width: number, height: number }
+export type SceneLight = { name: string, type: "directional" | "point" | "spot", position: Vec3, direction: Vec3, color: [number, number, number], intensity: number, range: number, shadows: boolean,
+  area?: LightArea, along?: Vec3, up?: Vec3,
+  /** HDRP's unit of `intensity`: lumen | candela | lux | nits | ev100 (absent = the pipeline's unitless number). */
+  unit?: string }
+export type SceneCamera = { name: string, position: Vec3, forward: Vec3, fov: number }
+export type SceneTerrainInfo = {
+  name: string
+  dataPath: string
+  /** LeCodes node origin (sample (0,0) — the mirrored grid's corner). */
+  position: Vec3
+  resolution: number
+  size: Vec3
+  layers: { name: string, diffuse: string | null, normal: string | null, tileSize: [number, number], coverage: number }[]
+}
 export type SceneImport = {
   source: string
   frame: string
-  prefabs: Record<string, ScenePrefab>
+  kinds: Record<string, SceneKind>
   instances: SceneInstance[]
-  stats: { prefabInstances: number, meshObjects: number, inactive: number, approximate: number, unresolvedPrefabs: number }
+  lights: SceneLight[]
+  cameras: SceneCamera[]
+  terrain: SceneTerrainInfo | null
+  stats: { prefabInstances: number, sceneMeshes: number, trees: number, details: number, inactive: number, unresolvedMods: number, guessedTransforms: number, missingPrefabs: number, binaryPrefabs: string[], variants: number, particles: number, prefabLights: number }
 }
+/** The terrain arrays that do not belong in JSON (the `.terrain` writer reads them). */
+export type SceneImportFull = SceneImport & { terrainData: UnityTerrain | null }
 
 export type ImportSceneOptions = {
-  /** `unity-index.txt` for GUID → path (default: found walking up from the scene file) */
+  /** `unity-index.txt` for GUID → path (default: found walking up from the scene, else the Unity
+   *  project's `.meta` sidecars). */
   indexFile?: string | null
   handedness?: Handedness
-  /** keep only instances whose prefab path / name / group matches */
+  /** keep only instances whose kind name / group matches */
   filter?: RegExp
+  /** …and the opposite: DROP every instance whose kind name / group / node name matches. For props a
+   *  pack authors inside the geometry they decorate — the Modular Shooting Range sinks its wall signs
+   *  ~3.5 cm into the concrete and lets Unity's decal ordering sort it out, so they z-fight here. */
+  drop?: RegExp
+  /** DROP the placements standing at these points (lecodes frame, as the scene file prints them; within 10 cm) —
+   *  for the one instance of a kind the game moves while its twins stay: the shooting range's five lane targets
+   *  are `SM_CardboardTarget_01` like the sixth on a shelf, so no name tells them apart, their place does. */
+  dropAt?: [number, number, number][]
   /** Unity-space X/Z rectangle [x0, z0, x1, z1] — instances outside are dropped */
   region?: [number, number, number, number]
   /** only instances under a group whose path contains this */
   group?: string
   includeInactive?: boolean
+  /** Skip the terrain's painted trees / detail meshes. */
+  noTrees?: boolean
+  noDetails?: boolean
+}
+
+// ---- component readers -----------------------------------------------------------------------------
+
+/** A collider component as a kind's collider (`M` = the owner's kind-local matrix, mirrored), or null for any other component. */
+const readCollider = (c: UComp, path: string, M: Mat4): KindCollider | null => {
+  const base = { path, matrix: M, trigger: num(c.body.m_IsTrigger, 0) !== 0 }
+  switch (c.cls) {
+    case "BoxCollider": return { ...base, shape: "box", center: vec3(c.body.m_Center), size: vec3(c.body.m_Size, [ 1, 1, 1 ]) }
+    case "SphereCollider": return { ...base, shape: "sphere", center: vec3(c.body.m_Center), radius: num(c.body.m_Radius, 0.5) }
+    case "CapsuleCollider": return { ...base, shape: "capsule", center: vec3(c.body.m_Center), radius: num(c.body.m_Radius, 0.5), height: num(c.body.m_Height, 2), direction: num(c.body.m_Direction, 1) }
+    case "MeshCollider": {
+      const mesh = ref(c.body.m_Mesh)
+      return { ...base, shape: "mesh", convex: num(c.body.m_Convex, 0) !== 0, mesh: mesh.guid ? { guid: mesh.guid, fileID: mesh.fileID } : null }
+    }
+    default: return null
+  }
+}
+
+/** The emitter of an area light, or undefined for a punctual one. HDRP keeps it in the HDAdditionalLightData script next to
+ *  the Light (m_PointlightHDType 1 = area; m_AreaLightShape 0 rectangle, 1 tube, 2 disc; m_ShapeWidth / m_ShapeHeight);
+ *  the built-in and URP pipelines in the Light itself (m_Type 3 rectangle, 4 disc; m_AreaSize). */
+const HD_UNITS = [ "lumen", "candela", "lux", "nits", "ev100" ]
+const readArea = (comps: UComp[], light: UComp): { area?: LightArea, unit?: string } => {
+  const hd = comps.find((c) => c.cls === "MonoBehaviour" && c.body.m_AreaLightShape !== undefined && c.body.m_ShapeWidth !== undefined)
+  if (hd) {
+    const unit = HD_UNITS[num(hd.body.m_LightUnit, -1)]
+    if (num(hd.body.m_PointlightHDType, 0) !== 1) return { unit }
+    const shape = ([ "rect", "tube", "disc" ] as const)[num(hd.body.m_AreaLightShape, 0)] ?? "rect"
+    const width = num(hd.body.m_ShapeWidth, 0.5)
+    return { unit, area: { shape, width, height: shape === "tube" ? 0 : shape === "disc" ? width : num(hd.body.m_ShapeHeight, 0.5) } }
+  }
+  const type = num(light.body.m_Type, 2)
+  if (type !== 3 && type !== 4) return {}
+  const size = light.body.m_AreaSize
+  const width = isMap(size) ? num(size.x, 1) : 1, height = isMap(size) ? num(size.y, 1) : 1
+  return { area: { shape: type === 4 ? "disc" : "rect", width, height: type === 4 ? width : height } }
+}
+const axisOf = (M: Mat4, col: number): Vec3 => {
+  const f = M.slice(col * 4, col * 4 + 3)
+  const l = Math.hypot(...f) || 1
+  return f.map((v) => r6(v / l)) as Vec3
+}
+
+/** The unit +Z of a (mirrored) world matrix: where a light shines and a camera looks. */
+const forwardOf = (M: Mat4): Vec3 => {
+  const f = M.slice(8, 11)
+  const l = Math.hypot(...f) || 1
+  return f.map((v) => r6(v / l)) as Vec3
+}
+
+const readLight = (name: string, light: UComp, M: Mat4, comps: UComp[] = []): SceneLight => {
+  const type = num(light.body.m_Type, 2)
+  const c = color(light.body.m_Color)
+  return {
+    name, type: type === 1 ? "directional" : type === 0 ? "spot" : "point", position: decompose(M).t.map(r6) as Vec3, direction: forwardOf(M),
+    color: [ c[0], c[1], c[2] ], intensity: num(light.body.m_Intensity, 1), range: num(light.body.m_Range, 10),
+    shadows: isMap(light.body.m_Shadows) ? num(light.body.m_Shadows.m_Type, 0) !== 0 : false,
+    ...readArea(comps, light), along: axisOf(M, 0), up: axisOf(M, 1),
+  }
 }
 
-export const importUnityScene = (scenePath: string, opts: ImportSceneOptions = {}): SceneImport => {
+const readCamera = (name: string, cam: UComp, M: Mat4): SceneCamera =>
+  ({ name, position: [ M[12], M[13], M[14] ].map(r6) as Vec3, forward: forwardOf(M), fov: num(cam.body["field of view"], 60) })
+
+export const importUnityScene = async (scenePath: string, opts: ImportSceneOptions = {}): Promise<SceneImportFull> => {
   const text = readFileSync(scenePath, "utf8")
   if (!text.startsWith("%YAML")) throw new Error(`${basename(scenePath)} is not text-serialised (Unity: Edit ▸ Project Settings ▸ Editor ▸ Asset Serialization = Force Text)`)
   const handedness = opts.handedness ?? "x"
-  const indexFile = opts.indexFile === undefined ? findUnityIndex(dirname(resolve(scenePath))) : opts.indexFile
-  const guidPath = new Map<string, string>()
-  if (indexFile && existsSync(indexFile)) {
-    for (const line of readFileSync(indexFile, "utf8").split(/\r?\n/)) { const t = line.indexOf("\t"); if (t > 0) guidPath.set(line.slice(0, t), line.slice(t + 1).trim()) }
-  }
+  const mirror = (m: Mat4): Mat4 => (handedness === "x" ? mirrorX(m) : m)
+  const resolver = resolverFor(scenePath, opts.indexFile)
+  const tstats = newStats()
+  const loader = new PrefabLoader(resolver, tstats)
+  // the terrain first: its tree / detail prototypes join the model preload
+  const tdGuid = /m_TerrainData: \{fileID: -?\d+, guid: ([0-9a-f]{32})/.exec(text)?.[1]
+  const tdPath = tdGuid ? resolver.resolve(tdGuid) : null
+  const tdLocal = tdPath ? readUnityTerrain(tdPath, [ 0, 0, 0 ], resolver) : null
+  await loader.preload([ text ], tdLocal ? [ ...new Set([ ...tdLocal.trees, ...tdLocal.details ].map((p) => p.prefab)) ] : [])
+  const tree = loader.buildText(text, null)
 
-  // split into objects
-  type Obj = { type: number, id: string, stripped: boolean, cls: string, body: { [k: string]: Y } }
-  const objs = new Map<string, Obj>()
-  const re = /^--- !u!(\d+) &(-?\d+)( stripped)?\s*$/gm
-  const starts: { idx: number, type: number, id: string, stripped: boolean, end: number }[] = []
-  for (let m = re.exec(text); m; m = re.exec(text)) starts.push({ idx: m.index, type: +m[1], id: m[2], stripped: !!m[3], end: m.index + m[0].length })
-  for (let i = 0; i < starts.length; i++) {
-    const s = starts[i]
-    const chunk = text.slice(s.end, i + 1 < starts.length ? starts[i + 1].idx : text.length)
-    const body = parseUnityYaml(chunk)
-    const cls = Object.keys(body)[0] ?? ""
-    objs.set(s.id, { type: s.type, id: s.id, stripped: s.stripped, cls, body: (body[cls] as { [k: string]: Y }) ?? {} })
-  }
+  const kinds: Record<string, SceneKind> = {}
+  const nameUse = new Map<string, number>()
+  const instances: SceneInstance[] = []
+  const lights: SceneLight[] = []
+  const cameras: SceneCamera[] = []
+  const stats: SceneImport["stats"] = { prefabInstances: 0, sceneMeshes: 0, trees: 0, details: 0, inactive: 0, unresolvedMods: 0, guessedTransforms: 0, missingPrefabs: 0, binaryPrefabs: [], variants: 0, particles: 0, prefabLights: 0 }
+  const prefabName = (guid: string | null): string | null => { const p = guid ? resolver.resolve(guid) : null; return p ? basename(p).replace(/\.(prefab|fbx|obj|dae|blend)$/i, "") : null }
 
-  // transforms + game objects
-  type T = { local: TRS, father: string, gameObject: string, prefabInstance: string | null }
-  const transforms = new Map<string, T>()
-  const gameObjects = new Map<string, { name: string, active: boolean, components: string[] }>()
-  const meshFilters = new Map<string, { mesh: Ref }>()          // by game object id
-  type PI = { parent: string, local: TRS, guid: string | undefined, name: string | null, active: boolean }
-  const prefabInstances = new Map<string, PI>()
-  for (const o of objs.values()) {
-    if (o.cls === "Transform" || o.cls === "RectTransform") {
-      transforms.set(o.id, {
-        local: { t: vec3(o.body.m_LocalPosition, [ 0, 0, 0 ]), r: quat(o.body.m_LocalRotation), s: vec3(o.body.m_LocalScale, [ 1, 1, 1 ]) },
-        father: ref(o.body.m_Father).fileID, gameObject: ref(o.body.m_GameObject).fileID,
-        prefabInstance: o.stripped ? ref(o.body.m_PrefabInstance).fileID : null,
-      })
-    } else if (o.cls === "GameObject") {
-      const comps = Array.isArray(o.body.m_Component) ? o.body.m_Component.map((c) => ref(typeof c === "object" && !Array.isArray(c) ? c.component : undefined).fileID) : []
-      gameObjects.set(o.id, { name: str(o.body.m_Name), active: num(o.body.m_IsActive, 1) !== 0, components: comps })
-    } else if (o.cls === "MeshFilter") {
-      meshFilters.set(ref(o.body.m_GameObject).fileID, { mesh: ref(o.body.m_Mesh) })
-    } else if (o.cls === "PrefabInstance") {
-      const mod = (typeof o.body.m_Modification === "object" && !Array.isArray(o.body.m_Modification) ? o.body.m_Modification : {}) as { [k: string]: Y }
-      const local: TRS = { t: [ 0, 0, 0 ], r: [ 0, 0, 0, 1 ], s: [ 1, 1, 1 ] }
-      let name: string | null = null, active = true
-      const mods = Array.isArray(mod.m_Modifications) ? mod.m_Modifications : []
-      // the modifications target the prefab's ROOT transform (the first fileID seen for TRS keys);
-      // overrides on inner children are ignored — they need the prefab's contents
-      let rootTarget: string | null = null
-      for (const m of mods) {
-        if (typeof m !== "object" || Array.isArray(m)) continue
-        const path = str(m.propertyPath), value = str(m.value), target = ref(m.target).fileID
-        const mt = /^m_Local(Position|Rotation|Scale)\.([xyzw])$/.exec(path)
-        if (mt) {
-          if (rootTarget === null) rootTarget = target
-          if (target !== rootTarget) continue
-          const k = "xyzw".indexOf(mt[2])
-          if (mt[1] === "Position") local.t[k] = num(value, local.t[k])
-          else if (mt[1] === "Rotation") local.r[k] = num(value, local.r[k])
-          else local.s[k] = num(value, local.s[k])
-        } else if (path === "m_Name" && name === null) name = value
-        else if (path === "m_IsActive" && value === "0") active = false
+  // ---- a prefab instance → a kind (+ its nested prefab instances as placements of their own) ----
+  // Kinds stop at nested prefab roots: a composite (a cliff wall built from cliff-rock prefabs, a
+  // campfire around a fire prefab) becomes placements of its LEAF prefabs, so a moved rock inside one
+  // wall is one more placement, not one more GLB carrying twelve rocks.
+  const lodSuffix = (n: string): number => { const m = /_LOD(\d+)$/i.exec(n); return m ? +m[1] : 0 }
+  const kindOf = (root: UGO, prefab: string | null, fallbackName: string, nested: { g: UGO, local: Mat4 }[]): SceneKind | null => {
+    const parts: KindPart[] = [], colliders: KindCollider[] = [], klights: KindLight[] = []
+    // a renderer and the levels it is drawn at: `[]` = every level the kind has (expanded once the kind's levels are known)
+    const drawn: { part: Omit<KindPart, "lod">, levels: number[] }[] = []
+    let particles = 0
+    const lods = lodLevels([ root ])
+    const walk = (g: UGO, parentM: Mat4, path: string, top: boolean): void => {
+      if (!goActive(g) && !opts.includeInactive) return
+      const l = localTRS(g)
+      const m = top ? I4() : mmul(parentM, trsMatrix(l.t, l.r, l.s))
+      if (!top && g.prefab) { nested.push({ g, local: m }); return }
+      const p = top ? "" : (path ? `${path}/` : "") + goName(g)
+      const M = mirror(m)
+      const mf = comp(g, "MeshFilter"), mr = comp(g, "MeshRenderer")
+      if (mf && mr && enabled(mr)) {
+        const mesh = ref(mf.body.m_Mesh)
+        if (mesh.guid && mesh.guid !== "0000000000000000e000000000000000") {
+          const mats = Array.isArray(mr.body.m_Materials) ? mr.body.m_Materials.map((x) => ref(x).guid ?? "") : []
+          // in no LODGroup: a loose renderer named like its node (`…_LOD1`) keeps that level; a plain one is drawn at every level
+          const suffix = lodSuffix(goName(g))
+          const levels = lods.get(mr) ?? (suffix > 0 ? [ suffix ] : [])
+          drawn.push({ part: { path: p, matrix: M, mesh: { guid: mesh.guid, fileID: mesh.fileID }, materials: mats, castShadows: num(mr.body.m_CastShadows, 1) !== 0 }, levels })
+        }
+      }
+      for (const c of g.comps) {
+        if (!enabled(c)) continue
+        const collider = readCollider(c, p, M)
+        if (collider) colliders.push(collider)
+        else if (c.cls === "Light") klights.push({ path: p, matrix: M, type: num(c.body.m_Type, 2), color: color(c.body.m_Color), intensity: num(c.body.m_Intensity, 1), range: num(c.body.m_Range, 10), ...readArea(g.comps, c) })
+        else if (c.cls === "ParticleSystem") particles++
       }
-      local.r = qnorm(local.r)
-      prefabInstances.set(o.id, { parent: ref(mod.m_TransformParent).fileID, local, guid: ref(o.body.m_SourcePrefab).guid, name, active })
+      for (const ch of g.children) walk(ch, m, p, false)
     }
+    walk(root, I4(), "", true)
+    // the kind's levels: a part drawn at every level gets a node per level (the same mesh, `<name>_LOD<n>` beside `<name>`)
+    const maxLevel = drawn.reduce((m, d) => Math.max(m, ...d.levels), 0)
+    for (const d of drawn) {
+      const levels = d.levels.length ? d.levels : Array.from({ length: maxLevel + 1 }, (_, i) => i)
+      for (const lod of levels) parts.push({ ...d.part, lod })
+    }
+    stats.particles += particles
+    stats.prefabLights += klights.length
+    if (!parts.length && !colliders.length) return null
+    const key = JSON.stringify([ prefab, parts.map((x) => [ x.path, x.matrix.map(r6), x.mesh, x.materials, x.lod, x.castShadows ]), colliders.map((c) => ({ ...c, matrix: c.matrix.map(r6) })) ])
+    let k = kinds[key]
+    if (!k) {
+      const base = (prefabName(prefab) ?? fallbackName).replace(/\s*\(\d+\)$/, "").replace(/[^\w.-]+/g, "_")
+      const n = (nameUse.get(base) ?? 0) + 1
+      nameUse.set(base, n)
+      if (n > 1) stats.variants++
+      k = kinds[key] = { key, name: n > 1 ? `${base}_v${n}` : base, prefab, prefabPath: prefab ? resolver.resolve(prefab) : null, parts, colliders, lights: klights, particles, count: 0 }
+    }
+    return k
   }
 
-  // world transforms, memoised; stripped transforms resolve to their prefab instance
-  const worldT = new Map<string, { w: TRS, approx: boolean, path: string[] }>()
-  const worldPI = new Map<string, { w: TRS, approx: boolean, path: string[] }>()
-  const ROOT = { w: ID, approx: false, path: [] as string[] }
-  const resolveT = (id: string, depth = 0): { w: TRS, approx: boolean, path: string[] } => {
-    if (id === "0" || depth > 64) return ROOT
-    const hit = worldT.get(id); if (hit) return hit
-    const t = transforms.get(id)
-    let out = ROOT
-    if (t) {
-      if (t.prefabInstance) { const p = resolvePI(t.prefabInstance, depth + 1); out = { w: p.w, approx: true, path: p.path } }
-      else {
-        const par = resolveT(t.father, depth + 1)
-        const go = gameObjects.get(t.gameObject)
-        out = { w: compose(par.w, t.local), approx: par.approx, path: go?.name ? [ ...par.path, go.name ] : par.path }
-      }
-    }
-    worldT.set(id, out)
-    return out
+  // ---- placements ----
+  const worldOf = (m: Mat4): { position: Vec3, rotation: Quat, scale: Vec3 } => {
+    const d = decompose(mirror(m))
+    return { position: d.t.map(r6) as Vec3, rotation: d.r.map(r6) as Quat, scale: d.s.map(r6) as Vec3 }
   }
-  const resolvePI = (id: string, depth = 0): { w: TRS, approx: boolean, path: string[] } => {
-    const hit = worldPI.get(id); if (hit) return hit
-    const p = prefabInstances.get(id)
-    let out = ROOT
-    if (p) {
-      const par = resolveT(p.parent, depth + 1)
-      const nm = p.name ?? prefabName(p.guid)
-      out = { w: compose(par.w, p.local), approx: par.approx, path: [ ...par.path, nm ] }
-    }
-    worldPI.set(id, out)
-    return out
+  const inRegion = (m: Mat4): boolean => !opts.region || (m[12] >= opts.region[0] && m[12] <= opts.region[2] && m[14] >= opts.region[1] && m[14] <= opts.region[3])
+  const place = (k: SceneKind, name: string, group: string, m: Mat4): boolean => {
+    if (opts.group && !group.includes(opts.group)) return false
+    if (opts.filter && !(opts.filter.test(k.name) || opts.filter.test(group) || opts.filter.test(name))) return false
+    if (opts.drop && (opts.drop.test(k.name) || opts.drop.test(group) || opts.drop.test(name))) return false
+    if (!inRegion(m)) return false
+    const w = worldOf(m)
+    if (opts.dropAt?.some((p) => Math.hypot(p[0] - w.position[0], p[1] - w.position[1], p[2] - w.position[2]) < 0.1)) return false
+    k.count++
+    instances.push({ kind: k.name, name, group, ...w })
+    return true
   }
-  const prefabName = (guid: string | undefined): string => {
-    const p = guid ? guidPath.get(guid) : undefined
-    return p ? basename(p).replace(/\.prefab$/i, "") : (guid ?? "prefab")
+  /** A prefab instance at `world` (its root's own transform included) — itself and every nested one. */
+  const placePrefab = (root: UGO, world: Mat4, groups: string[], fallbackName: string): number => {
+    const nested: { g: UGO, local: Mat4 }[] = []
+    const k = kindOf(root, root.prefab ?? null, fallbackName, nested)
+    const name = goName(root) || fallbackName
+    let n = k && place(k, name, groups.join("/"), world) ? 1 : 0
+    for (const x of nested) n += placePrefab(x.g, mmul(world, x.local), [ ...groups, name ], goName(x.g))
+    return n
   }
 
-  // FBX guess per prefab: an FBX from the index under the prefab's folder (`Source/` first), whose
-  // stem is a prefix of the prefab name when there are several
-  const fbxByDir = new Map<string, string[]>()
-  for (const p of guidPath.values()) if (/\.fbx$/i.test(p)) { const d = dirname(p); fbxByDir.set(d, [ ...(fbxByDir.get(d) ?? []), p ]) }
-  const guessFbx = (prefabPath: string, name: string): string | null => {
-    const d = dirname(prefabPath)
-    const cands = [ ...(fbxByDir.get(d + "/Source") ?? []), ...(fbxByDir.get(d) ?? []), ...(fbxByDir.get(dirname(d) + "/Source") ?? []) ]
-    if (cands.length === 0) return null
-    const lname = name.toLowerCase()
-    const stem = (f: string): string => basename(f).replace(/\.fbx$/i, "").toLowerCase()
-    return cands.find((f) => lname.startsWith(stem(f))) ?? cands.find((f) => lname.includes(stem(f)) || stem(f).includes(lname)) ?? (cands.length === 1 ? cands[0] : null)
+  let terrainInfo: SceneTerrainInfo | null = null
+  let terrainOrigin: Vec3 = [ 0, 0, 0 ]
+  const visit = (g: UGO, parentM: Mat4, groups: string[]): void => {
+    if (!goActive(g) && !opts.includeInactive) { stats.inactive++; return }
+    const l = localTRS(g)
+    const m = mmul(parentM, trsMatrix(l.t, l.r, l.s))
+    const name = goName(g)
+    if (g.prefab) {
+      stats.prefabInstances++
+      placePrefab(g, m, groups, name)
+      return
+    }
+    // the scene's own objects
+    const light = comp(g, "Light")
+    if (light && enabled(light)) lights.push(readLight(name, light, mirror(m), g.comps))
+    const cam = comp(g, "Camera")
+    if (cam && enabled(cam)) cameras.push(readCamera(name, cam, mirror(m)))
+    const terrain = comp(g, "Terrain")
+    if (terrain && enabled(terrain) && tdLocal && !terrainInfo) {
+      const td = tdLocal
+      terrainOrigin = [ m[12], m[13], m[14] ]
+      const origin: Vec3 = handedness === "x" ? [ -(m[12] + td.size[0]), m[13], m[14] ] : [ m[12], m[13], m[14] ]
+      terrainInfo = {
+        name: td.name, dataPath: tdPath!, position: origin.map(r6) as Vec3, resolution: td.resolution, size: td.size,
+        layers: td.layers.map((ly, i) => { let s = 0; const w = td.weights[i]; if (w) for (let k = 0; k < w.length; k++) s += w[k]; return { name: ly.name, diffuse: ly.diffuse, normal: ly.normal, tileSize: ly.tileSize, coverage: w ? r6(s / w.length / 255) : 0 } }),
+      }
+    }
+    if (comp(g, "MeshFilter") && comp(g, "MeshRenderer") && !terrain) {
+      // a loose mesh object: its own kind, children visited separately
+      const k = kindOf({ ...g, children: [] }, null, name, [])
+      if (k && place(k, name, groups.join("/"), m)) stats.sceneMeshes++
+    }
+    for (const ch of g.children) visit(ch, m, [ ...groups, name ])
   }
+  for (const r of tree.roots) visit(r, I4(), [])
 
-  const prefabs: Record<string, ScenePrefab> = {}
-  const instances: SceneInstance[] = []
-  const stats = { prefabInstances: 0, meshObjects: 0, inactive: 0, approximate: 0, unresolvedPrefabs: 0 }
-  const inRegion = (w: TRS): boolean => !opts.region || (w.t[0] >= opts.region[0] && w.t[0] <= opts.region[2] && w.t[2] >= opts.region[1] && w.t[2] <= opts.region[3])
-  const push = (name: string, prefab: string | null, res: { w: TRS, approx: boolean, path: string[] }, prefabPath: string | null): void => {
-    const group = res.path.slice(0, -1).join("/")
-    if (opts.group && !res.path.join("/").includes(opts.group)) return
-    if (opts.filter && !(opts.filter.test(name) || opts.filter.test(group) || (prefabPath !== null && opts.filter.test(prefabPath)))) return
-    if (!inRegion(res.w)) return
-    const w = toLeCodes(res.w, handedness)
-    const inst: SceneInstance = { name, prefab, group, position: w.t.map(r6) as Vec3, rotation: w.r.map(r6) as Quat, scale: w.s.map(r6) as Vec3 }
-    if (res.approx) { inst.approximate = true; stats.approximate++ }
-    instances.push(inst)
-  }
-  for (const [ id, p ] of prefabInstances) {
-    stats.prefabInstances++
-    if (!p.active && !opts.includeInactive) { stats.inactive++; continue }
-    const guid = p.guid ?? "?"
-    const path = guidPath.get(guid) ?? null
-    if (!prefabs[guid]) {
-      const name = prefabName(p.guid)
-      if (!path) stats.unresolvedPrefabs++
-      const fbx = path ? guessFbx(path, name) : null
-      prefabs[guid] = { path, name, fbx, node: fbx ? name : null, count: 0 }
+  // ---- terrain trees + details: placements of their prefabs ----
+  const td = terrainInfo ? tdLocal : null
+  if (td) {
+    const protos = new Map<string, UGO | null>()
+    const protoRoot = (guid: string): UGO | null => {
+      if (!protos.has(guid)) protos.set(guid, loader.prefab(guid)?.roots[0] ?? null)
+      return protos.get(guid)!
     }
-    prefabs[guid].count++
-    push(p.name ?? prefabs[guid].name, guid, resolvePI(id), path)
-  }
-  for (const [ goId, mf ] of meshFilters) {
-    const go = gameObjects.get(goId)
-    if (!go) continue
-    const tId = go.components.find((c) => transforms.has(c))
-    if (!tId) continue
-    if (!go.active && !opts.includeInactive) { stats.inactive++; continue }
-    if (mf.mesh.guid === "0000000000000000e000000000000000") continue        // Unity built-in primitives
-    stats.meshObjects++
-    const key = mf.mesh.guid ? `mesh:${mf.mesh.guid}` : `mesh:${goId}`
-    const fbx = mf.mesh.guid ? guidPath.get(mf.mesh.guid) ?? null : null
-    if (!prefabs[key]) prefabs[key] = { path: null, name: go.name, fbx, node: go.name.replace(/\s*\(\d+\)$/, ""), count: 0 }
-    prefabs[key].count++
-    push(go.name, key, resolveT(tId), fbx)
+    const emit = (list: UnityTerrain["trees"], group: string): number => {
+      let n = 0
+      for (const p of list) {
+        const root = protoRoot(p.prefab)
+        if (!root) continue
+        root.prefab ??= p.prefab
+        const h = p.rotation / 2
+        const pos: Vec3 = [ terrainOrigin[0] + p.position[0], terrainOrigin[1] + p.position[1], terrainOrigin[2] + p.position[2] ]
+        n += placePrefab(root, trsMatrix(pos, [ 0, Math.sin(h), 0, Math.cos(h) ], [ p.widthScale, p.heightScale, p.widthScale ]), [ group ], prefabName(p.prefab) ?? p.prefab)
+      }
+      return n
+    }
+    if (!opts.noTrees) stats.trees = emit(td.trees, "Terrain/Trees")
+    if (!opts.noDetails) stats.details = emit(td.details, "Terrain/Details")
   }
-  // counts = surviving instances (filters / region applied); prefabs nothing uses are dropped
-  for (const p of Object.values(prefabs)) p.count = 0
-  for (const i of instances) if (i.prefab && prefabs[i.prefab]) prefabs[i.prefab].count++
-  for (const k of Object.keys(prefabs)) if (!prefabs[k].count) delete prefabs[k]
+
+  // kinds nothing uses (filtered out) are dropped
+  for (const k of Object.keys(kinds)) if (!kinds[k].count) delete kinds[k]
+  stats.unresolvedMods = tstats.unresolvedMods
+  stats.guessedTransforms = tstats.guessedTransforms
+  stats.missingPrefabs = tstats.missingPrefabs.size
+  stats.binaryPrefabs = [ ...tstats.binaryPrefabs ]
 
   return {
     source: basename(scenePath),
-    frame: handedness === "none" ? "unity (left-handed, untouched)" : `lecodes: Unity mirrored on ${handedness.toUpperCase()} (position −${handedness}, quaternion ${handedness === "x" ? "(x, −y, −z, w)" : "(−x, −y, z, w)"}), metres, Y up`,
-    prefabs, instances, stats,
+    frame: handedness === "none" ? "unity (left-handed, untouched)" : "lecodes: Unity mirrored on X (position −x, quaternion (x, −y, −z, w)), metres, Y up",
+    kinds, instances, lights, cameras, terrain: terrainInfo, terrainData: terrainInfo ? tdLocal : null, stats,
   }
 }
 
-const r6 = (v: number): number => Math.round(v * 1e6) / 1e6
-
-/** The prefab table as printable lines, most used first. */
+/** The import as printable lines: kinds most used first, then what was skipped. */
 export const describeSceneImport = (r: SceneImport, max = 20): string[] => {
-  const rows = Object.entries(r.prefabs).sort((a, b) => b[1].count - a[1].count)
-  const lines = [ `${r.instances.length} instances of ${rows.length} prefab(s)${r.stats.inactive ? ` · ${r.stats.inactive} inactive skipped` : ""}${r.stats.approximate ? ` · ${r.stats.approximate} placed at a binary prefab's root (inner offset unknown)` : ""}${r.stats.unresolvedPrefabs ? ` · ${r.stats.unresolvedPrefabs} prefab GUID(s) not in the index` : ""}` ]
-  for (const [ , p ] of rows.slice(0, max)) lines.push(`  ${String(p.count).padStart(5)} × ${p.name.padEnd(36)} ${p.fbx ? `${basename(p.fbx)} → --keep ${p.node}` : p.path ? "(no FBX next to the prefab)" : "(unresolved)"}`)
+  const rows = Object.values(r.kinds).sort((a, b) => b.count - a.count)
+  const s = r.stats
+  const lines = [ `${r.instances.length} placements of ${rows.length} kind(s) — ${s.prefabInstances} prefab instances, ${s.trees} terrain trees, ${s.details} detail meshes, ${s.sceneMeshes} scene meshes${s.variants ? ` · ${s.variants} override variant(s)` : ""}${s.inactive ? ` · ${s.inactive} inactive skipped` : ""}` ]
+  for (const k of rows.slice(0, max)) lines.push(`  ${String(k.count).padStart(5)} × ${k.name.padEnd(34)} ${k.parts.length} mesh part(s)${k.colliders.length ? `, ${k.colliders.length} collider(s)` : ""}${k.parts.some((p) => p.lod > 0) ? `, LOD 0–${Math.max(...k.parts.map((p) => p.lod))}` : ""}`)
   if (rows.length > max) lines.push(`  … ${rows.length - max} more`)
+  if (r.terrain) lines.push(`  terrain ${r.terrain.name}: ${r.terrain.resolution}² samples, ${r.terrain.size[0]}×${r.terrain.size[2]} m, layers ${r.terrain.layers.map((l) => `${l.name} ${(l.coverage * 100).toFixed(1)}%`).join(", ")}`)
+  if (r.lights.length) lines.push(`  lights: ${r.lights.map((l) => `${l.area ? `${l.area.shape} ${+l.area.width.toFixed(2)}${l.area.height ? ` x ${+l.area.height.toFixed(2)}` : ""} m` : l.type} ${l.name}`).join(", ")}`)
+  const areaKinds = Object.values(r.kinds).filter((k) => k.lights.some((l) => l.area))
+  if (areaKinds.length) lines.push(`  area lights in prefabs: ${areaKinds.map((k) => `${k.name} x${k.count} (${k.lights.filter((l) => l.area).map((l) => `${l.area!.shape} ${+l.area!.width.toFixed(2)} x ${+l.area!.height.toFixed(2)} m`).join(", ")})`).join(", ")} - the lightmap bake takes them as rectangles: Light.point({ bakeArea })`)
+  const notes: string[] = []
+  if (s.unresolvedMods) notes.push(`${s.unresolvedMods} prefab modification(s) with no target`)
+  if (s.guessedTransforms) notes.push(`${s.guessedTransforms} unaddressable child transform(s) matched by position`)
+  if (s.missingPrefabs) notes.push(`${s.missingPrefabs} prefab GUID(s) not found`)
+  if (s.binaryPrefabs.length) notes.push(`${s.binaryPrefabs.length} binary-serialised prefab(s) skipped`)
+  if (s.particles) notes.push(`${s.particles} particle system(s) not converted`)
+  if (s.prefabLights) notes.push(`${s.prefabLights} light(s) inside prefabs not converted`)
+  if (notes.length) lines.push(`  ℹ ${notes.join(" · ")}`)
   return lines
 }