lecodes-assets 0.2.0 → 2.4.10

package/src/unity/prefabs.ts

@@ -0,0 +1,54 @@
+// Prefab material overrides.
+//
+// Asset-store packs often leave the FBX's materials as placeholders ("17 - Default", "Material #3150")
+// and assign the real material on the PREFAB's MeshRenderer — the FBX alone converts untextured.
+// This reads the text-serialised `.prefab` files around an FBX and reports, per GameObject that
+// 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 { readFileSync } from "node:fs"
+import { walkFiles } from "./guid"
+import { isMap, readUnityObjects, ref } from "./yaml"
+
+export type PrefabOverride = {
+  /** The .prefab file. */
+  prefab: string
+  /** GameObject name — the FBX node / glTF node it renders (packs keep them identical). */
+  node: string
+  /** GUID of the mesh asset (the FBX) the MeshFilter references, when it is an external asset. */
+  meshGuid: string | undefined
+  /** Material GUIDs by primitive (sub-mesh) index; an empty slot = keep the FBX's. */
+  materials: (string | undefined)[]
+}
+
+/** 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")
+  if (!text.startsWith("%YAML")) return []
+  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
+  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(go, ref(body.m_Mesh).guid)
+    else if (cls === "MeshRenderer" || cls === "SkinnedMeshRenderer") {
+      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[] = []
+  for (const [ go, materials ] of renderers) {
+    const node = names.get(go)
+    if (!node || materials.every((m) => !m)) continue
+    out.push({ prefab: file, node, meshGuid: meshes.get(go), materials })
+  }
+  return out
+}
+
+/** Every `.prefab` under `dirs` (recursive to `depth`), read for overrides. */
+export const collectPrefabOverrides = (dirs: string[], depth = 3): PrefabOverride[] => {
+  const files: string[] = []
+  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
+  }
+}

package/src/unity/scene.ts

@@ -0,0 +1,384 @@
+// 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.
+//
+// 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: every transform is conjugated by the X mirror (math.ts) — placements AND the part matrices
+// inside kinds.
+
+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"
+
+export type Handedness = "x" | "none"
+
+// ---- output types -------------------------------------------------------------------------------------
+
+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[]
+  /** LODGroup level (0 when the renderer is in no LODGroup). */
+  lod: number
+  castShadows: boolean
+}
+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
+  /** `Vegetation/Grass` — the scene groups above the instance; `Terrain/Trees`, `Terrain/Details`. */
+  group: string
+  position: Vec3
+  rotation: Quat
+  scale: Vec3
+}
+/** 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
+  kinds: Record<string, SceneKind>
+  instances: SceneInstance[]
+  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, else the Unity
+   *  project's `.meta` sidecars). */
+  indexFile?: string | null
+  handedness?: Handedness
+  /** 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),
+  }
+}
+
+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 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)
+
+  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 }
+
+  // ---- 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[] = []
+    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 ?? "") : []
+          parts.push({ path: p, matrix: M, mesh: { guid: mesh.guid, fileID: mesh.fileID }, materials: mats, lod: lods.get(mr) ?? lodSuffix(goName(g)), castShadows: num(mr.body.m_CastShadows, 1) !== 0 })
+        }
+      }
+      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++
+      }
+      for (const ch of g.children) walk(ch, m, p, false)
+    }
+    walk(root, I4(), "", true)
+    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
+  }
+
+  // ---- 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 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
+  }
+  /** 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
+  }
+
+  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(), [])
+
+  // ---- 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)!
+    }
+    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")
+  }
+
+  // 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 X (position −x, quaternion (x, −y, −z, w)), metres, Y up",
+    kinds, instances, lights, cameras, terrain: terrainInfo, terrainData: terrainInfo ? tdLocal : null, stats,
+  }
+}
+
+/** The import as printable lines: kinds most used first, then what was skipped. */
+export const describeSceneImport = (r: SceneImport, max = 20): string[] => {
+  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
+}