Map generation¶
Responsibility¶
Mapgen turns overmap terrain and regional context into submap contents. It dispatches built-in
or JSON mapgen functions, palettes, nested chunks, parameters, joins, rotations, placements,
and post-processing through mapgendata.
Entry points¶
Start in src/mapgen.h, src/mapgen.cpp, and src/mapgendata.h. JSON implementations derive
from mapgen_function_json_base; primitives and post-processing live in focused modules;
asynchronous orchestration is isolated in mapgen_async.
Data ownership¶
Registries own mapgen definitions and palettes. A mapgendata instance carries one generation
context and writes into a target map; generated terrain, furniture, items, fields, and
vehicles then belong to the produced submaps.
Dependencies¶
Mapgen depends on overmap terrain and specials, region settings, map data registries, RNG, coordinates, JSON loaders, palettes, and validators for spawned entities.
Lifecycle¶
Definitions load and finalize, a request selects an implementation and context, generation places and transforms content, post-processing enforces regional rules, and the finished submaps join normal map persistence.
Invariants¶
Mapgen IDs and nested references resolve; joins and rotations use the intended orientation; coordinates stay inside the target; unique placement rules hold; and a fixed seed reproduces the same contract where determinism is expected.
Extension points¶
Prefer JSON mapgen, palettes, nested mapgen, and parameters. Add a built-in generator only for algorithms data cannot express, register it centrally, and provide seeded tests.
Serialization¶
Mapgen definitions are source data, not save records. mapgen_arguments can serialize where a
deferred request needs persistence; generated submaps persist through normal map saving.
Tests¶
Use function, vehicle placement, post-process, remove-NPC/vehicle, rotation, special, and JSON load tests. Record the seed and inspect every orientation affected.
Performance¶
Generation may run during exploration and can block play. Avoid repeated registry scans and unbounded rejection loops; profile large or nested generators and asynchronous handoff.
CCB divergence¶
CCB's data set and selective worldgen ports define its mapgen behavior. Upstream JSON may rely on loaders, parameters, or post-processing not present here and must be validated, not copied.
Technical debt¶
Built-in and JSON generators share mutable map context but differ in validation. Move common invariants into validators without changing generation output accidentally.