P-E-R-R-Y
Utilitaires, contrats et vendors du moteur, en une seule doc
Loading...
Searching...
No Matches
procedurals

Procedural generation building blocks. More...

Collaboration diagram for procedurals:

Classes

class  PoissonDisk
class  TinyKeepDev
class  WaveFunctionCollapse

Functions

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)

Variables

constexpr double PHI = 1.6180339887498949
 phi, inv_phi, golden_ratio
constexpr double INV_PHI = 1.0 / PHI
constexpr uint64_t UINT64_MAX_CONST = ~0ULL
constexpr double DOUBLE_MAX = static_cast<double>(UINT64_MAX_CONST)
constexpr uint64_t GOLDEN_64 = static_cast<uint64_t>(INV_PHI * DOUBLE_MAX)
constexpr uint64_t MAGIC1 = GOLDEN_64 ^ 0xAAAAAAAAAAAAAAAAULL
 Magic Multipliers.
constexpr uint64_t MAGIC2 = GOLDEN_64 ^ 0x5555555555555555ULL
constexpr uint64_t MAGIC3 = GOLDEN_64 ^ 0x3333333333333333ULL
constexpr uint64_t MAGIC4 = GOLDEN_64 ^ 0xCCCCCCCCCCCCCCCCULL

Detailed Description

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 "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;
uint64_t height = SplitSeed(base, 0);
uint64_t biome = SplitSeed(base, 1);
uint64_t loot = SplitSeed(base, 2);
// 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);
auto delaunay = TinyKeepDev::bowyerWatson(rects);
auto mst = TinyKeepDev::mst(delaunay);
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"
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
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

doxygen Doxyfile

Author

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

Function Documentation

◆ Clamp()

float Clamp ( float x,
float minVal,
float maxVal )
inlinenoexcept

◆ EaseIn()

float EaseIn ( float t)
inlinenoexcept

◆ EaseInOut()

float EaseInOut ( float t)
inlinenoexcept

◆ EaseOut()

float EaseOut ( float t)
inlinenoexcept

◆ 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
xX coordinate (can be fractional)
yY coordinate (can be fractional)
seedOptional 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
Levels
Parameters
v
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

Variable Documentation

◆ DOUBLE_MAX

double DOUBLE_MAX = static_cast<double>(UINT64_MAX_CONST)
constexpr

◆ GOLDEN_64

uint64_t GOLDEN_64 = static_cast<uint64_t>(INV_PHI * DOUBLE_MAX)
constexpr

◆ INV_PHI

double INV_PHI = 1.0 / PHI
constexpr

◆ MAGIC1

uint64_t MAGIC1 = GOLDEN_64 ^ 0xAAAAAAAAAAAAAAAAULL
constexpr

Magic Multipliers.

◆ 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