three-low-poly 0.9.17 → 0.9.19

package/dist/index.d.ts

@@ -12,6 +12,7 @@ import { MeshLambertMaterial } from 'three';
 import { MeshPhongMaterial } from 'three';
 import { MeshPhysicalMaterial } from 'three';
 import { MeshStandardMaterial } from 'three';
+import { ParametricGeometry } from 'three-stdlib';
 import { PerspectiveCamera } from 'three';
 import { ShaderMaterial } from 'three';
 import { Shape } from 'three';
@@ -45,6 +46,48 @@ export declare function addWaterDisplacement<T extends Material>(material: T, {
     waveAmplitude?: number | undefined;
 }): void;
 
+/**
+ * Generates spherical curve profile points, for use with geometry.
+ * Enables connective geometry via holes at the top and bottom of the sphere.
+ *
+ * Example usage:
+ *
+ * Tube that connect with a sphere on the bottom:
+ * ```
+ *    const points: Vector2[] = [
+ *       new Vector2(1, 0),
+ *       ...appendSphericalCurve(
+ *         2,  // Radius x
+ *         2,  // Radius y
+ *         5,  // Start y
+ *         0,  // Hole top radius
+ *         1,  // Hole bottom radius
+ *         32, // Segments
+ *       ),
+ *     ];
+ *
+ *     const latheGeometry = new LatheGeometry(points, 32);
+ * ```
+ *
+ * Tube that connect with a sphere on the top:
+ * ```
+ *    const points: Vector2[] = [
+ *       ...appendSphericalCurve(
+ *         2,  // Radius x
+ *         2,  // Radius y
+ *         1,  // Start y
+ *         1,  // Hole top radius
+ *         0,  // Hole bottom radius
+ *         32, // Segments
+ *       ),
+ *       new Vector2(1, 5),
+ *     ];
+ *
+ *     const latheGeometry = new LatheGeometry(points, 32);
+ * ```
+ */
+export declare function appendSphericalCurve(sphereRadiusX: number, sphereRadiusY: number, sphereStartY: number, holeTopRadius?: number, holeBottomRadius?: number, segments?: number): Vector2[];
+
 /**
  * Atmospheric scattering shader.
  *
@@ -439,14 +482,132 @@ export declare function calculateXFromSlopeIntercept(x1: number, y1: number, x2:
  */
 export declare function calculateYFromSlopeIntercept(x1: number, y1: number, x2: number, y2: number, x: number): number;
 
