# perlin/perlin

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

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

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

## Usage: Advanced Example

```ts
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.