lecodes-assets 0.2.1 → 2.4.10

package/src/unity/serialized.ts

@@ -0,0 +1,242 @@
+// Unity's BINARY serialised files (`SerializedFile`: a `.asset` / `.prefab` / `.unity` written with
+// "Mixed" or "Force Binary" serialisation, TerrainData always) → plain objects, driven by the TYPE TREE
+// the editor stores next to the data. No per-class knowledge: every field comes back under its
+// serialised name (`m_Heightmap.m_Heights`, `m_SplatDatabase.m_AlphaTextures` …), vectors of
+// primitives as typed arrays (a 1025² heightmap is one Int16Array, not a million numbers), strings
+// decoded, `TypelessData` (texture pixels) as bytes.
+//
+// Files without a type tree (player builds) are refused — the editor always writes one. Format
+// versions 9 … 22 (Unity 5 … 2022+); layout per UnityPy's SerializedFile reader.
+
+import { readFileSync } from "node:fs"
+
+export type UValue = number | bigint | boolean | string | UValue[] | Uint8Array | Int8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | { [k: string]: UValue }
+export type UObject = { [k: string]: UValue }
+
+type TypeNode = { type: string, name: string, byteSize: number, level: number, isArray: boolean, align: boolean, children: TypeNode[] }
+type SType = { classID: number, root: TypeNode | null }
+export type SObjectInfo = { pathID: bigint, byteStart: number, byteSize: number, classID: number, type: SType }
+export type SExternal = { guid: string, type: number, path: string }
+
+// Unity's built-in string table: a type-tree string offset with the high bit set indexes into this.
+const COMMON = "AABB\0AnimationClip\0AnimationCurve\0AnimationState\0Array\0Base\0BitField\0bitset\0bool\0char\0ColorRGBA\0Component\0data\0deque\0double\0dynamic_array\0FastPropertyName\0first\0float\0Font\0GameObject\0Generic Mono\0GradientNEW\0GUID\0GUIStyle\0int\0list\0long long\0map\0Matrix4x4f\0MdFour\0MonoBehaviour\0MonoScript\0m_ByteSize\0m_Curve\0m_EditorClassIdentifier\0m_EditorHideFlags\0m_Enabled\0m_ExtensionPtr\0m_GameObject\0m_Index\0m_IsArray\0m_IsStatic\0m_MetaFlag\0m_Name\0m_ObjectHideFlags\0m_PrefabInternal\0m_PrefabParentObject\0m_Script\0m_StaticEditorFlags\0m_Type\0m_Version\0Object\0pair\0PPtr<Component>\0PPtr<GameObject>\0PPtr<Material>\0PPtr<MonoBehaviour>\0PPtr<MonoScript>\0PPtr<Object>\0PPtr<Prefab>\0PPtr<Sprite>\0PPtr<TextAsset>\0PPtr<Texture>\0PPtr<Texture2D>\0PPtr<Transform>\0Prefab\0Quaternionf\0Rectf\0RectInt\0RectOffset\0second\0set\0short\0size\0SInt16\0SInt32\0SInt64\0SInt8\0staticvector\0string\0TextAsset\0TextMesh\0Texture\0Texture2D\0Transform\0TypelessData\0UInt16\0UInt32\0UInt64\0UInt8\0unsigned int\0unsigned long long\0unsigned short\0vector\0Vector2f\0Vector3f\0Vector4f\0m_ScriptingClassIdentifier\0Gradient\0Type*\0int2_storage\0int3_storage\0BoundsInt\0m_CorrespondingSourceObject\0m_PrefabInstance\0m_PrefabAsset\0FileSize\0Hash128\0"
+const cstrAt = (s: string, off: number): string => { const e = s.indexOf("\0", off); return s.slice(off, e < 0 ? undefined : e) }
+
+class Reader {
+  pos = 0
+  readonly dv: DataView
+  constructor(readonly bytes: Uint8Array, public little = false) { this.dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength) }
+  u8(): number { return this.dv.getUint8(this.pos++) }
+  i16(): number { const v = this.dv.getInt16(this.pos, this.little); this.pos += 2; return v }
+  u16(): number { const v = this.dv.getUint16(this.pos, this.little); this.pos += 2; return v }
+  i32(): number { const v = this.dv.getInt32(this.pos, this.little); this.pos += 4; return v }
+  u32(): number { const v = this.dv.getUint32(this.pos, this.little); this.pos += 4; return v }
+  i64(): bigint { const v = this.dv.getBigInt64(this.pos, this.little); this.pos += 8; return v }
+  u64(): bigint { const v = this.dv.getBigUint64(this.pos, this.little); this.pos += 8; return v }
+  f32(): number { const v = this.dv.getFloat32(this.pos, this.little); this.pos += 4; return v }
+  f64(): number { const v = this.dv.getFloat64(this.pos, this.little); this.pos += 8; return v }
+  align(n = 4): void { this.pos = (this.pos + n - 1) & ~(n - 1) }
+  cstr(): string { let e = this.pos; while (e < this.bytes.length && this.bytes[e] !== 0) e++; const s = new TextDecoder().decode(this.bytes.subarray(this.pos, e)); this.pos = e + 1; return s }
+  take(n: number): Uint8Array { const b = this.bytes.subarray(this.pos, this.pos + n); this.pos += n; return b }
+}
+
+// ---- the file -------------------------------------------------------------------------------------
+
+export type SerializedFile = {
+  version: number
+  unityVersion: string
+  objects: SObjectInfo[]
+  externals: SExternal[]
+  /** Deserialize one object through its type tree. */
+  read: (o: SObjectInfo) => UObject
+  byPathID: (id: bigint | number | string) => SObjectInfo | undefined
+}
+
+export const isSerializedFile = (bytes: Uint8Array): boolean => {
+  if (bytes.length < 20 || (bytes[0] === 0x25 && bytes[1] === 0x59)) return false        // "%YAML"
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const version = dv.getUint32(8)
+  return version >= 9 && version <= 30
+}
+
+export const openSerializedFile = (pathOrBytes: string | Uint8Array): SerializedFile => {
+  const bytes = typeof pathOrBytes === "string" ? new Uint8Array(readFileSync(pathOrBytes)) : pathOrBytes
+  const r = new Reader(bytes, false)
+  let metadataSize = r.u32(); let fileSize: number = r.u32()
+  const version = r.u32()
+  let dataOffset: number = r.u32()
+  if (version < 9) throw new Error(`SerializedFile version ${version} is too old (Unity < 5)`)
+  const endian = r.u8(); r.take(3)
+  if (version >= 22) { metadataSize = r.u32(); fileSize = Number(r.i64()); dataOffset = Number(r.i64()); r.i64() }
+  void metadataSize; void fileSize
+  r.little = endian === 0
+
+  const unityVersion = r.cstr()
+  r.i32()                                                                  // target platform
+  const typeTree = r.u8() !== 0
+  if (!typeTree) throw new Error("SerializedFile has no type tree (a player build?) — only editor-written assets are readable")
+
+  const readType = (isRef: boolean): SType => {
+    const classID = r.i32()
+    if (version >= 16) r.u8()                                              // stripped
+    const scriptIndex = version >= 17 ? r.i16() : -1
+    if (version >= 13) {
+      if ((isRef && scriptIndex >= 0) || (version < 16 && classID < 0) || (version >= 16 && classID === 114)) r.take(16)
+      r.take(16)
+    }
+    let root: TypeNode | null = null
+    if (version >= 12 || version === 10) root = readTreeBlob()
+    else throw new Error(`SerializedFile version ${version}: legacy type tree not supported`)
+    if (version >= 21) {
+      if (isRef) { r.cstr(); r.cstr(); r.cstr() } else { const n = r.i32(); r.take(n * 4) }
+    }
+    return { classID, root }
+  }
+  const readTreeBlob = (): TypeNode => {
+    const count = r.i32(), strLen = r.i32()
+    const raw: { ver: number, level: number, flags: number, typeOff: number, nameOff: number, byteSize: number, meta: number }[] = []
+    for (let i = 0; i < count; i++) {
+      const ver = r.u16(), level = r.u8(), flags = r.u8(), typeOff = r.u32(), nameOff = r.u32(), byteSize = r.i32()
+      r.i32()                                                              // index
+      const meta = r.i32()
+      if (version >= 19) r.u64()                                           // ref type hash
+      raw.push({ ver, level, flags, typeOff, nameOff, byteSize, meta })
+    }
+    const strs = new TextDecoder().decode(r.take(strLen))
+    const str = (off: number): string => (off & 0x80000000 ? cstrAt(COMMON, off & 0x7fffffff) : cstrAt(strs, off))
+    const nodes: TypeNode[] = raw.map((n) => ({ type: str(n.typeOff), name: str(n.nameOff), byteSize: n.byteSize, level: n.level, isArray: (n.flags & 1) !== 0, align: (n.meta & 0x4000) !== 0, children: [] }))
+    const stack: TypeNode[] = []
+    for (const n of nodes) {
+      while (stack.length && stack[stack.length - 1].level >= n.level) stack.pop()
+      if (stack.length) stack[stack.length - 1].children.push(n)
+      stack.push(n)
+    }
+    return nodes[0]
+  }
+
+  const types: SType[] = []
+  const typeCount = r.i32()
+  for (let i = 0; i < typeCount; i++) types.push(readType(false))
+
+  if (version >= 7 && version < 14) r.i32()                                // big ID enabled
+  const objects: SObjectInfo[] = []
+  const objCount = r.i32()
+  for (let i = 0; i < objCount; i++) {
+    if (version >= 14) r.align(4)
+    const pathID = version >= 14 ? r.i64() : BigInt(r.i32())
+    const byteStart = version >= 22 ? Number(r.i64()) : r.u32()
+    const byteSize = r.u32()
+    const typeID = r.i32()
+    let classID: number
+    let type: SType
+    if (version < 16) { classID = r.u16(); type = types.find((t) => t.classID === typeID) ?? { classID, root: null } }
+    else { type = types[typeID]; classID = type.classID }
+    if (version < 11) r.u16()
+    if (version >= 11 && version < 17) r.i16()
+    if (version === 15 || version === 16) r.u8()
+    objects.push({ pathID, byteStart: dataOffset + byteStart, byteSize, classID, type })
+  }
+  if (version >= 11) {
+    const n = r.i32()
+    for (let i = 0; i < n; i++) { r.i32(); if (version >= 14) { r.align(4); r.i64() } else r.i32() }
+  }
+  const externals: SExternal[] = []
+  const extCount = r.i32()
+  for (let i = 0; i < extCount; i++) {
+    if (version >= 6) r.cstr()
+    let guid = ""
+    let type = 0
+    if (version >= 5) {
+      // GUID bytes → Unity's text form: each byte's nibbles swapped (low nibble first)
+      const g = r.take(16)
+      for (let k = 0; k < 16; k++) guid += (g[k] & 15).toString(16) + (g[k] >> 4).toString(16)
+      type = r.i32()
+    }
+    externals.push({ guid, type, path: r.cstr() })
+  }
+
+  const byId = new Map<string, SObjectInfo>()
+  for (const o of objects) byId.set(o.pathID.toString(), o)
+
+  const read = (o: SObjectInfo): UObject => {
+    if (!o.type.root) throw new Error(`object ${o.pathID}: no type tree for class ${o.classID}`)
+    const dr = new Reader(bytes, r.little)
+    dr.pos = o.byteStart
+    const v = readNode(dr, o.type.root)
+    return v as UObject
+  }
+  return { version, unityVersion, objects, externals, read, byPathID: (id) => byId.get(String(id)) }
+}
+
+// ---- values ---------------------------------------------------------------------------------------
+
+const PRIM: Record<string, (r: Reader) => UValue> = {
+  bool: (r) => r.u8() !== 0, SInt8: (r) => (r.u8() << 24) >> 24, UInt8: (r) => r.u8(), char: (r) => r.u8(),
+  short: (r) => r.i16(), SInt16: (r) => r.i16(), UInt16: (r) => r.u16(), "unsigned short": (r) => r.u16(),
+  int: (r) => r.i32(), SInt32: (r) => r.i32(), UInt32: (r) => r.u32(), "unsigned int": (r) => r.u32(), "Type*": (r) => r.u32(),
+  "long long": (r) => r.i64(), SInt64: (r) => r.i64(), UInt64: (r) => r.u64(), "unsigned long long": (r) => r.u64(), FileSize: (r) => r.u64(),
+  float: (r) => r.f32(), double: (r) => r.f64(),
+}
+// Typed-array fast path for vectors of primitives (heightmaps, index buffers …). Copies, so the
+// result stays valid and aligned whatever the source offset.
+const TYPED: Record<string, (b: Uint8Array, n: number, little: boolean) => UValue> = {
+  UInt8: (b) => b.slice(), char: (b) => b.slice(), bool: (b) => b.slice(), SInt8: (b) => new Int8Array(b.slice().buffer),
+  SInt16: (b, n, l) => fill(new Int16Array(n), b, 2, (dv, o) => dv.getInt16(o, l)), short: (b, n, l) => fill(new Int16Array(n), b, 2, (dv, o) => dv.getInt16(o, l)),
+  UInt16: (b, n, l) => fill(new Uint16Array(n), b, 2, (dv, o) => dv.getUint16(o, l)), "unsigned short": (b, n, l) => fill(new Uint16Array(n), b, 2, (dv, o) => dv.getUint16(o, l)),
+  SInt32: (b, n, l) => fill(new Int32Array(n), b, 4, (dv, o) => dv.getInt32(o, l)), int: (b, n, l) => fill(new Int32Array(n), b, 4, (dv, o) => dv.getInt32(o, l)),
+  UInt32: (b, n, l) => fill(new Uint32Array(n), b, 4, (dv, o) => dv.getUint32(o, l)), "unsigned int": (b, n, l) => fill(new Uint32Array(n), b, 4, (dv, o) => dv.getUint32(o, l)),
+  float: (b, n, l) => fill(new Float32Array(n), b, 4, (dv, o) => dv.getFloat32(o, l)),
+  double: (b, n, l) => fill(new Float64Array(n), b, 8, (dv, o) => dv.getFloat64(o, l)),
+}
+const fill = <T extends { length: number, [i: number]: number }>(out: T, b: Uint8Array, size: number, get: (dv: DataView, o: number) => number): T => {
+  const dv = new DataView(b.buffer, b.byteOffset, b.byteLength)
+  for (let i = 0; i < out.length; i++) out[i] = get(dv, i * size)
+  return out
+}
+
+const readArray = (r: Reader, node: TypeNode): UValue => {
+  // node = the "Array" node: children [size, data]
+  const n = r.i32()
+  const elem = node.children[1]
+  let out: UValue
+  if (elem.children.length === 0 && TYPED[elem.type] && elem.byteSize > 0) out = TYPED[elem.type](r.take(n * elem.byteSize), n, r.little)
+  else { const a: UValue[] = []; for (let i = 0; i < n; i++) a.push(readNode(r, elem)); out = a }
+  if (node.align) r.align(4)
+  return out
+}
+
+const readNode = (r: Reader, node: TypeNode): UValue => {
+  let v: UValue
+  if (node.isArray) return readArray(r, node)
+  if (node.type === "string") {
+    const n = r.i32()
+    v = new TextDecoder().decode(r.take(n))
+    if (node.align || node.children[0]?.align) r.align(4)
+    return v
+  }
+  if (node.type === "TypelessData") {
+    const n = r.i32()
+    v = r.take(n).slice()
+    if (node.align) r.align(4)
+    return v
+  }
+  if (node.children.length === 0) {
+    const p = PRIM[node.type]
+    if (!p) throw new Error(`unknown primitive '${node.type}' (${node.name})`)
+    v = p(r)
+  } else if (node.children.length === 1 && node.children[0].isArray) {
+    v = readArray(r, node.children[0])
+  } else {
+    const o: UObject = {}
+    for (const c of node.children) o[c.name] = readNode(r, c)
+    v = o
+  }
+  if (node.align) r.align(4)
+  return v
+}
+
+/** A PPtr field → { fileID, pathID } (fileID 0 = this file, n = externals[n − 1]). */
+export const pptr = (v: UValue | undefined): { fileID: number, pathID: bigint } => {
+  const o = (v && typeof v === "object" && !ArrayBuffer.isView(v) && !Array.isArray(v) ? v : {}) as UObject
+  return { fileID: Number(o.m_FileID ?? 0), pathID: BigInt((o.m_PathID as number | bigint | undefined) ?? 0) }
+}