-export declare class Candle extends Group {
-    private candle;
-    private flame;
-    private candleLight;
-    private height;
-    private radius;
-    constructor(height?: number, radius?: number);
-    animateFlicker(): void;
+/**
+ * Dolly backward
+ *
+ * Example:
+ * ```
+ * dollyAnimation(camera, 5, 3000, () => {
+ *   console.log("Dolly animation complete");
+ * });
+ * ```
+ */
+export declare function cameraDollyAnimation(camera: Camera, distance: number, duration: number, onComplete?: () => void): void;
+
+/**
+ * The camera flies through a sequence of points, ideal for showcasing specific elements in the scene.
+ *
+ * Example:
+ * ```
+ * flythroughAnimation(
+ *   camera,
+ *   [
+ *     new THREE.Vector3(0, 5, 5),
+ *     new THREE.Vector3(0, 5, -25.5),
+ *     new THREE.Vector3(-20.5, 5, 0),
+ *   ],
+ *   6000,
+ *   () => {
+ *     console.log("Flythrough animation complete");
+ *   }
+ * );
+ * ```
+ */
+export declare function cameraFlythroughAnimation(camera: Camera, waypoints: Vector3[], duration: number, onComplete?: () => void): void;
+
+/**
+ * Orbit around a target
+ *
+ * Example:
+ * ```
+ * orbitAnimation(camera, new THREE.Vector3(0, 0, 0), 10, 5000, () => {
+ *   console.log("Orbit animation complete");
+ * });
+ * ```
+ */
+export declare function cameraOrbitAnimation(camera: Camera, target: Vector3, radius: number, duration: number, onComplete?: () => void): void;
+
+/**
+ * The camera swings back and forth like a pendulum.
+ *
+ * Example:
+ * ```
+ * pendulumAnimation(camera, new THREE.Vector3(0, 5, 5), 0.5, 9000, 3, () => {
+ *   console.log("Pendulum animation complete");
+ * });
+ * ```
+ */
+export declare function cameraPendulumAnimation(camera: Camera, center: Vector3, radius: number, duration: number, oscillations: number, onComplete?: () => void): void;
+
+/**
+ * The camera spirals upward, perfect for revealing a large scene or structure.
+ *
+ * Example:
+ * ```
+ * spiralAscensionAnimation(camera, new THREE.Vector3(0, 0, 0), 10, 300, 7, 12000, () => {
+ *   console.log("Spiral ascension animation complete");
+ * });
+ * ```
+ */
+export declare function cameraSpiralAscensionAnimation(camera: Camera, center: Vector3, radius: number, height: number, revolutions: number, duration: number, onComplete?: () => void): void;
+
+/**
+ * Add a slight random wobble for intensity or realism (e.g., during an explosion).
+ *
+ * Example:
+ * ```
+ * wobbleAnimation(camera, 0.5, 1000, () => {
+ *   console.log("Wobble animation complete");
+ * });
+ * ```
+ */
+export declare function cameraWobbleAnimation(camera: Camera, intensity: number, duration: number, onComplete?: () => void): void;
+
+/**
+ * The camera smoothly zooms in toward a target, focusing attention on a specific point,
+ * and resets to its original FOV after completion.
+ *
+ * Example:
+ * ```
+ * zoomInAnimation(camera, new THREE.Vector3(0, 0, 0), 120, 75, 2000, () => {
+ *   console.log("Zoom in animation complete");
+ * });
+ * ```
+ */
+export declare function cameraZoomInAnimation(camera: PerspectiveCamera, target: Vector3, startFov: number, endFov: number, duration: number, onComplete?: () => void): void;
+
+/**
+ * Material indices
+ * 0: Stick
+ * 1: Flame
+ */
+export declare class Candle extends Mesh<CandleGeometry, MeshStandardMaterial[]> {
+    constructor({ radiusTop, //
+        radiusBottom, height, flameHeight, flameRadius, segments, }?: {
+        radiusTop?: number | undefined;
+        radiusBottom?: number | undefined;
+        height?: number | undefined;
+        flameHeight?: number | undefined;
+        flameRadius?: number | undefined;
+        segments?: number | undefined;
+    });
+}
+
+/**
+ * Group indices
+ * 0: Stick
+ * 1: Flame
+ */
+export declare class CandleGeometry extends BufferGeometry {
+    constructor({ radiusTop, //
+        radiusBottom, height, flameHeight, flameRadius, segments, }?: {
+        radiusTop?: number | undefined;
+        radiusBottom?: number | undefined;
+        height?: number | undefined;
+        flameHeight?: number | undefined;
+        flameRadius?: number | undefined;
+        segments?: number | undefined;
+    });
 }
 
 /**
@@ -487,12 +648,22 @@ export declare function centerInstancedMesh<T extends InstancedMesh>(mesh: T): v
 export declare function centerMesh<T extends Mesh>(mesh: T): void;
 
 /**
- * Centers the geometry of the given mesh at the local origin (0, 0, 0) by modifying the geometry vertices.
+ * Centers a Mesh at the specified target position.
+ */
+export declare function centerMeshAtTarget<T extends Mesh>(mesh: T, target?: Vector3): void;
+
+/**
+ * Centers the geometry of the Mesh at the local origin (0, 0, 0) by modifying the geometry vertices.
  * This method moves the geometry itself so that its center is at the local origin,
  * without affecting the position, rotation, or scale of the mesh.
  */
 export declare function centerMeshGeometry<T extends Mesh>(mesh: T): void;
 
+/**
+ * Centers the geometry of a Mesh at the specified target position.
+ */
+export declare function centerMeshGeometryAtTarget<T extends Mesh>(mesh: T, target?: Vector3): void;
+
 /**
  * Create a checkerboard texture
  *
@@ -964,18 +1135,6 @@ export declare const Direction: {
  */
 export declare const displacementBrush: <T extends BufferGeometry>(geometry: T, position: Vector3, radius: number, strength: number, direction?: Vector3, falloffFn?: (distance: number, radius: number) => number) => void;
 
-/**
- * Dolly backward
- *
- * Example:
- * ```
- * dollyAnimation(camera, 5, 3000, () => {
- *   console.log("Dolly animation complete");
- * });
- * ```
- */
-export declare function dollyAnimation(camera: Camera, distance: number, duration: number, onComplete?: () => void): void;
-
 /**
  * Easing functions for interpolating values over time.
  */
@@ -1020,18 +1179,26 @@ export declare class EllipticLeafGeometry extends BufferGeometry {
 }
 
 /**
- * Emissive pulse effect, designed for flickering lights.
+ * Emissive pulse animation, producing a flickering light effect for materials that have emissive properties.
  * The emissive intensity of the material will oscillate between `minIntensity` and `maxIntensity`.
  *
- * Use with materials that have emissive properties.
- *
  * Oscillation time = 2π / speed
  *  - Low speed values (e.g., 0.5) will result in a slow pulse
  *  - High speed values (e.g., 10) will result in a rapid flicker
  *
  *  Requires `update()` frame handler with `clock.getElapsedTime()` for animation.
+ *
+ *  Example usage:
+ *  ```
+ *  const pulseAnimation = new EmissivePulseAnimation();
+ *  const clock = new THREE.Clock();
+ *
+ *  function animate() {
+ *    pulseAnimation.update(clock.getElapsedTime());
+ *  }
+ *  ```
  */
-export declare class EmissivePulseEffect {
+export declare class EmissivePulseAnimation {
     speed: number;
     maxIntensity: number;
     minIntensity: number;
@@ -1118,8 +1285,22 @@ export declare function findClosestColor(inputColor: number, dataset: number[]):
 
 export declare function findClosestColorChannelWise(inputColor: number, dataset: number[]): number | null;
 
-export declare class Flask extends Group {
-    constructor();
+export declare class Flame extends Mesh<FlameGeometry, MeshStandardMaterial> {
+    constructor({ height, radius, segmentsU, segmentsV }?: {
+        height?: number | undefined;
+        radius?: number | undefined;
+        segmentsU?: number | undefined;
+        segmentsV?: number | undefined;
+    });
+}
+
+export declare class FlameGeometry extends ParametricGeometry {
+    constructor({ height, radius, segmentsU, segmentsV }?: {
+        height?: number | undefined;
+        radius?: number | undefined;
+        segmentsU?: number | undefined;
+        segmentsV?: number | undefined;
+    });
 }
 
 /**
@@ -1135,27 +1316,6 @@ export declare class FlorenceFlaskGeometry extends BufferGeometry {
     constructor();
 }
 
-/**
- * The camera flies through a sequence of points, ideal for showcasing specific elements in the scene.
- *
- * Example:
- * ```
- * flythroughAnimation(
- *   camera,
- *   [
- *     new THREE.Vector3(0, 5, 5),
- *     new THREE.Vector3(0, 5, -25.5),
- *     new THREE.Vector3(-20.5, 5, 0),
- *   ],
- *   6000,
- *   () => {
- *     console.log("Flythrough animation complete");
- *   }
- * );
- * ```
- */
-export declare function flythroughAnimation(camera: Camera, waypoints: Vector3[], duration: number, onComplete?: () => void): void;
-
 export declare const gaussian: (t: number) => number;
 
 export declare class Gear extends Mesh {
@@ -1192,7 +1352,7 @@ export declare function hexToHsl(hex: number): [number, number, number];
  */
 export declare function hexToRgb(hex: number): [number, number, number];
 
-export declare class Hill extends Mesh {
+export declare class Hill extends Mesh<HillGeometry, MeshStandardMaterial> {
     constructor({ radius, //
         height, widthSegments, heightSegments, phiStart, phiLength, }?: {
         radius?: number | undefined;
@@ -1246,6 +1406,24 @@ export declare function interpolateCurve(curveFunction: (t: number) => number, s
 
 export declare const inverse: (t: number) => number;
 
+/**
+ * Material indices
+ * 0. Jar
+ * 1. Cork
+ */
+export declare class Jar extends Mesh<JarGeometry, MeshStandardMaterial[]> {
+    constructor();
+}
+
+/**
+ * Group indices
+ * 0. Jar
+ * 1. Cork
+ */
+export declare class JarGeometry extends BufferGeometry {
+    constructor();
+}
+
 export declare class Lantern extends Group {
     constructor(height?: number, baseWidth?: number);
 }
@@ -1274,7 +1452,66 @@ export declare class LeverPanel extends Group {
 }
 
 /**
- * A lightning effect that can be used to simulate a lightning storm.
+ * Create a light flicker animation that will randomly change the intensity and position of a light.
+ * Effect resembles a flickering flame of candlelight.
+ *
+ * Example usage:
+ * ```
+ *    // Create a candle
+ *    const candle = new Candle({
+ *      height: 1,
+ *      flameHeight: 0.25,
+ *    });
+ *    scene.add(candle);
+ *
+ *    // Create a point light
+ *    const candleLight = new THREE.PointLight(0xffa500, 1, 5);
+ *    scene.add(candleLight);
+ *
+ *    // Apply the animator to the light
+ *    const lightAnimation = new LightFlickerAnimation({
+ *      light: candleLight,
+ *      maxIntensity: 2.2,
+ *      x: candle.position.x,
+ *      y: candle.position.y + 1 + 0.125, // height + half flame height
+ *      z: candle.position.z,
+ *    });
+ *    animations.push(lightAnimation);
+ *
+ *    // Update the light animation in the render loop
+ *    renderer.setAnimationLoop(() => {
+ *      lightAnimation.update();
+ *    });
+ * ```
+ */
+export declare class LightFlickerAnimation {
+    private light?;
+    minIntensity: number;
+    maxIntensity: number;
+    x: number;
+    y: number;
+    z: number;
+    jitterX: number;
+    jitterY: number;
+    jitterZ: number;
+    constructor({ light, minIntensity, maxIntensity, x, y, z, jitterX, jitterY, jitterZ, }?: Partial<LightFlickerAnimationOptions>);
+    update(): void;
+}
+
+export declare interface LightFlickerAnimationOptions {
+    light?: Light;
+    minIntensity: number;
+    maxIntensity: number;
+    x: number;
+    y: number;
+    z: number;
+    jitterX: number;
+    jitterY: number;
+    jitterZ: number;
+}
+
+/**
+ * A lightning animation that can be used to simulate a lightning storm.
  * This effect is applied to a light source.
  *
  * Example usage:
@@ -1283,12 +1520,14 @@ export declare class LeverPanel extends Group {
  * scene.add(lightning);
  * lightning.position.set(5, 10, -5);
  *
+ * const lightningAnimation = new LightningAnimation();
+ *
  * setRandomInterval(() => {
  *   lightningEffect.triggerLightning();
  * }, 250, 1250);
  * ```
  */
-export declare class LightningEffect {
+export declare class LightningAnimation {
     private light?;
     minIntensity: number;
     maxIntensity: number;
@@ -1401,7 +1640,21 @@ export declare class MortarGeometry extends BufferGeometry {
     constructor();
 }
 
-export declare class MossyRocks extends Group {
+/**
+ * Material indices:
+ * 0. Rocks
+ * 1. Moss
+ */
+export declare class MossyRocks extends Mesh<MossyRocksGeometry, MeshStandardMaterial[]> {
+    constructor();
+}
+
+/**
+ * Group indices:
+ * 0. Rocks
+ * 1. Moss
+ */
+export declare class MossyRocksGeometry extends BufferGeometry {
     constructor();
 }
 
@@ -1422,7 +1675,7 @@ export declare class MossyRocks extends Group {
  * }
  * ```
  */
-export declare class Mound extends Mesh {
+export declare class Mound extends Mesh<MoundGeometry, MeshStandardMaterial> {
     constructor({ radius, //
         widthSegments, heightSegments, phiStart, phiLength, thetaLength, }?: {
         radius?: number | undefined;
@@ -1562,18 +1815,6 @@ declare interface ObeliskHeadstoneOptions {
     totalHeight?: number;
 }
 
-/**
- * Orbit around a target
- *
- * Example:
- * ```
- * orbitAnimation(camera, new THREE.Vector3(0, 0, 0), 10, 5000, () => {
- *   console.log("Orbit animation complete");
- * });
- * ```
- */
-export declare function orbitAnimation(camera: Camera, target: Vector3, radius: number, duration: number, onComplete?: () => void): void;
-
 /**
  * Prefab for a panel.
  * Designed to be used as a control panel for switches, lights, levels, dials, and gauges.
@@ -1636,18 +1877,6 @@ export declare const ParametricCurveUtils: {
  */
 export declare function parseHexCode(hex: string): [number, number, number];
 
-/**
- * The camera swings back and forth like a pendulum.
- *
- * Example:
- * ```
- * pendulumAnimation(camera, new THREE.Vector3(0, 5, 5), 0.5, 9000, 3, () => {
- *   console.log("Pendulum animation complete");
- * });
- * ```
- */
-export declare function pendulumAnimation(camera: Camera, center: Vector3, radius: number, duration: number, oscillations: number, onComplete?: () => void): void;
-
 /**
  * Planar UV Mapping
  * Projects UVs onto the geometry from a single direction (like shining a projector onto a surface).
@@ -1772,7 +2001,11 @@ export declare class RockGeometry extends BufferGeometry {
     constructor(radius?: number, widthSegments?: number, heightSegments?: number);
 }
 
-export declare class Rocks extends Group {
+export declare class Rocks extends Mesh<RocksGeometry, MeshStandardMaterial> {
+    constructor();
+}
+
+export declare class RocksGeometry extends BufferGeometry {
     constructor();
 }
 
@@ -1892,18 +2125,6 @@ export declare function sphericalUVMapping(vertices: [number, number, number][])
  */
 export declare const spikeBrush: <T extends BufferGeometry>(geometry: T, position: Vector3, radius: number, strength: number, inward?: boolean, falloffFn?: (distance: number, radius: number) => number) => void;
 
-/**
- * The camera spirals upward, perfect for revealing a large scene or structure.
- *
- * Example:
- * ```
- * spiralAscensionAnimation(camera, new THREE.Vector3(0, 0, 0), 10, 300, 7, 12000, () => {
- *   console.log("Spiral ascension animation complete");
- * });
- * ```
- */
-export declare function spiralAscensionAnimation(camera: Camera, center: Vector3, radius: number, height: number, revolutions: number, duration: number, onComplete?: () => void): void;
-
 export declare class SpiralStaircaseGeometry extends BufferGeometry {
     constructor(stepWidth?: number, stepDepth?: number, stepHeight?: number, numSteps?: number, radius?: number, angleIncrement?: number);
 }
@@ -1971,7 +2192,21 @@ export declare class StoneFencePostGeometry extends BufferGeometry {
     });
 }
 
-export declare class TeslaCoil extends Group {
+/**
+ * Material indices
+ * 0: Base
+ * 1: Coil
+ */
+export declare class TeslaCoil extends Mesh<TeslaCoilGeometry, MeshStandardMaterial[]> {
+    constructor();
+}
+
+/**
+ * Group indices
+ * 0: Base
+ * 1: Coil
+ */
+export declare class TeslaCoilGeometry extends BufferGeometry {
     constructor();
 }
 
@@ -1987,6 +2222,21 @@ export declare class TestTubeRack extends Group {
     constructor(count?: number, colors?: number[]);
 }
 
+/**
+ * Calculate the thetaLength to achieve a specific hole radius in a sphere.
+ *   thetaLength = asin(w / (2 * R))
+ *
+ * Returns the thetaLength in radians.
+ *
+ * Example usage:
+ * ```
+ * const sphereRadius = 5; // Radius of the sphere
+ * const holeRadius = 1;   // Desired radius of the hole at the top
+ * const thetaLength = thetaLengthForRadius(sphereRadius, holeRadius);
+ * ```
+ */
+export declare const thetaLengthForRadius: (sphereRadius: number, holeRadius: number) => number;
+
 /**
  * Material indices:
  * 0. Trunk
@@ -2076,18 +2326,6 @@ export declare class WineBottleGeometry extends BufferGeometry {
     });
 }
 
-/**
- * Add a slight random wobble for intensity or realism (e.g., during an explosion).
- *
- * Example:
- * ```
- * wobbleAnimation(camera, 0.5, 1000, () => {
- *   console.log("Wobble animation complete");
- * });
- * ```
- */
-export declare function wobbleAnimation(camera: Camera, intensity: number, duration: number, onComplete?: () => void): void;
-
 export declare class WroughtIronBar extends Mesh<WroughtIronBarGeometry, MeshStandardMaterial> {
     constructor({ barHeight, //
         barRadius, spikeHeight, spikeRadius, spikeScaleZ, radialSegments, }?: {
@@ -2149,17 +2387,4 @@ export declare class WroughtIronFenceGeometry extends BufferGeometry {
     });
 }
 
-/**
- * The camera smoothly zooms in toward a target, focusing attention on a specific point,
- * and resets to its original FOV after completion.
- *
- * Example:
- * ```
- * zoomInAnimation(camera, new THREE.Vector3(0, 0, 0), 120, 75, 2000, () => {
- *   console.log("Zoom in animation complete");
- * });
- * ```
- */
-export declare function zoomInAnimation(camera: PerspectiveCamera, target: Vector3, startFov: number, endFov: number, duration: number, onComplete?: () => void): void;
-
 export { }