ldr 0.0.0-alpha.1 → 0.2.0

package/dist/node/library.d.ts

@@ -0,0 +1,35 @@
+import { type Doc, type PartMesh, type Instance } from "../spec.js";
+export declare class Library {
+    root: string;
+    unofficialRoot?: string | undefined;
+    cache: Map<string, Doc | null>;
+    meshCache: Map<string, PartMesh>;
+    /** Optional second root for unofficial parts (e.g. Unofficial/ next to the official tree). */
+    constructor(root: string, unofficialRoot?: string | undefined);
+    /**
+     * Resolve a part/prim/model by LDraw search order (case-insensitive):
+     * parts/, p/, models/, then parts/s (subparts). If `unofficial/` exists under root
+     * (or `unofficialRoot` is set), those trees are tried after the official ones.
+     * Follows `~Moved to` aliases to the canonical file.
+     */
+    where(name: string, _seen?: Set<string>): {
+        kind: "part" | "prim" | "model";
+        doc: Doc;
+        aliasOf?: string;
+    } | null;
+    private lookup;
+    /** Case-insensitive path resolve (library files are lowercase; callers may pass any case). */
+    private resolveFile;
+    colors(): Map<number, {
+        name: string;
+        hex: string;
+        edge: string;
+        alpha: number;
+    }>;
+    /** Flattened triangle mesh: positions + color code per tri (16 = inherit); edges as line segments.
+     *  `cond` stores type-5 lines as 12 floats each: endpoint0, endpoint1, control0, control1 (for future conditional-line rendering). */
+    mesh(name: string): PartMesh;
+    private emit;
+    /** Flatten a model into part instances. 24 handled at render (edge color). Alias parts resolve to canonical names. */
+    flatten(doc: Doc): Instance[];
+}

package/dist/node/resolver.d.ts

@@ -0,0 +1,32 @@
+export declare const TOP_STUD_RE: RegExp;
+export declare const UNDER_STUD_RE: RegExp;
+export declare const norm: (ref: any) => any;
+export declare const threeName: (ref: any) => any;
+export declare function parseType1(line: any): {
+    color: any;
+    m: any;
+    name: any;
+} | null;
+export declare function xf(m: any, p: any): any[];
+export declare function compose(a: any, b: any): any[];
+export declare const IDENT: number[];
+export declare class Library {
+    #private;
+    root: string;
+    index: Map<string, string>;
+    text: Map<string, string>;
+    stats: Map<string, any>;
+    constructor(root: string);
+    resolve(ref: any): string | null;
+    read(key: string): string;
+    isPart(key: any): any;
+    fileStats(key: any): any;
+}
+export declare function splitModel(text: any, fallbackName?: string): {
+    files: Map<string, string>;
+    main: string | null;
+};
+export declare function flatten(model: any, lib: any, onInstance: any): {
+    missing: Map<any, any>;
+};
+export declare function collectDeps(lib: any, refs: any): Map<any, any>;

package/dist/pack-io.d.ts

@@ -0,0 +1,2 @@
+/** Detect gzip / zstd magic and return raw pack bytes (an ArrayBuffer you can hand to `decodePack`). */
+export declare function decompressPack(data: ArrayBuffer | Uint8Array): Promise<ArrayBuffer>;

package/dist/render.d.ts

@@ -0,0 +1,43 @@
+import * as THREE from 'three';
+export type LdrParams = {
+    pack: string;
+    cullStuds: boolean;
+    cullUnder: boolean;
+    edges: boolean | 'idx' | 'ss';
+    side: 'double' | 'front';
+    uncertDouble?: boolean;
+};
+export type Inst = {
+    part: string;
+    color: string;
+    m: number[];
+};
+export type Pack = {
+    header: any;
+    arr: (r: any) => any;
+    bytes: number;
+};
+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). */
+export declare function decodePack(buf: ArrayBuffer): Pack;
+export declare function makeMaterial(side: THREE.Side): THREE.MeshStandardMaterial;
+/** Edge lines for an InstancedMesh: welds + indexes `pos` (line-segment endpoints, part space) and shares the mesh's instanceMatrix buffer, so edges cost one extra draw and no extra per-instance memory. Keep `geometry.instanceCount` in sync with `im.count`. */
+export declare function createInstancedEdges(pos: ArrayLike<number>, im: THREE.InstancedMesh, material?: THREE.Material): THREE.LineSegments;
+export declare function computeCulling(insts: Inst[], H: any): {
+    studs: {
+        kind: string;
+        color: string;
+        w: number[];
+        hidden: boolean;
+    }[];
+    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>;
+    stats: any;
+    setCull: (studs: boolean, under: boolean) => void;
+    setSide: (front: boolean) => void;
+    setEdges: (v: boolean) => void;
+    swapStuds: (alt: any) => () => void;
+    box: THREE.Box3;
+};

package/dist/scene.d.ts

@@ -0,0 +1,56 @@
+import * as THREE from "three";
+import { type Pack } from "./render.js";
+import type { PartInstance, LDrawColor } from "./model.js";
+export type ColorSource = Map<number, string | LDrawColor> | Record<number | string, string | LDrawColor> | ((code: number) => THREE.ColorRepresentation | undefined);
+export interface LdrObjectOptions {
+    /** Draw LDraw type-2 edge lines (indexed, sharing each part's instance matrices). Default true. */
+    edges?: boolean;
+    /** Hide studs fully covered by a part above. Default true. */
+    cullStuds?: boolean;
+    /** Hide undersides (tubes) sitting fully on studs below. Default true. */
+    cullUndersides?: boolean;
+    /** 'front' = single-sided BFC faces (fast); 'double' = render both sides. Uncertified parts are always double-sided. Default 'front'. */
+    side?: "front" | "double";
+    /** 'plastic' = MeshPhysicalMaterial with clearcoat; 'standard' = MeshStandardMaterial (cheapest, used by the benchmarks). Default 'plastic'. */
+    material?: "plastic" | "standard";
+    /** Colour table override. Defaults to the `colors` table embedded in the pack by `ldr pack`. */
+    colors?: ColorSource;
+    /** Colour for unknown codes. Default #A0A5A9. */
+    fallbackColor?: THREE.ColorRepresentation;
+    /** Keep native LDraw space (-Y up, 1 unit = 1 LDU). Default false: the object is rotated to +Y up. */
+    ldrawSpace?: boolean;
+    /** Uniform scale applied to the object (e.g. 0.4 for millimetres, 0.01 for ~metres-ish). Default 1 (LDU). */
+    scale?: number;
+    /** Initial step (inclusive, 0-based global sequence from `sequenceSteps`). Default: show all. */
+    step?: number;
+}
+export interface LdrStats {
+    instances: number;
+    drawn: number;
+    missing: string[];
+    studsTotal: number;
+    studsHidden: number;
+    undersTotal: number;
+    undersHidden: number;
+    buildMs: number;
+}
+export interface LdrObject {
+    /** Add this to your scene. */
+    object: THREE.Group;
+    stats: LdrStats;
+    /** Number of build steps (nested submodel steps are sequenced). */
+    stepCount: number;
+    /** Show instances up to and including `step` (null = all). Rebuilds batches; culling is recomputed for the partial model. */
+    setStep(step: number | null): void;
+    setEdges(on: boolean): void;
+    setCulling(studs: boolean, undersides: boolean): void;
+    setSide(side: "front" | "double"): void;
+    /** Bounding box in the object's parent space. */
+    getBox(target?: THREE.Box3): THREE.Box3;
+    dispose(): void;
+}
+/**
+ * Build a three.js object for a flattened model using a parts pack.
+ * Instances whose part is not in the pack are skipped and listed in `stats.missing`.
+ */
+export declare function createLdrObject(instances: PartInstance[], pack: Pack, options?: LdrObjectOptions): LdrObject;

package/dist/spec.d.ts

