ldr 0.34.10 → 0.34.12

package/dist/parts-cdn.d.ts

@@ -1,8 +1,8 @@
 import { type Pack } from "./pack-io.js";
 import { type PartInstance } from "./model.js";
 import { type CullResult } from "./cull.js";
-/** Default parts CDN (LDraw library parts, CC BY 2.0 / 4.0, compiled by ldr; hosted with the demo site). */
-export declare const DEFAULT_PARTS_CDN = "https://ldr-demo.vercel.app/cdn/v1/";
+/** Default parts CDN (LDraw library parts, CC BY 2.0 / 4.0, compiled by ldr; hosted on the ldr-parts-cdn Worker in front of R2; not the demo's /cdn/v1/* proxy, whose edge cache answers Range requests with the wrong bytes). */
+export declare const DEFAULT_PARTS_CDN = "https://ldr-parts-cdn.baconbrix.workers.dev/v1/";
 export interface PartsCdnIndex {
     format: string;
     release?: string;

package/dist/render.d.ts

@@ -2,6 +2,13 @@ import * as THREE from 'three';
 import { decodePack, type Pack } from './pack-io.js';
 import { type ColourSurface, type LDrawColor } from './model.js';
 export { decodePack, type Pack };
+import { type StudDecalUniforms } from './stud-decal';
+/** which studs stay real geometry (setStudMask): per instance, or those whose stud cell centre is within `r` of (x, z) in model space */
+export type StudMask = ArrayLike<number | boolean> | {
+    x: number;
+    z: number;
+    r: number;
+};
 /** `edges`: LDraw edge lines, welded + indexed and sharing each batch's instance matrices (`'idx'` is the same as `true`).
  *  `cond`: draw type-5 conditional lines when the pack carries them (pack v2, built with `cond: true`) and edges are on. Default true.
  *  `condStuds`: also draw them on stud batches (stud silhouettes). Default true. Uncertified (no BFC) parts are always double-sided. */
@@ -10,13 +17,16 @@ export type LdrParams = {
     /** Colours of instance colour keys that aren't table codes: model-level `0 !COLOUR` definitions (see `sceneInstances`). */
     localColours?: Map<string, LDrawColor>;
     cullStuds: boolean;
-    cullUnder: boolean;
+    cullUnder: boolean; /** see LdrObjectOptions.studGrid */
+    studGrid?: number;
     edges?: boolean | 'idx';
     side: 'double' | 'front';
     cond?: boolean;
     condStuds?: boolean;
     /** Draw textured (!TEXMAP) parts with their PNGs when the pack carries them (pack v2 "tex", `ldr pack --textures`). Default true. */
     tex?: boolean;
+    /** Step mode: also draw every stud as a flat decal quad (stud-decal.ts), shown where `setStudMask` takes the real studs away. */
+    studDecal?: StudDecalUniforms;
     /** Distance LOD: spatial clusters per part, simplified meshes from `lod` packs, studs as full → square stud → flat disc → dropped, edges hidden once sub-pixel. Default true. */
     lod?: boolean;
     /** LOD: max screen-space error in pixels (default 0.5). */
@@ -121,6 +131,7 @@ export declare function studSquareLines(E: ArrayLike<number>, w: number, hole?:
 /** Box-level outline (Round 67): the 12 edges of a body's bounding-box LOD level (`lod.ts` boxMesh: an axis-aligned box in part
  *  space), drawn with that level in place of the part's own edge lines. Null unless `pos` is exactly such a box's corners. */
 export declare function boxLevelLines(pos: ArrayLike<number>): Float32Array | null;
+export declare function studGridGeom(g: THREE.BufferGeometry, n: number): THREE.BufferGeometry;
 /**
  * Builds (and caches on the pack) the shared BufferGeometries `buildLdrScene` will use, in time slices of about `sliceMs` that yield
  * to the event loop, until done or `stop()` returns true. Lets the main thread do this useful work while the load worker culls.

package/dist/scene.d.ts

@@ -1,8 +1,9 @@
 import * as THREE from "three";
-import { type Pack } from "./render.js";
+import { type Pack, type StudMask } from "./render.js";
 import { type CullResult } from "./cull.js";
 import { type PartInstance, type LDrawColor } from "./model.js";
 import type { StepView } from "./spec.js";
+import type { StudDecalUniforms } from "./stud-decal.js";
 export type ColorSource = Map<number, string | LDrawColor> | Record<number | string, string | LDrawColor> | ((code: number) => THREE.ColorRepresentation | undefined);
 export interface LdrObjectOptions {
     /** Culling computed ahead (e.g. by `prepareModel({ cull: true })` in a worker) for these same instances and `textures` setting. */
@@ -20,6 +21,12 @@ export interface LdrObjectOptions {
     textures?: boolean;
     /** Hide studs fully covered by a part above. Default true. */
     cullStuds?: boolean;
+    /** Draw each stud as an n x n grid of studs 1/n its size on the same 20-LDU cell (the city's bricks are a stud per metre, its
+     *  minifigs a third of LDraw size: `studGrid: 3` gives the ground and buildings minifig-scale studs). Same instances and culling;
+     *  stud LOD thresholds shrink by n. No stud edge lines with n > 1. Default 1. Only read when the object is built. */
+    studGrid?: number;
+    /** Step mode: flat stud decals (stud-decal.ts) where `setStudMask` takes the real studs away; these uniforms move their near hole. */
+    studDecal?: StudDecalUniforms;
     /** 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'. */
@@ -36,6 +43,10 @@ export interface LdrObjectOptions {
     scale?: number;
     /** Initial step (inclusive, 0-based global sequence from `sequenceSteps`). Default: show all. */
     step?: number;
+    /** Build the per-step tables up front, so the first `setStep` is as cheap as later ones. Default false (`loadModel`: true with
+     *  `callouts`): a multi-step model loads as one plain all-steps scene (no step tables, culled slots dropped, ~15-20% faster on big
+     *  models) and the first `setStep` that hides something builds step mode once (about one more build of the model). Implied by `step`. */
+    eagerSteps?: boolean;
     /** 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`, swaps closed studs to a 10-triangle square stud, then a flat disc, then drops them once under `lodPx`, and hides edge lines where a stud spans under
@@ -97,10 +108,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). 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. With `mask` (per instance), only the
-     *  instances whose entry is truthy are shown, e.g. a sub-assembly on its own (an instruction callout; see `planStepViews`). */
-    setStep(step: number | null, mask?: ArrayLike<number | boolean> | null): void;
+    /** Show instances up to and including `step` (null = all). Instance buffers are compacted, and culling is step-aware (a stud
+     *  covered only by a later step's part stays visible). An object built showing every step (no `step` option) has no step tables
+     *  yet (it builds faster, like a single-step model): the first call that hides something builds them, about one `createLdrObject`
+     *  of work; later calls don't rebuild. `stats` reflect the shown step. With `mask` (per instance), only the
+     *  instances whose entry is truthy are shown, e.g. a sub-assembly on its own (an instruction callout; see `planStepViews`).
+     *  `ghostAfter`: the ghost (`setGhost`) shows the steps after this one instead of after `step` (default `step`). A step animated in
+     *  shows the step before while its new parts are drawn in flight elsewhere: `setStep(s - 1, mask, s)` keeps those parts out of the
+     *  ghost too, so no part is ever drawn as a ghost and a solid in the same place (they z-fight, a flickery doubled brick). */
+    setStep(step: number | null, mask?: ArrayLike<number | boolean> | null, ghostAfter?: number | null): void;
+    /** Step mode only (false otherwise): real studs only on the instances whose `mask` entry is truthy, `studDecal` decals on the
+     *  rest, or (`{ x, z, r }`, model space) only the stud cells within `r` of a point; null: every stud real, no decals. Cheap (only the stud batches are rewritten). */
+    setStudMask(mask: StudMask | null): boolean;
     setEdges(on: boolean): void;
     /** Resolves when the pack's textures (if any) are decoded and ready to render. */
     texturesReady: Promise<void>;

package/dist/stud-decal.d.ts

@@ -0,0 +1,16 @@
+import * as THREE from 'three';
+/** shared uniforms: the app moves `center` (world space) and sets `near` (world units) once */
+export type StudDecalUniforms = {
+    center: {
+        value: THREE.Vector3;
+    };
+    near: {
+        value: number;
+    };
+};
+export declare function studDecalUniforms(near?: number): StudDecalUniforms;
+/** the 20 x 20 LDU footprint of a stud at the height of its studs' tops (stud space: y = 0 is the part's top, -y up), facing up: the
+ *  shader marches down from there, and a quad that high wins the depth test over the plate under it at any distance */
+export declare function studDecalGeom(grid?: number): THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>;
+/** `base` (a stud batch's plastic) with the decal shading on top of whatever it already patches; one per base material and grid */
+export declare function studDecalMaterial(base: THREE.Material, U: StudDecalUniforms, grid: number): THREE.Material;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldr",
-  "version": "0.34.10",
+  "version": "0.34.12",
   "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",