Procedural generation building blocks.
More...
|
| uint64_t | mix64 (uint64_t x) noexcept |
| float | normaliseHash (uint64_t x) noexcept |
| float | random0D (uint64_t seed=0) noexcept |
| float | random1D (int x, uint64_t seed=0) noexcept |
| float | random2D (int x, int y, uint64_t seed=0) noexcept |
| float | random3D (int x, int y, int z, uint64_t seed=0) noexcept |
| float | random4D (int x, int y, int z, int w, uint64_t seed=0) noexcept |
| uint64_t | SplitSeed (uint64_t seed, uint64_t channel) noexcept |
| float | noise2D (float x, float y, uint64_t seed=0) noexcept |
| | 2D deterministic value noise in [-1, 1].
|
| float | fbm2D (float x, float y, int octaves=5, uint64_t seed=0, float gain=0.5f, float lacunarity=2.0f) noexcept |
| | Fractal Brownian Motion (fBm).
|
| float | warp2D (float x, float y, uint64_t seed=0, float strength=2.0f) noexcept |
| float | ridge2D (float x, float y, int octaves=5, float gain=0.5f, float lacunarity=2.0f, uint64_t seed=0) noexcept |
| | Ridged Fractal Noise (inverted fBm).
|
| float | rarity2D (float x, float y, float rarity=0.01f, uint64_t seed=0) |
| float | worley2D (float x, float y, uint64_t seed=0) noexcept |
| void | initPerm (uint8_t *perm, uint64_t seed) |
| float | grad (int hash, float x, float y) |
| float | simplex2D (float xin, float yin, uint64_t seed=0) |
| float | Lerp (float a, float b, float t) noexcept |
| float | Clamp (float x, float minVal, float maxVal) noexcept |
| float | EaseIn (float t) noexcept |
| float | EaseOut (float t) noexcept |
| float | EaseInOut (float t) noexcept |
| float | InterpolateEaseInOut (float a, float b, float t) noexcept |
| template<int Levels = 10> |
| float | Quantize (float v) |
| | Quantize a float value into discrete levels, useful for stylized effects.
|
| void | visualizer2D (const std::string &filename, int width, int height, float scale, const std::function< float(float, float)> &noiseFunc) |
| void | visualizer2D (const std::string &filename, const std::vector< std::vector< float > > &map) |
Procedural generation building blocks.
Noise, Poisson disk sampling, smoothing, and a TinyKeep-style dungeon generator. Deterministic : same seed, same output.
procedurals
A deterministic, header-mostly C++20 library for procedural generation — noise, sampling, rule systems, and dungeon/world primitives.
Same input + seed → same output. No global RNG, no <random> dependency.
| fBm + ridge + warp | TinyKeep dungeon | Wave Function Collapse |
| | |
Features
- Hash-based deterministic PRNG (random0D/1D/2D/3D/4D)
- Value noise, fBm, ridge, domain warp, Worley, Simplex
- Easing / quantize / rarity helpers
- Poisson-disk sampling (Bridson)
- Wave Function Collapse with user-defined adjacency rules
- BSP dungeons, drunkard walk, cellular automata
- TinyKeep room layout: scatter → relax → Delaunay → MST + loopback
- PPM visualizer for quick debug renders
Build & test
Requirements: a C++20 compiler, CMake ≥ 3.14, GoogleTest discoverable by find_package (the cmake/ folder provides finders for System, Maths, and GoogleTest).
cmake -S . -B build
cmake --build build -j
ctest --test-dir build --output-on-failure
This produces build/libprocedurals.a and build/procedurals_tests. The tests dump .ppm images into the working directory — open them with Preview (macOS), GIMP, feh, or any PPM-capable viewer.
Use in your own project
Via FetchContent
include(FetchContent)
FetchContent_Declare(procedurals
GIT_REPOSITORY https://github.com/p-e-r-r-y/procedurals.git
GIT_TAG main)
FetchContent_MakeAvailable(procedurals)
target_link_libraries(my_app PRIVATE procedurals)
Via submodule
git submodule add https://github.com/p-e-r-r-y/procedurals.git third_party/procedurals
add_subdirectory(third_party/procedurals)
target_link_libraries(my_app PRIVATE procedurals)
Then include whichever headers you need:
#include "PoissonDisk.hpp"
Tile-based WFC, best-effort. Always returns a grid. On contradiction, the offending constraint is ski...
What's in the box
| Header | Provides |
| Deterministic.hpp | random0D/1D/2D/3D/4D, mix64, SplitSeed |
| Smoothing.hpp | Lerp, Clamp, EaseIn/Out/InOut, Quantize, RareEvent |
| Noise.hpp | noise2D, fbm2D, ridge2D, warp2D, worley2D, simplex2D, rarity2D |
| Visualizer.hpp | visualizer2D(...) PPM writers (callback, grid, points) |
| TinyKeepDev.hpp | Room scatter + relax + Bowyer-Watson Delaunay + mst() + mstWithLoopback() |
| PoissonDisk.hpp | Bridson's algorithm — evenly-spaced point sets |
| WaveFunctionCollapse.hpp | Tile-based WFC with user-defined adjacency rules |
Examples
Deterministic random per coordinate
float random2D(int x, int y, uint64_t seed=0) noexcept
Definition Deterministic.hpp:67
2D noise and fBm
float n =
noise2D(x * 0.05f, y * 0.05f, seed);
float h =
fbm2D (x * 0.01f, y * 0.01f, 5, seed);
float noise2D(float x, float y, uint64_t seed=0) noexcept
2D deterministic value noise in [-1, 1].
Definition Noise.hpp:31
float fbm2D(float x, float y, int octaves=5, uint64_t seed=0, float gain=0.5f, float lacunarity=2.0f) noexcept
Fractal Brownian Motion (fBm).
Definition Noise.hpp:54
| noise2D | fbm2D |
| |
Layered terrain
visualizer2D(
"terrain.ppm", 512, 512, 50.0f, [](
float x,
float y) {
float terrain =
fbm2D(x, y, 5);
float warped =
warp2D(x, y, 1, 2.0f);
});
float warp2D(float x, float y, uint64_t seed=0, float strength=2.0f) noexcept
Definition Noise.hpp:68
void visualizer2D(const std::string &filename, int width, int height, float scale, const std::function< float(float, float)> &noiseFunc)
Definition Visualizer.hpp:20
float Quantize(float v)
Quantize a float value into discrete levels, useful for stylized effects.
Definition Smoothing.hpp:49

