docs: design spatial simulation and worldgen

This commit is contained in:
Dandaedre 2026-09-21 02:12:52 +02:00
parent 150be03511
commit 4a8af40dc6
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 168 additions and 0 deletions

View File

@ -29,6 +29,10 @@ prototype reader, migration command, fixtures, and compatibility aliases are
removed. Future evolution uses explicit `1.x` major/minor versions. Default
and portable quality and release gates passed on 2026-09-21.
**Milestone 7 — deterministic worldgen foundation: planned.** The spatial,
fuzzing, configuration, rendering, and release-asset contract is approved in
[`docs/simulation-worldgen-design.md`](docs/simulation-worldgen-design.md).
## Phase 0 — audit and guardrails
- [x] Inventory workspace crates, commands, persistence files, CI, and tests.
@ -149,6 +153,55 @@ and portable quality and release gates passed on 2026-09-21.
- [x] Pass default and portable formatting, test, strict Clippy, and release
gates without running release-only badge tooling.
## Simulation and generation track
### Checkpoint 1 — deterministic configuration-driven worldgen
- [x] Define cumulative event/settlement/region/world generation levels.
- [x] Choose embedded defaults plus explicit local `--config` overrides.
- [x] Define seeded reproducibility, preview/apply behavior, and restoration.
- [ ] Add a versioned `WorldGenConfig` with strict semantic validation.
- [ ] Move canonical defaults to `lib_efo/assets/worldgen/default.json` and
embed them in the library.
- [ ] Generate deterministic IDs, positions, names, events, and entity counts
from a caller-supplied seed without thread-local randomness.
- [ ] Add `efo gen world --level ... --seed ... [--config ...] [--apply]` with
preview as the default and worktree-only application.
- [ ] Add seed-replay, invalid-config, invariant, and CLI reversal tests.
- [ ] Package the editable config and schema notes as a reproducible zip;
document the Gitea release upload endpoint without publishing in routine CI.
### Checkpoint 2 — roads, residency, and travel
- [ ] Add stable, validated road edges between positioned place entities.
- [ ] Model resident, roaming, and travelling character states without
overloading governance links.
- [ ] Implement deterministic shortest-time routing with road speed and slower
direct-travel fallback.
- [ ] Preview travel plans and advance progress only through staged simulation
ticks with clear restore/revert guidance.
- [ ] Fuzz disconnected, cyclic, duplicate, and malformed topology.
### Checkpoint 3 — spatial event diffusion
- [ ] Define event origins, speed, frontier, affected-set, and expiry data.
- [ ] Diffuse over roads and slower direct distance using configured
coefficients and deterministic tie-breaking.
- [ ] Preview each tick with route/reason output before applying it.
- [ ] Test repeated application, convergence, expiry, disconnected graphs, and
deterministic replay across many seeds.
### Checkpoint 4 — PNG map rendering
- [ ] Store optional base-map path and coordinate bounds without embedding
image bytes in repository history.
- [ ] Render entities, roads, travellers, events, and diffusion fronts onto a
supplied PNG or a generated blank RGBA canvas.
- [ ] Use shape and labels as well as colour, enforce allocation limits, and
atomically write a distinct output path.
- [ ] Add pixel/snapshot fixtures for blank and supplied-base rendering.
- [ ] Add `efo map render` help, examples, and recovery-safe error messages.
## Stretch goals — proposal only
These require user approval and are not part of the current implementation:

View File

@ -11,6 +11,8 @@ behavior clearly.
and migration contract.
- [TUI design](tui-design.md): approved first-pass scope, interaction, safety,
and accessibility contract.
- [Simulation and world generation](simulation-worldgen-design.md): seeded
fuzzing, roads, movement, diffusion, map rendering, and config packaging.
- [Roadmap](roadmap.md): current work and stretch proposals.
Start with the project [README](../README.md). Contributors should also read

View File

@ -35,6 +35,11 @@ read-only `efo-tui` binary browses repository status and entities through the
same library API. Interactive mutations remain a later, separately reviewed
checkpoint.
The next implementation track is the [simulation and world-generation
design](simulation-worldgen-design.md). Its first checkpoint is deterministic,
configuration-driven generation; road topology, event diffusion, and PNG
rendering build on that validated foundation.
## Proposed stretch goals
1. Shell completions and generated man pages.

View File

@ -0,0 +1,108 @@
# 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.