first commit

docs/foundation/random/noise/src/perlin/perlin.md

@@ -0,0 +1,50 @@
+# 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.