Splitting a seed into independent channels
uint64_t base = 12345;
uint64_t SplitSeed(uint64_t seed, uint64_t channel) noexcept
Definition Deterministic.hpp:91
TinyKeep-style dungeon (full pipeline)
static std::vector< Linef > bowyerWatson(const std::vector< Rectf > &rects)
Definition TinyKeepDev.hpp:166
static std::vector< Rectf > generateRects(float radius, float maxRectRatio=0.5, std::pair< float, float > radiusRatios={0.1f, 1.f}, uint64_t seed=0)
Definition TinyKeepDev.hpp:75
static std::vector< Linef > mst(const std::vector< Linef > &edges)
Definition TinyKeepDev.hpp:297
static void relaxRects(std::vector< Rectf > &rects)
Definition TinyKeepDev.hpp:125
| 1. Scatter | 2. Relax | 3. Delaunay | 4. MST |
| | | |
Poisson disk sampling
#include "PoissonDisk.hpp"
10.0f,
10, 123);
static std::vector< Vector2f > generate(float width, float height, float r, int k=30, uint64_t seed=42)
Generate points evenly spaced by at least r, inside a width x height area.
Definition PoissonDiskSampling.hpp:29

Wave Function Collapse
{0, 1},
{0, 1, 2},
{1, 2, 3},
{2, 3}
}};
static std::vector< std::vector< int > > collapse(int width, int height, const Rules &rules, uint64_t seed=0)
Generate a width x height tile map. Best-effort: returns a complete grid even if a few adjacencies en...
Definition WaveFunctionCollapse.hpp:34
User-defined adjacency rules. Tile IDs are indices 0..neighbors.size()-1. neighbors[t] = list of tile...
Definition WaveFunctionCollapse.hpp:24

