epoch_forge/docs/simulation-worldgen-design.md

5.8 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.

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 an explicit scripts/upload-worldgen-config.sh TAG ZIP. The upload helper 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 --all until staged.
  • PNG rendering cannot mutate repository state or overwrite input maps.