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,53 @@
|
||||
#include "evo/simulation/world.hpp"
|
||||
|
||||
#include <chrono>
|
||||
#include <exception>
|
||||
#include <iostream>
|
||||
|
||||
int main() try {
|
||||
try {
|
||||
constexpr std::uint64_t seed = 123456;
|
||||
constexpr std::uint32_t count = 10'000;
|
||||
constexpr std::uint64_t ticks = 1'000;
|
||||
evo::SimulationWorld world{seed};
|
||||
for (std::uint32_t index = 0; index < count; ++index) {
|
||||
if (!world.create_entity()) {
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
const auto start = std::chrono::steady_clock::now();
|
||||
for (std::uint64_t tick = 0; tick < ticks; ++tick) {
|
||||
if (!world.tick()) {
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
const auto elapsed =
|
||||
std::chrono::duration<double>(std::chrono::steady_clock::now() - start);
|
||||
std::cout << "{\"benchmark\":\"synthetic_tick\",\"seed\":" << seed
|
||||
<< ",\"entities\":" << count << ",\"ticks\":" << ticks
|
||||
<< ",\"seconds\":" << elapsed.count() << ",\"state_hash\":\"" << std::hex
|
||||
<< world.state_hash() << "\",\"compiler\":\""
|
||||
#if defined(__clang__)
|
||||
<< "Clang " << __clang_version__
|
||||
#elif defined(_MSC_VER)
|
||||
<< "MSVC " << _MSC_VER
|
||||
#elif defined(__GNUC__)
|
||||
<< "GCC " << __VERSION__
|
||||
#else
|
||||
<< "unknown"
|
||||
#endif
|
||||
<< "\",\"build\":\""
|
||||
#if defined(NDEBUG)
|
||||
<< "release"
|
||||
#else
|
||||
<< "debug"
|
||||
#endif
|
||||
<< "\"}\n";
|
||||
return 0;
|
||||
} catch (const std::exception& error) {
|
||||
std::cerr << error.what() << '\n';
|
||||
return 1;
|
||||
}
|
||||
} catch (...) {
|
||||
return 1;
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
if(NOT DEFINED EVO_SIM OR NOT DEFINED TEST_DIR)
|
||||
message(FATAL_ERROR "EVO_SIM and TEST_DIR are required")
|
||||
endif()
|
||||
# Fresh build-local files each run; no recursive deletion or source-tree writes.
|
||||
string(RANDOM LENGTH 16 ALPHABET 0123456789abcdef run_id)
|
||||
set(run_dir "${TEST_DIR}/${run_id}")
|
||||
file(MAKE_DIRECTORY "${run_dir}")
|
||||
|
||||
function(expect_success)
|
||||
execute_process(COMMAND "${EVO_SIM}" ${ARGN}
|
||||
RESULT_VARIABLE result OUTPUT_VARIABLE output ERROR_VARIABLE error)
|
||||
if(NOT result EQUAL 0)
|
||||
message(FATAL_ERROR "CLI failed (${result}): ${error}")
|
||||
endif()
|
||||
endfunction()
|
||||
function(expect_failure)
|
||||
execute_process(COMMAND "${EVO_SIM}" ${ARGN}
|
||||
RESULT_VARIABLE result OUTPUT_VARIABLE output ERROR_VARIABLE error)
|
||||
if(NOT result MATCHES "^[1-9][0-9]*$")
|
||||
message(FATAL_ERROR "Expected normal nonzero CLI exit, got ${result}: ${output} ${error}")
|
||||
endif()
|
||||
endfunction()
|
||||
|
||||
expect_success(--seed 123456 --entities 8 --ticks 500 --save "${run_dir}/half.evo")
|
||||
expect_success(--load "${run_dir}/half.evo" --ticks 500 --save "${run_dir}/resumed.evo"
|
||||
--output "${run_dir}/report.json" --metrics "${run_dir}/metrics.prom")
|
||||
expect_success(--seed 123456 --entities 8 --ticks 1000 --verify-replay
|
||||
--save "${run_dir}/full.evo")
|
||||
file(SHA256 "${run_dir}/resumed.evo" resumed_digest)
|
||||
file(SHA256 "${run_dir}/full.evo" full_digest)
|
||||
if(NOT resumed_digest STREQUAL full_digest)
|
||||
message(FATAL_ERROR "CLI continuation differs from uninterrupted simulation")
|
||||
endif()
|
||||
file(READ "${run_dir}/report.json" report)
|
||||
string(JSON state_hash GET "${report}" state_hash)
|
||||
string(JSON tick GET "${report}" ticks)
|
||||
if(NOT state_hash STREQUAL "d61ad5bf0c928c76" OR NOT tick EQUAL 1000)
|
||||
message(FATAL_ERROR "CLI report does not match independent frozen fixture")
|
||||
endif()
|
||||
file(READ "${run_dir}/metrics.prom" metrics)
|
||||
if(NOT metrics MATCHES "evo_active_entities 8" OR NOT metrics MATCHES "evo_simulation_tick 1000")
|
||||
message(FATAL_ERROR "Missing or wrong metrics")
|
||||
endif()
|
||||
|
||||
file(WRITE "${run_dir}/sentinel" "preserve this file")
|
||||
execute_process(COMMAND "${CMAKE_COMMAND}" -E create_hardlink
|
||||
"${run_dir}/sentinel" "${run_dir}/alias" RESULT_VARIABLE linked)
|
||||
if(NOT linked EQUAL 0)
|
||||
message(FATAL_ERROR "Hard-link regression fixture could not be created")
|
||||
endif()
|
||||
expect_failure(--ticks 0 --save "${run_dir}/sentinel" --output "${run_dir}/alias")
|
||||
expect_failure(--load "${run_dir}/sentinel" --output "${run_dir}/alias")
|
||||
file(READ "${run_dir}/sentinel" preserved)
|
||||
if(NOT preserved STREQUAL "preserve this file")
|
||||
message(FATAL_ERROR "CLI overwrote an aliased input/output")
|
||||
endif()
|
||||
expect_failure(--load "${run_dir}/half.evo" --seed 123)
|
||||
expect_failure(--entities 100001)
|
||||
expect_failure(--ticks 18446744073709551616)
|
||||
expect_failure(--unknown value)
|
||||
expect_failure(--load "${run_dir}/missing")
|
||||
expect_success(--entities 0 --ticks 2 --verify-replay)
|
||||
@@ -0,0 +1,29 @@
|
||||
#include "evo/simulation/world.hpp"
|
||||
|
||||
#include <algorithm>
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
#include <cstdlib>
|
||||
#include <span>
|
||||
|
||||
extern "C" int LLVMFuzzerTestOneInput(const std::uint8_t* data, std::size_t size) {
|
||||
if (size > evo::max_snapshot_bytes) {
|
||||
return 0;
|
||||
}
|
||||
const auto input = std::span{data, size};
|
||||
auto restored = evo::SimulationWorld::restore(input);
|
||||
if (restored) {
|
||||
const auto canonical = restored->serialize();
|
||||
if (!std::equal(canonical.begin(), canonical.end(), input.begin(), input.end())) {
|
||||
std::abort();
|
||||
}
|
||||
const auto ticked = restored->tick();
|
||||
if (!ticked && ticked.error() != evo::Error::tick_exhausted) {
|
||||
std::abort();
|
||||
}
|
||||
if (!evo::SimulationWorld::restore(restored->serialize())) {
|
||||
std::abort();
|
||||
}
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
@@ -0,0 +1,259 @@
|
||||
#include "evo/simulation/world.hpp"
|
||||
#include "evo/telemetry/sinks.hpp"
|
||||
|
||||
#include <array>
|
||||
#include <exception>
|
||||
#include <iostream>
|
||||
#include <limits>
|
||||
#include <source_location>
|
||||
#include <sstream>
|
||||
#include <stdexcept>
|
||||
#include <string>
|
||||
|
||||
namespace {
|
||||
void check(bool condition, const char* expression,
|
||||
std::source_location location = std::source_location::current()) {
|
||||
if (!condition) {
|
||||
throw std::runtime_error(std::string{location.file_name()} + ":" +
|
||||
std::to_string(location.line()) + " " + expression);
|
||||
}
|
||||
}
|
||||
#define CHECK(expression) check(static_cast<bool>(expression), #expression)
|
||||
|
||||
void advance(evo::SimulationWorld& world, std::uint64_t ticks) {
|
||||
for (std::uint64_t tick = 0; tick < ticks; ++tick) {
|
||||
CHECK(world.tick());
|
||||
}
|
||||
}
|
||||
evo::SimulationWorld fixture(std::uint64_t seed, std::uint32_t count) {
|
||||
evo::SimulationWorld world{seed};
|
||||
for (std::uint32_t index = 0; index < count; ++index) {
|
||||
CHECK(world.create_entity());
|
||||
}
|
||||
return world;
|
||||
}
|
||||
void put(evo::Snapshot& bytes, std::size_t offset, std::uint64_t value, std::size_t width) {
|
||||
for (std::size_t index = 0; index < width; ++index) {
|
||||
bytes.at(offset + index) = static_cast<std::uint8_t>(value & 0xffU);
|
||||
value >>= 8U;
|
||||
}
|
||||
}
|
||||
void resign(evo::Snapshot& bytes) {
|
||||
std::uint64_t hash = 14695981039346656037ULL;
|
||||
for (std::size_t index = 0; index < bytes.size() - 8; ++index) {
|
||||
hash = (hash ^ bytes[index]) * 1099511628211ULL;
|
||||
}
|
||||
put(bytes, bytes.size() - 8, hash, 8);
|
||||
}
|
||||
|
||||
void random_vectors() {
|
||||
evo::Random random{0};
|
||||
constexpr std::array<std::uint64_t, 4> expected{0xe220a8397b1dcdafULL, 0x6e789e6aa1b965f4ULL,
|
||||
0x06c45d188009454fULL, 0xf88bb8a8724c81ecULL};
|
||||
for (const auto value : expected) {
|
||||
CHECK(random.next() == value);
|
||||
}
|
||||
evo::Random resumed{random.state()};
|
||||
CHECK(resumed.next() == random.next());
|
||||
evo::Random zero_first{0x61c8864680b583ebULL};
|
||||
CHECK(zero_first.ternary() == 1);
|
||||
CHECK(zero_first.state() == 0x9e3779b97f4a7c15ULL);
|
||||
for (int index = 0; index < 10'000; ++index) {
|
||||
CHECK(random.ternary() < 3);
|
||||
}
|
||||
}
|
||||
void entity_lifecycle() {
|
||||
evo::SimulationWorld world{42};
|
||||
CHECK(world.entities().empty());
|
||||
const auto first = world.create_entity();
|
||||
const auto second = world.create_entity({evo::Millimetres{1023}, evo::Millimetres{0}});
|
||||
CHECK(first && second);
|
||||
CHECK(first->value == 1 && second->value == 2);
|
||||
const auto before = world.serialize();
|
||||
const auto invalid = world.create_entity({evo::Millimetres{1024}, evo::Millimetres{0}});
|
||||
CHECK(!invalid && invalid.error() == evo::Error::invalid_position);
|
||||
CHECK(world.serialize() == before);
|
||||
CHECK(world.remove_entity(*first));
|
||||
const auto stale = world.remove_entity(*first);
|
||||
CHECK(!stale && stale.error() == evo::Error::entity_not_found);
|
||||
const auto third = world.create_entity();
|
||||
CHECK(third && third->value == 3);
|
||||
CHECK(world.entities()[0].id == *second);
|
||||
CHECK(world.entities()[1].id == *third);
|
||||
CHECK(!world.remove_entity(evo::EntityId{0}));
|
||||
}
|
||||
void golden_simulation() {
|
||||
auto world = fixture(123456, 8);
|
||||
advance(world, 1000);
|
||||
CHECK(world.state_hash() == 0xd61ad5bf0c928c76ULL);
|
||||
constexpr std::array<std::array<std::uint32_t, 2>, 8> positions{
|
||||
{{49, 10}, {985, 993}, {39, 33}, {1008, 0}, {16, 1}, {7, 3}, {1004, 1007}, {995, 15}}};
|
||||
for (std::size_t index = 0; index < positions.size(); ++index) {
|
||||
CHECK(world.entities()[index].position.x.value == positions[index][0]);
|
||||
CHECK(world.entities()[index].position.y.value == positions[index][1]);
|
||||
}
|
||||
auto other = fixture(123457, 8);
|
||||
advance(other, 1000);
|
||||
CHECK(other.state_hash() != world.state_hash());
|
||||
}
|
||||
void replay_properties() {
|
||||
for (std::uint64_t seed = 0; seed < 64; ++seed) {
|
||||
auto full = fixture(seed, static_cast<std::uint32_t>(seed % 17));
|
||||
auto partial = full;
|
||||
const auto total = 2 * seed + 1;
|
||||
advance(full, total);
|
||||
advance(partial, seed);
|
||||
const auto bytes = partial.serialize();
|
||||
auto restored = evo::SimulationWorld::restore(bytes);
|
||||
CHECK(restored);
|
||||
CHECK(restored->serialize() == bytes);
|
||||
advance(*restored, total - seed);
|
||||
CHECK(restored->serialize() == full.serialize());
|
||||
CHECK(restored->current_tick().value == total);
|
||||
for (const auto& entity : restored->entities()) {
|
||||
CHECK(entity.position.x.value < evo::domain_extent_mm);
|
||||
CHECK(entity.position.y.value < evo::domain_extent_mm);
|
||||
}
|
||||
}
|
||||
}
|
||||
void stream_independence() {
|
||||
auto full = fixture(91, 2);
|
||||
auto reduced = full;
|
||||
CHECK(reduced.remove_entity(evo::EntityId{1}));
|
||||
advance(full, 500);
|
||||
advance(reduced, 500);
|
||||
CHECK(full.entities()[1].position == reduced.entities()[0].position);
|
||||
CHECK(full.entities()[1].random.state() == reduced.entities()[0].random.state());
|
||||
}
|
||||
void malformed_snapshots() {
|
||||
const auto bytes = fixture(77, 2).serialize();
|
||||
for (std::size_t length = 0; length < bytes.size(); ++length) {
|
||||
CHECK(!evo::SimulationWorld::restore(std::span{bytes}.first(length)));
|
||||
}
|
||||
for (std::size_t index = 0; index < bytes.size(); ++index) {
|
||||
auto corrupted = bytes;
|
||||
corrupted[index] ^= 0x80U;
|
||||
CHECK(!evo::SimulationWorld::restore(corrupted));
|
||||
}
|
||||
auto extra = bytes;
|
||||
extra.push_back(0);
|
||||
CHECK(!evo::SimulationWorld::restore(extra));
|
||||
CHECK(!evo::SimulationWorld::restore(evo::Snapshot(evo::max_snapshot_bytes + 1)));
|
||||
struct Field {
|
||||
std::size_t offset;
|
||||
std::uint64_t value;
|
||||
std::size_t width;
|
||||
};
|
||||
const std::array fields{Field{40, 0, 8},
|
||||
Field{40, 2, 8}, // invalid next ID
|
||||
Field{48, evo::max_entities + 1, 4},
|
||||
Field{48, 1, 4}, // count/length
|
||||
Field{52, 0, 8},
|
||||
Field{52, 2, 8},
|
||||
Field{76, 1, 8}, // zero/duplicate/order
|
||||
Field{60, evo::domain_extent_mm, 4},
|
||||
Field{64, evo::domain_extent_mm, 4}};
|
||||
for (const auto field : fields) {
|
||||
auto invalid = bytes;
|
||||
put(invalid, field.offset, field.value, field.width);
|
||||
resign(invalid); // Reach semantic checks beyond checksum rejection.
|
||||
CHECK(!evo::SimulationWorld::restore(invalid));
|
||||
}
|
||||
for (const auto offset : {8U, 12U, 16U}) {
|
||||
auto unsupported = bytes;
|
||||
put(unsupported, offset, 999, 4);
|
||||
resign(unsupported);
|
||||
const auto restored = evo::SimulationWorld::restore(unsupported);
|
||||
CHECK(!restored && restored.error() == evo::Error::unsupported_version);
|
||||
}
|
||||
}
|
||||
void exhaustion_is_atomic() {
|
||||
auto bytes = fixture(17, 1).serialize();
|
||||
put(bytes, 32, std::numeric_limits<std::uint64_t>::max(), 8);
|
||||
resign(bytes);
|
||||
auto full_tick = evo::SimulationWorld::restore(bytes);
|
||||
CHECK(full_tick);
|
||||
const auto result = full_tick->tick();
|
||||
CHECK(!result && result.error() == evo::Error::tick_exhausted);
|
||||
CHECK(full_tick->serialize() == bytes);
|
||||
bytes = fixture(17, 1).serialize();
|
||||
put(bytes, 40, std::numeric_limits<std::uint64_t>::max(), 8);
|
||||
resign(bytes);
|
||||
auto full_id = evo::SimulationWorld::restore(bytes);
|
||||
CHECK(full_id);
|
||||
const auto created = full_id->create_entity();
|
||||
CHECK(!created && created.error() == evo::Error::id_exhausted);
|
||||
CHECK(full_id->serialize() == bytes);
|
||||
}
|
||||
void capacity_boundary() {
|
||||
auto world = fixture(31, evo::max_entities);
|
||||
const auto before = world.state_hash();
|
||||
const auto result = world.create_entity();
|
||||
CHECK(!result && result.error() == evo::Error::entity_limit);
|
||||
CHECK(world.state_hash() == before);
|
||||
const auto restored = evo::SimulationWorld::restore(world.serialize());
|
||||
CHECK(restored && restored->entities().size() == evo::max_entities);
|
||||
}
|
||||
void wire_layout_and_empty_state() {
|
||||
evo::SimulationWorld world{0x1122334455667788ULL};
|
||||
const auto bytes = world.serialize();
|
||||
CHECK(bytes.size() == 60);
|
||||
CHECK(bytes[8] == 1 && bytes[9] == 0);
|
||||
CHECK(bytes[24] == 0x88 && bytes[31] == 0x11);
|
||||
auto restored = evo::SimulationWorld::restore(bytes);
|
||||
CHECK(restored && restored->serialize() == bytes);
|
||||
const auto created = restored->create_entity();
|
||||
CHECK(created && created->value == 1);
|
||||
}
|
||||
void telemetry_is_host_owned() {
|
||||
const auto world = fixture(4, 3);
|
||||
const auto before = world.serialize();
|
||||
std::ostringstream text;
|
||||
evo::PrometheusTextSink sink{text};
|
||||
sink.observe({world.current_tick(), static_cast<std::uint64_t>(world.entities().size())});
|
||||
CHECK(text.str().find("evo_active_entities 3\n") != std::string::npos);
|
||||
CHECK(world.serialize() == before);
|
||||
std::ostringstream log;
|
||||
evo::log_error(log, evo::Error::invalid_snapshot);
|
||||
CHECK(log.str() == "{\"level\":\"error\",\"event\":\"invalid_snapshot\"}\n");
|
||||
}
|
||||
} // namespace
|
||||
|
||||
int main(int argc, char**) try {
|
||||
// Dedicated CTest WILL_FAIL entry checks that this harness fails in Release.
|
||||
if (argc > 1) {
|
||||
try {
|
||||
CHECK(false);
|
||||
} catch (const std::exception&) {
|
||||
return 1;
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
struct Test {
|
||||
const char* name;
|
||||
void (*run)();
|
||||
};
|
||||
const std::array tests{Test{"random reference vectors", random_vectors},
|
||||
Test{"entity lifecycle", entity_lifecycle},
|
||||
Test{"frozen simulation fixture", golden_simulation},
|
||||
Test{"seeded replay properties", replay_properties},
|
||||
Test{"independent streams", stream_independence},
|
||||
Test{"bounded snapshots", malformed_snapshots},
|
||||
Test{"atomic exhaustion", exhaustion_is_atomic},
|
||||
Test{"capacity", capacity_boundary},
|
||||
Test{"canonical empty state", wire_layout_and_empty_state},
|
||||
Test{"host telemetry", telemetry_is_host_owned}};
|
||||
int failures = 0;
|
||||
for (const auto& test : tests) {
|
||||
try {
|
||||
test.run();
|
||||
std::cout << "PASS " << test.name << '\n';
|
||||
} catch (const std::exception& error) {
|
||||
++failures;
|
||||
std::cerr << "FAIL " << test.name << ": " << error.what() << '\n';
|
||||
}
|
||||
}
|
||||
return failures == 0 ? 0 : 1;
|
||||
} catch (...) {
|
||||
return 1;
|
||||
}
|
||||
Reference in New Issue
Block a user