6.1 KiB
Simulation, world generation, and map design
This design connects four related capabilities: spatial event diffusion, character travel, visual maps, and data-driven fuzz/world generation. They share coordinates and topology but remain separate library modules so testing, simulation, and rendering do not become one irreversible command.
Delivery order
- Deterministic world generation. Add a versioned configuration, embedded defaults, external overrides, seeded generation from one event through a complete world, validation, previews, and explicit worktree application.
- Road and mobility topology. Add stable road edges between positioned places. Characters are either resident at a place or travelling. A route uses roads when available and can fall back to slower straight-line travel.
- Event diffusion. Each tick derives an event frontier from its origin, reach, speed, remaining duration, and configured terrain/road multipliers. Roads accelerate diffusion; direct spatial diffusion remains possible and slower. A seeded tick must be reproducible and previewable before commit.
- PNG rendering. Render roads, places, characters, events, and diffusion fronts onto an optional user-supplied PNG. Without a base image, create a configured blank canvas. Rendering is read-only and writes to a named output path atomically.
World-generation configuration
The canonical default lives at lib_efo/assets/worldgen/default.json and is
compiled into lib_efo. This guarantees that tests and installed binaries work
offline. --config PATH loads an editable replacement; configuration errors
name the JSON path and never silently fall back to defaults.
The configuration owns generation ranges, name/template pools, map dimensions, road density, mobility ratios, and simulation coefficients. It has its own schema version, separate from repository format and application version. Unknown future fields should be retained or rejected deliberately once custom metadata lands; they must never be silently misinterpreted.
Generation levels are cumulative:
event: one positioned event;settlement: a town, residents, and local events;region: several connected settlements, roads, organisations, and events;world: the complete configured population and topology.
Every generation accepts and prints a u64 seed. The same binary,
configuration bytes, level, and seed must produce byte-equivalent semantic
world state. Generated UUIDs come from the seeded generator rather than the OS.
Preview is the default; --apply replaces only the worktree through the normal
transaction layer. Staging and committing remain separate user decisions.
Spatial model
Places and events have Cartesian positions. A road is an undirected edge with a stable ID, two place IDs, distance/cost, and optional tags. Duplicate, self-referential, dangling, and non-place edges are invalid.
A character has an explicit mobility state:
Resident { place }is tied to a positioned place;Roaming { position }can travel directly;Travelling { from, to, progress, route }records recoverable progress.
Route selection minimizes configured travel time. Road segments use their speed multiplier; a direct fallback uses Euclidean distance and the slower off-road speed. Simulation stores intent/progress, not transient pathfinder caches, so old state remains interpretable.
Event diffusion uses the same weighted graph plus direct distance. It records which entities/places have already been affected to avoid accidental repeated application. Preview output explains why a target is reached and which route or direct distance was used.
Spatial arrival is implemented. Influx-aware outcomes, protection, character targeting, and fight/war share the follow-on contract in Influx, diffusion resolution, and conflict.
Map rendering
The repository may reference a base map path plus coordinate bounds, but never
embeds arbitrary image bytes into snapshots. efo map render --base map.png --output world.png overrides the configured base. With no base, the renderer
creates a blank RGBA canvas using configured dimensions and background colour.
Essential meaning must not depend on colour: markers differ by shape and have optional labels. Roads and diffusion fronts use distinct line patterns. The renderer validates coordinate bounds and image limits before allocation and writes to a temporary sibling before rename.
Packaging and releases
Embedded defaults are authoritative for a binary. Tagged releases may also
attach epoch-forge-worldgen-config-vX.Y.zip containing the editable JSON,
schema notes, and checksum. Runtime fetching is opt-in only; local embedded
operation remains the default.
The public Gitea API exposes release asset uploads at
/api/v1/repos/idle-org/epoch_forge/releases/{id}/assets. The existing
v0.1.0 release already has binary assets and SHA256SUMS, so the config zip
can follow that mechanism once the Jenkins credential ID used by the release
job is known. Routine CI must validate/package the config but must not publish
or run release-only badge tooling.
The repository provides scripts/package-worldgen-config.sh VERSION and
scripts/package-simulation-config.sh VERSION; both create reproducible
archives from embedded defaults. The explicit
scripts/upload-worldgen-config.sh TAG ZIP helper can upload either archive.
It requires GITEA_TOKEN; Jenkins should bind its existing release credential
to that environment variable only inside a tag-release stage. It is never
invoked by the routine Jenkinsfile.
Safety and test gates
- Property tests generate many seeds and validate IDs, links, bounds, roads, and deterministic replay; failures print the seed and config checksum.
- Fuzz targets parse configurations and exercise generation, route finding, diffusion, and rendering with strict size limits.
- Simulation and generation never write unless explicitly applied.
- Applying generated state uses the workspace transaction and is reversible
with
efo restore --worktree --alluntil staged. - PNG rendering cannot mutate repository state or overwrite input maps.