package/src/unity/terrain.ts

@@ -0,0 +1,221 @@
+// Unity TerrainData (`.asset`, binary-serialised — the editor always writes it binary) → what a
+// LeCodes terrain and the level around it need: the heightmap in metres, the splat weights per sample,
+// the terrain layers (textures + tiling from the `.terrainlayer` files), and the TREES and DETAIL
+// objects painted on it as ordinary placements of their prefabs.
+//
+// Frames: Unity's terrain grows +X across columns and +Z across rows from its transform. Everything
+// here stays in UNITY's frame (the heights row-major, row = z); the caller mirrors — see
+// `toLeCodesGrid`.
+
+import { readFileSync } from "node:fs"
+import { isSerializedFile, openSerializedFile, pptr, type SerializedFile, type UObject, type UValue } from "./serialized"
+import { num, readUnityObjects, ref, vec3, isMap, type Vec3 } from "./yaml"
+import type { GuidResolver } from "./guid"
+
+export type UnityTerrainLayer = {
+  name: string
+  /** Absolute paths (null = not found). */
+  diffuse: string | null
+  normal: string | null
+  mask: string | null
+  /** Metres per texture repeat (Unity m_TileSize). */
+  tileSize: [number, number]
+  normalScale: number
+  metallic: number
+  smoothness: number
+  /** Unity `m_DiffuseRemapMax` RGB — a per-channel scale on the sampled albedo (a tint the artist dialled on the layer;
+   *  remap-min is taken as 0). 1 = untouched. */
+  albedoScale: [number, number, number]
+}
+
+export type UnityTreePlacement = {
+  prefab: string                            // prefab GUID
+  /** Unity world position (terrain origin applied). */
+  position: Vec3
+  /** Yaw in radians (Unity: around +Y). */
+  rotation: number
+  widthScale: number
+  heightScale: number
+}
+
+export type UnityTerrain = {
+  name: string
+  /** Samples per side. */
+  resolution: number
+  /** Terrain size in metres (x, height, z). */
+  size: Vec3
+  /** Transform position of the terrain object (Unity world). */
+  origin: Vec3
+  /** Heights in metres above `origin.y`, row-major (row = z), resolution². */
+  heights: Float32Array
+  /** Per-layer weight maps at `alphaResolution`², 0–255, row-major (row = z); one array per layer. */
+  weights: Uint8Array[]
+  alphaResolution: number
+  layers: UnityTerrainLayer[]
+  trees: UnityTreePlacement[]
+  details: UnityTreePlacement[]
+  /** Prototypes the importer could not use (texture-billboard grass, missing prefabs). */
+  skipped: string[]
+}
+
+const obj = (v: UValue | undefined): UObject => (v && typeof v === "object" && !Array.isArray(v) && !ArrayBuffer.isView(v) ? v as UObject : {})
+const arr = (v: UValue | undefined): UValue[] => (Array.isArray(v) ? v : [])
+
+/** The GUID of an external PPtr (fileID ≥ 1), null for a local / empty one. */
+const extGuid = (f: SerializedFile, v: UValue | undefined): string | null => {
+  const p = pptr(v)
+  if (p.fileID <= 0) return null
+  return f.externals[p.fileID - 1]?.guid ?? null
+}
+
+const readLayer = (resolver: GuidResolver, guid: string): UnityTerrainLayer | null => {
+  const path = resolver.resolve(guid)
+  if (!path) return null
+  const bytes = new Uint8Array(readFileSync(path))
+  let body: Record<string, unknown> = {}
+  let name = path.replace(/^.*[\\/]/, "").replace(/\.terrainlayer$/i, "")
+  if (isSerializedFile(bytes)) {
+    const f = openSerializedFile(bytes)
+    const o = f.objects[0]
+    if (!o) return null
+    const v = f.read(o)
+    const g = (k: string): string | null => extGuid(f, v[k])
+    const ts = obj(v.m_TileSize)
+    return {
+      name: String(v.m_Name ?? name), diffuse: resolvePath(resolver, g("m_DiffuseTexture")), normal: resolvePath(resolver, g("m_NormalMapTexture")),
+      mask: resolvePath(resolver, g("m_MaskMapTexture")), tileSize: [ Number(ts.x ?? 15), Number(ts.y ?? 15) ],
+      normalScale: Number(v.m_NormalScale ?? 1), metallic: Number(v.m_Metallic ?? 0), smoothness: Number(v.m_Smoothness ?? 0),
+      albedoScale: [ Number(obj(v.m_DiffuseRemapMax).x ?? 1), Number(obj(v.m_DiffuseRemapMax).y ?? 1), Number(obj(v.m_DiffuseRemapMax).z ?? 1) ],
+    }
+  }
+  const objs = readUnityObjects(new TextDecoder().decode(bytes))
+  body = objs.find((o) => o.cls === "TerrainLayer")?.body ?? {}
+  const b = body as Record<string, never>
+  name = String(b.m_Name || name)
+  const g = (k: string): string | null => ref(b[k]).guid ?? null
+  const ts = vec3(b.m_TileSize, [ 15, 15, 0 ])
+  return {
+    name, diffuse: resolvePath(resolver, g("m_DiffuseTexture")), normal: resolvePath(resolver, g("m_NormalMapTexture")),
+    mask: resolvePath(resolver, g("m_MaskMapTexture")), tileSize: [ ts[0], ts[1] ],
+    normalScale: num(b.m_NormalScale, 1), metallic: num(b.m_Metallic, 0), smoothness: num(b.m_Smoothness, 0),
+    albedoScale: (() => { const r = vec3(b.m_DiffuseRemapMax, [ 1, 1, 1 ]); return [ r[0], r[1], r[2] ] as [number, number, number] })(),
+  }
+}
+const resolvePath = (r: GuidResolver, g: string | null): string | null => (g ? r.resolve(g) : null)
+
+/** Unity's heightmap integers are 0 … 32766 for 0 … size.y. */
+const HEIGHT_MAX = 32766
+
+// Unity scatters detail objects inside each cell with its own RNG; a seeded jitter is the honest
+// stand-in (same counts per cell, positions deterministic across runs).
+const mulberry = (seed: number): (() => number) => () => {
+  seed |= 0; seed = (seed + 0x6d2b79f5) | 0
+  let t = Math.imul(seed ^ (seed >>> 15), 1 | seed)
+  t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+  return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+}
+
+export const readUnityTerrain = (terrainDataPath: string, origin: Vec3, resolver: GuidResolver): UnityTerrain => {
+  const bytes = new Uint8Array(readFileSync(terrainDataPath))
+  if (!isSerializedFile(bytes)) throw new Error(`${terrainDataPath}: a text-serialised TerrainData is not supported (Unity writes them binary)`)
+  const f = openSerializedFile(bytes)
+  const tdInfo = f.objects.find((o) => o.classID === 156)
+  if (!tdInfo) throw new Error(`${terrainDataPath}: no TerrainData inside`)
+  const td = f.read(tdInfo)
+  const hm = obj(td.m_Heightmap)
+  const res = Number(hm.m_Resolution)
+  const scale = obj(hm.m_Scale)
+  const size: Vec3 = [ Number(scale.x) * (res - 1), Number(scale.y), Number(scale.z) * (res - 1) ]
+  const raw = hm.m_Heights as Int16Array
+  const heights = new Float32Array(res * res)
+  for (let i = 0; i < heights.length; i++) heights[i] = (raw[i] / HEIGHT_MAX) * size[1]
+
+  // splat weights: every alpha texture carries four layers in R, G, B, A
+  const splat = obj(td.m_SplatDatabase)
+  const layerGuids = arr(splat.m_TerrainLayers).map((v) => extGuid(f, v))
+  const layers: UnityTerrainLayer[] = []
+  const skipped: string[] = []
+  for (const g of layerGuids) {
+    const l = g ? readLayer(resolver, g) : null
+    if (l) layers.push(l)
+    else { skipped.push(`terrain layer ${g ?? "?"}`); layers.push({ name: "missing", diffuse: null, normal: null, mask: null, tileSize: [ 15, 15 ], normalScale: 1, metallic: 0, smoothness: 0, albedoScale: [ 1, 1, 1 ] }) }
+  }
+  const weights: Uint8Array[] = []
+  let alphaRes = Number(splat.m_AlphamapResolution ?? 0)
+  arr(splat.m_AlphaTextures).forEach((v) => {
+    const info = f.byPathID(pptr(v).pathID)
+    const tex = info ? f.read(info) : null
+    if (!tex) return
+    const w = Number(tex.m_Width), h = Number(tex.m_Height), fmt = Number(tex.m_TextureFormat)
+    const img = tex["image data"] as Uint8Array
+    alphaRes = w
+    // TextureFormat: 4 = RGBA32 (bytes R G B A), 5 = ARGB32 (bytes A R G B)
+    const chan = fmt === 5 ? [ 1, 2, 3, 0 ] : fmt === 4 ? [ 0, 1, 2, 3 ] : null
+    if (!chan || !img || img.length < w * h * 4) { skipped.push(`splat ${String(tex.m_Name)} (format ${fmt})`); for (let c = 0; c < 4; c++) weights.push(new Uint8Array(w * h)); return }
+    for (let c = 0; c < 4; c++) {
+      const out = new Uint8Array(w * h)
+      for (let i = 0; i < w * h; i++) out[i] = img[i * 4 + chan[c]]
+      weights.push(out)
+    }
+  })
+  weights.length = layers.length
+
+  // trees: normalised positions on the terrain, one prefab per prototype
+  const dd = obj(td.m_DetailDatabase)
+  const protos = arr(dd.m_TreePrototypes).map((p) => extGuid(f, obj(p).prefab))
+  const trees: UnityTreePlacement[] = []
+  for (const t of arr(dd.m_TreeInstances)) {
+    const o = obj(t)
+    const g = protos[Number(o.index)]
+    if (!g) continue
+    const p = obj(o.position)
+    trees.push({
+      prefab: g,
+      position: [ origin[0] + Number(p.x) * size[0], origin[1] + Number(p.y) * size[1], origin[2] + Number(p.z) * size[2] ],
+      rotation: Number(o.rotation ?? 0), widthScale: Number(o.widthScale ?? 1), heightScale: Number(o.heightScale ?? 1),
+    })
+  }
+
+  // details: per patch, per layer, a count per cell — mesh prototypes only (texture grass has no prefab)
+  const dprotos = arr(dd.m_DetailPrototypes).map((p) => {
+    const o = obj(p)
+    const g = Number(o.usePrototypeMesh) ? extGuid(f, o.prototype) : null
+    return { guid: g, minW: Number(o.minWidth ?? 1), maxW: Number(o.maxWidth ?? 1), minH: Number(o.minHeight ?? 1), maxH: Number(o.maxHeight ?? 1) }
+  })
+  const patchCount = Number(dd.m_PatchCount ?? 0), patchSamples = Number(dd.m_PatchSamples ?? 0)
+  const details: UnityTreePlacement[] = []
+  const rnd = mulberry(0x7e11a1)
+  const cellX = size[0] / (patchCount * patchSamples), cellZ = size[2] / (patchCount * patchSamples)
+  const heightAt = (x: number, z: number): number => {
+    const fx = Math.min(res - 1.0001, Math.max(0, x / size[0] * (res - 1))), fz = Math.min(res - 1.0001, Math.max(0, z / size[2] * (res - 1)))
+    const x0 = Math.floor(fx), z0 = Math.floor(fz), tx = fx - x0, tz = fz - z0
+    const h = (i: number, j: number): number => heights[j * res + i]
+    return (h(x0, z0) * (1 - tx) + h(x0 + 1, z0) * tx) * (1 - tz) + (h(x0, z0 + 1) * (1 - tx) + h(x0 + 1, z0 + 1) * tx) * tz
+  }
+  arr(dd.m_Patches).forEach((patch, pi) => {
+    const o = obj(patch)
+    const li = o.layerIndices as Uint8Array
+    const counts = o.numberOfObjects as Uint8Array
+    if (!li?.length) return
+    const px = pi % patchCount, pz = Math.floor(pi / patchCount)
+    for (let k = 0; k < li.length; k++) {
+      const proto = dprotos[li[k]]
+      if (!proto?.guid) { skipped.push(`detail layer ${li[k]} (texture grass)`); continue }
+      for (let cz = 0; cz < patchSamples; cz++) for (let cx = 0; cx < patchSamples; cx++) {
+        const n = counts[k * patchSamples * patchSamples + cz * patchSamples + cx] ?? 0
+        for (let i = 0; i < n; i++) {
+          const x = (px * patchSamples + cx + rnd()) * cellX, z = (pz * patchSamples + cz + rnd()) * cellZ
+          const w = proto.minW + rnd() * (proto.maxW - proto.minW)
+          const hsc = proto.minH + rnd() * (proto.maxH - proto.minH)
+          details.push({ prefab: proto.guid, position: [ origin[0] + x, origin[1] + heightAt(x, z), origin[2] + z ], rotation: rnd() * Math.PI * 2, widthScale: w, heightScale: hsc })
+        }
+      }
+    }
+  })
+
+  return { name: String(td.m_Name ?? "terrain"), resolution: res, size, origin, heights, weights, alphaResolution: alphaRes, layers, trees, details, skipped: [ ...new Set(skipped) ] }
+}
+
+/** The terrain component of a scene: its TerrainData GUID and transform position. */
+export const terrainDataRef = (body: Record<string, unknown>): string | null => ref((body as { m_TerrainData?: never }).m_TerrainData).guid ?? null
+export { isMap }

