ldr 0.32.0 → 0.33.1

package/README.md

@@ -139,7 +139,7 @@ MPD-embedded parts, such as Studio/OMR unofficial parts or stickers, become part
 | `ldrawSpace` | `false` | `true` keeps native LDraw space (-Y up). |
 | `scale` | `1` | Uniform scale (1 = 1 LDU; 1 stud = 20 LDU). |
 | `step` | all | Initial build step (inclusive, 0-based). |
-| `lod` | `true` | Distance LOD, re-selected for each camera you render with. Batches are split into spatial clusters (off-screen ones are frustum-culled). Each cluster draws the coarsest simplified mesh (from `lod` packs) whose error stays under `lodPx`, drops studs whose 12-LDU disc is under `lodPx`, and hides edges where a stud spans less than `lodEdgePx`. |
+| `lod` | `true` | Distance LOD, re-selected for each camera you render with. Batches are split into spatial clusters (off-screen ones are frustum-culled). Each cluster draws the coarsest simplified mesh (from `lod` packs) whose error stays under `lodPx`, swaps closed studs to a 10-triangle square stud then a flat disc, and drops them once their 12-LDU disc is under `lodPx`, and hides edges where a stud spans less than `lodEdgePx`. |
 | `lodPx` | `0.5` | LOD: maximum screen-space error in pixels. |
 | `lodEdgePx` | `0.5` | LOD: draw edge and conditional lines only where one stud (20 LDU) spans at least this many pixels. `0` = always. |
 | `lodEdgeMinPx` | `0.4` | LOD: draw only edge segments at least this many pixels long on screen. `0` = every segment. |
