lecodes-assets 0.2.0 → 0.2.1

package/src/unity/png.ts

@@ -0,0 +1,75 @@
+// Minimal PNG decoder — 8-bit (and 16-bit, truncated) grey / grey+alpha / RGB / RGBA / palette,
+// non-interlaced, all five scanline filters. Enough for every texture a game asset pack ships, so
+// ORM packing does not need `sharp` (an optional native dependency). Interlaced or <8-bit images
+// return null and the caller falls back to sharp / a warning.
+
+import { inflateSync } from "node:zlib"
+import type { Rgba } from "../textures/resolveImage"
+
+const u32 = (b: Uint8Array, o: number): number => ((b[o] << 24) | (b[o + 1] << 16) | (b[o + 2] << 8) | b[o + 3]) >>> 0
+
+export const decodePng = (b: Uint8Array): Rgba | null => {
+  if (b.length < 33 || b[0] !== 0x89 || b[1] !== 0x50 || b[2] !== 0x4e || b[3] !== 0x47) return null
+  let o = 8
+  let width = 0, height = 0, depth = 0, color = 0, interlace = 0
+  const idat: Uint8Array[] = []
+  let palette: Uint8Array | null = null
+  let trns: Uint8Array | null = null
+  while (o + 8 <= b.length) {
+    const len = u32(b, o)
+    const type = String.fromCharCode(b[o + 4], b[o + 5], b[o + 6], b[o + 7])
+    const data = b.subarray(o + 8, o + 8 + len)
+    if (type === "IHDR") { width = u32(data, 0); height = u32(data, 4); depth = data[8]; color = data[9]; interlace = data[12] }
+    else if (type === "PLTE") palette = data
+    else if (type === "tRNS") trns = data
+    else if (type === "IDAT") idat.push(data)
+    else if (type === "IEND") break
+    o += 12 + len
+  }
+  if (!width || !height || interlace !== 0 || (depth !== 8 && depth !== 16)) return null
+  const channels = color === 0 ? 1 : color === 2 ? 3 : color === 3 ? 1 : color === 4 ? 2 : color === 6 ? 4 : 0
+  if (!channels) return null
+  const bps = depth / 8
+  const bpp = channels * bps                      // bytes per pixel (filter unit)
+  const stride = width * bpp
+  let raw: Uint8Array
+  try {
+    const total = idat.reduce((n, c) => n + c.length, 0)
+    const joined = new Uint8Array(total)
+    let p = 0
+    for (const c of idat) { joined.set(c, p); p += c.length }
+    raw = new Uint8Array(inflateSync(joined))
+  } catch { return null }
+  if (raw.length < (stride + 1) * height) return null
+  const out = new Uint8Array(width * height * 4)
+  const prev = new Uint8Array(stride)
+  const cur = new Uint8Array(stride)
+  for (let y = 0; y < height; y++) {
+    const f = raw[y * (stride + 1)]
+    const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1))
+    for (let x = 0; x < stride; x++) {
+      const a = x >= bpp ? cur[x - bpp] : 0
+      const bb = prev[x]
+      const c = x >= bpp ? prev[x - bpp] : 0
+      let v = line[x]
+      if (f === 1) v += a
+      else if (f === 2) v += bb
+      else if (f === 3) v += (a + bb) >> 1
+      else if (f === 4) { const p = a + bb - c; const pa = Math.abs(p - a), pb = Math.abs(p - bb), pc = Math.abs(p - c); v += pa <= pb && pa <= pc ? a : pb <= pc ? bb : c }
+      cur[x] = v & 0xff
+    }
+    for (let x = 0; x < width; x++) {
+      const s = x * bpp, d = (y * width + x) * 4
+      if (color === 3) {
+        const i = cur[s]
+        out[d] = palette ? palette[i * 3] : i; out[d + 1] = palette ? palette[i * 3 + 1] : i; out[d + 2] = palette ? palette[i * 3 + 2] : i
+        out[d + 3] = trns && i < trns.length ? trns[i] : 255
+      } else if (channels === 1) { out[d] = out[d + 1] = out[d + 2] = cur[s]; out[d + 3] = 255 }
+      else if (channels === 2) { out[d] = out[d + 1] = out[d + 2] = cur[s]; out[d + 3] = cur[s + bps] }
+      else if (channels === 3) { out[d] = cur[s]; out[d + 1] = cur[s + bps]; out[d + 2] = cur[s + 2 * bps]; out[d + 3] = 255 }
+      else { out[d] = cur[s]; out[d + 1] = cur[s + bps]; out[d + 2] = cur[s + 2 * bps]; out[d + 3] = cur[s + 3 * bps] }
+    }
+    prev.set(cur)
+  }
+  return { width, height, data: out }
+}