@@ -0,0 +1,73 @@
+export type M = number[];
+export type RotStep = {
+    x: number;
+    y: number;
+    z: number;
+    mode: "REL" | "ABS" | "ADD" | "END";
+};
+export type BufExchg = {
+    op: "STORE" | "RETRIEVE";
+    buf: string;
+};
+export type Cmd = {
+    t: 0;
+    text: string;
+    meta?: string;
+    bfc?: string;
+    step?: boolean;
+    rotstep?: RotStep;
+    bufexchg?: BufExchg;
+} | {
+    t: 1;
+    color: number;
+    m: M;
+    file: string;
+} | {
+    t: 2 | 5;
+    color: number;
+    p: number[];
+} | {
+    t: 3 | 4;
+    color: number;
+    p: number[];
+};
+export interface LFile {
+    name: string;
+    cmds: Cmd[];
+    movedTo?: string;
+}
+export interface Doc {
+    main: string;
+    files: Map<string, LFile>;
+}
+export declare const norm: (s: string) => string;
+/** Parse LDraw color token: decimal code, or direct color 0x2RRGGBB (and related 0xN…… forms). */
+export declare function parseColor(tok: string): number;
+export declare function parse(src: string, name?: string): Doc;
+export declare function mul(a: M, b: M): M;
+export declare const I: M;
+/** True if color is an LDraw direct color (0x2RRGGBB etc.), not a palette CODE. */
+export declare const isDirectColor: (c: number) => boolean;
+export interface PartMesh {
+    name: string;
+    pos: Float32Array;
+    col: Uint32Array;
+    edges: Float32Array;
+    cond: Float32Array;
+    nrm: Float32Array;
+}
+export interface Instance {
+    part: string;
+    color: number;
+    m: M;
+    step: number;
+    localStep: number;
+    steps: number[];
+    path: string;
+    missing: boolean;
+    aliasOf?: string;
+}
+/** Smooth normals that respect LDraw semantics: faces sharing an edge are smoothed together unless the
+ *  edge is a type-2 line (hard). Conditional (type-5) lines force smooth; unmarked edges smooth only below creaseDeg.
+ *  `cond` may be stride-6 (legacy endpoints only) or stride-12 (endpoints + 2 control points). */
+export declare function smoothNormals(pos: number[], edges: number[], cond: number[], creaseDeg?: number): Float32Array;

package/package.json

@@ -1,52 +1,72 @@
 {
   "name": "ldr",
-  "version": "0.0.0-alpha.1",
-  "description": "LDraw",
-  "files": [
-    "lib"
-  ],
-  "homepage": "https://github.com/evanbacon/ldr#readme",
+  "version": "0.2.0",
+  "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",
+  "type": "module",
+  "sideEffects": false,
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/evanbacon/ldr.git"
-  },
-  "bugs": {
-    "url": "https://github.com/evanbacon/ldr/issues"
-  },
-  "main": "lib/index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "lint": "eslint .",
-    "prettier": "eslint . --fix"
-  },
-  "directories": {
-    "example": "examples",
-    "lib": "lib"
+    "url": "git+https://github.com/EvanBacon/ldr.git",
+    "directory": "packages/ldr"
   },
+  "homepage": "https://github.com/EvanBacon/ldr#readme",
+  "bugs": "https://github.com/EvanBacon/ldr/issues",
   "keywords": [
     "lego",
-    "three.js",
-    "graphics",
-    "opengl",
-    "gl",
-    "arkit",
-    "ldraw"
+    "ldraw",
+    "three",
+    "threejs",
+    "webgl",
+    "instancing",
+    "renderer",
+    "mpd",
+    "ldr",
+    "bricks",
+    "3d"
   ],
-  "author": "Evan Bacon",
-  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "ldr": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "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",
+    "test": "bun test",
+    "prepublishOnly": "bun run build && bun test"
+  },
   "dependencies": {
-    "three": "0.88.0"
+    "fzstd": "^0.1.1"
   },
   "peerDependencies": {
-    "three": "0.88.0"
+    "three": ">=0.160.0"
   },
   "devDependencies": {
-    "babel-jest": "^23.0.1",
-    "eslint": "^4.19.1",
-    "flow-bin": "^0.26.0",
-    "jest": "^23.1.0",
-    "prettier": "^1.13.5"
+    "@types/bun": "latest",
+    "@types/node": "^26.6.5",
+    "@types/three": "^0.180.0",
+    "three": "^0.186.1",
+    "typescript": "^5.9.0"
   },
-  "eslintConfig": {
+  "engines": {
+    "node": ">=18"
   }
 }

package/lib/index.js

@@ -1 +0,0 @@
-export default {};