@@ -190,7 +190,7 @@ Sources: `bench/results/2026-10-18T18-10-46-518Z-falcon-vs-stock.md` (the Falcon
 | Millennium Falcon ×19 | 100,054 | 54.2 ms | **19.6 ms** | 2.04 s | **0.38 s** |
 | Millennium Falcon ×75 | 394,950 | 204.7 ms | **29.2 ms** | 2.40 s | **1.03 s** |
 
-The benchmark model is a fleet: the LDraw OMR model of set 10179 (UCS Millennium Falcon, 5,266 parts, 251 unique) placed 2, 19 or 75 times on a grid (`apps/demo-site/scripts/build-fleet.ts`). It is a hard case for ldr: dense, detailed ships stay large on screen, so distance LOD can't drop much and the overview still draws ~27M triangles (32M before Round 62 measured LOD distance from each cluster's box); on two ships ldr only matches stock instancing per frame (it still loads 14× faster). Datsville, the benchmark until Round 60 (a flat town, 392,514 bricks, mostly baseplates), went from 409.6 to 12.5 ms per frame and 24.7 to 1.6 s load.
+The benchmark model is a fleet: the LDraw OMR model of set 10179 (UCS Millennium Falcon, 5,266 parts, 251 unique) placed 2, 19 or 75 times on a grid (`apps/demo-site/scripts/build-fleet.ts`). It is a hard case for ldr: dense, detailed ships stay large on screen, so distance LOD can't drop much and the overview still draws ~22M triangles (32M before Round 62's cluster-box distances, 27M before Round 63's square-stud mid LOD); on two ships ldr only matches stock instancing per frame (it still loads 14× faster). Datsville, the benchmark until Round 60 (a flat town, 392,514 bricks, mostly baseplates), went from 409.6 to 12.5 ms per frame and 24.7 to 1.6 s load.
 
 How much each optimization contributed on Datsville 100k (Rounds 1–20, before the Falcon fleets), in ms per frame: welding 108.1 → 64.6, stud culling → 50.8, underside culling → 41.7, low-detail studs → 31.0, single-sided faces → 30.1. Triangles per frame drop from 142.7M to 59.1M. Distance LOD (Rounds 19–20: simplified and bounding-box levels with a silhouette-coverage error, sub-pixel studs dropped, undersides skipped where they can't be seen) then takes it to 4.4 ms and 4.0M triangles; ≤ 1.5% of pixels differ from full detail (mostly sub-pixel stud moiré).
 
@@ -209,7 +209,7 @@ Reproduce: `cd bench && bun run setup && bun run perf` (regression gate) or `bun
 
 ## LDraw spec compliance
 
-- Line types 0–5. BFC: `CERTIFY`, `CCW`/`CW`, `INVERTNEXT`, `NOCLIP`, inverted matrices.
+- Line types 0–5. BFC (ldraw.org article 415): `CERTIFY`/`NOCERTIFY` (decided by the first BFC statement before the file's first type 1-5 line, so `0 BFC CCW` alone certifies and a late `CERTIFY` doesn't), `CCW`/`CW`, `CLIP`/`NOCLIP` (polygons drawn while culling is off are visible from both sides, including in subfiles referenced then, which can't turn it back on), `INVERTNEXT` (the immediately following subfile reference only), inverted matrices.
 - MPD: `0 FILE` / `0 NOFILE`, and `0 !DATA` (base64 PNGs). An MPD file is a part or a model by its `!LDRAW_ORG` type, otherwise by whether it has its own geometry. Embedded parts override library parts.
 - Geometry drawn directly in model files (type 2–5 lines outside parts), on by default.
 - `0 STEP`, nested submodel step sequencing, `0 ROTSTEP` (`REL`/`ADD`/`ABS`/`END`), and `0 BUFEXCHG`.

package/dist/cli.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 
-// ../../../../../../../tmp/ldr-build-MGO8Dx/src/cli.ts
+// ../../../../../../../tmp/ldr-build-78cdvu/src/cli.ts
 import fs4 from "node:fs";
 import zlib from "node:zlib";
 
-// ../../../../../../../tmp/ldr-build-MGO8Dx/src/node/build-pack.ts
+// ../../../../../../../tmp/ldr-build-78cdvu/src/node/build-pack.ts
 import fs3 from "node:fs";
 import path3 from "node:path";
 
-// ../../../../../../../tmp/ldr-build-MGO8Dx/src/node/resolver.ts
+// ../../../../../../../tmp/ldr-build-78cdvu/src/node/resolver.ts
 import fs from "node:fs";
 import path from "node:path";
 
-// ../../../../../../../tmp/ldr-build-MGO8Dx/src/spec.ts
+// ../../../../../../../tmp/ldr-build-78cdvu/src/spec.ts
 var norm = (s) => s.trim().toLowerCase().replace(/\\/g, "/").replace(/\/+/g, "/");
 var COLOUR_ID_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
 var namedCodes = new Map;
@@ -723,7 +723,7 @@ function fileStepViews(f) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-MGO8Dx/src/model.ts
+// ../../../../../../../tmp/ldr-build-78cdvu/src/model.ts
 var CALLOUT_END = 999999;
 var stepKey = (steps) => steps.map((x) => String(x).padStart(6, "0")).join(".") + "~";
 var defLine = new WeakMap;
@@ -1138,7 +1138,7 @@ function blendedColourHex(code) {
   return "#" + [0, 1, 2].map((k) => (a[k] + b[k] >> 1).toString(16).padStart(2, "0")).join("").toUpperCase();
 }
 
-// ../../../../../../../tmp/ldr-build-MGO8Dx/src/node/resolver.ts
+// ../../../../../../../tmp/ldr-build-78cdvu/src/node/resolver.ts
 var TOP_STUD_RE = /^(stud|studa|stud2|stud2a|stud6|stud6a|stud10|stud15|stud2s|stud2s2|stud-logo\d*|stud2-logo\d*)\.dat$/i;
 var UNDER_STUD_RE = /^(stud3|stud3a|stud4.*|stud12|stud16.*|stud18a)\.dat$/i;
 var norm2 = (ref) => ref.trim().replace(/\\/g, "/").toLowerCase();
@@ -1465,11 +1465,11 @@ function collectDeps(lib, refs) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-MGO8Dx/src/node/compile.ts
+// ../../../../../../../tmp/ldr-build-78cdvu/src/node/compile.ts
 import fs2 from "node:fs";
 import path2 from "node:path";
 
-// ../../../../../../../tmp/ldr-build-MGO8Dx/src/node/lod.ts
+// ../../../../../../../tmp/ldr-build-78cdvu/src/node/lod.ts
 import { MeshoptSimplifier, MeshoptEncoder } from "meshoptimizer";
 await Promise.all([MeshoptSimplifier.ready, MeshoptEncoder.ready]);
 function reorderMesh(P, N, C, I) {
@@ -1661,7 +1661,55 @@ function lodChain(P, C, I) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-MGO8Dx/src/node/compile.ts
+// ../../../../../../../tmp/ldr-build-78cdvu/src/node/compile.ts
+class BfcState {
+  accum;
+  ccw = true;
+  certified = null;
+  local = true;
+  inv = false;
+  constructor(accum = true) {
+    this.accum = accum;
+  }
+  meta(t) {
+    const o = t.split(/\s+/).slice(2);
+    this.inv = false;
+    if (this.certified === null)
+      this.certified = !o.includes("NOCERTIFY");
+    if (!this.certified)
+      return;
+    for (const w of o) {
+      if (w === "CW")
+        this.ccw = false;
+      else if (w === "CCW")
+        this.ccw = true;
+      else if (w === "CLIP")
+        this.local = true;
+      else if (w === "NOCLIP")
+        this.local = false;
+      else if (w === "INVERTNEXT")
+        this.inv = true;
+    }
+  }
+  line(type) {
+    if (type !== "0" && this.certified === null)
+      this.certified = false;
+    if (type !== "1")
+      this.inv = false;
+  }
+  takeInvert() {
+    const v = this.inv;
+    this.inv = false;
+    return v;
+  }
+  get cull() {
+    return this.accum && this.local;
+  }
+}
+var windOrder = (n, flip, cull) => {
+  const f = n === 3 ? [0, 1, 2] : [0, 1, 2, 0, 2, 3], b = n === 3 ? [0, 2, 1] : [0, 2, 1, 0, 3, 2];
+  return cull ? flip ? b : f : [...f, ...b];
+};
 function loadColors(root) {
   const map = new Map;
   for (const l of fs2.readFileSync(path2.join(root, "LDConfig.ldr"), "latin1").split(/\r?\n/)) {
@@ -1731,54 +1779,48 @@ class Compiler {
       return this.cache.get(ck);
     const out = { body: { pos: [], col: [] }, under: { pos: [], col: [] }, edges: [], condLines: 0, cond: this.opts.cond ? [] : undefined, condUnder: this.opts.cond ? [] : undefined, studs: [], bbox: [Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity], fullBottom: false };
     const colorOf = (code) => code === "16" ? [1, 1, 1, 0] : [...this.colors.get(code) || (code.startsWith("0x2") ? [parseInt(code.slice(3, 5), 16) / 255, parseInt(code.slice(5, 7), 16) / 255, parseInt(code.slice(7, 9), 16) / 255] : blendedRgb(code) ?? [1, 0, 1]), 1];
-    const walk = (fk, M, color, invert, target, depth, inh = null, scope0 = null) => {
+    const walk = (fk, M, color, invert, target, depth, inh = null, scope0 = null, cull = true) => {
       if (depth > 40)
         return;
-      let ccw = true, certified = false, invertNext = false, scope = scope0;
+      const bfc = new BfcState(cull);
+      let scope = scope0;
       for (const raw of this.lib.read(fk).split(/\r?\n/)) {
         const t = raw.trim();
         if (!t)
           continue;
         const c = t[0];
+        if (c === "0" && /^0\s+BFC(\s|$)/.test(t)) {
+          bfc.meta(t);
+          continue;
+        }
+        bfc.line(c);
         if (c === "0") {
           if (t.includes("!COLOUR") && COLOUR_RE.test(t)) {
             scope = defineColour(t, scope);
             continue;
           }
-          if (/^0\s+BFC/.test(t)) {
-            if (/CERTIFY/.test(t) && !/NOCERTIFY/.test(t))
-              certified = true;
-            if (/\bCW\b/.test(t))
-              ccw = false;
-            if (/\bCCW\b/.test(t))
-              ccw = true;
-            if (/INVERTNEXT/.test(t))
-              invertNext = true;
-          }
           continue;
         }
         if (c === "1") {
+          const invertNext = bfc.takeInvert();
           const r = parseType1(t);
           if (!r)
             continue;
           const base = r.name.trim().replace(/\\/g, "/").split("/").pop().toLowerCase();
           const isTop = TOP_STUD_RE.test(base), isUnder = UNDER_STUD_RE.test(base);
           const ck2 = this.resolve(r.name, isTop);
-          if (!ck2) {
-            invertNext = false;
+          if (!ck2)
             continue;
-          }
           const childColor = r.color === "16" ? color : r.color, childInh = r.color === "16" ? inh : this.local(r.color, scope);
           const Mc = compose(M, r.m);
           const inv = invert !== invertNext !== det3(r.m) < 0;
-          invertNext = false;
           if (isTop && separateStuds) {
             out.studs.push({ kind: ck2, color: childInh ? this.studToken(childColor, childInh) : childColor, m: Mc });
             fullKind.set(out.studs.length - 1, this.lib.resolve(r.name));
             growBox(out.bbox, Mc, this.compile(ck2, false).bbox);
             continue;
           }
-          walk(ck2, Mc, childColor, inv, isUnder ? "under" : target, depth + 1, childInh, scope);
+          walk(ck2, Mc, childColor, inv, isUnder ? "under" : target, depth + 1, childInh, scope, bfc.cull);
           continue;
         }
         const tok = t.split(/\s+/);
@@ -1806,22 +1848,40 @@ class Compiler {
             pts.push(xf(M, v.slice(i * 3, i * 3 + 3)));
           for (const p of pts)
             grow(out.bbox, p);
-          let order = n === 3 ? [0, 1, 2] : [0, 1, 2, 0, 2, 3];
-          if (!ccw !== invert)
-            order = n === 3 ? [0, 2, 1] : [0, 2, 1, 0, 3, 2];
-          const rgba = this.rgbaAt(tok[1], color, inh, scope, colorOf);
-          const b = out[target];
-          for (const i of order) {
+          const flip = !bfc.ccw !== invert, rgba = this.rgbaAt(tok[1], color, inh, scope, colorOf), b = out[target];
+          for (const i of windOrder(n, flip, true)) {
             b.pos.push(...pts[i]);
             b.col.push(...rgba);
           }
+          if (bfc.cull)
+            culled++;
+          else {
+            const bb = back[target];
+            for (const i of windOrder(n, !flip, true)) {
+              bb.pos.push(...pts[i]);
+              bb.col.push(...rgba);
+            }
+          }
         }
       }
-      if (!certified)
+      if (!bfc.certified)
         out.uncertified = true;
     };
     const fullKind = new Map;
+    let culled = 0;
+    const back = { body: { pos: [], col: [] }, under: { pos: [], col: [] } };
     walk(key, IDENT, "16", false, "body", 0);
+    if (back.body.pos.length || back.under.pos.length) {
+      if (!culled)
+        out.uncertified = true;
+      if (!out.uncertified)
+        for (const t of ["body", "under"]) {
+          for (const x of back[t].pos)
+            out[t].pos.push(x);
+          for (const x of back[t].col)
+            out[t].col.push(x);
+        }
+    }
     seatStuds(out, fullKind, (k) => this.compile(k, false).bbox);
     if (this.opts.tex && this.hasTex(key))
       this.texPass(key, out, separateStuds, colorOf);
@@ -1906,10 +1966,11 @@ class Compiler {
   }
   texPass(key, out, separateStuds, colorOf) {
     const tbody = { pos: [], col: [] }, texb = new Map;
-    const walk = (fk, M, color, invert, target, depth, texIn, inh = null, scope0 = null) => {
+    const walk = (fk, M, color, invert, target, depth, texIn, inh = null, scope0 = null, cull = true) => {
       if (depth > 40)
         return;
-      let ccw = true, invertNext = false, scope = scope0;
+      const bfc = new BfcState(cull);
+      let scope = scope0;
       let stack = [];
       let next = null;
       for (const raw of this.lib.read(fk).split(/\r?\n/)) {
@@ -1920,7 +1981,13 @@ class Compiler {
         if (t[0] === "0") {
           const m = /^0\s+(\S+)\s*(.*)$/.exec(t);
           const kw = (m?.[1] ?? "").toUpperCase(), rest = m?.[2] ?? "";
+          if (m?.[1] === "BFC") {
+            bfc.meta(t);
+            next = null;
+            continue;
+          }
           if (kw === "!TEXMAP") {
+            bfc.line("0");
             const op = (rest.split(/\s+/)[0] || "").toUpperCase();
             next = null;
             if (op === "START" || op === "NEXT") {
@@ -1944,25 +2011,23 @@ class Compiler {
             next = null;
             t = rest.trim();
             colon = true;
-            if (!t || t[0] === "0")
+            if (!t || t[0] === "0") {
+              bfc.line("0");
               continue;
+            }
           } else {
+            bfc.line("0");
             if (kw === "!COLOUR")
               scope = defineColour(t, scope);
-            if (kw === "BFC") {
-              if (/\bCW\b/.test(t))
-                ccw = false;
-              if (/\bCCW\b/.test(t))
-                ccw = true;
-              if (/INVERTNEXT/.test(t))
-                invertNext = true;
-            }
             if (kw === "STEP")
               stack = [];
             next = null;
             continue;
           }
         }
+        const c = t[0];
+        bfc.line(c);
+        const invertNext = c === "1" && bfc.takeInvert();
         let tex = texIn;
         if (next) {
           tex = next;
@@ -1977,7 +2042,6 @@ class Compiler {
               tex = top.map;
           }
         }
-        const c = t[0];
         if (c === "1") {
           const r = parseType1(t);
           if (!r)
@@ -1985,15 +2049,12 @@ class Compiler {
           const base = r.name.trim().replace(/\\/g, "/").split("/").pop().toLowerCase();
           const isTop = TOP_STUD_RE.test(base), isUnder = UNDER_STUD_RE.test(base);
           const ck2 = this.resolve(r.name, isTop);
-          if (!ck2) {
-            invertNext = false;
+          if (!ck2)
             continue;
-          }
           const inv = invert !== invertNext !== det3(r.m) < 0;
-          invertNext = false;
           if (isTop && separateStuds)
             continue;
-          walk(ck2, compose(M, r.m), r.color === "16" ? color : r.color, inv, isUnder ? "under" : target, depth + 1, tex, r.color === "16" ? inh : this.local(r.color, scope), scope);
+          walk(ck2, compose(M, r.m), r.color === "16" ? color : r.color, inv, isUnder ? "under" : target, depth + 1, tex, r.color === "16" ? inh : this.local(r.color, scope), scope, bfc.cull);
           continue;
         }
         if (c !== "3" && c !== "4")
@@ -2004,9 +2065,7 @@ class Compiler {
         const pts = [];
         for (let i = 0;i < n; i++)
           pts.push(xf(M, v.slice(i * 3, i * 3 + 3)));
-        let order = n === 3 ? [0, 1, 2] : [0, 1, 2, 0, 2, 3];
-        if (!ccw !== invert)
-          order = n === 3 ? [0, 2, 1] : [0, 2, 1, 0, 3, 2];
+        const order = windOrder(n, !bfc.ccw !== invert, bfc.cull || !!out.uncertified);
         const rgba = this.rgbaAt(tok[1], color, inh, scope, colorOf);
         if (tex) {
           const tk = tex.glossmap ? tex.texture + "\x00" + tex.glossmap : tex.texture;
@@ -2376,7 +2435,7 @@ function encodePack(parts, studKinds, weld, extra, options = {}) {
   return Buffer.concat([head, ...chunks.map((c) => new Uint8Array(c.buffer, c.byteOffset, c.byteLength))]);
 }
 
-// ../../../../../../../tmp/ldr-build-MGO8Dx/src/node/build-pack.ts
+// ../../../../../../../tmp/ldr-build-78cdvu/src/node/build-pack.ts
 function packCompilerOpts(o) {
   return { studs: o.studs ?? "low", prims: o.primitives ?? "full", weld: o.weld ?? true, separateStuds: true, cond: !!o.cond, tex: !!o.textures };
 }
@@ -2449,7 +2508,7 @@ function buildPack(o) {
   return { data: encodePack(parts, kinds, comp.opts.weld, extra, { texture, lod: o.lod !== false, reorder: !!o.reorder }), parts: parts.size, studKinds: kinds.size, missing: [...missing], ...warnings.length ? { warnings } : {} };
 }
 
-// ../../../../../../../tmp/ldr-build-MGO8Dx/src/cli.ts
+// ../../../../../../../tmp/ldr-build-78cdvu/src/cli.ts
 var HELP = `ldr pack — build a parts pack for the ldr three.js renderer
 
 Usage: