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