package/src/unity/triBudget.ts

@@ -0,0 +1,77 @@
+// A TRIANGLE BUDGET PER KIND. Packs and hand-assembled projects carry photogrammetry scans as props:
+// Peremena's open herbarium is 1 057 824 triangles (81 MB of GLB) and a single book 170 000 — on a
+// school desk, next to 500-triangle furniture. Imported as they are, they are not merely heavy: their
+// MESH COLLIDER (the scene file's `Shape { mesh: true }` is built from the GLB) took the headless
+// renderer's physics down with an out-of-bounds abort before the first frame.
+//
+// So a kind over the budget is simplified at import (meshoptimizer, the same weld + simplify the doctor's
+// LOD pass runs), all of its primitives by one ratio. A scan's look lives in its normal map, which the
+// simplified surface keeps (the UVs are preserved), and the collider shrinks with it. Skinned meshes are
+// left alone: collapsing vertices under a skin moves weights the budget knows nothing about.
+
+import { PropertyType, type Document, type Primitive } from "@gltf-transform/core"
+import { prune, simplifyPrimitive, weldPrimitive } from "@gltf-transform/functions"
+import { MeshoptSimplifier } from "meshoptimizer"
+
+export const DEFAULT_MAX_TRIS = 50_000
+
+const trisOf = (p: Primitive): number => p.getMode() !== 4 ? 0 : Math.floor((p.getIndices()?.getCount() ?? p.getAttribute("POSITION")?.getCount() ?? 0) / 3)
+
+/** Simplify the document's meshes down to about `maxTris` triangles in total. Null when it already fits. */
+export const fitTriangleBudget = async (doc: Document, maxTris: number): Promise<{ before: number, after: number } | null> => {
+  // a Set: a kind's parts that share a mesh share its primitives (kindGlb clones meshes shallowly)
+  const prims = [ ...new Set(doc.getRoot().listMeshes().flatMap((m) => m.listPrimitives())) ].filter((p) => p.getMode() === 4 && !p.getAttribute("JOINTS_0"))
+  const before = prims.reduce((n, p) => n + trisOf(p), 0)
+  if (maxTris <= 0 || before <= maxTris) return null
+  await MeshoptSimplifier.ready
+  const ratio = maxTris / before
+  for (const p of prims) {
+    const want = trisOf(p) * ratio
+    weldPrimitive(p)
+    // `error` is the ceiling on how far the surface may move, relative to the mesh's size: a scan has
+    // to go down 20× here, which a tight 1 % stops short of
+    simplifyPrimitive(p, { simplifier: MeshoptSimplifier, ratio, error: 0.05, lockBorder: false })
+    // A FACETED SCAN DOES NOT WELD: every triangle carries its own normals, so no two faces share a
+    // vertex and every edge is a seam the simplifier must keep (the herbarium: 2.1 M vertices on 0.53 M
+    // positions, 1 057 824 triangles in, 1 057 824 out). Its shading is in the normal map anyway, so the
+    // normals go, the mesh welds on position + UV and simplifies, and smooth ones are rebuilt. Tried
+    // SECOND, so hard-surface props that simplify with their normals keep their hard edges.
+    if (trisOf(p) > want * 1.5 && p.getAttribute("NORMAL")) {
+      p.setAttribute("NORMAL", null).setAttribute("TANGENT", null)
+      weldPrimitive(p)
+      simplifyPrimitive(p, { simplifier: MeshoptSimplifier, ratio: Math.min(1, want / Math.max(1, trisOf(p))), error: 0.05, lockBorder: false })
+      smoothNormals(doc, p)
+    }
+  }
+  // weld and simplify write NEW accessors: the million-triangle originals stay in the file until pruned
+  // (the herbarium was 27 MB at 50 000 triangles without this)
+  await doc.transform(prune({ propertyTypes: [ PropertyType.ACCESSOR ] }))
+  return { before, after: prims.reduce((n, p) => n + trisOf(p), 0) }
+}
+
+/** Area-weighted vertex normals, summed per POSITION so a UV seam (two vertices, one point) shades as one. */
+const smoothNormals = (doc: Document, p: Primitive): void => {
+  const pos = p.getAttribute("POSITION")!, idx = p.getIndices()
+  const n = pos.getCount()
+  const P = pos.getArray()!, I = idx ? idx.getArray()! : Uint32Array.from({ length: n }, (_, i) => i)
+  const keyOf = new Int32Array(n), sums: number[] = [], byPos = new Map<string, number>()
+  for (let i = 0; i < n; i++) {
+    const k = `${P[i * 3]},${P[i * 3 + 1]},${P[i * 3 + 2]}`
+    let s = byPos.get(k)
+    if (s === undefined) { s = byPos.size; byPos.set(k, s); sums.push(0, 0, 0) }
+    keyOf[i] = s
+  }
+  for (let t = 0; t + 2 < I.length; t += 3) {
+    const a = I[t] * 3, b = I[t + 1] * 3, c = I[t + 2] * 3
+    const ux = P[b] - P[a], uy = P[b + 1] - P[a + 1], uz = P[b + 2] - P[a + 2]
+    const vx = P[c] - P[a], vy = P[c + 1] - P[a + 1], vz = P[c + 2] - P[a + 2]
+    const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx   // |n| = 2 × area
+    for (const v of [ I[t], I[t + 1], I[t + 2] ]) { const s = keyOf[v] * 3; sums[s] += nx; sums[s + 1] += ny; sums[s + 2] += nz }
+  }
+  const out = new Float32Array(n * 3)
+  for (let i = 0; i < n; i++) {
+    const s = keyOf[i] * 3, l = Math.hypot(sums[s], sums[s + 1], sums[s + 2]) || 1
+    out[i * 3] = sums[s] / l; out[i * 3 + 1] = sums[s + 1] / l; out[i * 3 + 2] = sums[s + 2] / l
+  }
+  p.setAttribute("NORMAL", doc.createAccessor("NORMAL", pos.getBuffer()).setType("VEC3").setArray(out))
+}

