first commit

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

@@ -0,0 +1,49 @@
+# fbm/fbm
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+The `fbm` module composes Fractional Brownian Motion on top of any base noise function. It layers `octaves` copies of the base at geometrically increasing frequencies (`lacunarity`) and geometrically decreasing amplitudes (`gain`), yielding the classical cloud/terrain/texture multi-scale roughness pattern that underlies most procedurally generated content.
+
+Because `fbm2`/`fbm3` take the base function as a parameter, you can layer any of `perlin2`, `simplex2`, `value2`, or even Worley distances on top of fBm — the module has no coupling to a specific noise kind.
+
+## Features
+
+- `fbm2(base, x, y, opts?)` — 2D compositor
+- `fbm3(base, x, y, z, opts?)` — 3D compositor
+- Configurable `octaves`, `lacunarity`, `gain`, `frequency`, `amplitude`
+- Argument validation via `NoiseError.ARG.INVALID` / `FBM.INVALID_OCTAVES`
+
+## Usage: Basic Example
+
+```ts
+import { fbm2, PerlinNoise } from "@suaveplan/noise";
+
+const p = new PerlinNoise("world");
+const h = fbm2((x, y) => p.noise2(x, y), 1.5, 2.3);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { fbm3, SimplexNoise } from "@suaveplan/noise";
+
+const s = new SimplexNoise("clouds");
+const v = fbm3(
+  (x, y, z) => s.noise3(x, y, z),
+  0.1, 0.2, 0.3,
+  { octaves: 6, lacunarity: 2.0, gain: 0.5, frequency: 1, amplitude: 1 },
+);
+```
+
+## API Reference
+
+- `FbmOptions` — every field optional: `octaves` (default 4, must be an integer 1–32), `lacunarity` (default 2), `gain` (default 0.5, must be in (0, 1]), `frequency` (default 1), `amplitude` (default 1).
+- `fbm2(base, x, y, opts?): number`
+- `fbm3(base, x, y, z, opts?): number`
+
+## Implementation Notes
+
+Clamping `octaves` to 1–32 avoids pathological input (negative or absurdly large numbers of loop iterations). `gain > 1` would diverge rather than converge, so it's rejected; `gain` exactly 1 means every octave contributes equally, which is useful for certain stylised effects but rejected here to keep the numeric output bounded — if you need that, call the base function manually in a loop.