three-low-poly 0.9.26 → 0.9.28

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { ExtrudeGeometry } from 'three';
 import { Group } from 'three';
 import { InstancedMesh } from 'three';
 import { Material } from 'three';
+import { MaterialEventMap } from 'three';
 import { Mesh } from 'three';
 import { MeshBasicMaterial } from 'three';
 import { MeshLambertMaterial } from 'three';
@@ -16,7 +17,7 @@ import { MeshPhysicalMaterial } from 'three';
 import { MeshStandardMaterial } from 'three';
 import { Object3D } from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
-import { ParametricGeometry } from 'three-stdlib';
+import { ParametricGeometry } from 'three/addons/geometries/ParametricGeometry.js';
 import { PerspectiveCamera } from 'three';
 import { Plane } from 'three';
 import { PlaneGeometry } from 'three';
@@ -69,7 +70,7 @@ import { Vector3 } from 'three';
  *     instancedMesh.geometry.setAttribute("instanceColor", new THREE.InstancedBufferAttribute(colors, 3));
  * ```
  */
-export declare function addInstanceColor(material: Material): Material;
+export declare function addInstanceColor(material: Material): Material< MaterialEventMap>;
 
 /**
  * Utility function to add noise-based vertex displacement to an existing Three.js material.
@@ -647,6 +648,59 @@ export declare interface BookshelfOptions extends BookshelfGeometryOptions {
     color?: ColorRepresentation;
 }
 
+/**
+ * Boulder prefab — a {@link BoulderGeometry} lumped by coherent 3D noise, with a
+ * matte flat-shaded stone material. Centered on the origin; casts and receives
+ * shadows. Vary `seed` per instance for a field of unique boulders.
+ */
+export declare class Boulder extends Mesh<BoulderGeometry, MeshStandardMaterial> {
+    readonly radius: number;
+    constructor({ color, flatShading, ...geometryOptions }?: BoulderOptions);
+}
+
+/**
+ * Boulder — an icosphere lumped by coherent 3D fbm ({@link fbm3}) displaced along
+ * each vertex's radial direction. The 3D counterpart to the terrain heightfields:
+ * same noise strategy, applied over a closed surface instead of a height map.
+ *
+ * The icosphere is welded (`mergeVertices` after stripping seam UVs) so coincident
+ * vertices share one displacement — the coherent noise then moves neighbors together,
+ * so the surface stays watertight and never cracks (the failure mode of displacing a
+ * non-indexed polyhedron along normals). Real baked geometry, so shadows, raycasts,
+ * and physics colliders match what's drawn, on WebGL and WebGPU/TSL alike.
+ *
+ * Centered on the origin. Pair with a `flatShading` material for a faceted low-poly
+ * look. Vary `seed` per instance to fill a field with unique boulders.
+ */
+export declare class BoulderGeometry extends BufferGeometry {
+    readonly radius: number;
+    constructor({ radius, detail, noiseHeight, noiseScale, octaves, persistence, seed, }?: BoulderGeometryOptions);
+}
+
+export declare interface BoulderGeometryOptions {
+    /** Base radius before displacement (world units). Defaults to `1`. */
+    radius?: number;
+    /** Icosahedron subdivision — more detail = more, finer facets. Defaults to `2`. */
+    detail?: number;
+    /** Radial relief amplitude (world units, ±). Keep below `radius`. Defaults to `0.35`. */
+    noiseHeight?: number;
+    /** Noise frequency over the unit sphere — higher packs more, smaller lumps. Defaults to `1.6`. */
+    noiseScale?: number;
+    /** fbm octaves (detail layers). Defaults to `3`. */
+    octaves?: number;
+    /** fbm gain per octave (0–1); lower is smoother, higher is rougher. Defaults to `0.5`. */
+    persistence?: number;
+    /** Seed for reproducible shape. Defaults to `1`. */
+    seed?: number;
+}
+
+export declare interface BoulderOptions extends BoulderGeometryOptions {
+    /** Stone tint. Defaults to `#6f6f6f`. */
+    color?: ColorRepresentation;
+    /** Faceted low-poly shading. Defaults to `true`. */
+    flatShading?: boolean;
+}
+
 export declare enum BoxSide {
     LEFT = "left",
     RIGHT = "right",
@@ -1783,6 +1837,90 @@ export declare interface DollyClipOptions extends CameraClipTiming {
     ease?: EasingFunction;
 }
 
+/**
+ * Fine dust drifting through a lit interior — tiny additive specks slowly
+ * settling and wafting, twinkling as they catch the light and all but vanishing
+ * in shadow. This is the thing that sells a light shaft as volumetric. Additive
+ * spheres read the same from any angle, so no billboarding is needed.
+ *
+ * Call {@link DustMotesEffect.update} each frame with elapsed time in seconds.
+ *
+ * @example
+ * ```typescript
+ * const dust = new DustMotesEffect({
+ *   count: 150,
+ *   width: 8,
+ *   height: 9,
+ *   depth: 8,
+ *   color: "#aebfe6",
+ * });
+ * scene.add(dust);
+ *
+ * onFrame((dt) => dust.update(dt));
+ * ```
+ */
+export declare class DustMotesEffect extends InstancedMesh {
+    private readonly width;
+    private readonly height;
+    private readonly depth;
+    private readonly floorY;
+    private readonly waft;
+    private readonly scaleMin;
+    private readonly scaleMax;
+    private readonly px;
+    private readonly py;
+    private readonly pz;
+    private readonly settle;
+    private readonly twinkle;
+    private readonly phase;
+    private readonly dummy;
+    private clock;
+    constructor(options?: DustMotesEffectOptions);
+    /**
+     * Advance the drift and twinkle. Pass elapsed frame time in seconds.
+     */
+    update(dt: number): void;
+    /** Release geometry and materials held by the field. */
+    dispose(): this;
+    private respawn;
+    private writeMatrices;
+}
+
+export declare interface DustMotesEffectOptions {
+    /** Number of dust instances. Defaults to `150`. */
+    count?: number;
+    /** Horizontal spread (world units). Defaults to `12`. */
+    width?: number;
+    /** Vertical spawn span (world units). Defaults to `8`. */
+    height?: number;
+    /** Depth spread (world units). Defaults to `12`. */
+    depth?: number;
+    /** World Y of the volume floor; motes respawn at the top after settling past it. Defaults to `0`. */
+    floorY?: number;
+    /** Speck tint. Defaults to `#aebfe6`. */
+    color?: ColorRepresentation;
+    /** Speck radius (world units). Defaults to `0.02`. */
+    radius?: number;
+    /** Base material opacity. Defaults to `0.9`. */
+    opacity?: number;
+    /** Override the default additive speck material. */
+    material?: Material;
+    /** Minimum settle (fall) speed (units/s). Defaults to `0.1`. */
+    settleMin?: number;
+    /** Maximum settle (fall) speed (units/s). Defaults to `0.35`. */
+    settleMax?: number;
+    /** Lateral waft amplitude (units/s). Defaults to `0.08`. */
+    waft?: number;
+    /** Smallest twinkle scale multiplier. Defaults to `0.6`. */
+    scaleMin?: number;
+    /** Largest twinkle scale multiplier. Defaults to `1.2`. */
+    scaleMax?: number;
+    /** Minimum twinkle frequency (rad/s). Defaults to `0.7`. */
+    twinkleMin?: number;
+    /** Maximum twinkle frequency (rad/s). Defaults to `1.6`. */
+    twinkleMax?: number;
+}
+
 /**
  * Easing functions for interpolating values over time.
  *
@@ -2617,44 +2755,6 @@ export declare function hexToHsl(hex: number): [number, number, number];
  */
 export declare function hexToRgb(hex: number): [number, number, number];
 
-/**
- * Hill prefab — hemispherical terrain mound.
- */
-export declare class Hill extends Mesh<HillGeometry, MeshStandardMaterial> {
-    readonly radius: number;
-    readonly height: number;
-    constructor({ color, ...geometryOptions }?: HillOptions);
-}
-
-/**
- * Hemispherical hill — a sphere cap scaled on Y, base on the Y=0 plane.
- */
-export declare class HillGeometry extends BufferGeometry {
-    readonly radius: number;
-    readonly height: number;
-    constructor({ radius, height, widthSegments, heightSegments, phiStart, phiLength, }?: HillGeometryOptions);
-}
-
-export declare interface HillGeometryOptions {
-    /** Base sphere radius before vertical squash. Defaults to `3`. */
-    radius?: number;
-    /** Peak height. Defaults to `0.6`. */
-    height?: number;
-    /** Horizontal segments. Defaults to `64`. */
-    widthSegments?: number;
-    /** Vertical segments. Defaults to `16`. */
-    heightSegments?: number;
-    /** Azimuth start angle (radians). Defaults to `0`. */
-    phiStart?: number;
-    /** Azimuth sweep (radians). Defaults to `2π`. */
-    phiLength?: number;
-}
-
-export declare interface HillOptions extends HillGeometryOptions {
-    /** Surface tint. Defaults to `#00ff00`. */
-    color?: ColorRepresentation;
-}
-
 /**
  * Example usage:
  * ```
@@ -3030,43 +3130,6 @@ export declare interface MossyRockOptions extends MossyRockGeometryOptions {
     mossOpacity?: number;
 }
 
-/**
- * Mound prefab — flat-topped terrain cap.
- */
-export declare class Mound extends Mesh<MoundGeometry, MeshStandardMaterial> {
-    readonly radius: number;
-    constructor({ color, radius, ...geometryOptions }?: MoundOptions);
-}
-
-/**
- * Mound-like geometry with a flat top — sphere cap, base on Y=0.
- */
-export declare class MoundGeometry extends BufferGeometry {
-    readonly radius: number;
-    readonly thetaLength: number;
-    constructor({ radius, widthSegments, heightSegments, phiStart, phiLength, thetaLength, }?: MoundGeometryOptions);
-}
-
-export declare interface MoundGeometryOptions {
-    /** Sphere radius. Defaults to a cap width of `5` at `thetaLength`. */
-    radius?: number;
-    /** Horizontal segments. Defaults to `64`. */
-    widthSegments?: number;
-    /** Vertical segments. Defaults to `32`. */
-    heightSegments?: number;
-    /** Azimuth start angle (radians). Defaults to `0`. */
-    phiStart?: number;
-    /** Azimuth sweep (radians). Defaults to `2π`. */
-    phiLength?: number;
-    /** Polar sweep from the north pole (radians). Defaults to `π/10`. */
-    thetaLength?: number;
-}
-
-export declare interface MoundOptions extends MoundGeometryOptions {
-    /** Surface tint. Defaults to `#00ff00`. */
-    color?: ColorRepresentation;
-}
-
 /**
  * Fast seeded PRNG — portfolio Gotham/Water parity.
  * Returns a closure yielding floats in [0, 1).
@@ -3843,6 +3906,51 @@ export declare interface RowOfBooksOptions<T extends Material = Material> {
     seed?: number;
 }
 
+/**
+ * Scatter a field of instanced boulders inside a horizontal bounds region — a "created
+ * layer" of the noise-lumped {@link BoulderGeometry}. Unlike {@link scatterRocks}, which
+ * rotates a single shared shape, this generates several distinct boulder geometries
+ * (see `variants`) and distributes instances across them, so the field reads as unique
+ * rocks while staying to a few draw calls.
+ *
+ * Returns a {@link Group} of {@link InstancedMesh}es (one per variant), each sharing the
+ * stone material. Pass a `seed` for a reproducible field. Dispose each child's geometry
+ * and the shared material when removing it.
+ *
+ * @example
+ * ```ts
+ * const boulders = scatterBoulders({ count: 24, width: 12, depth: 12, seed: 1337 });
+ * scene.add(boulders);
+ * ```
+ */
+export declare function scatterBoulders({ count, width, depth, heightJitter, scaleMin, scaleMax, seed, radius, detail, noiseHeight, noiseScale, octaves, persistence, variants, material, color, }?: ScatterBouldersOptions): Group;
+
+export declare interface ScatterBouldersOptions extends RockScatterPlacementOptions {
+    /** Base radius for each boulder geometry. Defaults to `1`. */
+    radius?: number;
+    /** Icosphere subdivision per boulder. Defaults to `2`. */
+    detail?: number;
+    /** Radial relief amplitude per boulder. Defaults to `0.35`. */
+    noiseHeight?: number;
+    /** Noise frequency per boulder. Defaults to `1.6`. */
+    noiseScale?: number;
+    /** fbm octaves per boulder. Defaults to `3`. */
+    octaves?: number;
+    /** fbm gain per octave. Defaults to `0.5`. */
+    persistence?: number;
+    /**
+     * Distinct boulder geometries generated and distributed across the field. Each is
+     * a real, unique lumped shape (unlike rotating one shared mesh); instances round-robin
+     * across them, so the field stays batch-friendly (one draw call per variant).
+     * Defaults to `4`.
+     */
+    variants?: number;
+    /** Override the default stone material (shared across all instances). */
+    material?: Material;
+    /** Stone tint when `material` is omitted. Defaults to `#6f6f6f`. */
+    color?: ColorRepresentation;
+}
+
 /**
  * Scatter instanced mossy rocks inside a horizontal bounds region.
  *
@@ -4489,6 +4597,8 @@ export declare class StarFieldEffect extends Object3D {
     private readonly baseSize;
     private readonly baseScales?;
     private readonly twinklePhases?;
+    /** Untwinkled per-point RGB (points style), multiplied by each star's pulse each frame. */
+    private baseColors?;
     private spriteTexture?;
     private readonly dummy;
     constructor(options?: StarFieldEffectOptions);
@@ -4500,8 +4610,9 @@ export declare class StarFieldEffect extends Object3D {
     /**
      * Animate twinkling. No-op when `twinkle` is `false`.
      *
-     * Points style modulates sprite size; burst style pulses each instance scale with
-     * a per-star phase offset. Pass elapsed time in seconds (defaults to `performance.now()`).
+     * Both styles pulse with a per-star phase offset so stars twinkle out of sync:
+     * points modulate per-point brightness (via the color attribute), burst pulses
+     * each instance scale. Pass elapsed time in seconds (defaults to `performance.now()`).
      */
     update(elapsed?: number): void;
     private createPointsField;
@@ -4603,6 +4714,130 @@ export declare interface StoneFencePostOptions extends StoneFencePostGeometryOpt
     color?: ColorRepresentation;
 }
 
+/**
+ * Rounded terrain mound prefab — a {@link TerrainMoundGeometry} with a matte,
+ * flat-shaded material. Base sits on Y=0; drop it into a scene as a diorama
+ * ground or a small rise. Casts and receives shadows.
+ */
+export declare class TerrainMound extends Mesh<TerrainMoundGeometry, MeshStandardMaterial> {
+    readonly radius: number;
+    readonly height: number;
+    constructor({ color, flatShading, ...geometryOptions }?: TerrainMoundOptions);
+}
+
+/**
+ * Rounded terrain cap — a circular disc bulged into a gentle dome, then broken up
+ * with coherent fbm noise so it reads as rolling terrain rather than a smooth lens.
+ * The relief tapers to a clean circular rim seated on the Y=0 plane.
+ *
+ * Displacement is baked into real vertices (no shader), so shadows, raycasts, and
+ * any physics collider derived from the mesh match exactly what's drawn — and it
+ * renders identically on WebGL and WebGPU/TSL. Pair with a `flatShading` material
+ * for a faceted low-poly look; the coherent noise keeps neighboring vertices moving
+ * together, so faces never tear.
+ *
+ * Local frame: base on Y=0, peak toward +Y, centered on the origin.
+ */
+export declare class TerrainMoundGeometry extends BufferGeometry {
+    readonly radius: number;
+    readonly height: number;
+    constructor({ radius, height, radialSegments, angularSegments, noiseHeight, noiseScale, octaves, persistence, rim, seed, }?: TerrainMoundGeometryOptions);
+}
+
+export declare interface TerrainMoundGeometryOptions {
+    /** Footprint radius (world units). Defaults to `8`. */
+    radius?: number;
+    /** Dome peak height at the center. Defaults to `1.2`. */
+    height?: number;
+    /** Concentric rings from center to rim. Defaults to `40`. */
+    radialSegments?: number;
+    /** Segments around the circumference. Defaults to `64`. */
+    angularSegments?: number;
+    /** Amplitude of the terrain relief added on top of the dome. Defaults to `0.5`. */
+    noiseHeight?: number;
+    /** Noise frequency — higher packs more, smaller bumps into the footprint. Defaults to `0.35`. */
+    noiseScale?: number;
+    /** fbm octaves (detail layers). Defaults to `4`. */
+    octaves?: number;
+    /** fbm gain per octave (0–1); lower is smoother, higher is rougher. Defaults to `0.5`. */
+    persistence?: number;
+    /** Normalized radius (0–1) where the rim begins fading relief to a flat edge. Defaults to `0.82`. */
+    rim?: number;
+    /** Seed for reproducible terrain. Defaults to `1`. */
+    seed?: number;
+}
+
+export declare interface TerrainMoundOptions extends TerrainMoundGeometryOptions {
+    /** Surface tint. Defaults to `#3a5a3a`. */
+    color?: ColorRepresentation;
+    /** Faceted low-poly shading. Defaults to `true`. */
+    flatShading?: boolean;
+}
+
+/**
+ * Rectangular terrain patch prefab — a {@link TerrainPlaneGeometry} with a matte,
+ * flat-shaded material. Base grid on Y=0; drop it into a scene as a diorama ground
+ * or a tileable terrain field. Casts and receives shadows.
+ */
+export declare class TerrainPlane extends Mesh<TerrainPlaneGeometry, MeshStandardMaterial> {
+    readonly width: number;
+    readonly depth: number;
+    constructor({ color, flatShading, ...geometryOptions }?: TerrainPlaneOptions);
+}
+
+/**
+ * Rectangular terrain patch — a flat grid displaced on Y by the shared coherent fbm
+ * sampler ({@link fbm2}). The rectangular counterpart to {@link TerrainMoundGeometry}:
+ * same noise strategy, grid layout instead of a radial disc.
+ *
+ * A pure heightfield (Y is single-valued per XZ) so faces can never fold, and it's
+ * baked into real vertices — shadows, raycasts, and physics colliders match what's
+ * drawn, on WebGL and WebGPU/TSL alike. Pair with a `flatShading` material for a
+ * faceted low-poly look. Leave `edgeFalloff` at `0` for a tileable field; raise it to
+ * seat the edges flat at Y=0.
+ *
+ * Local frame: base grid on Y=0, relief toward ±Y, centered on the origin.
+ */
+export declare class TerrainPlaneGeometry extends BufferGeometry {
+    readonly width: number;
+    readonly depth: number;
+    constructor({ width, depth, widthSegments, depthSegments, noiseHeight, noiseScale, octaves, persistence, edgeFalloff, seed, }?: TerrainPlaneGeometryOptions);
+}
+
+export declare interface TerrainPlaneGeometryOptions {
+    /** Extent along X (world units). Defaults to `16`. */
+    width?: number;
+    /** Extent along Z (world units). Defaults to `16`. */
+    depth?: number;
+    /** Grid segments along X. Defaults to `48`. */
+    widthSegments?: number;
+    /** Grid segments along Z. Defaults to `48`. */
+    depthSegments?: number;
+    /** Amplitude of the terrain relief (world units, ±). Defaults to `0.8`. */
+    noiseHeight?: number;
+    /** Noise frequency — higher packs more, smaller features into the footprint. Defaults to `0.35`. */
+    noiseScale?: number;
+    /** fbm octaves (detail layers). Defaults to `4`. */
+    octaves?: number;
+    /** fbm gain per octave (0–1); lower is smoother, higher is rougher. Defaults to `0.5`. */
+    persistence?: number;
+    /**
+     * Border band (0–1 fraction of the half-extent) over which relief fades to a flat
+     * edge at Y=0. `0` leaves a raw, seamless heightfield (tileable); higher values
+     * seat the slab like a contained diorama patch. Defaults to `0`.
+     */
+    edgeFalloff?: number;
+    /** Seed for reproducible terrain. Defaults to `1`. */
+    seed?: number;
+}
+
+export declare interface TerrainPlaneOptions extends TerrainPlaneGeometryOptions {
+    /** Surface tint. Defaults to `#3a5a3a`. */
+    color?: ColorRepresentation;
+    /** Faceted low-poly shading. Defaults to `true`. */
+    flatShading?: boolean;
+}
+
 /**
  * Material indices
  * 0: Base