lecodes-assets 2.4.10 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-assets",
-  "version": "2.4.10",
+  "version": "2.5.0",
   "description": "LeCodes asset pipeline: FBX → GLB (ufbx), clip merging by bone name, texture embedding, GLB doctor (bone cap, texture normalize, KTX2).",
   "type": "module",
   "bin": {

package/src/commands/doctor.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs"
-import { bool, CliError, defineCommand, missing, str } from "../cli-kit"
-import { doctorFlags, doctorOptions, ktx2Progress, log, logDoctorResult, resolveInputs, wantsDoctorFix, wantsKtx2 } from "./shared"
+import { bool, CliError, defineCommand, int, missing, str } from "../cli-kit"
+import { doctorFlags, doctorOptions, impostorFlag, ktx2Progress, log, logDoctorResult, resolveInputs, wantsDoctorFix, wantsKtx2 } from "./shared"
 
 export default defineCommand({
   name: "doctor",
@@ -15,6 +15,8 @@ export default defineCommand({
     ...doctorFlags,
     lod: str("add mesh LOD levels (<name>_LOD1… siblings at these triangle ratios, same skin; >= 2000-tri meshes only) — creator-gl shows one by screen size (docs/lod-plan.md)", { value: "0.5,0.2", group: "LOD" }),
     "lod-bones": bool("fold fingers / toes / twists onto their parents in the last level's skin"),
+    impostor: str("bake the level-0 geometry into an impostor atlas (albedo + hull normal / AO) and add it as a LOD level, one camera-facing quad (<name>_LOD<k>, k = --impostor-level, never past the first missing level; the levels from k up are replaced). PNG / JPEG base colours only — run it with --ktx2, not after it; the atlases skip --max-size. <A>x<E>[@<px>] = A azimuths × E elevation rows (0°, 90°/E, …; 8x2@256), oct<N>[@<px>] = the N×N hemi-octahedron (steep views too); bare = 12x3; px = a frame's pixels (default 256 for a plant ≥ 8 m, 128 under)", { value: "<A>x<E>[@px]|oct<N>[@px]", bare: "12x3" }),
+    "impostor-level": int("the LOD slot the quad takes (default 2: shown under 0.12 of the viewport height; 1 = under 0.30)"),
   },
   examples: [
     "lecodes assets doctor hero.glb",
@@ -29,7 +31,8 @@ export default defineCommand({
     const { validateGlb, formatReport } = await import("../doctor/validateGlb")
     const useKtx2 = wantsKtx2(flags)
     const lod = (flags.lod ?? "").split(",").map(Number).filter((n) => n > 0 && n < 1)
-    const doFix = wantsDoctorFix(flags) || flags["fix-metallic"] || lod.length > 0
+    const impostor = impostorFlag(flags.impostor, flags["impostor-level"])
+    const doFix = wantsDoctorFix(flags) || flags["fix-metallic"] || lod.length > 0 || !!impostor
     const opts = { ...doctorOptions(flags), lod, lodBones: flags["lod-bones"] }
     const ktxEncoder = useKtx2 ? findKtxEncoder() : null
     if (useKtx2) {
@@ -44,6 +47,15 @@ export default defineCommand({
       if (!existsSync(input)) { console.error(`\n✗ not found: ${input}`); exitCode = 1; continue }
       const doc = await io.read(input)
       if (given.has("dump")) { await dumpTextures(doc, flags.dump && files.length === 1 ? flags.dump : input.replace(/\.glb$/i, "-textures")); continue }
+      // before the analysis: the plan then sees the atlases (KTX2 encodes them) and not the levels the quad replaced
+      if (impostor) {
+        const { bakeImpostor, impostorLabel } = await import("../doctor/impostor")
+        try {
+          const imp = await bakeImpostor(doc, { ...impostor, log })
+          if (imp) log(`   impostor: ${imp.node} · ${impostorLabel(imp)} · r ${imp.radius.toFixed(2)} m · ${imp.triangles} triangles in ${imp.ms} ms`)
+          else log(`   impostor: no level-0 triangles in ${input}`)
+        } catch (e) { console.error(`\n✗ ${input}: ${(e as Error).message}`); exitCode = 1; continue }
+      }
       const plan = await analyzeDoc(doc, opts)
       const rep = reportPlan(plan)
       log(`\n🔍 ${input}`)

package/src/commands/scene.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { dirname } from "node:path"
 import { bool, defineCommand, int, missing, notFound, num, str, usageError } from "../cli-kit"
-import { log, regexFlag, seconds } from "./shared"
+import { impostorFlag, log, regexFlag, seconds } from "./shared"
 
 /** `x0,z0,x1,z1` (any corner order) → [minX, minZ, maxX, maxZ]. */
 const parseDropAt = (s: string | undefined): [number, number, number][] | undefined => {
@@ -48,6 +48,8 @@ export default defineCommand({
     "no-shadows": str("kinds whose name matches take 'castShadows: false': a pack's BACKGROUND MOUNTAINS are 2 km meshes a kilometre out that Unity's shadow distance never reaches, and here their shadow lies across the whole map", { value: "<re>" }),
     "no-colliders": bool("write NO colliders: the kinds are pure visuals, nothing gets a Physics body. For a viewer, or a level whose 78 000 placements would otherwise be 20 000 Jolt bodies before the game adds one of its own"),
     "max-tris": int("triangles a kind may have before the import simplifies it (default 50000, 0 = no cap): a photogrammetry scan otherwise arrives as a million-triangle prop AND mesh collider"),
+    impostor: str("foliage kinds ≥ 4 m tall get their far LOD level as ONE camera-facing quad over an atlas of views (albedo + hull normal / AO), replacing the pack's billboard; the atlases skip --max-size. <A>x<E>[@<px>] = A azimuths × E elevation rows (0°, 90°/E, …; 8x2@256), oct<N>[@<px>] = the N×N hemi-octahedron (steep views too); bare = 12x3; px = a frame's pixels (default 256 for a plant ≥ 8 m, 128 under)", { value: "<A>x<E>[@px]|oct<N>[@px]", bare: "12x3" }),
+    "impostor-level": int("the LOD slot the quad takes (default 2: shown under 0.12 of the viewport height; 1 = under 0.30, the pack's LOD1 goes; never past the first missing level)"),
     "no-trim-cards": bool("skip the alpha-card trim the import otherwise runs (it can empty a kind whose decal atlas is mostly clear)"),
     filter: str("keep only instances whose kind name / scene group / node name matches", { value: "<re>", group: "Subset" }),
     "drop-at": str(`leave OUT the placements standing at these points ("x,y,z;x,y,z", the lecodes frame the scene file prints, within 10 cm): the one instance of a kind the game moves while its twins stay put — the range's five lane targets, which Unity names like the sixth on a shelf`, { value: "<x,y,z;…>" }),
@@ -55,6 +57,7 @@ export default defineCommand({
     group: str("only instances under a scene group whose path contains this", { value: "name" }),
     region: str("only instances inside this Unity X/Z rectangle", { value: "x0,z0,x1,z1" }),
     "no-trees": bool("skip the terrain's painted trees"),
+    "terrain-res": num("the heightfield's largest resolution, samples a side — a finer Unity heightmap is read every k-th sample (Chernobyl's 4097² over 500 m: 12 cm cells, 117 MB, 33 M navmesh triangles; 1025 = half-metre cells; default 1025)", { value: "<n>" }),
     "no-details": bool("skip the terrain's detail meshes"),
     "include-inactive": bool("import inactive GameObjects too"),
     handedness: str("how Unity's left-handed frame is undone (default x: −x, (x, −y, −z, w))", { value: "x|none", group: "Source" }),
@@ -86,6 +89,8 @@ export default defineCommand({
         project: flags.project, name: flags.name, force: flags.force, maxSize: flags["max-size"] ?? 1024, ktx2: !flags.png, log,
         foliage: regexFlag(flags.foliage), noFoliage: flags["no-foliage"], noSun: flags["no-sun"],
         noLightmap: regexFlag(flags["no-lightmap"]), noTrimCards: flags["no-trim-cards"], colliderFit: flags["collider-fit"], noColliders: flags["no-colliders"], noShadows: regexFlag(flags["no-shadows"]), maxTris: flags["max-tris"],
+        impostor: impostorFlag(flags.impostor, flags["impostor-level"]),
+        terrainRes: flags["terrain-res"] ?? 1025,
         // the invocation, for the scene file's header (quote what a shell would need quoted)
         command: "lecodes assets scene " + argv.map((a) => (/[\s"'|<>^&();]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)).join(" "),
       })

package/src/commands/shared.ts

@@ -3,7 +3,7 @@
 
 import { existsSync, readdirSync, statSync } from "node:fs"
 import { join } from "node:path"
-import { bool, int, num, str, type FlagValues } from "../cli-kit"
+import { bool, int, num, str, usageError, type FlagValues } from "../cli-kit"
 import type { ApplyResult, DoctorOptions } from "../doctor/doctor"
 
 export const log = (s: string): void => console.log(s)
@@ -117,5 +117,24 @@ export const resolveInputs = (args: string[], ext = /\.glb$/i, skipGenerated = t
   return [ ...new Set(out) ]
 }
 
+/** `--impostor <A>x<E>[@<px>]` (the grid of A azimuths × E elevation rows: "12x3", "8x2@256") or `oct<N>[@<px>]` (the
+ *  hemi-octahedron: "oct8", "oct8@128"), bare = 12x3, + `--impostor-level` → the bake's options (rows 0 = the
+ *  octahedron, cols = N), or undefined when absent. */
+export const impostorFlag = (v: string | undefined, level?: number): { cols: number, rows: number, px?: number, level?: number } | undefined => {
+  if (v === undefined) return undefined
+  if (level !== undefined && (!Number.isInteger(level) || level < 1 || level > 3)) throw usageError(`--impostor-level wants 1, 2 or 3 — got "${level}"`)
+  const s = v.trim() || "12x3"
+  const bad = (why: string): Error => usageError(`--impostor wants <A>x<E>[@<px>] (azimuths ≥ 3, rows 1..8) or oct<N>[@<px>] (N 2..64), px 32..1024 a multiple of 4 — e.g. 12x3, 8x2@256, oct8@128 — got "${v}" (${why})`)
+  const grid = /^(\d+)x(\d+)(?:@(\d+))?$/i.exec(s), oct = /^oct(\d+)(?:@(\d+))?$/i.exec(s)
+  if (!grid && !oct) throw bad("not either form")
+  const cols = Number(grid ? grid[1] : oct![1]), rows = grid ? Number(grid[2]) : 0
+  const pxs = grid ? grid[3] : oct![2], px = pxs ? Number(pxs) : undefined
+  if (grid && (cols < 3 || cols > 64)) throw bad("azimuths 3..64")
+  if (grid && (rows < 1 || rows > 8)) throw bad("rows 1..8")
+  if (oct && (cols < 2 || cols > 64)) throw bad("N 2..64")
+  if (px !== undefined && (px < 32 || px > 1024 || px % 4 !== 0)) throw bad("px 32..1024, a multiple of 4")
+  return { cols, rows, px, level }
+}
+
 /** `--x <regex>` as a case-insensitive RegExp, or undefined. */
 export const regexFlag = (v: string | undefined): RegExp | undefined => (v ? new RegExp(v, "i") : undefined)

package/src/doctor/cardTrim.ts

@@ -50,6 +50,8 @@ export function planCardTrim(doc: Document, opts: CardTrimOptions): CardTrimPlan
     for (const prim of mesh.listPrimitives()) {
       const mat = prim.getMaterial()
       if (!mat || mat.getAlphaMode() !== 'MASK' || prim.getMode() !== 4) continue
+      // an impostor quad (doctor/impostor.ts) is a MASK quad over an atlas of views, not a card: its corners are ids
+      if ((mat.getExtras() as { lecodes?: { impostor?: unknown } } | null)?.lecodes?.impostor !== undefined) continue
       if (!prim.getAttribute('POSITION') || !prim.getAttribute('TEXCOORD_0')) continue
       const tex = mat.getBaseColorTexture()
       const info = mat.getBaseColorTextureInfo()