package/src/unity/prefabs.ts

@@ -0,0 +1,80 @@
+// 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 { existsSync, readFileSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+import { parseUnityYaml } from "./scene"
+
+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)[]
+}
+
+type Y = string | Y[] | { [k: string]: Y }
+const isMap = (v: Y | undefined): v is { [k: string]: Y } => typeof v === "object" && v !== null && !Array.isArray(v)
+const guidOf = (v: Y | undefined): string | undefined => (isMap(v) && typeof v.guid === "string" ? v.guid : undefined)
+const idOf = (v: Y | undefined): string => (isMap(v) ? String(v.fileID ?? "0") : "0")
+
+/** 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
+  const re = /^--- !u!(\d+) &(-?\d+)( stripped)?\s*$/gm
+  const starts: { idx: number, end: number }[] = []
+  for (let m = re.exec(text); m; m = re.exec(text)) starts.push({ idx: m.index, end: m.index + m[0].length })
+  for (let i = 0; i < starts.length; i++) {
+    const chunk = text.slice(starts[i].end, i + 1 < starts.length ? starts[i + 1].idx : text.length)
+    const doc = parseUnityYaml(chunk)
+    const cls = Object.keys(doc)[0] ?? ""
+    const body = doc[cls]
+    if (!isMap(body)) continue
+    const id = /&(-?\d+)/.exec(text.slice(starts[i].idx, starts[i].end))?.[1] ?? ""
+    if (cls === "GameObject" && typeof body.m_Name === "string") names.set(id, body.m_Name)
+    else if (cls === "MeshFilter") meshes.set(idOf(body.m_GameObject), guidOf(body.m_Mesh))
+    else if (cls === "MeshRenderer" || cls === "SkinnedMeshRenderer") {
+      const mats = Array.isArray(body.m_Materials) ? body.m_Materials.map((m) => guidOf(m)) : []
+      renderers.set(idOf(body.m_GameObject), mats)
+      if (cls === "SkinnedMeshRenderer") meshes.set(idOf(body.m_GameObject), guidOf(body.m_Mesh))
+    }
+  }
+  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[] = []
+  const walk = (dir: string, d: number): void => {
+    if (d < 0 || !existsSync(dir)) return
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      const p = join(dir, e.name)
+      if (e.isDirectory()) { if (!e.name.startsWith(".")) walk(p, d - 1) }
+      else if (/\.prefab$/i.test(e.name)) files.push(p)
+    }
+  }
+  for (const d of dirs) walk(d, depth)
+  const out: PrefabOverride[] = []
+  for (const f of [ ...new Set(files) ]) out.push(...readPrefabOverrides(f))
+  return out
+}

package/src/unity/scene.ts

@@ -0,0 +1,363 @@
+// Unity scene (`.unity`, text-serialised YAML) → a level description: every placed prefab instance
+// and mesh object with its world transform, already in LeCodes' frame, plus a table of the prefabs
+// used (and a best guess at the FBX + node each one renders). The vendor's demo map becomes a JSON
+// a `level.ts` can walk: one `Model.load` per prefab, one `clone()` per instance.
+//
+// What is read: `PrefabInstance` (source prefab GUID, the m_LocalPosition/Rotation/Scale + m_Name +
+// m_IsActive overrides, the transform it is parented to), `Transform` / `GameObject` (the scene's
+// own hierarchy: groups like "Static/Roads", plain mesh objects via `MeshFilter`). Parents that are
+// themselves inside a prefab instance ("stripped" transforms) resolve to that instance's transform —
+// the prefab's internal offsets live in the prefab file, which the big packs ship binary-serialised,
+// so a child parented deep inside a prefab lands at the prefab's root (counted in `approximate`).
+//
+// Frame: Unity is left-handed (+Z forward); glTF/LeCodes right-handed. Unity's FBX importer mirrors
+// X, so undoing it is: position (−x, y, z), quaternion (x, −y, −z, w), scale unchanged — the
+// UnityGLTF convention. `handedness: "z"` mirrors Z instead (for content authored in Unity itself),
+// `"none"` keeps Unity's numbers.
+
+import { existsSync, readFileSync } from "node:fs"
+import { basename, dirname, resolve } from "node:path"
+import { findUnityIndex } from "./materials"
+
+// ---- a YAML subset parser (what Unity writes: block maps/sequences, flow maps, scalars) ----------
+
+export type Y = string | Y[] | { [k: string]: Y }
+type Line = { indent: number, text: string }
+
+const splitLines = (text: string): Line[] => {
+  const raw = text.split(/\r?\n/)
+  const out: Line[] = []
+  for (let i = 0; i < raw.length; i++) {
+    let l = raw[i]
+    if (!l.trim() || l.startsWith("%")) continue
+    // wrapped flow maps: `{fileID: 1, guid: abc,` ⏎ `  type: 3}`
+    let open = (l.match(/\{/g) ?? []).length - (l.match(/\}/g) ?? []).length
+    while (open > 0 && i + 1 < raw.length) {
+      const nx = raw[++i]
+      l += " " + nx.trim()
+      open += (nx.match(/\{/g) ?? []).length - (nx.match(/\}/g) ?? []).length
+    }
+    const indent = l.length - l.trimStart().length
+    out.push({ indent, text: l.trim() })
+  }
+  return out
+}
+
+const scalar = (s: string): Y => {
+  s = s.trim()
+  if (s === "" || s === "~" || s === "null") return ""
+  if (s === "[]") return []
+  if (s === "{}") return {}
+  if (s.startsWith("{") && s.endsWith("}")) {
+    const obj: { [k: string]: Y } = {}
+    for (const part of s.slice(1, -1).split(",")) {
+      const c = part.indexOf(":")
+      if (c < 0) continue
+      obj[part.slice(0, c).trim()] = scalar(part.slice(c + 1))
+    }
+    return obj
+  }
+  if (s.startsWith("[") && s.endsWith("]")) return s.slice(1, -1).split(",").map((x) => scalar(x))
+  if ((s.startsWith("'") && s.endsWith("'")) || (s.startsWith("\"") && s.endsWith("\""))) return s.slice(1, -1).replace(/''/g, "'")
+  return s
+}
+
+export const parseUnityYaml = (text: string): { [k: string]: Y } => {
+  const lines = splitLines(text)
+  let pos = 0
+  const parseValue = (minIndent: number): Y => {
+    if (pos >= lines.length || lines[pos].indent < minIndent) return ""
+    return lines[pos].text.startsWith("- ") || lines[pos].text === "-" ? parseSeq(lines[pos].indent) : parseMap(lines[pos].indent)
+  }
+  const parseMap = (indent: number): { [k: string]: Y } => {
+    const obj: { [k: string]: Y } = {}
+    while (pos < lines.length && lines[pos].indent === indent && !lines[pos].text.startsWith("- ")) {
+      const t = lines[pos].text
+      const c = t.search(/:( |$)/)
+      if (c < 0) { pos++; continue }
+      const key = t.slice(0, c).trim()
+      const rest = t.slice(c + 1).trim()
+      pos++
+      if (rest === "") obj[key] = pos < lines.length && lines[pos].indent > indent ? parseValue(indent + 1) : (pos < lines.length && lines[pos].indent === indent && lines[pos].text.startsWith("- ") ? parseSeq(indent) : "")
+      else obj[key] = scalar(rest)
+    }
+    return obj
+  }
+  const parseSeq = (indent: number): Y[] => {
+    const arr: Y[] = []
+    while (pos < lines.length && lines[pos].indent === indent && (lines[pos].text.startsWith("- ") || lines[pos].text === "-")) {
+      const rest = lines[pos].text.slice(1).trim()
+      if (rest === "") { pos++; arr.push(parseValue(indent + 1)); continue }
+      // a flow map / flow list / plain scalar item (`- {fileID: 0, guid: …}`) is one value, not a key
+      if (rest.startsWith("{") || rest.startsWith("[") || rest.search(/:( |$)/) < 0) { pos++; arr.push(scalar(rest)); continue }
+      // the item's first key shares the dash line; the rest of its keys sit two deeper
+      lines[pos] = { indent: indent + 2, text: rest }
+      arr.push(parseValue(indent + 2))
+    }
+    return arr
+  }
+  return parseMap(lines[0]?.indent ?? 0)
+}
+
+// ---- the scene -----------------------------------------------------------------------------------
+
+type Ref = { fileID: string, guid?: string }
+const ref = (v: Y | undefined): Ref => (typeof v === "object" && !Array.isArray(v) && v ? { fileID: String(v.fileID ?? "0"), guid: typeof v.guid === "string" ? v.guid : undefined } : { fileID: "0" })
+const num = (v: Y | undefined, d = 0): number => { const n = typeof v === "string" ? Number(v) : NaN; return Number.isFinite(n) ? n : d }
+const str = (v: Y | undefined): string => (typeof v === "string" ? v : "")
+const vec3 = (v: Y | undefined, d: [number, number, number]): [number, number, number] => {
+  const o = typeof v === "object" && !Array.isArray(v) && v ? v : {}
+  return [ num(o.x, d[0]), num(o.y, d[1]), num(o.z, d[2]) ]
+}
+const quat = (v: Y | undefined): [number, number, number, number] => {
+  const o = typeof v === "object" && !Array.isArray(v) && v ? v : {}
+  return [ num(o.x, 0), num(o.y, 0), num(o.z, 0), num(o.w, 1) ]
+}
+
+type Vec3 = [number, number, number]
+type Quat = [number, number, number, number]
+type TRS = { t: Vec3, r: Quat, s: Vec3 }
+const ID: TRS = { t: [ 0, 0, 0 ], r: [ 0, 0, 0, 1 ], s: [ 1, 1, 1 ] }
+const qmul = (a: Quat, b: Quat): Quat => [
+  a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+  a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+  a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+  a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+]
+const qnorm = (q: Quat): Quat => { const l = Math.hypot(q[0], q[1], q[2], q[3]) || 1; return [ q[0] / l, q[1] / l, q[2] / l, q[3] / l ] }
+const qrot = (q: Quat, v: Vec3): Vec3 => {
+  const [ x, y, z, w ] = q
+  const ix = w * v[0] + y * v[2] - z * v[1], iy = w * v[1] + z * v[0] - x * v[2], iz = w * v[2] + x * v[1] - y * v[0], iw = -x * v[0] - y * v[1] - z * v[2]
+  return [ ix * w + iw * -x + iy * -z - iz * -y, iy * w + iw * -y + iz * -x - ix * -z, iz * w + iw * -z + ix * -y - iy * -x ]
+}
+const compose = (p: TRS, l: TRS): TRS => {
+  const st: Vec3 = [ p.s[0] * l.t[0], p.s[1] * l.t[1], p.s[2] * l.t[2] ]
+  const rt = qrot(p.r, st)
+  return { t: [ p.t[0] + rt[0], p.t[1] + rt[1], p.t[2] + rt[2] ], r: qnorm(qmul(p.r, l.r)), s: [ p.s[0] * l.s[0], p.s[1] * l.s[1], p.s[2] * l.s[2] ] }
+}
+
+export type Handedness = "x" | "z" | "none"
+const toLeCodes = (w: TRS, h: Handedness): TRS => {
+  if (h === "x") return { t: [ -w.t[0], w.t[1], w.t[2] ], r: [ w.r[0], -w.r[1], -w.r[2], w.r[3] ], s: w.s }
+  if (h === "z") return { t: [ w.t[0], w.t[1], -w.t[2] ], r: [ -w.r[0], -w.r[1], w.r[2], w.r[3] ], s: w.s }
+  return w
+}
+
+export type SceneInstance = {
+  name: string
+  /** prefab GUID (key into `prefabs`), or null for a plain mesh object */
+  prefab: string | null
+  /** `Static/Roads` — the scene's grouping GameObjects above the instance */
+  group: string
+  position: Vec3
+  rotation: Quat
+  scale: Vec3
+  /** true when a parent sat inside a binary prefab — placed at that prefab's root, not its inner child */
+  approximate?: boolean
+}
+export type ScenePrefab = { path: string | null, name: string, fbx: string | null, node: string | null, count: number }
+export type SceneImport = {
+  source: string
+  frame: string
+  prefabs: Record<string, ScenePrefab>
+  instances: SceneInstance[]
+  stats: { prefabInstances: number, meshObjects: number, inactive: number, approximate: number, unresolvedPrefabs: number }
+}
+
+export type ImportSceneOptions = {
+  /** `unity-index.txt` for GUID → path (default: found walking up from the scene file) */
+  indexFile?: string | null
+  handedness?: Handedness
+  /** keep only instances whose prefab path / name / group matches */
+  filter?: RegExp
+  /** 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
+}
+
+export const importUnityScene = (scenePath: string, opts: ImportSceneOptions = {}): SceneImport => {
+  const text = readFileSync(scenePath, "utf8")
+  if (!text.startsWith("%YAML")) throw new Error(`${basename(scenePath)} is not text-serialised (Unity: Edit ▸ Project Settings ▸ Editor ▸ Asset Serialization = Force Text)`)
+  const handedness = opts.handedness ?? "x"
+  const indexFile = opts.indexFile === undefined ? findUnityIndex(dirname(resolve(scenePath))) : opts.indexFile
+  const guidPath = new Map<string, string>()
+  if (indexFile && existsSync(indexFile)) {
+    for (const line of readFileSync(indexFile, "utf8").split(/\r?\n/)) { const t = line.indexOf("\t"); if (t > 0) guidPath.set(line.slice(0, t), line.slice(t + 1).trim()) }
+  }
+
+  // split into objects
+  type Obj = { type: number, id: string, stripped: boolean, cls: string, body: { [k: string]: Y } }
+  const objs = new Map<string, Obj>()
+  const re = /^--- !u!(\d+) &(-?\d+)( stripped)?\s*$/gm
+  const starts: { idx: number, type: number, id: string, stripped: boolean, end: number }[] = []
+  for (let m = re.exec(text); m; m = re.exec(text)) starts.push({ idx: m.index, type: +m[1], id: m[2], stripped: !!m[3], end: m.index + m[0].length })
+  for (let i = 0; i < starts.length; i++) {
+    const s = starts[i]
+    const chunk = text.slice(s.end, i + 1 < starts.length ? starts[i + 1].idx : text.length)
+    const body = parseUnityYaml(chunk)
+    const cls = Object.keys(body)[0] ?? ""
+    objs.set(s.id, { type: s.type, id: s.id, stripped: s.stripped, cls, body: (body[cls] as { [k: string]: Y }) ?? {} })
+  }
+
+  // transforms + game objects
+  type T = { local: TRS, father: string, gameObject: string, prefabInstance: string | null }
+  const transforms = new Map<string, T>()
+  const gameObjects = new Map<string, { name: string, active: boolean, components: string[] }>()
+  const meshFilters = new Map<string, { mesh: Ref }>()          // by game object id
+  type PI = { parent: string, local: TRS, guid: string | undefined, name: string | null, active: boolean }
+  const prefabInstances = new Map<string, PI>()
+  for (const o of objs.values()) {
+    if (o.cls === "Transform" || o.cls === "RectTransform") {
+      transforms.set(o.id, {
+        local: { t: vec3(o.body.m_LocalPosition, [ 0, 0, 0 ]), r: quat(o.body.m_LocalRotation), s: vec3(o.body.m_LocalScale, [ 1, 1, 1 ]) },
+        father: ref(o.body.m_Father).fileID, gameObject: ref(o.body.m_GameObject).fileID,
+        prefabInstance: o.stripped ? ref(o.body.m_PrefabInstance).fileID : null,
+      })
+    } else if (o.cls === "GameObject") {
+      const comps = Array.isArray(o.body.m_Component) ? o.body.m_Component.map((c) => ref(typeof c === "object" && !Array.isArray(c) ? c.component : undefined).fileID) : []
+      gameObjects.set(o.id, { name: str(o.body.m_Name), active: num(o.body.m_IsActive, 1) !== 0, components: comps })
+    } else if (o.cls === "MeshFilter") {
+      meshFilters.set(ref(o.body.m_GameObject).fileID, { mesh: ref(o.body.m_Mesh) })
+    } else if (o.cls === "PrefabInstance") {
+      const mod = (typeof o.body.m_Modification === "object" && !Array.isArray(o.body.m_Modification) ? o.body.m_Modification : {}) as { [k: string]: Y }
+      const local: TRS = { t: [ 0, 0, 0 ], r: [ 0, 0, 0, 1 ], s: [ 1, 1, 1 ] }
+      let name: string | null = null, active = true
+      const mods = Array.isArray(mod.m_Modifications) ? mod.m_Modifications : []
+      // the modifications target the prefab's ROOT transform (the first fileID seen for TRS keys);
+      // overrides on inner children are ignored — they need the prefab's contents
+      let rootTarget: string | null = null
+      for (const m of mods) {
+        if (typeof m !== "object" || Array.isArray(m)) continue
+        const path = str(m.propertyPath), value = str(m.value), target = ref(m.target).fileID
+        const mt = /^m_Local(Position|Rotation|Scale)\.([xyzw])$/.exec(path)
+        if (mt) {
+          if (rootTarget === null) rootTarget = target
+          if (target !== rootTarget) continue
+          const k = "xyzw".indexOf(mt[2])
+          if (mt[1] === "Position") local.t[k] = num(value, local.t[k])
+          else if (mt[1] === "Rotation") local.r[k] = num(value, local.r[k])
+          else local.s[k] = num(value, local.s[k])
+        } else if (path === "m_Name" && name === null) name = value
+        else if (path === "m_IsActive" && value === "0") active = false
+      }
+      local.r = qnorm(local.r)
+      prefabInstances.set(o.id, { parent: ref(mod.m_TransformParent).fileID, local, guid: ref(o.body.m_SourcePrefab).guid, name, active })
+    }
+  }
+
+  // world transforms, memoised; stripped transforms resolve to their prefab instance
+  const worldT = new Map<string, { w: TRS, approx: boolean, path: string[] }>()
+  const worldPI = new Map<string, { w: TRS, approx: boolean, path: string[] }>()
+  const ROOT = { w: ID, approx: false, path: [] as string[] }
+  const resolveT = (id: string, depth = 0): { w: TRS, approx: boolean, path: string[] } => {
+    if (id === "0" || depth > 64) return ROOT
+    const hit = worldT.get(id); if (hit) return hit
+    const t = transforms.get(id)
+    let out = ROOT
+    if (t) {
+      if (t.prefabInstance) { const p = resolvePI(t.prefabInstance, depth + 1); out = { w: p.w, approx: true, path: p.path } }
+      else {
+        const par = resolveT(t.father, depth + 1)
+        const go = gameObjects.get(t.gameObject)
+        out = { w: compose(par.w, t.local), approx: par.approx, path: go?.name ? [ ...par.path, go.name ] : par.path }
+      }
+    }
+    worldT.set(id, out)
+    return out
+  }
+  const resolvePI = (id: string, depth = 0): { w: TRS, approx: boolean, path: string[] } => {
+    const hit = worldPI.get(id); if (hit) return hit
+    const p = prefabInstances.get(id)
+    let out = ROOT
+    if (p) {
+      const par = resolveT(p.parent, depth + 1)
+      const nm = p.name ?? prefabName(p.guid)
+      out = { w: compose(par.w, p.local), approx: par.approx, path: [ ...par.path, nm ] }
+    }
+    worldPI.set(id, out)
+    return out
+  }
+  const prefabName = (guid: string | undefined): string => {
+    const p = guid ? guidPath.get(guid) : undefined
+    return p ? basename(p).replace(/\.prefab$/i, "") : (guid ?? "prefab")
+  }
+
+  // FBX guess per prefab: an FBX from the index under the prefab's folder (`Source/` first), whose
+  // stem is a prefix of the prefab name when there are several
+  const fbxByDir = new Map<string, string[]>()
+  for (const p of guidPath.values()) if (/\.fbx$/i.test(p)) { const d = dirname(p); fbxByDir.set(d, [ ...(fbxByDir.get(d) ?? []), p ]) }
+  const guessFbx = (prefabPath: string, name: string): string | null => {
+    const d = dirname(prefabPath)
+    const cands = [ ...(fbxByDir.get(d + "/Source") ?? []), ...(fbxByDir.get(d) ?? []), ...(fbxByDir.get(dirname(d) + "/Source") ?? []) ]
+    if (cands.length === 0) return null
+    const lname = name.toLowerCase()
+    const stem = (f: string): string => basename(f).replace(/\.fbx$/i, "").toLowerCase()
+    return cands.find((f) => lname.startsWith(stem(f))) ?? cands.find((f) => lname.includes(stem(f)) || stem(f).includes(lname)) ?? (cands.length === 1 ? cands[0] : null)
+  }
+
+  const prefabs: Record<string, ScenePrefab> = {}
+  const instances: SceneInstance[] = []
+  const stats = { prefabInstances: 0, meshObjects: 0, inactive: 0, approximate: 0, unresolvedPrefabs: 0 }
+  const inRegion = (w: TRS): boolean => !opts.region || (w.t[0] >= opts.region[0] && w.t[0] <= opts.region[2] && w.t[2] >= opts.region[1] && w.t[2] <= opts.region[3])
+  const push = (name: string, prefab: string | null, res: { w: TRS, approx: boolean, path: string[] }, prefabPath: string | null): void => {
+    const group = res.path.slice(0, -1).join("/")
+    if (opts.group && !res.path.join("/").includes(opts.group)) return
+    if (opts.filter && !(opts.filter.test(name) || opts.filter.test(group) || (prefabPath !== null && opts.filter.test(prefabPath)))) return
+    if (!inRegion(res.w)) return
+    const w = toLeCodes(res.w, handedness)
+    const inst: SceneInstance = { name, prefab, group, position: w.t.map(r6) as Vec3, rotation: w.r.map(r6) as Quat, scale: w.s.map(r6) as Vec3 }
+    if (res.approx) { inst.approximate = true; stats.approximate++ }
+    instances.push(inst)
+  }
+  for (const [ id, p ] of prefabInstances) {
+    stats.prefabInstances++
+    if (!p.active && !opts.includeInactive) { stats.inactive++; continue }
+    const guid = p.guid ?? "?"
+    const path = guidPath.get(guid) ?? null
+    if (!prefabs[guid]) {
+      const name = prefabName(p.guid)
+      if (!path) stats.unresolvedPrefabs++
+      const fbx = path ? guessFbx(path, name) : null
+      prefabs[guid] = { path, name, fbx, node: fbx ? name : null, count: 0 }
+    }
+    prefabs[guid].count++
+    push(p.name ?? prefabs[guid].name, guid, resolvePI(id), path)
+  }
+  for (const [ goId, mf ] of meshFilters) {
+    const go = gameObjects.get(goId)
+    if (!go) continue
+    const tId = go.components.find((c) => transforms.has(c))
+    if (!tId) continue
+    if (!go.active && !opts.includeInactive) { stats.inactive++; continue }
+    if (mf.mesh.guid === "0000000000000000e000000000000000") continue        // Unity built-in primitives
+    stats.meshObjects++
+    const key = mf.mesh.guid ? `mesh:${mf.mesh.guid}` : `mesh:${goId}`
+    const fbx = mf.mesh.guid ? guidPath.get(mf.mesh.guid) ?? null : null
+    if (!prefabs[key]) prefabs[key] = { path: null, name: go.name, fbx, node: go.name.replace(/\s*\(\d+\)$/, ""), count: 0 }
+    prefabs[key].count++
+    push(go.name, key, resolveT(tId), fbx)
+  }
+  // counts = surviving instances (filters / region applied); prefabs nothing uses are dropped
+  for (const p of Object.values(prefabs)) p.count = 0
+  for (const i of instances) if (i.prefab && prefabs[i.prefab]) prefabs[i.prefab].count++
+  for (const k of Object.keys(prefabs)) if (!prefabs[k].count) delete prefabs[k]
+
+  return {
+    source: basename(scenePath),
+    frame: handedness === "none" ? "unity (left-handed, untouched)" : `lecodes: Unity mirrored on ${handedness.toUpperCase()} (position −${handedness}, quaternion ${handedness === "x" ? "(x, −y, −z, w)" : "(−x, −y, z, w)"}), metres, Y up`,
+    prefabs, instances, stats,
+  }
+}
+
+const r6 = (v: number): number => Math.round(v * 1e6) / 1e6
+
+/** The prefab table as printable lines, most used first. */
+export const describeSceneImport = (r: SceneImport, max = 20): string[] => {
+  const rows = Object.entries(r.prefabs).sort((a, b) => b[1].count - a[1].count)
+  const lines = [ `${r.instances.length} instances of ${rows.length} prefab(s)${r.stats.inactive ? ` · ${r.stats.inactive} inactive skipped` : ""}${r.stats.approximate ? ` · ${r.stats.approximate} placed at a binary prefab's root (inner offset unknown)` : ""}${r.stats.unresolvedPrefabs ? ` · ${r.stats.unresolvedPrefabs} prefab GUID(s) not in the index` : ""}` ]
+  for (const [ , p ] of rows.slice(0, max)) lines.push(`  ${String(p.count).padStart(5)} × ${p.name.padEnd(36)} ${p.fbx ? `${basename(p.fbx)} → --keep ${p.node}` : p.path ? "(no FBX next to the prefab)" : "(unresolved)"}`)
+  if (rows.length > max) lines.push(`  … ${rows.length - max} more`)
+  return lines
+}

package/src/unity/unpack.ts

@@ -0,0 +1,130 @@
+// `.unitypackage` reader. The file is a gzip'd tar of one folder per asset GUID holding `asset`
+// (the bytes), `asset.meta` and `pathname` (its path under Assets/). Two streaming passes keep
+// memory flat on multi-GB packs: pass 1 indexes GUID → path (written as `unity-index.txt` at the
+// output root — `convert` resolves Unity material textures through it), pass 2 writes the files
+// that match the requested patterns (everything by default), `.meta` sidecars included so the
+// result is also a valid Unity project fragment.
+
+import { createReadStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { createGunzip } from "node:zlib"
+
+type Entry = { name: string, size: number }
+
+const tarStream = (file: string, onEntry: (e: Entry, data: Uint8Array) => void): Promise<void> => new Promise((resolveP, rejectP) => {
+  const gunzip = createGunzip()
+  createReadStream(file, { highWaterMark: 1 << 22 }).on("error", rejectP).pipe(gunzip)
+  let buf: Buffer = Buffer.alloc(0)
+  let state: "header" | "body" | "pad" = "header"
+  let entry: Entry | null = null
+  let remaining = 0, pad = 0
+  const chunks: Buffer[] = []
+  gunzip.on("data", (chunk: Buffer) => {
+    buf = buf.length ? Buffer.concat([ buf, chunk ]) : chunk
+    let off = 0
+    for (;;) {
+      if (state === "header") {
+        if (buf.length - off < 512) break
+        const h = buf.subarray(off, off + 512)
+        off += 512
+        if (h[0] === 0) continue
+        const name = h.subarray(0, 100).toString("utf8").replace(/\0.*$/s, "")
+        const size = parseInt(h.subarray(124, 136).toString("utf8").replace(/[\0 ]/g, ""), 8) || 0
+        const prefix = h.subarray(345, 500).toString("utf8").replace(/\0.*$/s, "")
+        entry = { name: prefix ? prefix + "/" + name : name, size }
+        remaining = size
+        pad = (512 - (size % 512)) % 512
+        chunks.length = 0
+        state = size > 0 ? "body" : "pad"
+      } else if (state === "body") {
+        const avail = buf.length - off
+        if (avail === 0) break
+        const take = Math.min(remaining, avail)
+        chunks.push(buf.subarray(off, off + take))
+        off += take
+        remaining -= take
+        if (remaining === 0) state = "pad"
+      } else {
+        if (buf.length - off < pad) break
+        off += pad
+        pad = 0
+        if (entry && entry.size > 0) onEntry(entry, Buffer.concat(chunks))
+        chunks.length = 0
+        entry = null
+        state = "header"
+      }
+    }
+    buf = buf.subarray(off)
+  })
+  gunzip.on("end", () => resolveP())
+  gunzip.on("error", rejectP)
+})
+
+export const INDEX_NAME = "unity-index.txt"
+
+/** Pass 1: GUID → path for every asset in the package. */
+export const indexUnityPackage = async (pkg: string, progress?: (entries: number, assets: number) => void): Promise<Map<string, string>> => {
+  const map = new Map<string, string>()
+  let n = 0
+  await tarStream(pkg, (e, data) => {
+    n++
+    if (e.name.endsWith("/pathname")) {
+      const guid = e.name.split("/")[0]
+      const p = Buffer.from(data).toString("utf8").split("\n")[0].trim()
+      if (/^[0-9a-f]{32}$/.test(guid) && p) map.set(guid, p)
+    }
+    if (n % 20000 === 0) progress?.(n, map.size)
+  })
+  return map
+}
+
+export const writeUnityIndex = (outDir: string, index: Map<string, string>): string => {
+  mkdirSync(outDir, { recursive: true })
+  const f = join(outDir, INDEX_NAME)
+  writeFileSync(f, [ ...index ].map(([ g, p ]) => `${g}\t${p}`).join("\n") + "\n")
+  return f
+}
+
+export const readUnityIndex = (file: string): Map<string, string> => {
+  const map = new Map<string, string>()
+  for (const line of readFileSync(file, "utf8").split(/\r?\n/)) {
+    const t = line.indexOf("\t")
+    if (t > 0) map.set(line.slice(0, t), line.slice(t + 1).trim())
+  }
+  return map
+}
+
+export type ExtractOptions = {
+  /** Regexes (case-insensitive) a path must match; none = everything. */
+  only?: RegExp[]
+  /** Also write the `.meta` sidecars (default true). */
+  meta?: boolean
+  /** Skip files that already exist with the same size (default true — re-runs are cheap). */
+  skipExisting?: boolean
+  progress?: (files: number, bytes: number) => void
+}
+
+/** Pass 2: write the matching assets under `outDir/<pathname>`. */
+export const extractUnityPackage = async (pkg: string, index: Map<string, string>, outDir: string, opts: ExtractOptions = {}): Promise<{ files: number, bytes: number, matched: number }> => {
+  const want = new Map<string, string>()
+  for (const [ g, p ] of index) if (!opts.only?.length || opts.only.some((r) => r.test(p))) want.set(g, p)
+  let files = 0, bytes = 0
+  await tarStream(pkg, (e, data) => {
+    const parts = e.name.split("/")
+    if (parts.length < 2) return
+    const leaf = parts[parts.length - 1]
+    const isAsset = leaf === "asset", isMeta = leaf === "asset.meta"
+    if (!isAsset && !(isMeta && (opts.meta ?? true))) return
+    const p = want.get(parts[0])
+    if (!p) return
+    const dest = join(outDir, p) + (isMeta ? ".meta" : "")
+    if ((opts.skipExisting ?? true) && existsSync(dest)) {
+      try { if (statSync(dest).size === data.length) return } catch { /* fall through */ }
+    }
+    mkdirSync(dirname(dest), { recursive: true })
+    writeFileSync(dest, data)
+    if (isAsset) { files++; bytes += data.length }
+    if (files % 50 === 0) opts.progress?.(files, bytes)
+  })
+  return { files, bytes, matched: want.size }
+}