109 lines
5.4 KiB
Markdown
109 lines
5.4 KiB
Markdown
# 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.
|
|
|
|
## 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.
|