Aetheris Engine

The deterministic heart and authoritative simulation core of the Aetheris multiplayer platform.

---

⚙️ The Deterministic Heart — Authoritative Simulation

In modern multiplayer architecture, the server is more than a message relay — it is the absolute source of truth. Aetheris Engine provides the sub-millisecond precision, high-frequency tick scheduling, and deterministic ECS bridging required to synchronize complex worlds across unreliable networks.

Important

🚀 Current State: Phase 1 Performance Stabilization complete! Upgraded to Protocol v0.2.13. Implemented a Rayon-parallelized replication pipeline and stabilized gRPC/internal auth integration. All 11+ integration tests are green, providing a deterministic foundation for the upcoming Phase 2 stress-testing and telemetry phase.

📦 Workspace Components

Crate	Link	Documentation
aetheris-server
aetheris-ecs-bevy
aetheris-transport-renet
aetheris-transport-webtransport
aetheris-transport-quinn
aetheris-ecs-custom

Workspace Components

The engine is built on modular, specialized crates for maximum reuse and testing isolation:

• aetheris-server: The authoritative heartbeat. Handles tick scheduling (60Hz), delta extraction, and multi-transport orchestration.
• aetheris-ecs-bevy: The primary simulation adapter. Bridges Aetheris Protocol traits to the Bevy ECS ecosystem with zero-cost abstractions.
• aetheris-ecs-custom: Phase 3 custom SoA ECS. Optimized for extreme entity densities and cache-friendly iteration.
• aetheris-transport-renet: Phase 1 UDP transport using the renet protocol. Optimized for raw performance and low latency.
• aetheris-transport-quinn: Phase 3 native QUIC transport. Provides reliable streams and unreliable datagrams with modern security.
• aetheris-transport-webtransport: Phase 3 browser-native transport. Enables sub-millisecond latency for web-based clients.

Quickstart

# 1. Run the quality gate (fmt, clippy, tests, security, docs)
just check

# 2. Automatically apply formatting and clippy fixes
just fix

# 3. List all specialized maintenance and run commands
just --list

🛠️ Common Tasks

Command	Category	Description
just check	Quality	Fast local validation: fmt, clippy, integration tests, and security audit.
just fix	Lint	Forces formatting and applies legal clippy suggestions.
just test	Test	Runs the full integration suite using nextest.
just server	Run	Boots the game server in debug mode with auth bypass enabled.

The Three Pillars

1. Authoritative Scheduling: A high-precision 60Hz loop governing the five stages of a tick: POLL, APPLY, SIMULATE, EXTRACT, and SEND — each must complete within 16.6 ms total; no blocking I/O is permitted inside any stage.
2. Simulation Abstraction: A trait-driven bridge allowing the engine to drive any ECS (Bevy or custom) without modifying networking logic.
3. Hardened Integrity: Every input is validated, every state is replicated, and every vital is protected against division-by-zero or out-of-bounds corruption.

🚀 Performance & Determinism (VS-07)

The engine implements strict performance and architectural integrity contracts:

Microbenchmarks & Zero-Alloc

We use criterion for sub-microsecond precision and alloc_counter to enforce a Zero Heap Allocation policy in hot-path pipelines.

• Run all benchmarks: just bench
• Zero-Alloc Assertion: The ecs_extract_dirty benchmark will panic! if any heap allocation occurs during extraction.
• Warmup: Benchmarks include a mandatory 100-tick warmup to stabilize Bevy query states before measurement.

Determinism Validation (Golden Files)

To prevent drift across platforms or versions, we use Golden File Recording:

1. Record: just record-golden (Captures 600 ticks of world state hashes to golden_600ticks.bin).
2. Verify: rtk cargo test --test determinism --features phase1 (Replays simulation and verifies hashes bit-for-bit).

---

License: MIT / Apache-2.0