lecodes-assets 2.5.1 → 2.6.0

package/src/doctor/transcodeKtx2.ts

@@ -9,8 +9,12 @@
 // first-person weapon or gloves fill a third of the screen at 30 cm, where ETC1S's block artifacts
 // on the base colour are plainly visible. World props stay on the default: ETC1S is the right
 // trade there and the size difference is roughly 8x.
-// Mipmaps are generated; alpha is preserved (ETC1S/UASTC both encode it).
-import { createHash } from 'node:crypto'
+// Mipmaps are generated; alpha is preserved (ETC1S/UASTC both encode it). The base colour of an alpha-MASK material
+// takes COVERAGE-PRESERVING mips instead of the encoder's (doctor/coverageMips.ts): the chain is built here, every
+// level's alpha scaled to the source's coverage at the material's cutoff, and handed over as explicit levels — a box
+// mip of a hard-edged leaf atlas falls under the cutoff a few levels down and the crown goes bare (Chernobyl's birches
+// at 20 m; the pack's Unity meta asks for `mipMapsPreserveCoverage`). The `--max-size` downscale of such a texture is
+// the chain's level 0, scaled the same way.
 import sharp from 'sharp'
 import { spawn, spawnSync } from 'node:child_process'   // spawnSync only for the one-shot --version probe
 import { existsSync, mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
@@ -18,6 +22,9 @@ import { cpus, tmpdir } from 'node:os'
 import { join } from 'node:path'
 import type { Root, Texture } from '@gltf-transform/core'
 import { getTextureRoles, isImpostorAtlas, DEFAULT_MAX_SIZE } from './transcodeTextures'
+import { coverageMipChain } from './coverageMips'
+import { impostorDataMipChain } from './impostor'
+import { imageInfo, imageSha1 } from './imageFacts'
 
 /**
  * The KTX2 encoder: KTX-Software's legacy `toktx`, or — when there is none — its unified `ktx`
@@ -84,15 +91,19 @@ export interface KtxEncodeJob {
   uastcQuality: number
   /** Zstandard level for UASTC (ETC1S is Basis-LZ, never supercompressed on top). */
   zstd: number
+  /** An explicit mip chain (level 0 first, down to 1 × 1) in place of the encoder's own mips; `input` is then unused. */
+  levels?: string[]
 }
 
