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
+54
View File
@@ -0,0 +1,54 @@
#pragma once
#include "evo/core/random.hpp"
#include "evo/core/types.hpp"
#include <cstddef>
#include <cstdint>
#include <expected>
#include <span>
#include <vector>
namespace evo {
inline constexpr std::uint32_t format_version = 1;
inline constexpr std::uint32_t rules_version = 1;
inline constexpr std::uint64_t tick_quantum_us = 50'000;
inline constexpr std::uint32_t domain_extent_mm = 1'024;
inline constexpr std::uint32_t max_entities = 100'000;
inline constexpr std::size_t max_snapshot_bytes = 60 + 24 * max_entities;
struct EntityState {
EntityId id;
Position2 position;
Random random;
};
using Snapshot = std::vector<std::uint8_t>;
class SimulationWorld {
public:
explicit SimulationWorld(std::uint64_t seed) noexcept : seed_{seed} {}
[[nodiscard]] std::expected<EntityId, Error> create_entity(Position2 position = {});
[[nodiscard]] std::expected<void, Error> remove_entity(EntityId id);
[[nodiscard]] std::expected<void, Error> tick() noexcept;
// Non-owning inspection; mutation can invalidate views and references.
[[nodiscard]] std::span<const EntityState> entities() const noexcept {
return entities_;
}
[[nodiscard]] Tick current_tick() const noexcept {
return tick_;
}
[[nodiscard]] std::uint64_t seed() const noexcept {
return seed_;
}
[[nodiscard]] Snapshot serialize() const;
[[nodiscard]] std::uint64_t state_hash() const;
[[nodiscard]] static std::expected<SimulationWorld, Error>
restore(std::span<const std::uint8_t> bytes);
private:
std::uint64_t seed_;
Tick tick_{};
std::uint64_t next_id_{1};
std::vector<EntityState> entities_;
};
} // namespace evo
+35
View File
@@ -0,0 +1,35 @@
#pragma once
#include "evo/core/types.hpp"
#include <cstdint>
#include <ostream>
namespace evo {
struct SimulationMetrics {
Tick tick;
std::uint64_t active_entities;
};
// Host-owned observers; no kernel calls to I/O, exporters or clocks.
class MetricsSink {
public:
virtual ~MetricsSink() = default;
virtual void observe(SimulationMetrics metrics) = 0;
};
class PrometheusTextSink final : public MetricsSink {
public:
explicit PrometheusTextSink(std::ostream& output) : output_{output} {}
void observe(SimulationMetrics metrics) override {
output_ << "# TYPE evo_simulation_tick gauge\nevo_simulation_tick " << metrics.tick.value
<< "\n# TYPE evo_active_entities gauge\nevo_active_entities "
<< metrics.active_entities << '\n';
}
private:
std::ostream& output_;
};
// Typed static names keep these records bounded without arbitrary-string escaping.
inline void log_error(std::ostream& output, Error error) {
output << "{\"level\":\"error\",\"event\":\"" << error_name(error) << "\"}\n";
}
} // namespace evo