From 4a8af40dc6faddd4eef8c10ab9da763aa5c793a7 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Mon, 21 Sep 2026 02:12:52 +0200 Subject: [PATCH] docs: design spatial simulation and worldgen --- AGENTS-TASKS.md | 53 ++++++++++++++ docs/README.md | 2 + docs/roadmap.md | 5 ++ docs/simulation-worldgen-design.md | 108 +++++++++++++++++++++++++++++ 4 files changed, 168 insertions(+) create mode 100644 docs/simulation-worldgen-design.md diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index d107fad..6fcb9bf 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -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: diff --git a/docs/README.md b/docs/README.md index 70918d2..9602bc2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/roadmap.md b/docs/roadmap.md index 920fd2a..41e11b4 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -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. diff --git a/docs/simulation-worldgen-design.md b/docs/simulation-worldgen-design.md new file mode 100644 index 0000000..8dcf75e --- /dev/null +++ b/docs/simulation-worldgen-design.md @@ -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.