-/** The encoder's command line for one PNG → KTX2 (always 2D, mipmapped, the transfer function assigned). */
+/** The encoder's command line for one PNG → KTX2 (always 2D, mipmapped, the transfer function assigned): the encoder's
+ *  own mips, or the explicit `levels` (toktx `--mipmap` takes one input per level; `ktx create` the same with `--levels`). */
 export function ktxEncodeArgs(enc: KtxEncoder, j: KtxEncodeJob): string[] {
+  const inputs = j.levels?.length ? j.levels : [ j.input ]
   if (enc.kind === 'toktx') {
     return [ '--t2', ...(j.codec === 'etc1s'
       ? [ '--encode', 'etc1s', '--clevel', '2', '--qlevel', '128' ]
       : [ '--encode', 'uastc', '--uastc_quality', String(j.uastcQuality), '--zcmp', String(j.zstd) ]),
-    '--genmipmap', '--assign_oetf', j.oetf, j.output, j.input ]
+    ...(j.levels?.length ? [ '--mipmap' ] : [ '--genmipmap' ]), '--assign_oetf', j.oetf, j.output, ...inputs ]
   }
   const format = `${j.channels === 4 ? 'R8G8B8A8' : 'R8G8B8'}_${j.oetf === 'srgb' ? 'SRGB' : 'UNORM'}`
   return [ 'create', '--format', format, ...(j.codec === 'etc1s'
@@ -100,7 +111,7 @@ export function ktxEncodeArgs(enc: KtxEncoder, j: KtxEncodeJob): string[] {
     : [ '--encode', 'uastc', '--uastc-quality', String(j.uastcQuality), '--zstd', String(j.zstd) ]),
   // --assign-tf: sharp's PNGs carry no colour chunk, which `ktx` reads as sRGB and then refuses to
   // put into a *_UNORM format without a conversion — the data maps ARE linear, so say so.
-  '--generate-mipmap', '--assign-tf', j.oetf, j.input, j.output ]
+  ...(j.levels?.length ? [ '--levels', String(j.levels.length) ] : [ '--generate-mipmap' ]), '--assign-tf', j.oetf, ...inputs, j.output ]
 }
 
 export interface Ktx2Plan {
@@ -114,6 +125,12 @@ export interface Ktx2Plan {
   width: number
   height: number
   hasAlpha: boolean
+  /** The base colour of an alpha-MASK material: its cutoff (the lowest of the MASK materials sharing it) — the mips and
+   *  the downscale keep the coverage at it. null = plain mips. */
+  maskCutoff: number | null
+  /** An impostor atlas' DATA map (the metallicRoughness slot of a `lecodes.impostor` material): its mips are built here
+   *  by averaging the decoded normals (impostor.ts impostorDataMipChain), never by a box over the octahedral map. */
+  impostorData: boolean
   beforeBytes: number
   afterBytes?: number
   category: 'lossy'
@@ -129,15 +146,9 @@ export async function planKtx2(tex: Texture, root: Root, maxSize = DEFAULT_MAX_S
   if (!img || fromFmt.includes('ktx')) return null // missing or already ktx2
 
   const { roles, isNormal, isData } = getTextureRoles(tex, root)
-  let width = 0, height = 0, hasAlpha = false
-  try {
-    const b = Buffer.from(img)
-    const m = await sharp(b).metadata()
-    width = m.width || 0; height = m.height || 0
-    hasAlpha = !(await sharp(b).stats()).isOpaque
-  } catch {
-    return null
-  }
+  const info = await imageInfo(img)
+  if (!info) return null
+  const { width, height, hasAlpha } = info
 
   // DATA maps (normal, metal / rough, occlusion) always take UASTC: ETC1S is a palette codec whose blocks show
   // as steps on a smooth metallic or roughness channel (the range's metal props read pixelated under the
@@ -153,10 +164,22 @@ export async function planKtx2(tex: Texture, root: Root, maxSize = DEFAULT_MAX_S
   const oetf: 'srgb' | 'linear' = isNormal || isData ? 'linear' : 'srgb'
   // an impostor atlas keeps its size whatever the cap (its frames are fixed pixel rects); still ×4 and mipmapped
   const resize = !isImpostorAtlas(tex) && Math.max(width, height) > maxSize
+  // COVERAGE-PRESERVING mips for the base colour of an alpha-MASK material, at the lowest cutoff of the MASK materials
+  // that share it. NOT for an impostor atlas (its material is MASK too): its alpha is the FRACTIONAL area coverage of a
+  // crown by design, not a hard-edged mask, and the engine's mip boost (foliage-impostor.mat) assumes plain mips of it
+  let maskCutoff: number | null = null
+  if (hasAlpha && !isImpostorAtlas(tex)) {
+    for (const m of root.listMaterials()) {
+      if (m.getBaseColorTexture() !== tex || m.getAlphaMode() !== 'MASK') continue
+      const c = m.getAlphaCutoff()
+      if (c > 0 && (maskCutoff === null || c < maskCutoff)) maskCutoff = c
+    }
+  }
+  const impostorData = isImpostorAtlas(tex) && root.listMaterials().some((m) => m.getMetallicRoughnessTexture() === tex)
   return {
-    tex, name: tex.getName() || '?', roles, fromFmt, codec, oetf, resize, width, height, hasAlpha,
+    tex, name: tex.getName() || '?', roles, fromFmt, codec, oetf, resize, width, height, hasAlpha, maskCutoff, impostorData,
     beforeBytes: img.length, category: 'lossy',
-    reason: `${fromFmt} → ktx2/${codec}${hasAlpha ? '+alpha' : ''}${resize ? ` (≤${maxSize}px)` : ''}`,
+    reason: `${fromFmt} → ktx2/${codec}${hasAlpha ? '+alpha' : ''}${resize ? ` (≤${maxSize}px)` : ''}${maskCutoff !== null ? ` · coverage mips @${maskCutoff}` : ''}${impostorData ? ' · normal mips' : ''}`,
   }
 }
 
@@ -216,7 +239,7 @@ export const ktx2CacheHits = (): number => hits
 export async function applyKtx2(plan: Ktx2Plan, enc: KtxEncoder, maxSize = DEFAULT_MAX_SIZE): Promise<void> {
   const src = plan.tex.getImage()
   const key = src
-    ? `${createHash('sha1').update(src).digest('hex')}:${maxSize}:${plan.codec}:${plan.oetf}:${plan.hasAlpha ? 1 : 0}`
+    ? `${await imageSha1(src)}:${maxSize}:${plan.codec}:${plan.oetf}:${plan.hasAlpha ? 1 : 0}:${plan.maskCutoff ?? '-'}:cov1:${plan.impostorData ? 'nmip1' : '-'}`
     : null
   if (key) {
     const hit = encoded.get(key)
@@ -257,16 +280,40 @@ async function encodeOne(plan: Ktx2Plan, enc: KtxEncoder, maxSize: number): Prom
     if (plan.resize && m > maxSize) { const s = maxSize / m; tw = tw * s; th = th * s }
     tw = snap4(tw); th = snap4(th)
 
-    let pipe = sharp(Buffer.from(plan.tex.getImage()!))
-    if (tw !== plan.width || th !== plan.height) pipe = pipe.resize({ width: tw, height: th, fit: 'fill' })
-    // Always RGB / RGBA (a grey or palette source too): `ktx create` declares the channel count up front.
-    pipe = pipe.toColourspace('srgb')
-    pipe = plan.hasAlpha ? pipe.ensureAlpha() : pipe.removeAlpha() // RGB → no wasted alpha slice
-    writeFileSync(inPng, await pipe.png().toBuffer())
+    let levels: string[] | undefined
+    if (plan.maskCutoff !== null && plan.hasAlpha) {
+      // the coverage-preserving chain (the header): decoded at the source's size, level 0 = the capped size
+      const raw = await sharp(Buffer.from(plan.tex.getImage()!)).toColourspace('srgb').ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+      const chain = coverageMipChain(new Uint8Array(raw.data.buffer, raw.data.byteOffset, raw.data.byteLength), raw.info.width, raw.info.height,
+        { cutoff: plan.maskCutoff, width: tw, height: th, srgb: plan.oetf === 'srgb' })
+      levels = []
+      for (const [ i, l ] of chain.levels.entries()) {
+        const f = join(dir, `level${i}.png`)
+        writeFileSync(f, await sharp(Buffer.from(l.data.buffer, l.data.byteOffset, l.data.byteLength), { raw: { width: l.width, height: l.height, channels: 4 } }).png().toBuffer())
+        levels.push(f)
+      }
+    } else if (plan.impostorData) {
+      // the data map of an impostor: its normals' mips by vector (impostor.ts impostorDataMipChain); never resized
+      const raw = await sharp(Buffer.from(plan.tex.getImage()!)).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+      const chain = impostorDataMipChain(new Uint8Array(raw.data.buffer, raw.data.byteOffset, raw.data.byteLength), raw.info.width, raw.info.height)
+      levels = []
+      for (const [ i, l ] of chain.entries()) {
+        const f = join(dir, `level${i}.png`)
+        writeFileSync(f, await sharp(Buffer.from(l.data.buffer, l.data.byteOffset, l.data.byteLength), { raw: { width: l.width, height: l.height, channels: 4 } }).png().toBuffer())
+        levels.push(f)
+      }
+    } else {
+      let pipe = sharp(Buffer.from(plan.tex.getImage()!))
+      if (tw !== plan.width || th !== plan.height) pipe = pipe.resize({ width: tw, height: th, fit: 'fill' })
+      // Always RGB / RGBA (a grey or palette source too): `ktx create` declares the channel count up front.
+      pipe = pipe.toColourspace('srgb')
+      pipe = plan.hasAlpha ? pipe.ensureAlpha() : pipe.removeAlpha() // RGB → no wasted alpha slice
+      writeFileSync(inPng, await pipe.png().toBuffer())
+    }
 
     const args = ktxEncodeArgs(enc, {
       input: inPng, output: outKtx, codec: plan.codec, oetf: plan.oetf,
-      channels: plan.hasAlpha ? 4 : 3, uastcQuality: 2, zstd: 18,
+      channels: plan.hasAlpha ? 4 : 3, uastcQuality: 2, zstd: 18, levels,
     })
 
     await acquire()

package/src/doctor/transcodeTextures.ts

@@ -11,6 +11,7 @@
 //   - ktx2                        -> left untouched (supported; sharp can't handle it)
 import sharp from 'sharp'
 import type { Root, Texture } from '@gltf-transform/core'
+import { imageInfo } from './imageFacts'
 
 export const DEFAULT_MAX_SIZE = 2048
 const HEAVY_PNG_MIN_DIM = 1024
@@ -58,15 +59,10 @@ export async function planTexture(tex: Texture, root: Root, maxSize = DEFAULT_MA
   if (fromFmt.includes('ktx')) return null
 
   const { roles, isNormal, isData } = getTextureRoles(tex, root)
-  let width = 0, height = 0, hasAlpha = false
-  try {
-    const buf = Buffer.from(img)
-    const meta = await sharp(buf).metadata()
-    width = meta.width || 0; height = meta.height || 0
-    hasAlpha = !(await sharp(buf).stats()).isOpaque
-  } catch {
-    return null // undecodable by sharp — leave it
-  }
+  // once per image object (transcodeKtx2.ts imageInfo): a level import shares one map's bytes between its kinds
+  const info = await imageInfo(img)
+  if (!info) return null // undecodable by sharp — leave it
+  const { width, height, hasAlpha } = info
 
   const resize = !isImpostorAtlas(tex) && Math.max(width, height) > maxSize
   let desired: 'jpeg' | 'png' = forceFmt ?? (hasAlpha ? 'png' : 'jpeg') // PNG only when alpha is needed

package/src/textures/byteLru.ts

@@ -0,0 +1,38 @@
+// A promise cache bounded by the BYTES its values hold, least-recently-used out first.
+//
+// The values are promises so two callers asking for the same key while it is being made share the
+// one piece of work; a value's size is counted once it resolves (a rejection or a null weighs 0 and
+// stays cached — the same input fails the same way). An entry larger than the whole budget is still
+// handed to the caller that made it, it just does not stay.
+
+export class ByteLru<V> {
+  private entries = new Map<string, { value: Promise<V>, bytes: number }>()
+  private total = 0
+  constructor(readonly budget: number, private readonly sizeOf: (v: V) => number) {}
+
+  get bytes(): number { return this.total }
+  get size(): number { return this.entries.size }
+
+  /** The cached value of `key`, or `make()`'s, cached. */
+  get(key: string, make: () => Promise<V>): Promise<V> {
+    const hit = this.entries.get(key)
+    if (hit) { this.entries.delete(key); this.entries.set(key, hit); return hit.value }
+    const entry = { value: make(), bytes: 0 }
+    this.entries.set(key, entry)
+    entry.value.then((v) => {
+      if (this.entries.get(key) !== entry) return
+      entry.bytes = v ? this.sizeOf(v) : 0
+      this.total += entry.bytes
+      this.evict()
+    }, () => {})
+    return entry.value
+  }
+
+  private evict(): void {
+    for (const [ k, e ] of this.entries) {
+      if (this.total <= this.budget) break
+      this.entries.delete(k)
+      this.total -= e.bytes
+    }
+  }
+}

package/src/textures/resolveImage.ts

@@ -4,7 +4,8 @@
 
 import { existsSync, readFileSync } from "node:fs"
 import { basename, dirname, join, isAbsolute } from "node:path"
-import { deflateSync } from "node:zlib"
+import * as zlib from "node:zlib"
+import { deflate, deflateSync } from "node:zlib"
 import { createHash } from "node:crypto"
 import type { FbxTexture } from "../fbx/read"
 
@@ -99,6 +100,16 @@ export const decodeTga = (b: Uint8Array): Rgba | null => {
   if (cmapType === 1) { cmap = b.subarray(p, p + cmapLen * cmapBytes); p += cmapLen * cmapBytes }
   const bytesPP = bpp >> 3
   const out = new Uint8Array(width * height * 4)
+  // uncompressed 24 / 32-bit truecolour — 435 of a pack's 445 maps (Chernobyl) — row by row, no per-texel closure
+  // (a 4096² map: 67 ms the general way)
+  if (imgType === 2 && (bytesPP === 3 || bytesPP === 4) && p + width * height * bytesPP <= b.length) {
+    for (let y = 0; y < height; y++) {
+      let s = p + y * width * bytesPP, o = (topDown ? y : height - 1 - y) * width * 4
+      if (bytesPP === 4) for (let x = 0; x < width; x++, s += 4, o += 4) { out[o] = b[s + 2]; out[o + 1] = b[s + 1]; out[o + 2] = b[s]; out[o + 3] = b[s + 3] }
+      else for (let x = 0; x < width; x++, s += 3, o += 4) { out[o] = b[s + 2]; out[o + 1] = b[s + 1]; out[o + 2] = b[s]; out[o + 3] = 255 }
+    }
+    return { width, height, data: out }
+  }
   const px = new Uint8Array(4)
   const readPixel = (at: number): void => {
     if (kind === 3) { const g = b[at]; px[0] = g; px[1] = g; px[2] = g; px[3] = bytesPP > 1 ? b[at + 1] : 255; return }
@@ -169,7 +180,10 @@ const CRC_TABLE = (() => {
   for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; t[n] = c >>> 0 }
   return t
 })()
+// zlib's own where the runtime has it (Node ≥ 22.2, Bun): the JS loop is ~25 ms over a 15 MB IDAT
+const zlibCrc32 = (zlib as { crc32?: (data: Uint8Array, value?: number) => number }).crc32
 const crc32 = (parts: Uint8Array[]): number => {
+  if (zlibCrc32) { let c = 0; for (const p of parts) c = zlibCrc32(p, c); return c >>> 0 }
   let c = 0xffffffff
   for (const p of parts) for (let i = 0; i < p.length; i++) c = CRC_TABLE[(c ^ p[i]) & 0xff] ^ (c >>> 8)
   return (c ^ 0xffffffff) >>> 0
@@ -184,15 +198,17 @@ const chunk = (type: string, data: Uint8Array): Uint8Array => {
   return out
 }
 
-export const encodePng = (img: Rgba): Uint8Array => {
+const pngFilterRows = (img: Rgba): Uint8Array => {
   const { width, height, data } = img
   const raw = new Uint8Array((width * 4 + 1) * height)
   for (let y = 0; y < height; y++) { raw[y * (width * 4 + 1)] = 0; raw.set(data.subarray(y * width * 4, (y + 1) * width * 4), y * (width * 4 + 1) + 1) }
+  return raw
+}
+const pngFile = (img: Rgba, idat: Uint8Array): Uint8Array => {
   const ihdr = new Uint8Array(13)
   const dv = new DataView(ihdr.buffer)
-  dv.setUint32(0, width); dv.setUint32(4, height)
+  dv.setUint32(0, img.width); dv.setUint32(4, img.height)
   ihdr[8] = 8; ihdr[9] = 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0
-  const idat = new Uint8Array(deflateSync(raw, { level: 6 }))
   const sig = new Uint8Array([ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a ])
   const parts = [ sig, chunk("IHDR", ihdr), chunk("IDAT", idat), chunk("IEND", new Uint8Array(0)) ]
   const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0))
@@ -200,3 +216,13 @@ export const encodePng = (img: Rgba): Uint8Array => {
   for (const p of parts) { out.set(p, o); o += p.length }
   return out
 }
+
+export const encodePng = (img: Rgba): Uint8Array => pngFile(img, new Uint8Array(deflateSync(pngFilterRows(img), { level: 6 })))
+
+/** `encodePng`, byte for byte, with the deflate on libuv's thread pool: it is ~90 % of the encode (a 4096² RGBA
+ *  map: 1.05 s of deflate on the main thread, 2026-11-04), so the textures of one kind can encode side by side. */
+export const encodePngAsync = async (img: Rgba): Promise<Uint8Array> => {
+  const raw = pngFilterRows(img)
+  const idat = await new Promise<Uint8Array>((res, rej) => deflate(raw, { level: 6 }, (e, b) => (e ? rej(e) : res(new Uint8Array(b.buffer, b.byteOffset, b.byteLength)))))
+  return pngFile(img, idat)
+}

package/src/unity/image.ts

@@ -15,24 +15,35 @@ export const decodeImage = async (bytes: Uint8Array, hint: string): Promise<Rgba
   } catch { return null }
 }
 
-/** Nearest-neighbour sample of one channel at (u, v) in 0..1. */
-const sampleCh = (img: Rgba, ch: number, x: number, y: number, w: number, h: number): number => {
-  const sx = Math.min(img.width - 1, Math.floor((x + 0.5) * img.width / w))
-  const sy = Math.min(img.height - 1, Math.floor((y + 0.5) * img.height / h))
-  return img.data[(sy * img.width + sx) * 4 + ch]
-}
-
 export type PackInput = { img: Rgba, channel: number, invert?: boolean }
-/** Pack occlusion / roughness / metallic sources into one RGB image (glTF layout). Missing = constant. */
+/** Pack occlusion / roughness / metallic sources into one RGB image (glTF layout). Missing = constant.
+ *  Nearest-neighbour onto the largest source's size; each source's column / row lookup is tabulated once (a
+ *  closure + two divisions per channel per texel was 1.6 s of the 30 maps of Chernobyl's Department_Store). */
 export const packOrm = (ao: PackInput | null, rough: PackInput | null, metal: PackInput | null, defaults = { ao: 255, rough: 255, metal: 0 }): Rgba => {
   const srcs = [ ao, rough, metal ].filter((s): s is PackInput => !!s)
   const w = Math.max(1, ...srcs.map((s) => s.img.width)), h = Math.max(1, ...srcs.map((s) => s.img.height))
   const out = new Uint8Array(w * h * 4)
-  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
-    const d = (y * w + x) * 4
-    const get = (s: PackInput | null, dflt: number): number => { if (!s) return dflt; const v = sampleCh(s.img, s.channel, x, y, w, h); return s.invert ? 255 - v : v }
-    out[d] = get(ao, defaults.ao); out[d + 1] = get(rough, defaults.rough); out[d + 2] = get(metal, defaults.metal); out[d + 3] = 255
+  // sample index of (x, y) in a source = row[y] + col[x] (+ channel): floor((x + 0.5) · W / w), clamped
+  const lookup = (n: number, size: number, scale: number): Int32Array => {
+    const t = new Int32Array(n)
+    for (let i = 0; i < n; i++) t[i] = Math.min(size - 1, Math.floor((i + 0.5) * size / n)) * scale
+    return t
+  }
+  const tables = new Map<Rgba, { col: Int32Array, row: Int32Array }>()
+  const fill = (s: PackInput | null, dflt: number, o: number): void => {
+    if (!s) { for (let d = o; d < out.length; d += 4) out[d] = dflt; return }
+    let t = tables.get(s.img)
+    if (!t) { t = { col: lookup(w, s.img.width, 4), row: lookup(h, s.img.height, s.img.width * 4) }; tables.set(s.img, t) }
+    const { col, row } = t, src = s.img.data, ch = s.channel
+    let d = o
+    for (let y = 0; y < h; y++) {
+      const r = row[y] + ch
+      if (s.invert) for (let x = 0; x < w; x++, d += 4) out[d] = 255 - src[r + col[x]]
+      else for (let x = 0; x < w; x++, d += 4) out[d] = src[r + col[x]]
+    }
   }
+  fill(ao, defaults.ao, 0); fill(rough, defaults.rough, 1); fill(metal, defaults.metal, 2)
+  for (let d = 3; d < out.length; d += 4) out[d] = 255
   return { width: w, height: h, data: out }
 }
 

package/src/unity/kindGlb.ts

@@ -10,19 +10,19 @@
 // expects; `globalScale` is the only factor left.
 
 import { basename, dirname } from "node:path"
-import { readFileSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { Document, type Material, type Mesh, type Node } from "@gltf-transform/core"
 import { mergeDocuments, prune } from "@gltf-transform/functions"
 import { readFbx } from "../fbx/read"
 import { toDocument } from "../fbx/toDocument"
 import { quiet } from "../props"
-import { readFbxMeta, type FbxMeta } from "./fbxModel"
+import { MODEL_EXT, readFbxMeta, type FbxMeta } from "./fbxModel"
 import { readUnityMeshAsset } from "./unityMesh"
 import type { GuidResolver } from "./guid"
 import { I4, mmul, scaleMatrix, type Mat4 } from "./math"
 import { collectUnityMaterials, materialKey, parseUnityMaterial, windProfile, type UnityMaterial } from "./matFile"
 import { pairSlots } from "./materialSlots"
-import { unityMaterialWriter } from "./materialWriter"
+import { SharedTextures, unityMaterialWriter } from "./materialWriter"
 import { projectTriplanar, triplanarOf } from "./triplanar"
 import type { KindPart, SceneKind } from "./scene"
 
@@ -103,6 +103,8 @@ export class KindGlbBuilder {
   private fbx = new Map<string, Promise<FbxSource | null>>()
   private mats = new Map<string, UnityMaterial | null>()
   private byKey: Map<string, UnityMaterial> | null = null
+  /** the texture bytes of the whole import: every kind's document takes its maps from here (materialWriter.ts) */
+  readonly textures = new SharedTextures()
   constructor(readonly ctx: KindGlbContext) {}
 
   private source(guid: string): Promise<FbxSource | null> {
@@ -137,8 +139,27 @@ export class KindGlbBuilder {
     return p
   }
 
+  /** A slot holding a material EMBEDDED in the model file (`{fileID: <id>, guid: <the FBX>, type: 3}`): the FBX's own
+   *  material, which the `.meta` neither remaps nor names (`internalIDToNameTable: []`). Chernobyl's Bus_Stop does it on
+   *  LOD1 alone — LOD0 names `Bus_Stop.mat`, LOD1 leaves that slot on the FBX's `Bus_Stop` — and read as a `.mat` the
+   *  ref is nothing, so the far level kept the FBX's untextured grey and its UVs were pruned away (2026-11-04). */
+  private embedded(ref: string): boolean {
+    return !ref.startsWith("name:") && MODEL_EXT.test(this.ctx.resolver.resolve(ref) ?? "")
+  }
+
+  /** `name:<fbx material>` as the `.mat`'s GUID when the pack has one — the ref its other slots use, so the kind
+   *  writes ONE material (and one set of maps) where LOD0 names it by GUID and LOD1 by the embedded slot. */
+  private byNameRef(fbxName: string): string {
+    const um = this.material(`name:${fbxName}`)
+    const meta = um ? `${um.file}.meta` : ""
+    const guid = meta && existsSync(meta) ? /^guid:\s*([0-9a-f]{32})/m.exec(readFileSync(meta, "utf8"))?.[1] : undefined
+    return guid && this.ctx.resolver.resolve(guid) ? guid : `name:${fbxName}`
+  }
+
   private material(ref: string): UnityMaterial | null {
     if (this.mats.has(ref)) return this.mats.get(ref)!
+    // resolved per primitive, by its FBX material's name (assignMaterials)
+    if (this.embedded(ref)) return null
     let um: UnityMaterial | null = null
     if (ref.startsWith("name:")) {
       this.byKey ??= collectUnityMaterials(this.ctx.materialDirs, 8).byKey
@@ -201,10 +222,20 @@ export class KindGlbBuilder {
     const prims = mesh.listPrimitives()
     const byGuid = new Map<string, string>()
     for (const [ n, g ] of src.meta.materials) if (!byGuid.has(g)) byGuid.set(g, n)
-    const slotName = part.materials.map((r) => (r.startsWith("name:") ? r.slice(5) : byGuid.get(r) ?? this.material(r)?.name ?? null))
-    const slotFor = pairSlots(prims.map((pr) => pr.getMaterial()?.getName() ?? ""), slotName)
+    // an embedded slot has no name of its own: it pairs with what is left over, then takes the pack's `.mat` named like
+    // that primitive's FBX material (what Unity's `materialSearch` would find; the FBX's own stays when there is none)
+    const nameOf = (r: string): string | null => (r.startsWith("name:") ? r.slice(5) : this.embedded(r) ? null : byGuid.get(r) ?? this.material(r)?.name ?? null)
+    // AN OVERRIDDEN SLOT IS KNOWN BY WHAT IT HELD IN THE SOURCE PREFAB. Its new material names nothing in the FBX, and
+    // pairing it by what was left over, in order, swapped the faces: Chernobyl's Pharmacy turns every `Wallpaper_01` slot
+    // into `Wall_Paint_01` and every `Wall_Tiiling_01` into `Wall_Tiiling_04`, and Front_Door_01's wall came out with the
+    // paint on the tiled face at LOD0/LOD1 while LOD2 (its `Wallpaper_01` slot left alone, so paired by name) was right —
+    // the material changed with the level (2026-11-04). The source slot is a name the FBX knows; the override is the material.
+    const slotName = part.materials.map((r, k) => nameOf(part.sourceMaterials?.[k] || r) ?? (part.sourceMaterials?.[k] ? nameOf(r) : null))
+    const fbxNames = prims.map((pr) => pr.getMaterial()?.getName() ?? "")
+    const slotFor = pairSlots(fbxNames, slotName)
     for (let i = 0; i < prims.length; i++) {
-      const ref = part.materials[slotFor[i] >= 0 ? slotFor[i] : Math.min(i, part.materials.length - 1)]
+      let ref = part.materials[slotFor[i] >= 0 ? slotFor[i] : Math.min(i, part.materials.length - 1)]
+      if (ref && this.embedded(ref)) ref = fbxNames[i] ? this.byNameRef(fbxNames[i]) : ""
       if (!ref) continue
       const um = this.material(ref)
       // THE DETAIL LAYER ON ANOTHER UV SET (NatureManufacture's bark shader): albedo / normal / ORM are
@@ -317,7 +348,16 @@ export class KindGlbBuilder {
     const scene = doc.createScene(kind.name)
     const root = doc.createNode(kind.name)
     scene.addChild(root)
-    const out: KindDoc = { doc, writer: unityMaterialWriter(doc, this.ctx.resolver), merged: new Map(), imported: new Set(), materials: new Map(), meshes: new Map() }
+    const out: KindDoc = { doc, writer: unityMaterialWriter(doc, this.ctx.resolver, undefined, this.textures), merged: new Map(), imported: new Set(), materials: new Map(), meshes: new Map() }
+    // EVERY MAP OF THE KIND STARTS PREPARING AT ONCE (materialWriter.ts `prefetch`): the parts below take them in
+    // their order, but the decodes / deflates overlap — a kind's first-seen maps one after another were its build time
+    // (Department_Store, 27 new maps: 8.2 s of PNG deflate on the main thread, 2026-11-04)
+    for (const part of kind.parts) {
+      for (const ref of part.materials) {
+        const um = ref && !this.embedded(ref) ? this.material(ref) : null
+        if (um) void this.detailLayer(um).then((d) => out.writer.prefetch(d ? d.um : um)).catch(() => {})   // a hint: a failure shows where the part reads it
+      }
+    }
     const missing: string[] = []
     let parts = 0
     for (const part of kind.parts) {

package/src/unity/lecodesLevel.ts

@@ -70,7 +70,7 @@ export type WriteLevelOptions = FoliageOptions & {
    *  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 }
+  impostor?: { cols: number, rows: number, px?: number, level?: number, samples?: 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. */
@@ -105,7 +105,15 @@ export type WriteLevelOptions = FoliageOptions & {
 // 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
+// 21 (2026-11-04): the impostor bakes S×S samples a texel (`--impostor-samples`, default 8: fractional coverage the engine's
+//     mask cuts) and a third map, the BARK fraction (occlusionTexture r), with the bark's own mesh normal in the data map
+// 22 (2026-11-04): under `--impostor` the pack's `Billboard_*` level goes for every vegetation kind, the ones under 4 m too
+//     (the quad is the billboard; drawn by the cards' shader the pack's cross was a flat pale far tree)
+// 23 (2026-11-04): an alpha-MASK base colour takes COVERAGE-PRESERVING mips and downscale (doctor/coverageMips.ts)
+// 24 (2026-11-04): the triangle budget is PER LOD LEVEL (a chain's levels under it stay whole), and a slot holding the FBX's
+//     EMBEDDED material takes the pack's `.mat` of that name (Bus_Stop LOD1, Ladder_03 were untextured grey)
+//     and an OVERRIDDEN material slot pairs with its primitive by what it held in the source prefab (Pharmacy's walls had swapped faces)
+const BUILDER_VERSION = 26
 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 }
 
@@ -228,8 +236,17 @@ const buildKindGlbs = async (kinds: SceneKind[], builder: KindGlbBuilder, assetD
   // 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 }
+  // `LECODES_IMPORT_PROFILE=1`: a stage stopwatch per kind and a total at the end — where a 40-minute import spends it
+  const profile = !!process.env.LECODES_IMPORT_PROFILE
+  const { ktx2CacheHits } = await import("../doctor/transcodeKtx2")
+  const total: Record<string, number> = {}
+  let stageT = 0
+  const laps: string[] = []
+  const lap = (stage: string): void => { const n = performance.now(); total[stage] = (total[stage] ?? 0) + n - stageT; laps.push(`${stage} ${Math.round(n - stageT)}`); stageT = n }
   let converted = 0, reused = 0
   for (const [ i, k ] of kinds.entries()) {
+    stageT = performance.now(); laps.length = 0
+    const hits0 = ktx2CacheHits()
     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
@@ -238,9 +255,10 @@ const buildKindGlbs = async (kinds: SceneKind[], builder: KindGlbBuilder, assetD
     // 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)
+    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, opts.impostor.samples ?? 0 ] : []) ])).digest("hex").slice(0, 16)
     if (!opts.force && existsSync(glb) && manifest[k.name] === hash) { reused++; continue }
     const { doc, parts, missing } = await builder.build(k)
+    lap("build")
     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
@@ -254,12 +272,18 @@ const buildKindGlbs = async (kinds: SceneKind[], builder: KindGlbBuilder, assetD
     }
     for (const m of missing) log(`   ⚠ ${k.name}: ${m}`)
     if (!parts) { log(`   ⚠ ${k.name}: no mesh could be built — skipped`); continue }
+    lap("ao")
     const cut = await fitTriangleBudget(doc, maxTris)
-    if (cut) log(`   ✂ ${k.name}: ${cut.before.toLocaleString("en")} → ${cut.after.toLocaleString("en")} triangles (--max-tris ${maxTris})`)
+    if (cut) log(`   ✂ ${k.name}: ${cut.before.toLocaleString("en")} → ${cut.after.toLocaleString("en")} triangles on its heaviest level (--max-tris ${maxTris})`)
+    lap("budget")
     // 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 { bakeImpostor, dropBillboards, impostorBounds, impostorLabel } = await import("../doctor/impostor")
+      // the pack's own billboard cross goes for EVERY vegetation kind (the quad is the billboard; a small kind ends at
+      // its last mesh level) — drawn by the cards' shader it was a flat pale cross on every far Chernobyl tree
+      const billboards = await dropBillboards(doc)
+      if (billboards) log(`   ✂ ${k.name}: the pack's billboard level dropped (${billboards} node${billboards > 1 ? "s" : ""})`)
       const box = impostorBounds(doc)
       const height = box ? box.max[1] - box.min[1] : 0
       if (height >= 4) {
@@ -268,13 +292,20 @@ const buildKindGlbs = async (kinds: SceneKind[], builder: KindGlbBuilder, assetD
         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)
+    lap("impostor")
+    const plan = await analyzeDoc(doc, doctor)
+    lap("analyze")
+    const applied = await applyPlan(doc, plan, doctor)
+    lap("doctor")
     writeFileSync(glb, await makeIO().writeBinary(doc))
+    lap("write")
     manifest[k.name] = hash
     converted++
     log(`   [${i + 1}/${kinds.length}] ${k.name}.glb · ${parts} part(s) · ${Math.round(readFileSync(glb).length / 1024)} KB`)
+    if (profile) log(`   ⏱ ${k.name}: ${laps.join(" · ")} ms · ktx2 ${applied.ktx2Encoded} tex (${ktx2CacheHits() - hits0} cached) · ${doc.getRoot().listTextures().length} textures`)
     writeFileSync(manifestPath, JSON.stringify(manifest, null, 1) + "\n")
   }
+  if (profile && converted) log(`   ⏱ total over ${converted} kinds: ${Object.entries(total).map(([ s, ms ]) => `${s} ${(ms / 1000).toFixed(1)} s`).join(" · ")} · texture bytes cached ${builder.textures.images.size} images, ${Math.round(builder.textures.images.bytes / 1048576)} MB`)
   return { converted, reused }
 }