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

npm install fastnoiselite-builder

Usage

Basic 2D Noise

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

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

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

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

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.

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

# 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
• JavaScript port: snowfoxsh
• TypeScript implementation: Sébastien Vincent