ldr 0.4.1 → 0.5.1

package/dist/node/lod.d.ts

@@ -0,0 +1,17 @@
+/** Vertex-cache + vertex-fetch order (meshoptimizer): reorders triangles for post-transform cache reuse, then vertices by first use. */
+export declare function reorderMesh(P: ArrayLike<number>, N: ArrayLike<number>, C: ArrayLike<number>, I: ArrayLike<number>): {
+    P: Float32Array<ArrayBuffer>;
+    N: Float32Array<ArrayBuffer>;
+    C: Float32Array<ArrayBuffer>;
+    I: Uint32Array<ArrayBuffer>;
+};
+/** Welded, flat-shaded mesh: positions / normals (3 per vertex), colours (rgba per vertex), triangle indices. */
+export type LodMesh = {
+    P: Float32Array;
+    N: Float32Array;
+    C: Float32Array;
+    I: Uint32Array;
+    err: number;
+};
+/** Simplified levels of a welded mesh (positions P, rgba C per vertex, triangles I). Empty when the mesh is too small to benefit. */
+export declare function lodChain(P: ArrayLike<number>, C: ArrayLike<number>, I: ArrayLike<number>): LodMesh[];

package/dist/render.d.ts

@@ -12,16 +12,33 @@ export type LdrParams = {
     condStuds?: boolean;
     /** Draw textured (!TEXMAP) parts with their PNGs when the pack carries them (pack v2 "tex", `ldr pack --textures`). Default true. */
     tex?: boolean;
+    /** Compact vertex formats (int8 normals, uint8 colours). Default true. */
+    quant?: boolean;
+    /** Distance LOD: spatial clusters per part, simplified meshes from `lod` packs, studs dropped and edges hidden once sub-pixel. Default true. */
+    lod?: boolean;
+    /** LOD: max screen-space error in pixels (default 0.5). */
+    lodPx?: number;
+    /** LOD: draw edge lines only where one stud (20 LDU) spans at least this many pixels (default 0.5; 0 = always). */
+    lodEdgePx?: number;
+    /** LOD: drop sub-pixel studs (default true). */
+    lodStuds?: boolean;
+    /** LOD: use simplified meshes from `lod` packs (default true). */
+    lodMesh?: boolean;
+    /** Global build step per instance (same order as `insts`). Enables `setStep`: steps become instance-buffer compaction with
+     *  step-aware culling instead of a rebuild. */
+    steps?: ArrayLike<number>;
 };
 export type Inst = {
     part: string;
     color: string;
     m: number[];
 };
+/** A decoded parts pack. `buffer` is the raw (uncompressed) pack, used by `mergePacks`. */
 export type Pack = {
     header: any;
     arr: (r: any) => any;
     bytes: number;
+    buffer?: ArrayBuffer;
 };
 export declare function loadPack(url: string): Promise<Pack>;
 /** Decode an uncompressed parts pack (4-byte LE header length, JSON header, then aligned typed-array payload). */
