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:
@@ -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
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user