Overmap¶
Responsibility¶
overmap stores one large-scale world region: overmap terrain, cities, roads and connections,
special placements, monster groups, NPC/camp references, notes, visibility, and regional world
generation state. overmapbuffer coordinates regions.
Entry points¶
Read src/overmap.h and focused overmap_*.cpp files. Region retrieval and cross-boundary
queries enter through overmapbuffer; overmap::save, serialize, and unserialize define
the persistence boundary.
Data ownership¶
An overmap owns regional terrain layers and deferred world-scale records. The buffer owns or caches loaded overmap objects. A loaded reality-bubble monster is not the same ownership form as an overmap monster-group entry.
Dependencies¶
Overmap depends on absolute overmap coordinates, terrain/special/connection registries, regional settings, mapgen placement, monster groups, cities, weather, NPCs, and world storage.
Lifecycle¶
A region is generated or loaded, linked to neighboring regions, queried and updated while the world runs, then serialized and evicted according to buffer policy.
Invariants¶
Absolute coordinates identify the correct region and local cell; connections agree at region borders; unique specials obey placement state; and loaded/unloaded creature transitions do not duplicate population.
Extension points¶
Prefer JSON overmap terrain, specials, locations, and connections. Native generation belongs in a focused module with deterministic placement tests and explicit neighboring-region behavior.
Serialization¶
src/savegame.cpp persists terrain layers, groups, NPC/camp data, notes, and global overmap
state. Caches and generated summaries are rebuildable; new durable fields need old-save defaults.
Tests¶
Use overmap, noise, connection, cache, special-placement, and worldfactory tests. Generation regressions must report a seed and test region boundaries.
Performance¶
World travel and generation can touch many regions. Avoid forcing loads for read-only queries, and keep map-data summaries and route searches bounded.
CCB divergence¶
CCB's overmap generation and POI handling have project-specific fixes and selective upstream ports. Validate deletion, placement, and persistence against current CCB tests and data.
Technical debt¶
Generation, runtime queries, UI data, and persistence still meet in a broad regional object. Preserve buffer ownership and split work by responsibility rather than adding global scans.