perlin/perlin

(no submodules)

Purpose

The perlin module implements Ken Perlin's classic gradient noise in two and three dimensions. Perlin noise is the de-facto standard for procedurally generated terrains, clouds, and texture dithering: it returns a smooth, pseudo-random-looking field in [-1, 1] whose value depends continuously on its coordinates.

This implementation uses the 12-gradient table from Perlin's "Improving Noise" paper (SIGGRAPH 2002), so both 2D and 3D variants share the same gradient space — useful when mixing them in a single shader-like pipeline.

Features

PerlinNoise class — holds a seeded permutation table you can reuse across many noise2/noise3 calls
perlin2(seed, x, y) / perlin3(seed, x, y, z) — one-shot functional convenience
Deterministic per seed; Sfc32Rng-shuffled 256-byte permutation table
2D and 3D outputs in roughly [-1, 1] (theoretical max is √(N/4) per Perlin, in practice values stay well within [-0.86, 0.86] for 2D)

Usage: Basic Example

import { perlin2 } from "@suaveplan/noise";

const v = perlin2("terrain-42", 1.5, 2.3);

Usage: Advanced Example

import { PerlinNoise } from "@suaveplan/noise";

const p = new PerlinNoise("world");
for (let y = 0; y < 256; y += 1) {
  for (let x = 0; x < 256; x += 1) {
    const h = p.noise2(x * 0.05, y * 0.05); // [-1, 1]
    // ...paint tile height...
  }
}

API Reference

class PerlinNoise(seed: string | number = 0) — builds the permutation table once.
noise2(x: number, y: number): number
noise3(x: number, y: number, z: number): number
perlin2(seed, x, y): number / perlin3(seed, x, y, z): number — rebuild the table on every call; prefer PerlinNoise for hot loops.

Implementation Notes

Integer coordinates are masked with & 0xff — the permutation table is of length 512 with the second 256 entries mirroring the first, so perm[(perm[xi] + yi) & 0x1ff] can be written as perm[perm[xi] + yi] without risking out-of-bounds reads. Fractional coordinates run through Perlin's quintic fade (6t^5 - 15t^4 + 10t^3) for C² continuity.

2.1 KiB Raw Blame History