fastnoiselite-builder 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright(c) 2020 Jordan Peck (jordan.me2@gmail.com)
+Copyright(c) 2020 Contributors
+Copyright(c) 2026 Sébastien Vincent (metabast@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# fastnoiselite-builder
+
+A TypeScript implementation of FastNoiseLite with zero runtime dispatch overhead.
+
+## Key Features
+
+- **Zero runtime switch statements**: Function composition happens at build-time via the Builder pattern
+- **Fully typed**: Complete TypeScript type definitions
+- **Modular architecture**: Clean separation of concerns
+- **Implementation details**: Uses `Float64Array` for gradient tables, pre-computed constants, and closures to capture context
+- **Multiple noise algorithms**:
+  - OpenSimplex2 (2D & 3D)
+  - OpenSimplex2S (2D & 3D with skew)
+  - Cellular/Voronoi (2D & 3D) with 4 distance functions and 7 return types
+  - Perlin (2D & 3D)
+  - Value (2D & 3D)
+  - ValueCubic (2D & 3D)
+- **Fractal modifiers**:
+  - FBm (Fractional Brownian Motion)
+  - Ridged
+  - PingPong
+- **Domain Warp**:
+  - BasicGrid warp (smooth grid-based deformation)
+  - OpenSimplex2 warp (organic gradient-based deformation)
+  - OpenSimplex2Reduced warp (faster simplified version)
+  - Progressive fractal warp (multi-octave deformation)
+
+## Installation
+
+```bash
+npm install fastnoiselite-builder
+```
+
+## Usage
+
+### Basic 2D Noise
+
+```typescript
+import { NoiseBuilder2D, NoiseType } from 'fastnoiselite-builder';
+
+const noise = new NoiseBuilder2D()
+  .seed(1337)
+  .frequency(0.01)
+  .noiseType(NoiseType.Perlin)
+  .build2D();
+
+const value = noise(x, y);  // Returns noise value in range [-1, 1]
+```
+
+### Fractal Noise
+
+```typescript
+import { NoiseBuilder2D, NoiseType, FractalType } from 'fastnoiselite-builder';
+
+const noise = new NoiseBuilder2D()
+  .seed(1337)
+  .frequency(0.01)
+  .noiseType(NoiseType.Perlin)
+  .fractalType(FractalType.FBm)
+  .fractalOctaves(4)
+  .fractalLacunarity(2.0)
+  .fractalGain(0.5)
+  .build2D();
+
+const value = noise(x, y);
+```
+
+### 3D Noise
+
+```typescript
+import { NoiseBuilder3D, NoiseType } from 'fastnoiselite-builder';
+
+const noise = new NoiseBuilder3D()
+  .seed(1337)
+  .frequency(0.01)
+  .noiseType(NoiseType.OpenSimplex2)
+  .build3D();
+
+const value = noise(x, y, z);
+```
+
+### Ridged Terrain
+
+```typescript
+import { NoiseBuilder2D, NoiseType, FractalType } from 'fastnoiselite-builder';
+
+const noise = new NoiseBuilder2D()
+  .seed(42)
+  .frequency(0.005)
+  .noiseType(NoiseType.Perlin)
+  .fractalType(FractalType.Ridged)
+  .fractalOctaves(6)
+  .fractalWeightedStrength(0.8)
+  .build2D();
+```
+
+### Cellular/Voronoi Noise
+
+```typescript
+import { NoiseBuilder2D, NoiseType, CellularDistanceFunction, CellularReturnType } from 'fastnoiselite-builder';
+
+// Basic voronoi pattern
+const noise = new NoiseBuilder2D()
+  .seed(1337)
+  .frequency(0.01)
+  .noiseType(NoiseType.Cellular)
+  .cellularDistanceFunction(CellularDistanceFunction.Euclidean)
+  .cellularReturnType(CellularReturnType.Distance)
+  .build2D();
+
+// Voronoi edges (great for cell boundaries)
+const edges = new NoiseBuilder2D()
+  .seed(1337)
+  .frequency(0.01)
+  .noiseType(NoiseType.Cellular)
+  .cellularReturnType(CellularReturnType.Distance2Sub)
+  .build2D();
+
+// Cell value (flat regions with hard edges)
+const cells = new NoiseBuilder2D()
+  .seed(1337)
+  .frequency(0.01)
+  .noiseType(NoiseType.Cellular)
+  .cellularReturnType(CellularReturnType.CellValue)
+  .cellularJitter(1.0)  // Control randomness (0-1)
+  .build2D();
+
+// Manhattan distance (diamond-shaped cells)
+const manhattan = new NoiseBuilder2D()
+  .seed(1337)
+  .frequency(0.01)
+  .noiseType(NoiseType.Cellular)
+  .cellularDistanceFunction(CellularDistanceFunction.Manhattan)
+  .cellularReturnType(CellularReturnType.Distance)
+  .build2D();
+```
+
+### Domain Warp
+
+Domain Warp deforms the coordinate space before sampling noise, creating organic flowing patterns.
+
+```typescript
+import { NoiseBuilder2D, NoiseType, DomainWarpType, DomainWarpFractalType } from 'fastnoiselite-builder';
+
+// Simple domain warp
+const noise = new NoiseBuilder2D()
+  .seed(42)
+  .frequency(0.01)
+  .noiseType(NoiseType.Perlin)
+  .domainWarpType(DomainWarpType.BasicGrid)
+  .domainWarpAmplitude(30.0)
+  .domainWarpFrequency(0.005)
+  .build2D();
+
+// Fractal domain warp (progressive)
+const fractalWarpNoise = new NoiseBuilder2D()
+  .seed(42)
+  .frequency(0.01)
+  .noiseType(NoiseType.OpenSimplex2)
+  .domainWarpType(DomainWarpType.OpenSimplex2)
+  .domainWarpAmplitude(50.0)
+  .domainWarpFrequency(0.005)
+  .domainWarpFractalType(DomainWarpFractalType.Progressive)
+  .domainWarpFractalOctaves(3)
+  .domainWarpFractalLacunarity(2.0)
+  .domainWarpFractalGain(0.5)
+  .build2D();
+
+const value = noise(x, y);
+```
+
+**Use Cases for Domain Warp:**
+- **Terrain generation** - Natural-looking height maps with flowing features
+- **Cloud patterns** - Organic, swirling cloud formations
+- **Marble textures** - Flowing veined patterns
+- **Water caustics** - Complex light refraction patterns
+- **Organic shapes** - Any pattern that needs natural, flowing deformation
+
+## Architecture
+
+The library uses a **composition over inheritance** approach with the Builder pattern:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│              NoiseBuilder2D / NoiseBuilder3D                 │
+│  • Fluent API for configuration                             │
+│  • Composes functions at build-time                         │
+│  • Returns composed noise function                          │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                ┌──────────┴──────────┐
+                ▼                     ▼
+        ┌──────────────┐      ┌──────────────┐
+        │  Base Noise  │      │   Fractals   │
+        │  Generators  │      │  Modifiers   │
+        └──────────────┘      └──────────────┘
+                │                     │
+    ┌───────────┼───────────┐        │
+    ▼           ▼           ▼        ▼
+ OpenSimplex  Perlin     Value      FBm
+   Value    ValueCubic            Ridged
+                                 PingPong
+```
+
+## Project Structure
+
+```
+lib/
+├── types/           # TypeScript type definitions
+├── core/            # Math utilities, hash functions, constants
+├── noise/           # Noise generators (OpenSimplex, Perlin, Value, etc.)
+├── fractal/         # Fractal modifiers (FBm, Ridged, PingPong)
+├── builder/         # NoiseBuilder2D / NoiseBuilder3D fluent API
+└── __tests__/       # Test suite
+```
+
+## Development
+
+```bash
+# Build the library (generates dist/)
+npm run build:lib
+
+# Run tests
+npm test
+
+# Run tests with UI
+npm run test:ui
+```
+
+## API Reference
+
+### NoiseBuilder2D / NoiseBuilder3D Methods
+
+| Method | Description | Default |
+|--------|-------------|---------|
+| `seed(n)` | Set random seed | 1337 |
+| `frequency(f)` | Set sampling frequency | 0.01 |
+| `noiseType(type)` | Set noise algorithm | `NoiseType.OpenSimplex2` |
+| `fractalType(type)` | Set fractal type | `FractalType.None` |
+| `fractalOctaves(n)` | Set number of octaves | 3 |
+| `fractalLacunarity(f)` | Set lacunarity | 2.0 |
+| `fractalGain(f)` | Set gain | 0.5 |
+| `fractalWeightedStrength(f)` | Set weighted strength | 0.0 |
+| `fractalPingPongStrength(f)` | Set ping-pong strength | 2.0 |
+| `cellularDistanceFunction(type)` | Distance metric for cellular noise | `CellularDistanceFunction.EuclideanSq` |
+| `cellularReturnType(type)` | Return type for cellular noise | `CellularReturnType.Distance` |
+| `cellularJitter(f)` | Cell position randomness (0-1) | 1.0 |
+| `domainWarpType(type)` | Set domain warp algorithm | `DomainWarpType.None` |
+| `domainWarpAmplitude(f)` | Set warp strength | 30.0 |
+| `domainWarpFrequency(f)` | Set warp sampling frequency | 0.005 |
+| `domainWarpFractalType(type)` | Set fractal warp mode | `DomainWarpFractalType.None` |
+| `domainWarpFractalOctaves(n)` | Set warp fractal octaves | 3 |
+| `domainWarpFractalLacunarity(f)` | Set warp fractal lacunarity | 2.0 |
+| `domainWarpFractalGain(f)` | Set warp fractal gain | 0.5 |
+| `build2D()` | Build 2D noise function *(NoiseBuilder2D only)* | - |
+| `build3D()` | Build 3D noise function *(NoiseBuilder3D only)* | - |
+
+### Cellular Options
+
+**Distance Functions:**
+- `CellularDistanceFunction.Euclidean` - True distance (with sqrt)
+- `CellularDistanceFunction.EuclideanSq` - Squared distance (faster)
+- `CellularDistanceFunction.Manhattan` - Sum of absolute differences (diamond-shaped cells)
+- `CellularDistanceFunction.Hybrid` - Combination of Manhattan and Euclidean
+
+**Return Types:**
+- `CellularReturnType.CellValue` - Value based on closest cell (flat regions)
+- `CellularReturnType.Distance` - Distance to closest point (voronoi)
+- `CellularReturnType.Distance2` - Distance to second closest point
+- `CellularReturnType.Distance2Add` - Average of both distances
+- `CellularReturnType.Distance2Sub` - Difference between distances (cell edges)
+- `CellularReturnType.Distance2Mul` - Product of both distances
+- `CellularReturnType.Distance2Div` - Ratio of distances
+
+## License
+
+MIT License - Based on FastNoiseLite by Jordan Peck
+
+## Credits
+
+- Original FastNoiseLite: [Auburn/FastNoiseLite](https://github.com/Auburn/FastNoiseLite)
+- JavaScript port: snowfoxsh
+- TypeScript implementation: Sébastien Vincent

package/dist/builder/ANoiseBuilder.d.ts

@@ -0,0 +1,100 @@
+import { type NoiseConfig, NoiseType, CellularDistanceFunction, CellularReturnType, FractalType, DomainWarpType, DomainWarpFractalType, TransformType3D, RotationType3D } from '../types';
+export declare abstract class ANoiseBuilder {
+    protected config: Required<NoiseConfig>;
+    /**
+     * Set the seed for noise generation
+     */
+    seed(value: number): this;
+    /**
+     * Set the frequency for noise generation
+     */
+    frequency(value: number): this;
+    /**
+     * Set the noise algorithm type
+     */
+    noiseType(value: NoiseType): this;
+    /**
+     * Set the rotation type for 3D noise
+     */
+    rotationType3D(value: RotationType3D): this;
+    /**
+     * Set the fractal type
+     */
+    fractalType(value: FractalType): this;
+    /**
+     * Set the number of octaves for fractal noise
+     */
+    fractalOctaves(value: number): this;
+    /**
+     * Set the lacunarity for fractal noise
+     */
+    fractalLacunarity(value: number): this;
+    /**
+     * Set the gain for fractal noise
+     */
+    fractalGain(value: number): this;
+    /**
+     * Set the weighted strength for fractal noise
+     */
+    fractalWeightedStrength(value: number): this;
+    /**
+     * Set the ping pong strength for ping pong fractal
+     */
+    fractalPingPongStrength(value: number): this;
+    /**
+     * Set the transform type for 3D noise
+     */
+    transformType3D(value: TransformType3D): this;
+    /**
+     * Set the distance function for cellular noise
+     */
+    cellularDistanceFunction(value: CellularDistanceFunction): this;
+    /**
+     * Set the return type for cellular noise
+     */
+    cellularReturnType(value: CellularReturnType): this;
+    /**
+     * Set the jitter modifier for cellular noise (0-1)
+     */
+    cellularJitter(value: number): this;
+    /**
+     * Set the domain warp type
+     */
+    domainWarpType(value: DomainWarpType): this;
+    /**
+     * Set the domain warp amplitude
+     */
+    domainWarpAmplitude(value: number): this;
+    /**
+     * Set the domain warp frequency
+     */
+    domainWarpFrequency(value: number): this;
+    /**
+     * Set the domain warp fractal type (Progressive or Independent)
+     */
+    domainWarpFractalType(value: DomainWarpFractalType): this;
+    /**
+     * Set the number of octaves for domain warp fractal
+     */
+    domainWarpFractalOctaves(value: number): this;
+    /**
+     * Set the lacunarity for domain warp fractal
+     */
+    domainWarpFractalLacunarity(value: number): this;
+    /**
+     * Set the gain for domain warp fractal
+     */
+    domainWarpFractalGain(value: number): this;
+    /**
+     * Calculate fractal bounding value
+     */
+    protected calculateFractalBounding(): number;
+    /**
+     * Calculate fractal bounding for domain warp amplitude scaling
+     */
+    protected calculateWarpFractalBounding(): number;
+    /**
+     * Get type-specific amplitude multiplier for domain warp
+     */
+    protected getWarpAmplitudeMultiplier(): number;
+}

package/dist/builder/NoiseBuilder2D.d.ts

@@ -0,0 +1,14 @@
+import { type NoiseFunction2D } from '../types';
+import { ANoiseBuilder } from './ANoiseBuilder';
+export declare class NoiseBuilder2D extends ANoiseBuilder {
+    /**
+     * Build a 2D noise function
+     * Returns an optimized function with zero runtime dispatch overhead
+     */
+    build2D(): NoiseFunction2D;
+    /**
+     * Build domain warp function for 2D (if enabled)
+     * Returns null if domain warp is disabled
+     */
+    private buildDomainWarp2D;
+}

package/dist/builder/NoiseBuilder3D.d.ts

@@ -0,0 +1,18 @@
+import { type NoiseFunction3D } from '../types';
+import { ANoiseBuilder } from './ANoiseBuilder';
+export declare class NoiseBuilder3D extends ANoiseBuilder {
+    /**
+     * Build a 3D noise function
+     * Returns an optimized function with zero runtime dispatch overhead
+     */
+    build3D(): NoiseFunction3D;
+    /**
+     * Build domain warp function for 3D (if enabled)
+     * Returns null if domain warp is disabled
+     */
+    private buildDomainWarp3D;
+    /**
+     * Get type-specific amplitude multiplier for domain warp
+     */
+    private getWarpAmplitudeMultiplier3D;
+}

package/dist/builder/index.d.ts

@@ -0,0 +1,3 @@
+import { NoiseBuilder2D } from './NoiseBuilder2D';
+import { NoiseBuilder3D } from './NoiseBuilder3D';
+export { NoiseBuilder2D, NoiseBuilder3D };

package/dist/core/gradients.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Gradient coordinate helper for 2D noise (Perlin, OpenSimplex2, OpenSimplex2S)
+ */
+export declare function gradCoordR2(seed: number, xPrimed: number, yPrimed: number, xd: number, yd: number): number;
+/**
+ * Gradient coordinate helper for 3D noise (Perlin, OpenSimplex2, OpenSimplex2S)
+ */
+export declare function gradCoordR3(seed: number, xPrimed: number, yPrimed: number, zPrimed: number, xd: number, yd: number, zd: number): number;
+/**
+ * 2D gradient vectors for OpenSimplex2 and Perlin noise
+ */
+export declare const GRADIENTS_2D: Float64Array<ArrayBuffer>;
+/**
+ * 2D random vectors
+ * Used for domain warp and cellular noise
+ */
+export declare const RAND_VECS_2D: Float64Array<ArrayBuffer>;
+/**
+ * 3D gradient vectors
+ * Used for Perlin noise and domain warp
+ * 256 elements (64 gradients * 4 components)
+ */
+export declare const GRADIENTS_3D: Float64Array<ArrayBuffer>;
+/**
+ * 3D random vectors for domain warp
+ */
+export declare const RAND_VECS_3D: Float64Array<ArrayBuffer>;

package/dist/core/hash.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Hash function for 2D coordinates (R2)
+ * Returns a hash value for seeded 2D coordinates
+ */
+export declare function hashR2(seed: number, xPrimed: number, yPrimed: number): number;
+/**
+ * Hash function for 3D coordinates (R3)
+ * Returns a hash value for seeded 3D coordinates
+ */
+export declare function hashR3(seed: number, xPrimed: number, yPrimed: number, zPrimed: number): number;

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export * from './math';
+export * from './hash';
+export * from './gradients';
+export * from './primes';

package/dist/core/math.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Fast floor using bitwise operation
+ * Equivalent to Math.floor for positive numbers, slightly faster
+ */
+export declare function fastFloor(f: number): number;
+/**
+ * Linear interpolation
+ */
+export declare function lerp(a: number, b: number, t: number): number;
+/**
+ * Hermite interpolation (smoothstep)
+ */
+export declare function interpHermite(t: number): number;
+/**
+ * Quintic interpolation (smootherstep)
+ */
+export declare function interpQuintic(t: number): number;
+/**
+ * Cubic interpolation
+ */
+export declare function cubicLerp(a: number, b: number, c: number, d: number, t: number): number;
+/**
+ * Ping pong function for fractal noise
+ */
+export declare function pingPong(t: number): number;

package/dist/core/primes.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Prime numbers used for hashing
+ */
+export declare const PRIME_X = 501125321;
+export declare const PRIME_Y = 1136930381;
+export declare const PRIME_Z = 1720413743;

package/dist/fractal/fbm.d.ts

@@ -0,0 +1,9 @@
+import type { NoiseFunction2D, NoiseFunction3D, FractalContext, TransformFunction3D } from '../types';
+/**
+ * Creates a Fractional Brownian Motion (FBm) 2D modifier
+ */
+export declare function createFBm2D(createBaseNoise: (seed: number) => NoiseFunction2D, ctx: FractalContext): NoiseFunction2D;
+/**
+ * Creates a Fractional Brownian Motion (FBm) 3D modifier
+ */
+export declare function createFBm3D(createBaseNoise: (seed: number) => NoiseFunction3D, transformFunction3d: TransformFunction3D, ctx: FractalContext): NoiseFunction3D;

package/dist/fractal/index.d.ts

@@ -0,0 +1,3 @@
+export * from './fbm';
+export * from './ridged';
+export * from './pingpong';

package/dist/fractal/pingpong.d.ts

@@ -0,0 +1,13 @@
+import type { NoiseFunction2D, NoiseFunction3D, PingPongContext } from '../types';
+/**
+ * Creates a PingPong fractal 2D modifier
+ */
+export declare function createPingPong2D(createBaseNoise: (seed: number) => NoiseFunction2D, ctx: PingPongContext): NoiseFunction2D;
+/**
+ * Creates a PingPong fractal 3D modifier
+ */
+export declare function createPingPong3D(createBaseNoise: (seed: number) => NoiseFunction3D, transformFunction3d: (x: number, y: number, z: number) => {
+    x: number;
+    y: number;
+    z: number;
+}, ctx: PingPongContext): NoiseFunction3D;

package/dist/fractal/ridged.d.ts

@@ -0,0 +1,9 @@
+import type { NoiseFunction2D, NoiseFunction3D, FractalContext, TransformFunction3D } from '../types';
+/**
+ * Creates a Ridged fractal 2D modifier
+ */
+export declare function createRidged2D(createBaseNoise: (seed: number) => NoiseFunction2D, ctx: FractalContext): NoiseFunction2D;
+/**
+ * Creates a Ridged fractal 3D modifier
+ */
+export declare function createRidged3D(createBaseNoise: (seed: number) => NoiseFunction3D, transformFunction3d: TransformFunction3D, ctx: FractalContext): NoiseFunction3D;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { NoiseBuilder2D, NoiseBuilder3D } from './builder';
+export { NoiseType, FractalType, CellularDistanceFunction, CellularReturnType, DomainWarpType, DomainWarpFractalType, RotationType3D, TransformType3D, } from './types/enums';
+export type { NoiseFunction2D, NoiseFunction3D } from './types/common';