ldr 0.2.0 → 0.4.0

package/dist/model.d.ts

@@ -1,4 +1,4 @@
-import { parse, norm, type Doc, type M } from "./spec.js";
+import { parse, norm, type Doc, type M, type LFile, type StepView } from "./spec.js";
 /** A placed part. `color` is an LDraw colour code (or direct colour 0x2RRGGBB); `m` is the 12-number LDraw matrix `x y z a b c d e f g h i`. */
 export interface PartInstance {
     part: string;
@@ -8,28 +8,55 @@ export interface PartInstance {
     step: number;
     /** Step path through nested submodels, e.g. [3, 1] = top step 3, submodel step 1. */
     steps: number[];
+    /** Step within the file that places this instance (the last entry of `steps`). */
+    localStep: number;
     /** Submodel path, e.g. "main.ldr/wheel.ldr". */
     path: string;
+    /** The part is defined inside the document (an MPD-embedded part, see `fileKind`), not taken from the library. */
+    embedded?: boolean;
+    /** Set for synthetic parts (a model file's own type 2-5 lines, named `<file>#<step>`): returns the part's LDraw source
+     *  (`source.file` / `source.step` give the model file and step, see `looseFile`). */
+    source?: (() => string) & {
+        file?: LFile;
+        step?: number;
+    };
+    /** Only with `flatten(doc, { textures: true })`: the part is wrapped by a model-level `!TEXMAP`. `texPart` names the synthetic
+     *  textured part (`<part>#tex-<hash>`, in packs built with `textures: true`) and `texSource` is its LDraw source; `part` stays the plain part. */
+    texPart?: string;
+    texSource?: string;
+    /** View rotation of this instance's step from `0 ROTSTEP` (absent = default view). See `fileStepViews`. */
+    view?: StepView;
 }
 export interface FlattenOptions {
     /** Resolve an external reference that is not a submodel of this document (e.g. a model file you loaded separately). Return null to treat it as a part. */
     resolveModel?: (name: string) => Doc | null;
     /** Max submodel nesting (cycle guard). Default 64. */
     maxDepth?: number;
+    /** Emit a model file's own type 2-5 lines as synthetic parts `<file>#<step>` (LDraw allows geometry in any file). Default true. */
+    looseGeometry?: boolean;
+    /** TEXMAP-aware view of the model: references wrapped by a model-level `!TEXMAP` get `texPart`, `0 !:` type-1 lines are
+     *  included and `!TEXMAP FALLBACK` references are skipped. Use with packs built with `textures: true`. Default false. */
+    textures?: boolean;
 }
-/** Flatten a parsed LDraw document into part instances. Submodels (`0 FILE` blocks in an MPD) are expanded; everything else is treated as a part. */
+/**
+ * Flatten a parsed LDraw document into part instances. Model files (`0 FILE` blocks in an MPD that `fileKind` calls models) are
+ * expanded; MPD-embedded parts and library references become instances. A model file's own geometry becomes synthetic parts.
+ */
 export declare function flatten(doc: Doc, opts?: FlattenOptions): PartInstance[];
 /** Parse LDraw text (.ldr/.mpd/.dat) and flatten it in one call. */
 export declare function parseModel(text: string, name?: string, opts?: FlattenOptions): PartInstance[];
 /**
  * Assign each instance a global sequential build-step index, ordering by the full nested step path
- * (so submodel steps become their own steps). Returns the number of steps.
+ * (so submodel steps become their own steps). Returns the number of steps and, per global step, its ROTSTEP view
+ * (null = default view; the view of the innermost file's step, see `fileStepViews`).
  */
 export declare function sequenceSteps<T extends {
     steps: number[];
+    view?: StepView;
 }>(insts: T[]): {
     count: number;
     stepOf: Int32Array;
+    views: (StepView | null)[];
 };
 /** Colour table entry. */
 export interface LDrawColor {

package/dist/node/build-pack.d.ts

@@ -16,6 +16,15 @@ export interface BuildPackOptions {
     primitives?: "low" | "full";
     /** Weld + index vertices (smaller GPU buffers, faster). Default true. */
     weld?: boolean;
+    /** Keep type-5 conditional lines so the renderer can draw curved-surface silhouettes (pack v2). Off by default:
+     *  Round 16 measured +7.5–13.6% zstd size and ~+25% build time on Datsville 10k/100k. Packs stay readable by ldr <= 0.2.0. */
+    cond?: boolean;
+    /** Keep textured (`!TEXMAP`) parts' TEXMAP-aware geometry + UVs and embed their PNGs (pack v2 "tex"). Off by default;
+     *  packs without textured parts are byte-identical either way. Textures resolve from model `!DATA` blocks, then `textures/` in the library. */
+    textures?: boolean;
+    /** Render a model file's own type 2-5 lines (as synthetic parts `<file>#<step>`). Default true (LDraw allows geometry in any file);
+     *  false reproduces packs from ldr <= 0.2.0, which dropped it. */
+    looseGeometry?: boolean;
     /** Embed the LDConfig colour table (code → hex) in the pack header. Default true. */
     colors?: boolean;
     onProgress?: (done: number, total: number) => void;
@@ -25,5 +34,7 @@ export interface BuildPackResult {
     parts: number;
     studKinds: number;
     missing: string[];
+    /** e.g. two models embedding different files under the same name (the first one is used). */
+    warnings?: string[];
 }
 export declare function buildPack(o: BuildPackOptions): BuildPackResult;

package/dist/node/compile.d.ts

@@ -1,19 +1,32 @@
 import { Library } from './resolver.js';
+/** `cond`: keep type-5 conditional lines (endpoints + control points) so the pack can draw them (pack v2). Default off.
+ *  `tex`: also compile the TEXMAP-aware view of parts that use `!TEXMAP` (textured triangles with UVs + PNGs; pack v2 "tex"). Default off. */
 export type Opts = {
     studs: 'full' | 'low';
     prims: 'full' | 'low';
     weld: boolean;
     separateStuds: boolean;
+    cond?: boolean;
+    tex?: boolean;
 };
 export type Bucket = {
     pos: number[];
     col: number[];
 };
+/** Textured triangles for one PNG: `uv` = 2 floats per vertex (LDraw !TEXMAP projection, v = 0 at the image's top row). */
+export type TexBucket = Bucket & {
+    uv: number[];
+    wrapU?: boolean;
+};
 export type Compiled = {
     body: Bucket;
     under: Bucket;
     edges: number[];
     condLines: number;
+    /** Type-5 lines in part space, stride 12 (p0, p1, control0, control1). Only filled when `opts.cond`.
+     *  `cond` = lines of the body; `condUnder` = lines inside underside (tube / anti-stud) subfiles, drawn with the underside batch so they follow underside culling. */
+    cond?: number[];
+    condUnder?: number[];
     studs: {
         kind: string;
         color: string;
@@ -27,6 +40,10 @@ export type Compiled = {
         nz: number;
         bits: number[];
     };
+    /** Only with `opts.tex`, for parts whose tree uses !TEXMAP: the untextured body a TEXMAP-aware renderer draws instead of
+     *  `body` (FALLBACK geometry dropped, `0 !:` geometry kept), plus textured triangles per texture name. Under/studs/edges are shared. */
+    tbody?: Bucket;
+    texb?: Map<string, TexBucket>;
 };
 export declare function loadColors(root: string): Map<string, number[]>;
 export declare class Compiler {
@@ -37,7 +54,17 @@ export declare class Compiler {
     constructor(lib: Library, opts: Opts);
     resolve(ref: string, isStud: boolean): string | null;
     compile(key: string, separateStuds?: boolean): Compiled;
+    private texMemo;
+    /** True if `key` or any file it references contains a `!TEXMAP` meta. */
+    hasTex(key: string): boolean;
+    /** Texture PNG bytes by !TEXMAP name: `textures/<name>` under parts/, p/, models/, then `<name>` (case-insensitive). */
+    texture(name: string): Uint8Array | null;
+    private texPass;
 }
-export declare function writePack(file: string, parts: Map<string, Compiled>, studKinds: Map<string, Compiled>, weld: boolean, extra?: Record<string, unknown>): void;
+export declare function writePack(file: string, parts: Map<string, Compiled>, studKinds: Map<string, Compiled>, weld: boolean, extra?: Record<string, unknown>, options?: EncodeOptions): void;
+/** `texture(name)`: PNG bytes for a !TEXMAP name used by a compiled part (e.g. `compiler.texture`, or an MPD `!DATA` block). */
+export type EncodeOptions = {
+    texture?: (name: string) => Uint8Array | null;
+};
 /** Serialize compiled parts into the binary pack format read by `decodePack`/`loadPack`. `extra` keys are merged into the JSON header (e.g. `colors`). */
-export declare function encodePack(parts: Map<string, Compiled>, studKinds: Map<string, Compiled>, weld: boolean, extra?: Record<string, unknown>): Uint8Array;
+export declare function encodePack(parts: Map<string, Compiled>, studKinds: Map<string, Compiled>, weld: boolean, extra?: Record<string, unknown>, options?: EncodeOptions): Uint8Array;