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
+117
View File
@@ -0,0 +1,117 @@
#include "evo/simulation/world.hpp"
#include <algorithm>
#include <array>
namespace evo {
namespace {
constexpr std::array<std::uint8_t, 8> magic{'A', 'E', 'V', 'O', 'P', 'R', 'F', '0'};
constexpr std::size_t header_size = 52;
constexpr std::size_t row_size = 24;
constexpr std::size_t checksum_size = 8;
std::uint64_t checksum(std::span<const std::uint8_t> bytes) noexcept {
std::uint64_t hash = 14695981039346656037ULL;
for (const auto byte : bytes) {
hash = (hash ^ byte) * 1099511628211ULL;
}
return hash;
}
void append(Snapshot& bytes, std::uint64_t value, std::size_t width) {
for (std::size_t index = 0; index < width; ++index) {
bytes.push_back(static_cast<std::uint8_t>(value & 0xffU));
value >>= 8U;
}
}
// Private reader: callers validate the whole fixed header or bounded row region
// before reading. Widths below are constants, not input-controlled values.
class Reader {
public:
explicit Reader(std::span<const std::uint8_t> bytes) noexcept : bytes_{bytes} {}
std::uint64_t read(std::size_t width) noexcept {
std::uint64_t value{};
for (std::size_t index = 0; index < width; ++index) {
value |= static_cast<std::uint64_t>(bytes_[offset_++]) << (8U * index);
}
return value;
}
private:
std::span<const std::uint8_t> bytes_;
std::size_t offset_{};
};
} // namespace
Snapshot SimulationWorld::serialize() const {
Snapshot bytes;
bytes.reserve(header_size + row_size * entities_.size() + checksum_size);
bytes.insert(bytes.end(), magic.begin(), magic.end());
append(bytes, format_version, 4);
append(bytes, rules_version, 4);
append(bytes, tick_quantum_us, 8);
append(bytes, seed_, 8);
append(bytes, tick_.value, 8);
append(bytes, next_id_, 8);
append(bytes, entities_.size(), 4);
for (const auto& entity : entities_) {
append(bytes, entity.id.value, 8);
append(bytes, entity.position.x.value, 4);
append(bytes, entity.position.y.value, 4);
append(bytes, entity.random.state(), 8);
}
append(bytes, checksum(bytes), checksum_size);
return bytes;
}
std::uint64_t SimulationWorld::state_hash() const {
const auto bytes = serialize();
return checksum(std::span{bytes}.first(bytes.size() - checksum_size));
}
std::expected<SimulationWorld, Error>
SimulationWorld::restore(std::span<const std::uint8_t> bytes) {
if (bytes.size() < header_size + checksum_size || bytes.size() > max_snapshot_bytes ||
!std::ranges::equal(bytes.first(magic.size()), magic)) {
return std::unexpected{Error::invalid_snapshot};
}
Reader header{bytes.subspan(magic.size())};
const auto format = header.read(4);
const auto rules = header.read(4);
if (format != format_version || rules != rules_version || header.read(8) != tick_quantum_us) {
return std::unexpected{Error::unsupported_version};
}
const auto seed = header.read(8);
const auto tick = header.read(8);
const auto next_id = header.read(8);
const auto count = header.read(4);
if (count > max_entities || next_id == 0 ||
bytes.size() != header_size + row_size * count + checksum_size) {
return std::unexpected{Error::invalid_snapshot};
}
Reader trailer{bytes.last(checksum_size)};
if (trailer.read(8) != checksum(bytes.first(bytes.size() - checksum_size))) {
return std::unexpected{Error::invalid_snapshot};
}
SimulationWorld restored{seed};
restored.tick_ = Tick{tick};
restored.next_id_ = next_id;
restored.entities_.reserve(static_cast<std::size_t>(count));
Reader rows{bytes.subspan(header_size, static_cast<std::size_t>(row_size * count))};
std::uint64_t previous_id{};
for (std::uint64_t index = 0; index < count; ++index) {
const auto id = rows.read(8);
const auto x = rows.read(4);
const auto y = rows.read(4);
const auto random_state = rows.read(8);
if (id <= previous_id || id >= next_id || x >= domain_extent_mm || y >= domain_extent_mm) {
return std::unexpected{Error::invalid_snapshot};
}
restored.entities_.push_back(
EntityState{EntityId{id},
Position2{Millimetres{static_cast<std::uint32_t>(x)},
Millimetres{static_cast<std::uint32_t>(y)}},
Random{random_state}});
previous_id = id;
}
return restored;
}
} // namespace evo
+47
View File
@@ -0,0 +1,47 @@
#include "evo/simulation/world.hpp"
#include <algorithm>
#include <limits>
namespace evo {
std::expected<EntityId, Error> SimulationWorld::create_entity(Position2 position) {
if (position.x.value >= domain_extent_mm || position.y.value >= domain_extent_mm) {
return std::unexpected{Error::invalid_position};
}
if (entities_.size() >= max_entities) {
return std::unexpected{Error::entity_limit};
}
if (next_id_ == std::numeric_limits<std::uint64_t>::max()) {
return std::unexpected{Error::id_exhausted};
}
const EntityId id{next_id_};
Random derivation{seed_ ^ (id.value * 0xd1b54a32d192ed03ULL)};
entities_.push_back(EntityState{id, position, Random{derivation.next()}});
++next_id_; // Publish only after successful allocation/construction.
return id;
}
std::expected<void, Error> SimulationWorld::remove_entity(EntityId id) {
const auto found = std::ranges::lower_bound(entities_, id, {}, &EntityState::id);
if (found == entities_.end() || found->id != id) {
return std::unexpected{Error::entity_not_found};
}
entities_.erase(found);
return {};
}
std::expected<void, Error> SimulationWorld::tick() noexcept {
if (tick_.value == std::numeric_limits<std::uint64_t>::max()) {
return std::unexpected{Error::tick_exhausted};
}
for (auto& entity : entities_) {
auto& position = entity.position;
position.x.value =
(position.x.value + entity.random.ternary() + domain_extent_mm - 1U) % domain_extent_mm;
position.y.value =
(position.y.value + entity.random.ternary() + domain_extent_mm - 1U) % domain_extent_mm;
}
++tick_.value;
return {};
}
} // namespace evo