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

0003. Seed-deterministic worldgen

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

Context

Procedural world generation has to be reproducible. Given the exact same seed, we expect the exact same world to generate on any platform and at any time. Reproducibility lets players share seeds, helps us reliably reproduce bugs, and ensures consistent behavior between a server and any client that tries to regenerate terrain locally.

Unfortunately, reproducibility is incredibly fragile. Common sources of nondeterminism include OS-seeded random number generators, the randomized iteration order of Rust's standard hasher, and platform-specific floating-point arithmetic.

Decision

Worldgen is strictly seed-deterministic and we hold it to a standard of bit-for-bit reproducibility across all supported platforms.

• We must use a fixed RNG algorithm (like wyrand or xoshiro) that is seeded only from the world seed. Using rand::thread_rng() or any other OS-seeded source is strictly prohibited anywhere in worldgen.
• Any iteration order that feeds into RNG draws or content placement must be completely deterministic. You cannot rely on the default randomized-hash HashMap iteration order; you must use BTreeMap, IndexMap, or apply an explicit sort.

Consequences

• Worldgen code is heavily constrained in its choice of RNG and collection types. Reviewers have to actively watch out for nondeterministic iteration order creeping in.
• In exchange, we guarantee identical worlds from identical seeds on any supported platform.
• This strict guarantee is scoped only to worldgen. See ADR-0004 for a detailed explanation of why we intentionally do not hold the rest of the simulation to this same standard.