@@ -47,6 +64,24 @@ export declare function conditionalLineVisible(cond: ArrayLike<number>, i: numbe
  *  `cond` is part-space stride 12 (p0, p1, c0, c1), e.g. from `conditionalLines(pack, pack.header.parts[name])`.
  *  GPU cost: 2 vertices x 13 floats per line (104 B/line), per part, not per instance. Keep `geometry.instanceCount` in sync with `im.count`. */
 export declare function createInstancedConditionalEdges(cond: ArrayLike<number>, im: THREE.InstancedMesh, material?: THREE.Material): THREE.LineSegments;
+/** Culling result in flat arrays. Studs are enumerated in instance order, then each part's `studs` order (the order `forEachStud` visits). */
+export type CullResult = {
+    nStuds: number;
+    studHidden: Uint8Array;
+    studUp: Uint8Array;
+    underHidden: Uint8Array;
+    studsHidden: number;
+    /** With `steps`: the first build step at which each stud / underside is hidden (STEP_NEVER = never), for step-aware culling. */
+    studHideStep?: Int32Array;
+    underHideStep?: Int32Array;
+};
+/** `studHideStep` / `underHideStep` value for "never hidden". */
+export declare const STEP_NEVER = 2147483647;
+/** Visit every stud (instance order, then part stud order) with its world matrix `w` (scratch; copy to keep). */
+export declare function forEachStud(insts: Inst[], H: any, fn: (j: number, inst: number, w: Float64Array, kind: string, color: string, stud: number) => void): void;
+/** `steps` (optional, per instance): also compute when each stud / underside becomes hidden as the model is built step by step. */
+export declare function cullCore(insts: Inst[], H: any, steps?: ArrayLike<number>): CullResult;
+/** Object-shaped culling result (one entry per stud with its world matrix). Kept for API compatibility; `buildLdrScene` uses `cullCore`. */
 export declare function computeCulling(insts: Inst[], H: any): {
     studs: {
         kind: string;
@@ -57,13 +92,20 @@ export declare function computeCulling(insts: Inst[], H: any): {
     underHidden: boolean[];
 };
 export declare function buildLdrScene(insts: Inst[], pack: Pack, P: LdrParams, color: (c: string) => THREE.Color, mark: (k: string) => void): {
-    root: THREE.Group<THREE.Object3DEventMap>;
+    root: THREE.Group;
     stats: any;
     setCull: (studs: boolean, under: boolean) => void;
     setSide: (front: boolean) => void;
     setEdges: (v: boolean) => void;
     setCond: (v: boolean) => void;
     swapStuds: (alt: any) => () => void;
+    setLod: (on: boolean) => void;
+    setStep: (s: number | null) => {
+        studsTotal: number;
+        studsHidden: number;
+        undersTotal: number;
+        undersHidden: number;
+    };
     box: THREE.Box3;
     texturesReady: Promise<void>;
 };

package/dist/scene.d.ts

@@ -33,6 +33,15 @@ export interface LdrObjectOptions {
     scale?: number;
     /** Initial step (inclusive, 0-based global sequence from `sequenceSteps`). Default: show all. */
     step?: number;
+    /** Distance LOD, re-selected for each camera you render with. Default true. Batches are split into spatial clusters (so off-screen
+     *  ones are frustum-culled); each cluster draws the coarsest simplified mesh (from `lod` packs, the `buildPack` default) whose error
+     *  stays under `lodPx`, drops studs whose 12-LDU disc is under `lodPx`, and hides edge lines where a stud spans under `lodEdgePx`.
+     *  Datsville 100k on an M4 Pro: 22 -> 6.3 ms per frame (57 -> 9.7 ms with edges); <=1.6% of pixels differ, mostly stud moire. */
+    lod?: boolean;
+    /** LOD: max screen-space error in pixels. Default 0.5. */
+    lodPx?: number;
+    /** LOD: draw edge / conditional lines only where one stud (20 LDU) spans at least this many pixels. Default 0.5; 0 = always. */
+    lodEdgePx?: number;
 }
 export interface LdrStats {
     instances: number;
@@ -48,6 +57,8 @@ export interface LdrStats {
     /** Textured batches (one per part x texture) and distinct textures; 0 for packs without textures. */
     texBatches?: number;
     textures?: number;
+    /** Drawable clusters (LOD / frustum-culling units). */
+    clusters?: number;
 }
 export interface LdrObject {
     /** Add this to your scene. */
@@ -58,15 +69,18 @@ export interface LdrObject {
     /** Per build step, the view rotation set by MLCad `0 ROTSTEP` (null = default view). Get the 3x3 (LDraw space, row-major) with
      *  `stepViewMatrix(view, yourDefaultView)`; in three.js terms rotate the model by it inside the object's -Y-up flip. */
     stepViews: (StepView | null)[];
-    /** Show instances up to and including `step` (null = all). Rebuilds batches; culling is recomputed for the partial model. */
+    /** Show instances up to and including `step` (null = all). No rebuild: instance buffers are compacted, and culling is step-aware
+     *  (a stud covered only by a later step's part stays visible). `stats` reflect the shown step. */
     setStep(step: number | null): void;
     setEdges(on: boolean): void;
-    /** Resolves when the pack's textures (if any) are decoded and ready to render. Replaced by a new promise after `setStep`. */
+    /** Resolves when the pack's textures (if any) are decoded and ready to render. */
     texturesReady: Promise<void>;
     /** Toggle conditional lines (only visible while edges are on). */
     setConditionalLines(on: boolean): void;
     setCulling(studs: boolean, undersides: boolean): void;
     setSide(side: "front" | "double"): void;
+    /** Turn distance LOD on/off (off = full detail and edges everywhere). Only has an effect if the object was built with `lod` (default). */
+    setLod(on: boolean): void;
     /** Bounding box in the object's parent space. */
     getBox(target?: THREE.Box3): THREE.Box3;
     dispose(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldr",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "High-performance LEGO (LDraw) rendering for three.js: instanced parts packs, hidden stud/tube culling, low-detail studs, indexed edges, build steps.",
   "license": "MIT",
   "author": "Evan Bacon",
@@ -41,7 +41,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "ldr": "./dist/cli.js"
+    "ldr": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -49,15 +49,16 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target browser --format esm --external three --external fzstd && bun build src/node/index.ts src/cli.ts --outdir dist --root src --target node --format esm --external three --external fzstd && tsc -p tsconfig.build.json && bun scripts/postbuild.ts",
+    "build": "rm -rf dist && bun scripts/build.ts && tsc -p tsconfig.build.json && bun scripts/postbuild.ts && node scripts/check-dist.mjs",
     "test": "bun test",
     "prepublishOnly": "bun run build && bun test"
   },
   "dependencies": {
-    "fzstd": "^0.1.1"
+    "fzstd": "^0.1.1",
+    "meshoptimizer": "1.2.0"
   },
   "peerDependencies": {
-    "three": ">=0.160.0"
+    "three": ">=0.151.0"
   },
   "devDependencies": {
     "@types/bun": "latest",