Initial commit: architecture docs and headless engineering proof

Aeternalis Evolution, a custom-engine persistent evolutionary MMO.

This first commit establishes the project skeleton:

- Architecture and design docs: project vision, system overview,
  engineering constitution, roadmap, 19 ADRs, and the simulation,
  world, network, persistence and infrastructure architectures.
- Headless engineering proof: deterministic synthetic particles,
  component lifecycle, explicit PRNG streams, canonical snapshots
  and restored execution.
- Build and tooling: CMake 3.28+ / Ninja presets, C++23 feature
  check, clang-format and clang-tidy config, format check script,
  Windows check script, and a Docker build context.
- Tests: unit tests, benchmarks, a snapshot fuzz target and CLI
  integration wiring.

No gameplay, renderer, network service or running deployment yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-09-14 15:44:41 -04:00
co-authored by Claude Opus 5
commit d5b4bd068e
63 changed files with 3531 additions and 0 deletions
+33
View File
@@ -0,0 +1,33 @@
#pragma once
#include <cstdint>
namespace evo {
// SplitMix64; explicit unsigned wraparound. Reference and scope: ADR-0007.
// This algorithm is never a security primitive.
class Random {
public:
explicit constexpr Random(std::uint64_t state) noexcept : state_{state} {}
[[nodiscard]] constexpr std::uint64_t next() noexcept {
state_ += 0x9e3779b97f4a7c15ULL;
auto value = state_;
value = (value ^ (value >> 30U)) * 0xbf58476d1ce4e5b9ULL;
value = (value ^ (value >> 27U)) * 0x94d049bb133111ebULL;
return value ^ (value >> 31U);
}
// The 2^64-1 accepted outputs divide equally among three bins.
[[nodiscard]] constexpr std::uint32_t ternary() noexcept {
auto value = next();
while (value == 0) {
value = next();
}
return static_cast<std::uint32_t>(value % 3U);
}
[[nodiscard]] constexpr std::uint64_t state() const noexcept {
return state_;
}
private:
std::uint64_t state_;
};
} // namespace evo
+67
View File
@@ -0,0 +1,67 @@
#pragma once
#include <compare>
#include <cstdint>
#include <string_view>
namespace evo {
struct EntityId {
std::uint64_t value{};
auto operator<=>(const EntityId&) const = default;
};
struct Millimetres {
std::uint32_t value{};
auto operator<=>(const Millimetres&) const = default;
};
struct Tick {
std::uint64_t value{};
auto operator<=>(const Tick&) const = default;
};
struct Position2 {
Millimetres x{};
Millimetres y{};
auto operator<=>(const Position2&) const = default;
};
enum class Error : std::uint8_t {
invalid_position,
entity_limit,
id_exhausted,
entity_not_found,
tick_exhausted,
invalid_snapshot,
unsupported_version,
invalid_arguments,
io_failure,
replay_mismatch,
unhandled_exception
};
[[nodiscard]] constexpr std::string_view error_name(Error error) noexcept {
switch (error) {
case Error::invalid_position:
return "invalid_position";
case Error::entity_limit:
return "entity_limit";
case Error::id_exhausted:
return "id_exhausted";
case Error::entity_not_found:
return "entity_not_found";
case Error::tick_exhausted:
return "tick_exhausted";
case Error::invalid_snapshot:
return "invalid_snapshot";
case Error::unsupported_version:
return "unsupported_version";
case Error::invalid_arguments:
return "invalid_arguments";
case Error::io_failure:
return "io_failure";
case Error::replay_mismatch:
return "replay_mismatch";
case Error::unhandled_exception:
return "unhandled_exception";
}
return "unknown_error";
}
} // namespace evo