lecodes-assets 0.2.1 → 2.5.0

package/src/unity/lecodesLevel.ts

@@ -0,0 +1,414 @@
+// A Unity scene import (scene.ts) → files in a LeCodes project:
+//
+//   assets/<map>/<Kind>.glb            one per kind (kindGlb.ts), texture-capped + KTX2 by the doctor
+//   assets/<map>/terrain/…             <map>.terrain (heights, control) + the packed layer textures
+//   src/<map>/<Kind>.scene.ts          a prefab scene per kind: the model + its colliders
+//   src/<map>.scene.ts                 sun, terrain, every placement (grouped like the Unity scene)
+//
+// Everything here is REGENERATED by the next import — the files say so at the top. A game level
+// instances `src/<map>.scene.ts` as a prefab in a scene file of its own and adds its gameplay
+// nodes there. GLBs are rebuilt only when their kind changed (assets/<map>/kinds.json) or --force.
+
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join, relative, resolve } from "node:path"
+import { makeIO } from "../fbx/convert"
+import { decideFoliage, describeFoliage, type FoliageOptions } from "./foliage"
+import { findUnityIndex, resolverFor } from "./guid"
+import { fitVerdict, readGlbTriangles, type FitBox, type FitTriangles } from "./colliderFit"
+import { DEFAULT_MAX_TRIS, fitTriangleBudget } from "./triBudget"
+import { KindGlbBuilder } from "./kindGlb"
+import { writeTerrain, type WrittenTerrain } from "./levelTerrain"
+import { decompose, eulerYXZ, qmul, r2, r3 } from "./math"
+import type { KindCollider, SceneImportFull, SceneKind } from "./scene"
+
+export type WriteLevelOptions = FoliageOptions & {
+  project: string
+  /** Map name: folder + scene file stem (default: the Unity scene's file name, lower-cased). */
+  name?: string
+  force?: boolean
+  maxSize?: number
+  ktx2?: boolean
+  /** The heightfield's largest resolution (samples a side): a finer Unity heightmap is read every k-th sample
+   *  (levelTerrain.ts). Default 1025: half-metre cells over a 500 m map, the size every level so far ran on. */
+  terrainRes?: number
+  log?: (s: string) => void
+  /** Leave the pack's directional light out of the scene file: the level owns its sun — filament renders the
+   *  brightest directional light of a scene and the bake follows it, so a second one only confuses. */
+  noSun?: boolean
+  /** Kinds (by name) that take `static: false` — no atlas rect, lit in real time. The case it was
+   *  written for is a LAMP FIXTURE: the pack models the bulb inside its housing, so the fixture's own
+   *  faces are the brightest texels in the level (the range's `SM_Door_lamp_a` read 18 000 lx against
+   *  a 1 700 lx floor) and the bake spends a rect on each. Also the right switch for anything the game
+   *  moves or swaps. */
+  noLightmap?: RegExp
+  /** METRES A BOX COLLIDER'S FACE MAY STAND OFF THE GEOMETRY under it before the kind takes a MESH
+   *  collider instead (default 0.015; colliderFit.ts measures it, a huge value keeps every box).
+   *  A pack's box is an approximation, and where it is a loose one everything that lands on the hit
+   *  point lands in mid-air: the shooting range's wall module is flat at ±0.100 m while its box was
+   *  fitted to the ±0.138 m of its edge trim, so bullets stopped 3.8 cm in front of the wall, their
+   *  impact particles hung there and the bullet-hole decals (a ±3 cm projection box) never reached
+   *  the wall at all. */
+  colliderFit?: number
+  /** Write NO colliders at all: every kind is pure visuals, no node carries a Physics body. A viewer
+   *  wants that, and so does any level whose placements outnumber what Jolt is configured for
+   *  (the Mountain scene: 78 000 placements, ~20 000 of them with a collider — the body cap fired
+   *  before the level finished loading). */
+  noColliders?: boolean
+  /** Kinds whose name matches take `castShadows: false`. A pack's BACKGROUND MOUNTAINS are 2 km meshes a
+   *  kilometre out that Unity's shadow distance never reaches; here they are casters like any other, and
+   *  their shadow lay across the whole map. */
+  noShadows?: RegExp
+  /** Skip the alpha-card trim (`doctor --trim-cards`), which the import otherwise always runs. It
+   *  DELETES a quad with no opaque texel in its UV rect, and a pack whose decal atlas is 94 % clear
+   *  can lose a whole kind that way — silently, since the GLB keeps its nodes and textures. */
+  noTrimCards?: boolean
+  /** Triangles a kind may have before the import simplifies it (triBudget.ts; default 50 000, 0 = no cap):
+   *  what keeps a photogrammetry scan from arriving as a million-triangle prop and mesh collider. */
+  maxTris?: number
+  /** IMPOSTORS (doctor/impostor.ts): every foliage kind whose level-0 height is ≥ 4 m gets its far LOD level as one
+   *  camera-facing quad over an atlas of views — `cols` azimuths × `rows` elevation rows, or the N×N hemi-octahedron
+   *  of N = `cols` when `rows` is 0 — `px` pixels a frame (default 256 for a plant ≥ 8 m, 128 under), at LOD slot
+   *  `level` (default 2: the engine shows it under 0.12 of the viewport height; 1 = under 0.30, the pack's own LOD1 goes). */
+  impostor?: { cols: number, rows: number, px?: number, level?: number }
+  /** The command that produced this import, written into the scene file's header. A re-import that
+   *  forgets a flag silently undoes a decision — the dropped kinds come back, the lamps go into the
+   *  atlas again — and nothing in the project records it, so the line IS the record. */
+  command?: string
+}
+
+// Bump when a kind GLB built from the same kind comes out different — the cache keys on it.
+// 3: the mesh lookup finds `Book (17)` as `Book` and the sole mesh under a parent node.
+// 4: triplanar Shader Graph materials — `_Diffuse_Tex` & co. read, the projection baked into TEXCOORD_0;
+//    materials found past a nested `assets/` folder (guid.ts).
+// 5: overrides on unaddressable model children matched by position (prefabTree.ts TransformGuess).
+// 6: Unity mesh assets as part sources (unityMesh.ts — the tree LOD3 cross); every texture slot picked
+//    by the first candidate whose file EXISTS (a stale `_MaskMap` no longer shadows the live pack).
+//    (same version, hash element "nocolor": non-foliage kinds lose COLOR_0 — a Unity pack's vertex colour is
+//    shader data, never a tint; NatureManufacture's branches came out pure red.)
+// 7: a Unity DETAIL LAYER on another UV set (kindGlb.ts detailLayer: `_DETALUSEUV3_ON` + `_DetailAlbedoMap` under a
+//    white `_DetailMask`) becomes the primitive's base/normal/ORM on TEXCOORD_0 = that set × tiling — the pines'
+//    bark, which UV0 never covered (the trunks were flat brown above the roots); FBX UV sets 1..3 now read.
+// 8: vegetation kinds carry VERTEX AO — COLOR_0 = (sky visibility, 1, 1, wind weight), doctor/vertexAo.ts.
+// 9: canopy normals on the leaf cards (vertexAo.ts `canopy`, 0.6 toward the crown centre).
+// 10: the pack's per-material WIND PROFILE (`_Drag` / `_Stiffness` / `_InitialBend` / `_ShiverDrag` /
+//     `_ShiverDirectionality`) in the glTF material extras `lecodes.wind` (kindGlb.ts windProfile) — creator-gl's
+//     foliage tier bends and shivers each material as Unity HDRP's Wind.hlsl does.
+// 11: the bark's CAVITY occlusion in COLOR_0.g (vertexAo.ts `cavity`: short rays in the normal's hemisphere — limb joints).
+// 12 (2026-10-18): a material without a metallic map or `_Metallic` is metallic 0, not glTF's 1 (the LOD3 crosses were black)
+// 13 (2026-11-03): an Amplify leaf graph's additive noise tint folds into the base colour factor (materialWriter.ts: Chernobyl's
+//     leaves drew at two thirds); the vertex alpha is the wind weight only under a `lecodes.wind` profile (vertexAo.ts)
+// 14 (2026-11-03): every MASK material of a vegetation kind is double-sided (a pack's leaf shader culls off in its source)
+// 15 (2026-11-03): `--impostor`: foliage kinds ≥ 4 m take an octahedral impostor quad as their last LOD level (doctor/impostor.ts)
+// 16 (2026-11-03): `--impostor-level`: the LOD slot the quad takes is the bake's choice (the engine's thresholds decide the distance)
+// 17 (2026-11-03): the impostor's data map carries the crown's HULL normal (xyz, the cards' shading normal), no depth
+// 18 (2026-11-03): `--impostor <A>x<E>[@px]`: azimuths × elevation rows (default 12x3), `oct<N>` keeps the octahedron; the atlases skip --max-size
+// 19 (2026-11-03): the impostor's albedo atlas is UASTC like its data map (ETC1S shifted the far crown's hue)
+// 20 (2026-11-03): the impostor's data map = octahedral hull normal (rg, object space) + depth (b) + AO (a): the quad self-shadows from its own atlas
+const BUILDER_VERSION = 20
+const v3 = (v: number[]): string => `[${v.map(r3).join(", ")}]`
+const ident = (s: string): string => { const x = s.replace(/[^\w$]/g, "_"); return /^\d/.test(x) ? `_${x}` : x }
+
+const transformFields = (pos: number[], rot: number[], scale?: number[]): string => {
+  const e = eulerYXZ(rot).map(r2)
+  const parts = [ `position: ${v3(pos)}` ]
+  if (e.some((v) => v !== 0)) parts.push(`eulerAngles: [${e.join(", ")}]`)
+  if (scale && scale.some((v) => Math.abs(v - 1) > 1e-3)) parts.push(Math.abs(scale[0] - scale[1]) < 1e-3 && Math.abs(scale[0] - scale[2]) < 1e-3 ? `scale: ${r3(scale[0])}` : `scale: ${v3(scale)}`)
+  return parts.join(", ")
+}
+
+// ---- colliders -------------------------------------------------------------------------------------
+
+type ColliderSpec = { line: (i: number) => string, box: FitBox | null }
+
+const STATIC_ASPECT = "use(Physics, { motion: 'static' })"
+
+/** The pack's solid colliders, each as the prefab file will spell it — plus the box's own frame, for
+ *  the fit test (colliderFit.ts) that decides whether the boxes may be trusted at all. */
+const colliderSpecs = (k: SceneKind): { mesh: (KindCollider & { shape: "mesh" }) | undefined, specs: ColliderSpec[] } => {
+  const solid = k.colliders.filter((c) => !c.trigger)
+  const mesh = solid.find((c) => c.shape === "mesh") as (KindCollider & { shape: "mesh" }) | undefined
+  const specs: ColliderSpec[] = []
+  for (const c of solid) {
+    if (c.shape === "mesh") continue
+    const d = decompose(c.matrix)
+    const s = d.s.map(Math.abs)
+    const center = c.center
+    const origin = [ -center[0] * s[0], center[1] * s[1], center[2] * s[2] ]           // Unity local → mirrored
+    let shape: string
+    let rot = d.r
+    let half: [number, number, number] | null = null
+    if (c.shape === "box") {
+      half = [ c.size[0] * s[0] / 2, c.size[1] * s[1] / 2, c.size[2] * s[2] / 2 ]
+      shape = `box: ${v3(half)}`
+    } else if (c.shape === "sphere") shape = `sphere: ${r3(c.radius * Math.max(...s))}`
+    else {
+      const ax = c.direction
+      const perp = Math.max(...s.filter((_, j) => j !== ax))
+      const radius = c.radius * perp
+      const halfH = Math.max(0, c.height * s[ax] / 2 - radius)
+      shape = `capsule: { halfHeight: ${r3(halfH)}, radius: ${r3(radius)} }`
+      // LeCodes capsules stand on Y: an X / Z capsule turns its node (origin stays in the collider's frame)
+      if (ax !== 1) {
+        const h = Math.SQRT1_2
+        const turn = ax === 0 ? [ 0, 0, h, h ] : [ h, 0, 0, h ]
+        rot = qmul(rot, turn)
+        // the origin was expressed in the unturned frame — rotate it into the turned one
+        const o = origin
+        if (ax === 0) { const [ ox, oy ] = o; o[0] = oy; o[1] = -ox } else { const [ , oy, oz ] = o; o[1] = oz; o[2] = -oy }
+      }
+    }
+    const box: FitBox | null = half
+      ? { half, origin: [ origin[0], origin[1], origin[2] ], t: [ d.t[0], d.t[1], d.t[2] ], rot: [ rot[0], rot[1], rot[2], rot[3] ] }
+      : null
+    specs.push({
+      line: (i: number) => `    collider_${i}: { ${transformFields(d.t, rot)}, aspects: [use(Shape, { ${shape}, origin: ${v3(origin)} }), ${STATIC_ASPECT}] },`,
+      box,
+    })
+  }
+  return { mesh, specs }
+}
+
+/** `forceMesh` = the fit test found a box that floats off the art: the whole kind takes the mesh
+ *  instead, since keeping the good boxes beside it would collide twice. */
+const colliderNodes = (k: SceneKind, forceMesh = false): { modelAspects: string[], children: string[] } => {
+  const modelAspects: string[] = []
+  const children: string[] = []
+  const { mesh, specs } = colliderSpecs(k)
+  // the colliders stay PICKABLE: a game's hitscan is Physics.raycast, and the physics raycast skips a body whose
+  // Shape has raycast: false (creator-physics PickableBodyFilter) - the range shot through its own walls (2026-09-18)
+  if (mesh || forceMesh) modelAspects.push(`use(Shape, { mesh: ${mesh?.convex ? "'convex'" : "true"} })`, STATIC_ASPECT)
+  if (!forceMesh) { let i = 0; for (const spec of specs) children.push(spec.line(++i)) }
+  return { modelAspects, children }
+}
+
+const kindSceneFile = (k: SceneKind, glbRel: string, source: string, foliage: boolean, noLightmap = false, forceMesh = false, noColliders = false, noShadows = false): string => {
+  const { modelAspects, children } = noColliders ? { modelAspects: [] as string[], children: [] as string[] } : colliderNodes(k, forceMesh)
+  const shadows = !noShadows && k.parts.some((p) => p.castShadows)
+  const model = [ `model: asset('${glbRel}')`, shadows ? "castShadows: true" : "castShadows: false" ]
+  // the SDK's vegetation tier: wind, touch bending, per-copy tint (Foliage); a level may add `{ fade }` per kind
+  if (foliage) model.push("foliage: true")
+  // out of the bake entirely (`--no-lightmap <re>`): no atlas rect, lit in real time
+  if (noLightmap) model.push("static: false")
+  if (modelAspects.length) model.push(`aspects: [${modelAspects.join(", ")}]`)
+  return `// Generated by \`lecodes assets scene\` from ${source}${k.prefabPath ? ` (${k.prefabPath.replace(/\\/g, "/").replace(/^.*\/Assets\//, "Assets/")})` : ""}.
+// Regenerated on every re-import — edit the level that instances it, not this file.
+
+export default defineScene({
+  nodes: {
+${[ `    model: { ${model.join(", ")} },`, ...children ].join("\n")}
+  },
+})
+`
+}
+
+// ---- kinds: GLB + prefab scene ---------------------------------------------------------------------------
+
+const rel = (from: string, to: string): string => { const x = relative(from, to).replace(/\\/g, "/"); return x.startsWith(".") ? x : `./${x}` }
+
+/** WHERE `name:<material>` REFS ARE ANSWERED FROM. A renderer's material list names a GUID only
+ *  when something REMAPPED it (the model importer's `externalObjects`, or a prefab / scene
+ *  override); left alone, it carries the FBX's own material NAME and Unity resolves that by
+ *  SEARCHING THE PROJECT (`materialSearch` in the importer). So the folder to walk is the pack
+ *  ROOT — the directory holding unity-index.txt — and not the prefab's grandparent: a pack that
+ *  keeps `Prefabs/` and `Materials/` as SIBLINGS, which is the ordinary layout, has no .mat file
+ *  anywhere under that grandparent and every one of those refs then falls back to the FBX's
+ *  placeholder. That failure is silent AND plausible-looking: an FBX placeholder still carries a
+ *  diffuse COLOUR, so a glass pane comes out flat grey rather than obviously missing, and the
+ *  pack's own transparency, textures and smoothness are simply gone. */
+const packRootOf = (prefabPath: string): string => dirname(findUnityIndex(dirname(prefabPath)) ?? join(dirname(prefabPath), ".."))
+
+/** One GLB per kind under `assetDir`, rebuilt only when the kind changed (kinds.json) or `force`. */
+const buildKindGlbs = async (kinds: SceneKind[], builder: KindGlbBuilder, assetDir: string, opts: WriteLevelOptions, log: (s: string) => void): Promise<{ converted: number, reused: number }> => {
+  const manifestPath = join(assetDir, "kinds.json")
+  const manifest: Record<string, string> = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : {}
+  const { analyzeDoc, applyPlan } = await import("../doctor/doctor")
+  const { ensureCodecs } = await import("../doctor/reduceGlbBones")
+  await ensureCodecs()
+  // cards trimmed to their opaque texels BEFORE the KTX2 encode (doctor/cardTrim.ts): a foliage pack's
+  // quads are mostly transparent, and that discarded fill was the frame on Twig & Twine's map
+  const doctor = { ktx2: opts.ktx2 !== false, maxSize: opts.maxSize ?? 1024, fixEmissive: true, trimCards: !opts.noTrimCards }
+  let converted = 0, reused = 0
+  for (const [ i, k ] of kinds.entries()) {
+    const glb = join(assetDir, `${k.name}.glb`)
+    const maxTris = opts.maxTris ?? DEFAULT_MAX_TRIS
+    // VERTEX COLOURS ARE NOT COLOURS in a Unity pack: the Standard / HDRP Lit shaders never read them, and
+    // a custom shader reads them as DATA — NatureManufacture bakes its wind weight there, (1, 0, 0, 1) on
+    // every branch vertex. glTF's rule is the opposite (COLOR_0 tints the base colour), so the ubershader
+    // painted every broken branch pure red (2026-09-23). Non-foliage kinds lose COLOR_0; the vegetation
+    // tier keeps it — its shader ignores the tint, and the alpha IS the wind weight it will read.
+    const foliage = decideFoliage(k, builder.materialsOf(k), opts)
+    const hash = createHash("sha1").update(JSON.stringify([ BUILDER_VERSION, k.key, opts.maxSize, opts.ktx2, maxTris, ...(foliage ? [] : [ "nocolor" ]), ...(foliage && opts.impostor ? [ "impostor", opts.impostor.cols, opts.impostor.rows, opts.impostor.px ?? 0, opts.impostor.level ?? 2 ] : []) ])).digest("hex").slice(0, 16)
+    if (!opts.force && existsSync(glb) && manifest[k.name] === hash) { reused++; continue }
+    const { doc, parts, missing } = await builder.build(k)
+    if (!foliage) for (const m of doc.getRoot().listMeshes()) for (const p of m.listPrimitives()) { const c = p.getAttribute("COLOR_0"); if (c) { p.setAttribute("COLOR_0", null); if (c.listParents().length <= 1) c.dispose() } }
+    // and the vegetation tier gets its VERTEX AO: the sky's visibility from every vertex baked into COLOR_0.r
+    // (doctor/vertexAo.ts), the wind weight kept in the alpha — the one thing that makes a crown read as a volume
+    if (foliage) {
+      // the cards of a plant are two-sided by nature; a pack's leaf shader may cull off in its SOURCE (Chernobyl's
+      // Leaves.shader: `Cull Off`), which no .mat property shows - the glTF flag says so for every reader (2026-11-03)
+      for (const m of doc.getRoot().listMaterials()) if (m.getAlphaMode() === "MASK") m.setDoubleSided(true)
+      const { bakeVertexAo } = await import("../doctor/vertexAo")
+      const ao = bakeVertexAo(doc)
+      if (ao.vertices) log(`   🌿 ${k.name}: vertex AO on ${ao.vertices} vertices (mean ${ao.meanAo.toFixed(2)})`)
+    }
+    for (const m of missing) log(`   ⚠ ${k.name}: ${m}`)
+    if (!parts) { log(`   ⚠ ${k.name}: no mesh could be built — skipped`); continue }
+    const cut = await fitTriangleBudget(doc, maxTris)
+    if (cut) log(`   ✂ ${k.name}: ${cut.before.toLocaleString("en")} → ${cut.after.toLocaleString("en")} triangles (--max-tris ${maxTris})`)
+    // a TREE's far level as one quad over an atlas of views (doctor/impostor.ts) — before the doctor: the bake reads the
+    // PNG / JPEG base colours the KTX2 encode takes away, and the atlases go through that encode like any map
+    if (foliage && opts.impostor) {
+      const { bakeImpostor, impostorBounds, impostorLabel } = await import("../doctor/impostor")
+      const box = impostorBounds(doc)
+      const height = box ? box.max[1] - box.min[1] : 0
+      if (height >= 4) {
+        // px unset: the bake's own default by the same level-0 height (256 for ≥ 8 m, 128 under)
+        const imp = await bakeImpostor(doc, { ...opts.impostor, log })
+        if (imp) log(`   🌲 ${k.name}: impostor ${impostorLabel(imp)} · ${imp.node} · r ${imp.radius.toFixed(2)} m · ${imp.triangles} triangles in ${imp.ms} ms`)
+      }
+    }
+    await applyPlan(doc, await analyzeDoc(doc, doctor), doctor)
+    writeFileSync(glb, await makeIO().writeBinary(doc))
+    manifest[k.name] = hash
+    converted++
+    log(`   [${i + 1}/${kinds.length}] ${k.name}.glb · ${parts} part(s) · ${Math.round(readFileSync(glb).length / 1024)} KB`)
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 1) + "\n")
+  }
+  return { converted, reused }
+}
+
+/** The LOD0 triangles of a kind's GLB, read once (the fit test below asks for the same file per kind). */
+const triCache = new Map<string, FitTriangles | null>()
+const trianglesOf = (glb: string): FitTriangles | null => {
+  const hit = triCache.get(glb)
+  if (hit !== undefined) return hit
+  let tris: FitTriangles | null = null
+  try { tris = readGlbTriangles(readFileSync(glb)) } catch { tris = null }
+  triCache.set(glb, tris)
+  return tris
+}
+
+/** `src/<map>/<Kind>.scene.ts` for every kind that has its GLB, with the foliage / no-lightmap / collider verdicts. */
+const writeKindScenes = (kinds: SceneKind[], builder: KindGlbBuilder, dirs: { assets: string, src: string }, source: string, opts: WriteLevelOptions, log: (s: string) => void): void => {
+  const foliageKinds: string[] = []
+  const unbakedKinds: string[] = []
+  const tol = opts.colliderFit ?? 0.015
+  const meshKinds: string[] = []
+  let boxKinds = 0
+  for (const k of kinds) {
+    const foliage = decideFoliage(k, builder.materialsOf(k), opts)
+    if (foliage) foliageKinds.push(k.name)
+    const noLightmap = !!opts.noLightmap?.test(k.name)
+    if (noLightmap) unbakedKinds.push(k.name)
+    // DOES THE PACK'S BOX SIT ON THE ART? (colliderFit.ts, `--collider-fit`) — measured against the
+    // kind's own GLB, which is on disk by now whether it was rebuilt or reused
+    const glb = join(dirs.assets, `${k.name}.glb`)
+    const boxes = colliderSpecs(k).specs.map((x) => x.box).filter((b): b is FitBox => b !== null)
+    let forceMesh = false
+    if (boxes.length > 0 && existsSync(glb) && !opts.noColliders) {
+      boxKinds++
+      const v = fitVerdict(trianglesOf(glb), boxes, { tolerance: tol })
+      if (v.mesh) {
+        forceMesh = true
+        meshKinds.push(`${k.name} (${v.worst && v.worst.covered >= 0.25 ? `${Math.round(v.worst.gap * 100)} cm off` : "over a void"})`)
+      }
+    }
+    writeFileSync(join(dirs.src, `${k.name}.scene.ts`), kindSceneFile(k, rel(dirs.src, join(dirs.assets, `${k.name}.glb`)), source, foliage, noLightmap, forceMesh, !!opts.noColliders, !!opts.noShadows?.test(k.name)))
+  }
+  if (boxKinds > 0) {
+    log(`   🧱 collider fit (${r3(tol * 100)} cm): ${meshKinds.length} of ${boxKinds} kind(s) with box colliders take a MESH collider instead${meshKinds.length ? `: ${meshKinds.slice(0, 6).join(", ")}${meshKinds.length > 6 ? ` … +${meshKinds.length - 6}` : ""}` : ""}`)
+  }
+  log(`   ${describeFoliage(foliageKinds, opts)}`)
+  if (opts.noLightmap) log(`   🔦 static: false on ${unbakedKinds.length} kind(s)${unbakedKinds.length ? `: ${unbakedKinds.slice(0, 8).join(", ")}${unbakedKinds.length > 8 ? " …" : ""}` : ` (nothing matched /${opts.noLightmap.source}/)`}`)
+}
+
+// ---- the map scene -----------------------------------------------------------------------------------------
+
+const terrainNode = (r: SceneImportFull, terrain: WrittenTerrain, sdir: string): string[] => {
+  const data = r.terrainData!
+  const layers = terrain.layers.map((f, i) => {
+    const l = data.layers.find((x) => x.name.replace(/^LAYER_/i, "").toLowerCase() === f.replace(/^.*[\\/]/, "").replace(/\.(ktx2|png)$/, "")) ?? data.layers[i]
+    return `{ albedo: asset('${rel(sdir, f)}'), tiling: ${r3(l.tileSize[0])}, roughness: ${l.mask ? r2(1 - l.smoothness) : 1}${l.normal ? `, normalScale: ${r2(l.normalScale)}` : ""} }`
+  })
+  const normals = terrain.normals.map((f) => `asset('${rel(sdir, f)}')`)
+  return [
+    `    terrain: {`,
+    `      terrain: { data: asset('${rel(sdir, terrain.file)}'), layers: [${layers.join(", ")}]${normals.length ? `, normals: [${normals.join(", ")}]` : ""} },`,
+    `      position: ${v3(r.terrain!.position)}, receiveShadows: true,`,
+    `      aspects: [use(Shape, { heightfield: true }), use(Physics, { motion: 'static' })],`,
+    `    },`,
+  ]
+}
+
+/** Placements grouped like the Unity scene: its top-level group objects (+ Trees / Details for the terrain's). */
+const placementGroups = (r: SceneImportFull, usable: Set<string>): string[] => {
+  const groups = new Map<string, string[]>()
+  const used = new Map<string, number>()
+  for (const inst of r.instances) {
+    if (!usable.has(inst.kind)) continue
+    const g = inst.group.startsWith("Terrain/") ? inst.group.slice(8) : (inst.group.split("/")[0] || "Objects")
+    const key = ident(g.replace(/^_+/, "")) || "Objects"
+    const n = (used.get(`${key}/${inst.kind}`) ?? 0) + 1
+    used.set(`${key}/${inst.kind}`, n)
+    const list = groups.get(key) ?? []
+    list.push(`        ${ident(inst.kind)}_${n}: { prefab: ${ident(inst.kind)}, ${transformFields(inst.position, inst.rotation, inst.scale)} },`)
+    groups.set(key, list)
+  }
+  return [ ...groups ].flatMap(([ g, list ]) => [ `    ${g}: {`, `      children: {`, ...list, `      },`, `    },` ])
+}
+
+const mapSceneFile = (r: SceneImportFull, name: string, usable: SceneKind[], terrain: WrittenTerrain | null, sdir: string, opts: WriteLevelOptions): string => {
+  const lines: string[] = []
+  lines.push(`// Generated by \`lecodes assets scene\` from ${r.source} — ${r.instances.length} placements of ${usable.length} kinds.`)
+  lines.push("// Regenerated on every re-import: instance this file as a prefab in a level of your own and put the")
+  lines.push("// gameplay there. Frame: Unity mirrored on X, metres, Y up.")
+  if (opts.command) {
+    lines.push("//")
+    lines.push("// RE-IMPORT WITH THE SAME LINE — the flags carry decisions this file cannot show (kinds dropped,")
+    lines.push("// placements dropped at a point, kinds kept out of the lightmap); drop one and it silently undoes itself:")
+    lines.push(`//   ${opts.command}`)
+  }
+  lines.push("")
+  for (const k of usable) lines.push(`import ${ident(k.name)} from './${name}/${k.name}.scene'`)
+  lines.push("")
+  lines.push("export default defineScene({")
+  const cam = r.cameras[0]
+  if (cam) {
+    const target = cam.position.map((v, i) => v + cam.forward[i] * 30)
+    lines.push(`  camera: { position: ${v3(cam.position)}, target: ${v3(target)}, fov: ${r2(cam.fov)} },`)
+  }
+  lines.push("  nodes: {")
+  const sun = opts.noSun ? undefined : r.lights.find((l) => l.type === "directional")
+  if (sun) lines.push(`    sun: { light: { kind: 'sun', direction: ${v3(sun.direction)}, intensity: ${Math.round(Math.min(120000, Math.max(20000, sun.intensity)))}, color: '#${sun.color.map((c) => Math.round(Math.min(1, c) * 255).toString(16).padStart(2, "0")).join("")}', shadowsQuality: 1, shadowDistance: 30 } },`)
+  if (terrain && r.terrain) lines.push(...terrainNode(r, terrain, sdir))
+  lines.push(...placementGroups(r, new Set(usable.map((k) => k.name))))
+  lines.push("  },", "})", "")
+  return lines.join("\n")
+}
+
+// ---- the whole level ---------------------------------------------------------------------------------
+
+export const writeLeCodesLevel = async (r: SceneImportFull, opts: WriteLevelOptions): Promise<{ scene: string, kinds: number, converted: number, reused: number }> => {
+  const log = opts.log ?? console.log
+  const project = resolve(opts.project)
+  const name = (opts.name ?? r.source.replace(/\.unity$/i, "")).toLowerCase().replace(/[^\w-]+/g, "_")
+  const dirs = { assets: join(project, "assets", name), src: join(project, "src", name) }
+  mkdirSync(dirs.assets, { recursive: true }); mkdirSync(dirs.src, { recursive: true })
+
+  const kinds = Object.values(r.kinds)
+  const anyPrefab = kinds.find((k) => k.prefabPath)?.prefabPath
+  const builder = new KindGlbBuilder({
+    resolver: resolverFor(anyPrefab ?? project),
+    materialDirs: anyPrefab ? [ packRootOf(anyPrefab) ] : [],
+    warn: (m) => log(`   ⚠ ${m}`),
+  })
+  const { converted, reused } = await buildKindGlbs(kinds, builder, dirs.assets, opts, log)
+  const usable = kinds.filter((k) => existsSync(join(dirs.assets, `${k.name}.glb`)))
+  writeKindScenes(usable, builder, dirs, r.source, opts, log)
+  const terrain = await writeTerrain(r, join(dirs.assets, "terrain"), name, opts, log)
+
+  const sceneFile = join(project, "src", `${name}.scene.ts`)
+  writeFileSync(sceneFile, mapSceneFile(r, name, usable, terrain, dirname(sceneFile), opts))
+  return { scene: sceneFile, kinds: usable.length, converted, reused }
+}

package/src/unity/levelTerrain.ts

@@ -0,0 +1,125 @@
+// A Unity terrain → the `.terrain` file the SDK's Terrain.parse reads (heights + control) and the
+// packed layer textures. LeCodes' terrain material blends FOUR layers, so a terrain with more has
+// its closest-coloured ones merged; the grid is mirrored on X like everything else in the import.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { decodeImage } from "./image"
+import { r3 } from "./math"
+import type { SceneImportFull } from "./scene"
+import type { UnityTerrain } from "./terrain"
+
+type LayerPlan = { keep: number[], mergeInto: Map<number, number> }
+
+/** Four layers is what the LeCodes terrain material blends: merge the closest-coloured pairs (by
+ *  mean albedo) until four remain, the lesser-covered layer folding into the other. */
+const planLayers = async (t: UnityTerrain): Promise<LayerPlan> => {
+  const n = t.layers.length
+  const cover = t.weights.map((w) => { let s = 0; for (let i = 0; i < w.length; i += 7) s += w[i]; return s })
+  const mean: number[][] = []
+  for (const l of t.layers) {
+    const img = l.diffuse ? await decodeImage(new Uint8Array(readFileSync(l.diffuse)), l.diffuse) : null
+    if (!img) { mean.push([ 0.5, 0.5, 0.5 ]); continue }
+    let r = 0, g = 0, b = 0, c = 0
+    for (let i = 0; i < img.data.length; i += 4 * 97) { r += img.data[i]; g += img.data[i + 1]; b += img.data[i + 2]; c++ }
+    mean.push([ r / c / 255, g / c / 255, b / c / 255 ])
+  }
+  const alive = new Set(Array.from({ length: n }, (_, i) => i))
+  const mergeInto = new Map<number, number>()
+  while (alive.size > 4) {
+    let best: [number, number] = [ -1, -1 ], bd = Infinity
+    for (const a of alive) for (const b of alive) {
+      if (a >= b) continue
+      const d = Math.hypot(mean[a][0] - mean[b][0], mean[a][1] - mean[b][1], mean[a][2] - mean[b][2])
+      if (d < bd) { bd = d; best = [ a, b ] }
+    }
+    const [ a, b ] = best
+    const [ win, lose ] = cover[a] >= cover[b] ? [ a, b ] : [ b, a ]
+    alive.delete(lose)
+    mergeInto.set(lose, win)
+    cover[win] += cover[lose]
+    for (const [ k, v ] of mergeInto) if (v === lose) mergeInto.set(k, win)
+  }
+  return { keep: [ ...alive ].sort((a, b) => a - b), mergeInto }
+}
+
+const LTER_MAGIC = 0x5245544c, LTER_VERSION = 1
+
+/** Heights (metres) + control (RGBA per sample) → the `.terrain` file the SDK's Terrain.parse reads. */
+const writeTerrainFile = (file: string, sizeX: number, sizeZ: number, cellSize: number, heights: Float32Array, control: Uint8Array, layers: object[]): void => {
+  let lo = Infinity, hi = -Infinity
+  for (const h of heights) { if (h < lo) lo = h; if (h > hi) hi = h }
+  const range = hi - lo > 1e-6 ? hi - lo : 1
+  const n = sizeX * sizeZ
+  const meta = { sizeX, sizeZ, cellSize, chunk: 64, heightMin: lo, heightMax: hi, layers, blobs: { heights: { fmt: "u16", off: 0, len: n * 2 }, holes: { off: n * 2, len: n }, control: { off: n * 3, len: n * 4 } } }
+  const json = new TextEncoder().encode(JSON.stringify(meta))
+  const blobStart = (12 + json.length + 3) & ~3
+  const out = new ArrayBuffer(blobStart + n * 7)
+  const dv = new DataView(out)
+  dv.setUint32(0, LTER_MAGIC, true); dv.setUint32(4, LTER_VERSION, true); dv.setUint32(8, json.length, true)
+  new Uint8Array(out, 12, json.length).set(json)
+  const u16 = new Uint16Array(out, blobStart, n)
+  for (let i = 0; i < n; i++) u16[i] = Math.round(((heights[i] - lo) / range) * 65535)
+  new Uint8Array(out, blobStart + n * 3, n * 4).set(control)
+  writeFileSync(file, new Uint8Array(out))
+}
+
+/** The `.terrain` file, the packed albedo file per kept layer, and the packed normal textures. */
+export type WrittenTerrain = { file: string, layers: string[], normals: string[] }
+
+export const writeTerrain = async (r: SceneImportFull, dir: string, name: string, opts: { ktx2?: boolean, terrainRes?: number }, log: (s: string) => void): Promise<WrittenTerrain | null> => {
+  const t = r.terrainData
+  if (!t || !r.terrain) return null
+  mkdirSync(dir, { recursive: true })
+  // THE HEIGHTFIELD'S RESOLUTION IS A COST EVERYWHERE: the file (7 bytes a sample), Jolt's height field, the navmesh's
+  // input (two triangles a cell: Chernobyl's 4097² = 33 M triangles, past what Recast's wasm can hold) and the render
+  // chunks. A pack's terrain is authored at Unity's 4097 over 500 m (12 cm cells) where half-metre cells draw the same
+  // ground; `--terrain-res` caps it: every k-th sample along both axes (the samples are exact, no filtering), the
+  // largest k whose result is at most the cap — a Unity heightmap is 2^n + 1, so every power of two divides it.
+  const src = t.resolution
+  let step = 1
+  if (opts.terrainRes && opts.terrainRes > 1) while ((src - 1) / step + 1 > opts.terrainRes && (src - 1) % (step * 2) === 0) step *= 2
+  const res = (src - 1) / step + 1
+  if (step > 1) log(`   🏔  terrain heightfield ${src}² → ${res}² (every ${step}th sample, --terrain-res ${opts.terrainRes})`)
+  // mirror the columns: LeCodes sample (0,0) is the Unity terrain's +X far corner
+  const heights = new Float32Array(res * res)
+  for (let z = 0; z < res; z++) for (let x = 0; x < res; x++) heights[z * res + x] = t.heights[(z * step) * src + (src - 1 - x * step)]
+  const plan = await planLayers(t)
+  const slot = new Map<number, number>()
+  plan.keep.forEach((li, s) => slot.set(li, s))
+  for (const [ lose, win ] of plan.mergeInto) slot.set(lose, slot.get(win)!)
+  // control: area-average the (finer) alphamaps onto the samples
+  const ar = t.alphaResolution, control = new Uint8Array(res * res * 4)
+  const f = ar / src
+  for (let z = 0; z < res; z++) for (let x = 0; x < res; x++) {
+    const ux = (res - 1 - x) * step, uz = z * step                             // mirrored column, in source samples
+    const acc = [ 0, 0, 0, 0 ]
+    const ax0 = Math.max(0, Math.floor((ux - step / 2) * f)), ax1 = Math.min(ar - 1, Math.ceil((ux + step / 2) * f))
+    const az0 = Math.max(0, Math.floor((uz - step / 2) * f)), az1 = Math.min(ar - 1, Math.ceil((uz + step / 2) * f))
+    for (let li = 0; li < t.weights.length; li++) {
+      const w = t.weights[li]
+      let s = 0
+      for (let az = az0; az <= az1; az++) for (let ax = ax0; ax <= ax1; ax++) s += w[az * ar + ax]
+      acc[slot.get(li)!] += s
+    }
+    const tot = acc[0] + acc[1] + acc[2] + acc[3] || 1
+    for (let c = 0; c < 4; c++) control[(z * res + x) * 4 + c] = Math.round(acc[c] / tot * 255)
+  }
+  const kept = plan.keep.map((li) => t.layers[li])
+  const file = join(dir, `${name}.terrain`)
+  // ROUGHNESS (terrain.mat: a layer's roughness = its factor × the ALPHA of its albedo, per pixel). An HDRP
+  // layer with a mask map keeps its smoothness in the mask's ALPHA and `m_Smoothness` is a MULTIPLIER on
+  // it (1 in every NatureManufacture layer) — read as the smoothness itself it made the whole terrain a
+  // mirror (factor 0: the ground sparkled under the sun, 2026-09-23). Now the mask rides the albedo's
+  // alpha as 1 − smoothness (terrainPack.ts `smoothnessAlpha`) and the factor is 1 — the multiplier is
+  // not expressible per pixel and is dropped (logged). No mask = the number IS the
+  // smoothness (Unity's built-in terrain), so the factor is 1 − it.
+  const layers = kept.map((l) => ({ tiling: l.tileSize[0], roughness: l.mask ? 1 : Math.min(1, Math.max(0, 1 - l.smoothness)), normalScale: l.normal ? l.normalScale : 0, triplanar: false }))
+  log(`   🪨 terrain roughness: ${kept.map((l, i) => `${l.name} ${l.mask ? "mask alpha" : "flat"} ×${layers[i].roughness.toFixed(2)}`).join(", ")}`)
+  writeTerrainFile(file, res, res, t.size[0] / (res - 1), heights, control, layers)
+  log(`🏔  terrain ${res}² · ${r3(t.size[0] / (res - 1))} m cells · layers ${kept.map((l) => l.name).join(", ")}${plan.mergeInto.size ? ` (merged: ${[ ...plan.mergeInto ].map(([ a, b ]) => `${t.layers[a].name} → ${t.layers[b].name}`).join(", ")})` : ""}`)
+  const { packTerrainTextures } = await import("../terrainPack")
+  const packed = await packTerrainTextures(kept.map((l) => ({ name: l.name.replace(/^LAYER_/i, "").toLowerCase(), albedo: l.diffuse!, normal: l.normal ?? undefined, smoothnessAlpha: l.mask ?? undefined, albedoScale: l.albedoScale })), { outDir: dir, size: 1024, png: opts.ktx2 === false, log: () => {} })
+  return { file, layers: packed.layers.map((l) => l.file), normals: packed.normals }
+}
+