cbournhonesque/lightyear

1. What this repository is

- Lightyear is a Rust workspace for building server-authoritative multiplayer games on Bevy.

- The repo is split into reusable crates rather than a single application, so the architecture is layered: low-level transport at the bottom, networking/session layers above that, then replication/input/sync features, then Bevy integrations and examples on top.

2. Primary runtime model

- The core runtime is a Bevy plugin-based ECS system.

- Games typically run as a client, server, or shared Bevy app, with plugins wiring network events into ECS resources, components, and systems.

- Most subsystems are designed to operate on ticks/timelines so that simulation, inputs, replication, and prediction stay aligned.

3. Transport and packet layer

- crates/transport/transport is the packet/channel engine: it handles packet framing, compression, priorities, fragmentation, acknowledgements, and reliability modes.

- crates/transport/messages defines the typed message API that sits on top of packet transport.

- crates/transport/serde provides the serialization layer used to encode messages and entity references.

- This layer is the boundary between game/network semantics and raw bytes.

4. Connection and session establishment

- crates/connection contains abstractions for client/host/server identities, connection roles, targets, and shared networking state.

- Subcrates implement specific connection strategies:

- netcode for authenticated secure client/server sessions

- raw_connection for simpler direct connections

- steam for SteamWorks-based networking

- These crates define how peers authenticate, identify each other, and map logical peers onto transport endpoints.

5. I/O backends and network plumbing

- crates/io contains the actual transport backends:

- udp for native socket networking

- websocket and webtransport for browser-compatible networking

- aeronet and crossbeam for other runtime/link-style backends

- link for local/test network conditioning and simulated link behavior

- These backends are the lowest boundary before packets leave the process, and they are what make the stack transport-agnostic.

6. Core time, sync, and simulation alignment

- crates/core/core provides shared primitives like tick handling, time tracking, interpolation, prediction history, and timeline management.

- crates/core/sync handles client/server time synchronization and ping estimation, including timeline syncing and diagnostics.

- crates/core/frame_interpolation is a small isolated crate for frame interpolation logic.

- These crates make sure networked state changes are interpreted against the right simulation time.

7. Replication and world state flow

- crates/replication/replication is the main entity/component replication engine.

- It handles authority, delta/state updates, checkpoints, send/receive paths, hierarchy handling, prespawning, visibility/interest management, and replication registry logic.

- Data flow here is typically: ECS state is inspected on the authoritative side → encoded into network messages → transmitted through transport → decoded and applied on remote worlds.

- This is the central subsystem for world synchronization.

8. Prediction and interpolation

- crates/replication/prediction implements client-side prediction with rollback/correction.

- crates/replication/interpolation handles snapshot interpolation for non-controlled or remote entities.

- Together they split remote-state handling into two paths:

- predicted entities advance locally and reconcile later

- interpolated entities lag behind slightly and smooth over packet cadence

- These crates are key to the “responsive client / authoritative server” architecture shown in the README.

9. Input networking

- crates/inputs contains the generic input pipeline, including buffering and network message types.

- inputs_native, input_bei, and inputs_leafwing are adapter crates for different input sources, including Bevy Enhanced Input and Leafwing Input Manager.

- Input flow is usually: local device input → buffered per tick on client → sent with redundancy → applied on the server for the matching tick.

- This is a distinct path from world replication because player intent must be time-aligned, loss-tolerant, and often replayable.

10. Deterministic replication mode

- crates/deterministic/deterministic_replication supports input-only deterministic simulation.

- It includes checksums, late-join logic, and mode control to support lockstep-style or deterministic rollback-style networking.

- This subsystem is separate from ordinary state replication because it assumes the simulation itself can be reproduced exactly from the same inputs.

11. Integration layer for game physics and ECS ecosystems

- crates/integration/avian and related crates provide Avian physics integration and lag compensation helpers.

- This is where network sync meets gameplay systems like rigid bodies, collision queries, and predicted/interpolated physics objects.

- The integrations act as adaptation layers between Lightyear’s network model and specific Bevy ecosystem crates.

12. Platform and browser support

- crates/platform/web contains browser-oriented support, including a background worker utility.

- Combined with websocket and webtransport, this is what enables the same networking architecture to run in wasm/browser environments as well as native ones.

13. Tooling, observability, and developer support

- crates/tools/metrics and crates/tools/tools provide diagnostics, debug UI, schema/component inspection, and tracing support.

- The repo also uses tracing and metrics as first-class observability hooks across the networking stack.

- This tooling is not the data path itself, but it matters architecturally because it exposes transport, replication, and sync behavior at runtime.

14. Examples, tests, docs, and validation

- examples/ and demos/ are the main architectural usage references: each example composes a client, server, shared protocol, and renderer around specific Lightyear features.

- crates/tests is a dedicated integration-test workspace covering client/server, host-server, multi-server, timeline sync, prediction, input, and replication scenarios.

- book/ is the conceptual documentation for the architecture, while benches/ measures compile-time and runtime performance of transport, replication, and compression paths.

15. How the major data flows connect

- The most important diagram boundary is:

- Bevy gameplay systems and ECS state

- through input/replication/prediction/sync plugins

- into message serialization and packet channels

- across connection + IO backends

- to the remote client/server world

- The architecture is intentionally modular so that a project can use only the transport layer, only replication, or the full authoritative client/server stack.