Synvael/docs/adr/0003-seed-deterministic-worldgen.md

0003. Seed-deterministic worldgen

• Status: Accepted
• Date: 2026-06-27

Context

Procedural world generation must be reproducible: given the same seed, the same world is expected on any platform and at any time. Reproducibility enables shared seeds, reliable bug reproduction, and consistent behaviour between a server and any client that regenerates terrain locally.

Reproducibility is fragile. Sources of nondeterminism include OS-seeded random number generators, the randomised iteration order of the standard hasher, and platform-specific arithmetic.

Decision

Worldgen is seed-deterministic and is held to bit-for-bit reproducibility across platforms.

• A fixed RNG algorithm (e.g. wyrand, xoshiro) is used, seeded only from the world seed. rand::thread_rng() and any OS-seeded source are prohibited in worldgen.
• Iteration order that feeds RNG draws or content placement must be deterministic. The default randomised-hash HashMap iteration order must not be relied upon; use BTreeMap, IndexMap, or an explicit sort.

Consequences

• Worldgen code is constrained in its choice of RNG and collection types, and reviewers must watch for nondeterministic iteration order.
• Identical worlds are guaranteed from identical seeds, on any supported platform.
• This guarantee is scoped to worldgen only; see ADR-0004 for why the rest of the simulation is deliberately not held to the same standard.