15 releases (8 breaking)
0.11.0 | Nov 30, 2024 |
---|---|
0.9.0 | Nov 7, 2024 |
0.7.0-alpha.1 | Jul 30, 2024 |
0.4.0 | Dec 14, 2023 |
0.3.0 | Nov 5, 2023 |
#497 in Game dev
496 downloads per month
Used in 4 crates
205KB
3K
SLoC
aeronet
A set of Bevy-native networking crates, focused on providing robust and rock-solid data transfer primitives.
Goals
- Native to Bevy ECS
- Network state is represented as entities, making them easily queryable
- React to connections and disconnections via observers
- Send and receive data by mutating components
- Correct and non-panicking
- Explicit error handling, where failure conditions are clear and documented
- No
unwrap
s - all panicking paths are a bug unless explicitly documented
- Support for any network topology
- Dedicated server/client, listen server, peer-to-peer
- Swappable IO layer
- Use whatever you like as the underlying byte transfer mechanism
- You can use multiple IO layers at the same time, e.g. Steam + WebTransport
High-level networking features such as replication, rollback, and prediction are explicit non-goals for this crate. Instead, this crate aims to provide a solid foundation for implementing these features.
Crates
IO layer implementations
aeronet_channel
: over MPSC channels- Native + WASM
- ✅ Complete
cargo run --example channel
aeronet_websocket
: over WebSockets (using TCP)- Native + WASM
- ✅ Complete
cargo run --example websocket_echo_server -F server
cargo run --example websocket_client -F client
# WASM
cargo install wasm-server-runner
cargo run --example websocket_client -F client --target wasm32-unknown-unknown
aeronet_webtransport
: over WebTransport (using QUIC)- Native + WASM
- ✅ Complete
cargo run --example webtransport_echo_server -F server
cargo run --example webtransport_client -F client,dangerous-configuration
# WASM
cargo install wasm-server-runner
cargo run --example webtransport_client -F client --target wasm32-unknown-unknown
aeronet_steam
: over Steam's networking sockets- Native
- 🛠️ WIP
cargo run --example steam_echo_server -F server
cargo run --example steam_client -F client
Integrations
aeronet_replicon
: high-level replication viabevy_replicon
cargo run --bin move_box_server
cargo run --bin move_box_client
Overview
Layers
aeronet
is fundamentally split into multiple layers:
- IO layer (abstraction) -
aeronet_io
- Defines what a
Session
is, and how it behaves - Handles core dis/connection logic, shared among all IO layer implementations
- Performs setup for the layers above
- Defines what a
- IO layer (implementation) -
aeronet_channel
,aeronet_webtransport
, etc.- Establishes and maintains a connection to a peer
- Detects connection and disconnection, and reports it to the session layer
- Allows sending and receiving packets unreliably
- User-swappable - can have multiple in a single app
- Transport layer -
aeronet_transport
- Handles fragmentation, reliability, and ordering of messages
- Splits messages into packets, and reassembles packets into messages, which can be used by layers above
- Allows receiving acknowledgement of sent message acknowledgements
- Technically user-swappable, but most code above this layer relies on
aeronet_transport
specifically
- Component replication, rollback, etc.
- This is not provided as part of
aeronet
, but you can use a crate which integratesaeronet
with one of these e.g.aeronet_replicon
- This is not provided as part of
Getting started
To learn about how to use this crate, it is recommended that you learn the architecture by skimming
the examples and reading the documentation of important types such as Session
. If you're not
sure where to start, take a look at the echo_client
and echo_server
crates. The examples are
designed to be self-contained and self-documenting, giving you an easy jumping-off point for
learning.
Crates and items are thoroughly documented through rustdoc, and are the most likely to be up to date, so you should use that as the definitive reference for information on specific items.
Once you have a rough idea of the architecture, choose an IO layer implementation from the list at
the top, add it and aeronet
to your app, and start building!
Testing
For aeronet
aeronet
and its subcrates use a combination of:
- unit tests, using
cargo
, for individual, self-contained features - integration tests, using
cargo
, for testing code in the context of a full Bevy app- currently, only
aeronet_channel
has integration tests
- currently, only
- fuzz tests, using
cargo-fuzz
, for protocol-level features and parsing- used by
aeronet_transport
- used by
Fuzz tests
To run the fuzz tests:
cd crates/aeronet_transport
cargo +nightly fuzz run <fuzz target>
For users
Visualizer
As a debug tool, you may want to see the state of your session over time while you are in the app.
If using aeronet_transport
, you can use the visualizer
feature to enable an egui_plot
visualizer which displays statistics on sessions. This includes data such as round-trip time and
packet loss percentage.
Conditioning
Using a conditioner allows you to emulate poor network conditions locally, and see how your app copes with problems such as duplicate or lost packets, delay, and jitter.
Some example tools you may use are:
- Linux
tc
sudo tc qdisc add dev lo root netem delay 250ms
sudo tc qdisc add dev lo root netem delay 200ms 50ms distribution normal
sudo tc qdisc add dev lo root netem loss 50%
sudo tc qdisc delete dev lo root
- MacOS
- Windows
aeronet
does not provide support for conditioning within the networking crate itself, since
conditioning testing is more effective (and representative of real-world results) when the
conditioning is applied at the lowest level possible.
Versions
bevy |
aeronet |
---|---|
0.15 |
0.10.0 |
0.14 |
0.9.0 |
Dependencies
~12–52MB
~876K SLoC