BSP dungeon
The tests/TestBSP.cpp showcase recursively splits a rectangle and connects room centers with corridors:

More patterns
| Domain warp | Simplex | Rarity |
| | |
Project layout
procedurals/
├── includes/ public headers (the actual library)
├── sources/ placeholder TU so CMake has something to compile
├── tests/ GoogleTest cases + PPM visualizers
├── cmake/ Find modules (GoogleTest,
System, Maths)
├── docs/ Doxyfile, roadmap, preview/ images
└── CMakeLists.txt
Abstract base class representing a system in the ECS architecture.
Design principles
- Deterministic. Output is a pure function of (coords…, seed).
- Header-mostly. Algorithms live in the headers; libprocedurals.a exists so CMake has a target to link.
- No global state. No srand, no <random>, no thread-local RNG.
- Composable. Functions take coordinates, return floats — chain them.
- Domain-agnostic. No assumptions about tiles, rooms, biomes, or game objects.
See Roadmap.md for planned phases.
Generating Doxygen docs
Author
Perry Chouteau — perry.nosp@m..cho.nosp@m.uteau.nosp@m.@out.nosp@m.look..nosp@m.com
◆ Clamp()
| float Clamp |
( |
float | x, |
|
|
float | minVal, |
|
|
float | maxVal ) |
|
inlinenoexcept |
◆ EaseIn()
◆ EaseInOut()
| float EaseInOut |
( |
float | t | ) |
|
|
inlinenoexcept |
◆ EaseOut()
◆ fbm2D()
| float fbm2D |
( |
float | x, |
|
|
float | y, |
|
|
int | octaves = 5, |
|
|
uint64_t | seed = 0, |
|
|
float | gain = 0.5f, |
|
|
float | lacunarity = 2.0f ) |
|
inlinenoexcept |
Fractal Brownian Motion (fBm).
Adds multiple octaves of noise to create fractal-like complexity. Each octave increases frequency and decreases amplitude.
◆ grad()
| float grad |
( |
int | hash, |
|
|
float | x, |
|
|
float | y ) |
|
inline |
◆ initPerm()
| void initPerm |
( |
uint8_t * | perm, |
|
|
uint64_t | seed ) |
|
inline |
◆ InterpolateEaseInOut()
| float InterpolateEaseInOut |
( |
float | a, |
|
|
float | b, |
|
|
float | t ) |
|
inlinenoexcept |
◆ Lerp()
| float Lerp |
( |
float | a, |
|
|
float | b, |
|
|
float | t ) |
|
inlinenoexcept |
◆ mix64()
| uint64_t mix64 |
( |
uint64_t | x | ) |
|
|
inlinenoexcept |
◆ noise2D()
| float noise2D |
( |
float | x, |
|
|
float | y, |
|
|
uint64_t | seed = 0 ) |
|
noexcept |
2D deterministic value noise in [-1, 1].
Computes smooth pseudo-random noise from (x, y) and an optional seed. Values at the four surrounding grid points are hashed and smoothly interpolated using an ease-in-out curve.
- Parameters
-
| x | X coordinate (can be fractional) |
| y | Y coordinate (can be fractional) |
| seed | Optional seed for reproducibility |
- Returns
- float Noise value in [-1, 1]
◆ normaliseHash()
| float normaliseHash |
( |
uint64_t | x | ) |
|
|
inlinenoexcept |
◆ Quantize()
template<int Levels = 10>
| float Quantize |
( |
float | v | ) |
|
|
inline |
Quantize a float value into discrete levels, useful for stylized effects.
- Template Parameters
-
- Parameters
-
- Returns
- float
◆ random0D()
| float random0D |
( |
uint64_t | seed = 0 | ) |
|
|
inlinenoexcept |
◆ random1D()
| float random1D |
( |
int | x, |
|
|
uint64_t | seed = 0 ) |
|
inlinenoexcept |
◆ random2D()
| float random2D |
( |
int | x, |
|
|
int | y, |
|
|
uint64_t | seed = 0 ) |
|
inlinenoexcept |
◆ random3D()
| float random3D |
( |
int | x, |
|
|
int | y, |
|
|
int | z, |
|
|
uint64_t | seed = 0 ) |
|
inlinenoexcept |
◆ random4D()
| float random4D |
( |
int | x, |
|
|
int | y, |
|
|
int | z, |
|
|
int | w, |
|
|
uint64_t | seed = 0 ) |
|
inlinenoexcept |
◆ rarity2D()
| float rarity2D |
( |
float | x, |
|
|
float | y, |
|
|
float | rarity = 0.01f, |
|
|
uint64_t | seed = 0 ) |
|
inline |
◆ ridge2D()
| float ridge2D |
( |
float | x, |
|
|
float | y, |
|
|
int | octaves = 5, |
|
|
float | gain = 0.5f, |
|
|
float | lacunarity = 2.0f, |
|
|
uint64_t | seed = 0 ) |
|
inlinenoexcept |
Ridged Fractal Noise (inverted fBm).
Turns smooth valleys into sharp ridges and peaks. Useful for mountain heightmaps or cracked stone surfaces.
◆ simplex2D()
| float simplex2D |
( |
float | xin, |
|
|
float | yin, |
|
|
uint64_t | seed = 0 ) |
|
inline |
◆ SplitSeed()
| uint64_t SplitSeed |
( |
uint64_t | seed, |
|
|
uint64_t | channel ) |
|
inlinenoexcept |
◆ visualizer2D() [1/2]
| void visualizer2D |
( |
const std::string & | filename, |
|
|
const std::vector< std::vector< float > > & | map ) |
|
inline |
◆ visualizer2D() [2/2]
| void visualizer2D |
( |
const std::string & | filename, |
|
|
int | width, |
|
|
int | height, |
|
|
float | scale, |
|
|
const std::function< float(float, float)> & | noiseFunc ) |
|
inline |
◆ warp2D()
| float warp2D |
( |
float | x, |
|
|
float | y, |
|
|
uint64_t | seed = 0, |
|
|
float | strength = 2.0f ) |
|
inlinenoexcept |
◆ worley2D()
| float worley2D |
( |
float | x, |
|
|
float | y, |
|
|
uint64_t | seed = 0 ) |
|
inlinenoexcept |
◆ DOUBLE_MAX
◆ GOLDEN_64
◆ INV_PHI
| double INV_PHI = 1.0 / PHI |
|
constexpr |
◆ MAGIC1
| uint64_t MAGIC1 = GOLDEN_64 ^ 0xAAAAAAAAAAAAAAAAULL |
|
constexpr |
◆ MAGIC2
| uint64_t MAGIC2 = GOLDEN_64 ^ 0x5555555555555555ULL |
|
constexpr |
◆ MAGIC3
| uint64_t MAGIC3 = GOLDEN_64 ^ 0x3333333333333333ULL |
|
constexpr |
◆ MAGIC4
| uint64_t MAGIC4 = GOLDEN_64 ^ 0xCCCCCCCCCCCCCCCCULL |
|
constexpr |
◆ PHI
| double PHI = 1.6180339887498949 |
|
constexpr |
phi, inv_phi, golden_ratio
◆ UINT64_MAX_CONST
| uint64_t UINT64_MAX_CONST = ~0ULL |
|
constexpr |