Initial Commit

packages/foundation/random/noise/src/worley/worley.md

@@ -0,0 +1,49 @@
+# worley/worley
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+The `worley` module implements Steven Worley's cellular noise in 2D and 3D. At every point in space it computes the distance to the nearest (F1) and second-nearest (F2) feature point, where feature points are scattered per-cell according to a seeded PRNG. The resulting fields (F1, F2, F2-F1) give procedural cell structures used for lava rock, cracked surfaces, Voronoi textures, stone patterns, and biological cell walls.
+
+## Features
+
+- `WorleyNoise` class and `worley2` / `worley3` functional APIs
+- `WorleyMode`: `"F1" | "F2" | "F2-F1"`
+- 3×3 (2D) / 3×3×3 (3D) neighbourhood search — the canonical compromise between quality and performance
+- 1..3 feature points per cell, seeded per-cell so different seeds give completely different fields
+
+## Usage: Basic Example
+
+```ts
+import { worley2 } from "@suaveplan/noise";
+
+const distance = worley2("stones", 0.25, 0.75); // F1 default
+```
+
+## Usage: Advanced Example
+
+```ts
+import { WorleyNoise } from "@suaveplan/noise";
+
+const w = new WorleyNoise("cracks");
+for (let y = 0; y < 256; y += 1) {
+  for (let x = 0; x < 256; x += 1) {
+    const edge = w.noise2(x * 0.05, y * 0.05, "F2-F1");
+    // Paint edges where two cells meet equidistantly.
+  }
+}
+```
+
+## API Reference
+
+- `class WorleyNoise(seed: string | number = 0)` — one seeded field
+- `noise2(x, y, mode?): number` — `mode` defaults to `"F1"`
+- `noise3(x, y, z, mode?): number`
+- `worley2(seed, x, y, mode?): number`
+- `worley3(seed, x, y, z, mode?): number`
+
+## Implementation Notes
+
+Feature points are _not_ cached between evaluations; we recreate the per-cell `Sfc32Rng` each time. This keeps the class stateless and thread-safe but makes repeated evaluation at nearby points slightly more expensive. For heavy workloads the simplest optimisation is to cache `featurePoints2/3` results by cell coordinate — feel free to subclass and override those protected methods.