Repository navigation
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
Repository files navigation
RLK
---
Minimal C99 library for 2D grid-based games and roguelikes.
Build:
make # Build librlk.a
make lint # Static analysis (-Werror): lib + test/ + demo/
make test # Build + run all tests: unit (test/) + demo harnesses (demo/)
make demo # Compile+link the demos (PXL viewer only when PXL_DIR is set)
make check # Full validation: lint + test
make dist # Vendoring snapshot: rlk-<commit>.tar.gz
make clean # Remove build artifacts
Note: the Makefiles use BSD make. On Linux, use `bmake` or `pmake`
instead of GNU make.
Configuration:
Main configuration is defined in Makefile.inc. Copy config.mk.example to
config.mk to customize CFLAGS, PXL_DIR or library paths. PXL_DIR is unset
by default: without it, `make demo` builds only the standalone text demos;
set it to a pxl checkout (e.g. PXL_DIR = ../../pxl) to also build the PXL
viewer demo_viewer, with PXL_BACKEND = x11 (default) or sdl.
Vendoring:
rlk is meant to be vendored as-is: flat sources, no generated files, no
config header. Build a clean snapshot and drop it into your project:
bmake dist # -> rlk-<commit>.tar.gz
mkdir -p vendor/rlk
tar -xzf rlk-<commit>.tar.gz -C vendor/rlk --strip-components=1
Then either compile the sources directly in your own build system:
cc -std=c99 -Ivendor/rlk -c vendor/rlk/*.c
or build the static library with bmake: 'bmake -C vendor/rlk', link with
-lrlk -lm. Note: Makefile.inc is bmake syntax; with another build system,
pass -Ivendor/rlk and -ffp-contract=off (determinism contract) yourself.
Keep LICENSE inside vendor/rlk and record the upstream commit there
(e.g. in vendor/rlk/VENDORED-AT) so updates stay traceable.
When vendoring several flat C libraries side by side (rlk and pxl both
ship err.h/geom.h), use a single include root and prefixed paths:
cc -Ivendor ... with #include "rlk/rlk.h" /* never bare "err.h" */
Quoted includes inside a header resolve in its own directory first, so
umbrella headers stay unambiguous regardless of -I order.
Design:
- Zero allocation: the lib never calls malloc/free; all buffers are
caller-owned (doc/architecture.md, "Memory model").
- Determinism: same seed + same build -> identical world, byte for byte
(build flags enforced in Makefile.inc).
Documentation:
doc/architecture.md # Zones (base / domains / user land), memory model,
# determinism contract, recipes
doc/conventions.md # Naming rules
doc/stats.md # Map quality stats: what each probe measures, golden
# policy, multi-seed report (demo/test_tilemap_gen)
Headers:
rlk.h # Umbrella header (includes all of the below)
Base — core:
err.h # Error codes (RLK_OK, RLK_E_INVALID, RLK_E_NOTFOUND)
hash.h # Deterministic 64-bit hashing
fmath.h # Math helpers (clamp, lerp, smoothstep, distances)
noise.h # Noise generation (value, perlin, fbm)
Base — data (POD, caller-owned):
entity.h # Generic entities: fixed-capacity list (push/get/move)
geom.h # Rect (region) + lattice (grid geometry on world)
grid.h # Coarse float grid with bilinear sampling
mask.h # Uint8 mask (weight, density, visibility) + constructors
# + 4-connected flood fill / component labelling (rlk_mask_flood, rlk_mask_components)
poi.h # Points of Interest (anchor, bbox, type, seed)
scatter.h # Stateless jittered-grid scatter (one point per cell)
stats.h # Deterministic map stats (entropy, edge/pair entropy,
# Moran's I, LZSS bits, patches) on caller-owned rasters
tilemap.h # Tile grid over a world rect + tile props + index/line drawing
Domain terrain:
slope.h # Slope from an elevation grid (Horn 3x3)
drain.h # Drainage: fill, D8 flow, accumulation, river SDF
hydro.h # Derived hydrology: slope, Strahler order, speed
Domain nav:
path.h # A* pathfinding (integer costs, lattice window) +
# rlk_path_snap (nearest enterable cell, ring scan)
path_distance.h # Multi-source distance field (flow field, nearest source)
Domain vision:
fov.h # Field of view (recursive shadowcasting)
Domain worldgen — pipeline (wg):
wg.h # Noise-field terrain generation engine
wg_region.h # Voronoi region (macro-area) stage
wg_drain.h # Drain reading stage
wg_hydro.h # Hydro reading stage
wg_relief.h # Standardised elevation stage
wg_rivers.h # River projection stage
wg_poi.h # POI detection stage
Domain worldgen — structure generators:
ca.h # Cellular Automata (caves)
bsp.h # Binary Space Partitioning (dungeons)
Chunked persistent world (on top of the wg pipeline):
world.h # rlk_world_t: macro field query without fine generation,
# on-demand chunks (seam-coherent), tile diffs applied on
# regeneration, save/load (seed + diffs), predicate search
Demos (demo/ is flat like the lib; prefixes mark generic vs demo-only blocks):
demo/demo_viewer.c # PXL viewer: demo_viewer [world|ca|bsp] [seed]
# (world mode: stage probes + river/POI/A* overlays)
demo/demo_world.c # Fantasy map in a terminal: tilemap_gen + ca/bsp per POI,
# scatter points, ASCII render, rlk_stats_* probes
demo/demo_gis.c # GIS raster export .asc/.pgm for external tools (QGIS/GDAL)
demo/test_tilemap_gen.c # Golden map stats per seed, run by `make check`
demo/tilemap_gen.* gen_* # Fantasy map generator package
demo/src_*.h gis_export.h # Viewer demo sources + GIS export helpers
demo/source.h viewer.h viewer_app.h widget.h font_6x10.h
# Generic PXL viewer harness (header-only)
License:
MIT. See LICENSE.