Skip to content

Architecture ​

A controlled Bevy World is the authority. Clients, presentation, and transports adapt that world; they do not introduce another simulation model.

Ownership ​

CrateOwnsDoes not own
CoreSchedules, clock, RNG, input validation, action arbitration, observation contracts, checksumsSnapshot storage, history navigation, sockets
SnapshotType registration, serialization, preflight, restore/remapping, retentionReplay policy and client authorization
ReplayAccepted input history, executed ticks, recording, branch topologyGameplay execution and the app
RunnerApp lifecycle, stepping, history reconstruction, coordinated checkpoints, portable bundles, captureSerialization and lineage rules delegated to other owners
RemoteRPC validation, capabilities, confinement, discovery, transport, retained operation outcomesGame rules and independent world mutation

The runner depends on core, snapshot, and replay. Snapshot and replay are siblings. The remote bridge depends on the runner. CLI and Python communicate through the wire protocol rather than linking a second simulation.

Tick lifecycle ​

AgentApp initializes a Bevy app, resets an episode, and runs explicit controlled ticks. AgentDecision runs once before a tick. AgentPreTick, AgentTick, and AgentPostTick complete before AgentFinalize extracts observations, records input, and captures periodic checkpoints.

Run authoritative gameplay in AgentTick. Explicitly order systems whose results depend on one another. Presentation can update independently, but must not change authoritative gameplay.

Snapshot and restore ​

Every registered type has a stable wire ID and positive schema version. Gameplay entities have stable identities so restore can remap references. Required resources must be present.

Restore validates the incoming data before activating it. State coverage includes hidden values and queued input that can affect the next tick. Snapshot and replay retention are bounded; the runner coordinates checkpoints still referenced by retained history.

Replay and branches ​

Replay records accepted input and executed ticks. Reconstruction starts from a compatible checkpoint, follows branch topology, and rebuilds pending input consistently. Portable bundles contain the log and all referenced snapshots, and are validated before activation.

Cargo package versions, artifact format version 3, per-type schema versions, and checksum encodings remain separate compatibility boundaries.

Remote execution ​

Validate a request's shape, session token, capability, and game contract before invoking a mutation. For a rendered app, the main thread owns world mutation and primary-window screenshots. Network I/O can run separately.

HTTP and WebSocket retain uncertain operation outcomes and deduplicate a retained retry key. Stdio does not provide that ledger. An error after mutation begins reports committed state and whether reset is required.

Verification ​

Unit tests exercise owner invariants. Sample integration tests exercise cross-crate transactions. The transport smoke script uses real client and server binaries. The rendered capture test checks the window boundary under Xvfb/Mesa in manual CI.

The contributing guide lists reproducible validation commands. The repository retains the detailed architecture review for implementation history and deeper invariants.

Released under MIT or Apache-2.0.