procedurals
Procedural generation building blocks
Loading...
Searching...
No Matches
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 "Noise.hpp"
#include "TinyKeepDev.hpp"
#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 v = random2D(x, y, /*seed=*/42); // in [0, 1], stable per (x, y, seed)
float random2D(int x, int y, uint64_t seed=0) noexcept
Definition Deterministic.hpp:67

2D noise and fBm

#include "Noise.hpp"
float n = noise2D(x * 0.05f, y * 0.05f, seed);
float h = fbm2D (x * 0.01f, y * 0.01f, /*octaves=*/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);
return Quantize<3>(terrain * 0.5f + warped * 0.5f);
});
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;
// each channel is independent but reproducible from base
uint64_t SplitSeed(uint64_t seed, uint64_t channel) noexcept
Definition Deterministic.hpp:91

TinyKeep-style dungeon (full pipeline)

#include "TinyKeepDev.hpp"
auto rects = TinyKeepDev::generateRects<50>(200.0f, 0.5f, {0.25f, 0.75f}, 42);
TinyKeepDev::relaxRects<100>(rects);
static std::vector< Linef > bowyerWatson(const std::vector< Rectf > &rects)
Definition TinyKeepDev.hpp:166
static std::vector< Linef > mst(const std::vector< Linef > &edges)
Definition TinyKeepDev.hpp:297
1. Scatter 2. Relax 3. Delaunay 4. MST

Poisson disk sampling

#include "PoissonDisk.hpp"
auto points = PoissonDisk::generate(/*W=*/200, /*H=*/200,
/*minDist=*/10.0f,
/*k=*/10, /*seed=*/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}, // tile 0 next to: 0, 1
{0, 1, 2}, // tile 1 next to: 0, 1, 2
{1, 2, 3}, // tile 2 next to: 1, 2, 3
{2, 3} // tile 3 next to: 2, 3
}};
auto grid = WaveFunctionCollapse::collapse(64, 64, rules, /*seed=*/0);
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

Worley Inv. Worley Ridge
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

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

doxygen Doxyfile

Author

Perry Chouteau — perry.nosp@m..cho.nosp@m.uteau.nosp@m.@out.nosp@m.look..nosp@m.com