package/src/unity/triplanar.ts

@@ -0,0 +1,122 @@
+// TRIPLANAR SHADER GRAPHS → REAL UVs.
+//
+// A Unity Shader Graph whose textures go through a Triplanar node samples them by POSITION, not by the
+// mesh's UVs: `uv = position × Tile`, the X face reading `.zy`, the Y face `.xz`, the Z face `.xy`,
+// blended by the normal. The mesh's own UVs are then whatever the modeller left — Peremena's school
+// shell (walls, ceiling) is one such mesh, and imported with its UVs it came out as garbage or, with
+// the graph's `_Diffuse_Tex` / `_Normal_Tex` / `_Roughness_Tex` names unknown, untextured.
+//
+// There is no triplanar material for models in the engine, and a custom one would take the surface out
+// of the lightmap (baked materials are the stock lit PBR). So the projection is BAKED into TEXCOORD_0
+// at import: per vertex, the face the vertex normal points along picks the plane, exactly the node's
+// planes. For the flat, axis-aligned surfaces triplanar is used on (walls, floors, ceilings) that IS
+// the node's picture; the blend zone on a slanted face and a smooth-shaded corner are where it
+// differs. Positions are the KIND's frame: a kind placed without rotation or scale (the school's shell)
+// matches Unity up to where the texture's tiling starts, a rotated or scaled one tiles in its own axes.
+
+import { existsSync, readFileSync } from "node:fs"
+import type { Accessor, Document, Primitive } from "@gltf-transform/core"
+import type { GuidResolver } from "./guid"
+import type { UnityMaterial } from "./matFile"
+import type { Mat4 } from "./math"
+
+export type Triplanar = { tile: number, space: "world" | "object" }
+
+type GraphObject = Record<string, any>
+
+/** A `.shadergraph` file: a run of JSON objects back to back (Unity ≥ 2021's multi-JSON format). */
+const graphObjects = (text: string): GraphObject[] => {
+  const out: GraphObject[] = []
+  let depth = 0, start = -1, inStr = false, esc = false
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    if (inStr) { if (esc) esc = false; else if (ch === "\\") esc = true; else if (ch === "\"") inStr = false; continue }
+    if (ch === "\"") inStr = true
+    else if (ch === "{") { if (depth++ === 0) start = i }
+    else if (ch === "}" && --depth === 0) { try { out.push(JSON.parse(text.slice(start, i + 1))) } catch { /* not a graph object */ } }
+  }
+  return out
+}
+
+const isType = (o: GraphObject, t: string): boolean => typeof o.m_Type === "string" && o.m_Type.endsWith(t)
+
+/** What a graph's Triplanar node samples with: its Tile (a number, or the reference name of the
+ *  material property wired into it) and its space. Null = no Triplanar node. */
+type GraphTriplanar = { tileProperty: string | null, tileDefault: number, space: "world" | "object" }
+
+const readGraph = (file: string): GraphTriplanar | null => {
+  const objs = graphObjects(readFileSync(file, "utf8"))
+  const byId = new Map<string, GraphObject>()
+  for (const o of objs) if (typeof o.m_ObjectId === "string") byId.set(o.m_ObjectId, o)
+  const node = objs.find((o) => isType(o, ".TriplanarNode"))
+  if (!node) return null
+  const slots = (node.m_Slots ?? []).map((s: GraphObject) => byId.get(s.m_Id)).filter(Boolean) as GraphObject[]
+  const tileSlot = slots.find((s) => s.m_DisplayName === "Tile")
+  const tileDefault = typeof tileSlot?.m_Value === "number" ? tileSlot.m_Value : 1
+  let tileProperty: string | null = null
+  const graph = objs.find((o) => isType(o, ".GraphData"))
+  for (const e of graph?.m_Edges ?? []) {
+    if (e.m_InputSlot?.m_Node?.m_Id !== node.m_ObjectId || e.m_InputSlot?.m_SlotId !== tileSlot?.m_Id) continue
+    const from = byId.get(e.m_OutputSlot?.m_Node?.m_Id)
+    const prop = from && isType(from, ".PropertyNode") ? byId.get(from.m_Property?.m_Id) : undefined
+    if (prop) tileProperty = prop.m_OverrideReferenceName || prop.m_DefaultReferenceName || null
+  }
+  // CoordinateSpace: 0 Object, 1 View, 2 World, 3 Tangent, 4 AbsoluteWorld
+  const space = node.m_InputSpace === 0 ? "object" : "world"
+  return { tileProperty, tileDefault, space }
+}
+
+/** Per resolver: shader guid → its triplanar read (null = none / not a graph). */
+const graphs = new WeakMap<GuidResolver, Map<string, GraphTriplanar | null>>()
+
+/** The triplanar projection a material's shader samples its textures with, or null. */
+export const triplanarOf = (um: UnityMaterial, resolver: GuidResolver): Triplanar | null => {
+  if (!um.shader.startsWith("guid:")) return null
+  const guid = um.shader.slice(5)
+  let cache = graphs.get(resolver)
+  if (!cache) graphs.set(resolver, cache = new Map())
+  if (!cache.has(guid)) {
+    const file = resolver.resolve(guid)
+    cache.set(guid, file && /\.shadergraph$/i.test(file) && existsSync(file) ? readGraph(file) : null)
+  }
+  const g = cache.get(guid)
+  if (!g) return null
+  const tile = g.tileProperty !== null ? um.floats[g.tileProperty] ?? g.tileDefault : g.tileDefault
+  return { tile: tile > 0 ? tile : 1, space: g.space }
+}
+
+const apply = (m: Mat4, p: number[], w: number): number[] => [
+  m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12] * w,
+  m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13] * w,
+  m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14] * w,
+]
+
+/**
+ * The projection's UVs for one primitive, as a new TEXCOORD_0 — `matrix` takes the primitive's
+ * positions into the frame the projection runs in (the part's node matrix: kind space). Our frame is
+ * Unity's mirrored on X, so Unity's `x` is our `−x`; glTF's V runs down where Unity's runs up.
+ * TANGENT is dropped: it belonged to the old UVs, and the engine derives one from the new ones.
+ */
+export const projectTriplanar = (doc: Document, prim: Primitive, matrix: Mat4, tile: number): boolean => {
+  const pos = prim.getAttribute("POSITION"), nrm = prim.getAttribute("NORMAL")
+  if (!pos || !nrm) return false
+  const n = pos.getCount()
+  const uv = new Float32Array(n * 2)
+  const p: number[] = [], q: number[] = []
+  // normals go through the inverse transpose; the kind matrices here are rotation × uniform-ish
+  // scale, where the matrix itself points the same way — the length is normalised away
+  for (let i = 0; i < n; i++) {
+    const [ x, y, z ] = apply(matrix, pos.getElement(i, p), 1)
+    const [ nx, ny, nz ] = apply(matrix, nrm.getElement(i, q), 0)
+    const ax = Math.abs(nx), ay = Math.abs(ny), az = Math.abs(nz)
+    const ux = -x   // Unity's x
+    const [ a, b ] = ax >= ay && ax >= az ? [ z, y ] : ay >= az ? [ ux, z ] : [ ux, y ]
+    uv[i * 2] = a * tile
+    uv[i * 2 + 1] = 1 - b * tile
+  }
+  const acc: Accessor = doc.createAccessor(prim.getName() ? `${prim.getName()}_triplanar` : "triplanar")
+    .setType("VEC2").setArray(uv).setBuffer(pos.getBuffer())
+  prim.setAttribute("TEXCOORD_0", acc)
+  prim.setAttribute("TANGENT", null)
+  return true
+}