docs: design spatial simulation and worldgen
This commit is contained in:
parent
150be03511
commit
4a8af40dc6
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue