A Client/Server game networking plugin using QUIC, for the Bevy game engine.
QUIC was really attractive to me as a game networking protocol because most of the hard-work is done by the protocol specification and the implementation (here Quinn). No need to reinvent the wheel once again on error-prones subjects such as a UDP reliability wrapper, some encryption & authentication mechanisms, congestion-control, and so on.
Most of the features proposed by the big networking libs are supported by default through QUIC. As an example, here is the list of features presented in GameNetworkingSockets:
-> Roughly 9 points out of 11 by default.
(*) Kinda, when sharing a QUIC stream, reliable messages need to be framed.
Quinnet does not have many features, I made it mostly to satisfy my own needs for my own game projects.
It currently features:
Although Quinn and parts of Quinnet are asynchronous, the APIs exposed by Quinnet for the client and server are synchronous. This makes the surface API easy to work with and adapted to a Bevy usage. The implementation uses tokio channels to communicate with the networking async tasks.
Those are the features/tasks that will probably come next (in no particular order):
QuinnetClientPlugin to the bevy app:rust
App::new()
// ...
.add_plugin(QuinnetClientPlugin::default())
// ...
.run();
Client resource to connect, send & receive messages:```rust
fn startconnection(client: ResMut
// When trully connected, you will receive a ConnectionEvent
```
receive_message is generic, here ServerMessage is a user provided enum deriving Serialize and Deserialize.rust
fn handle_server_messages(
mut client: ResMut<Client>,
/*...*/
) {
while let Ok(Some(message)) = client.connection().receive_message::<ServerMessage>() {
match message {
// Match on your own message types ...
ServerMessage::ClientConnected { client_id, username} => {/*...*/}
ServerMessage::ClientDisconnected { client_id } => {/*...*/}
ServerMessage::ChatMessage { client_id, message } => {/*...*/}
}
}
}
QuinnetServerPlugin to the bevy app:rust
App::new()
/*...*/
.add_plugin(QuinnetServerPlugin::default())
/*...*/
.run();
Server resource to start the listening server:rust
fn start_listening(mut server: ResMut<Server>) {
server
.start_endpoint(
ServerConfigurationData::new("127.0.0.1".to_string(), 6000, "0.0.0.0".to_string()),
CertificateRetrievalMode::GenerateSelfSigned,
)
.unwrap();
}
receive_message is generic, here ClientMessage is a user provided enum deriving Serialize and Deserialize.rust
fn handle_client_messages(
mut server: ResMut<Server>,
/*...*/
) {
let mut endpoint = server.endpoint_mut();
while let Ok(Some((message, client_id))) = endpoint.receive_message::<ClientMessage>() {
match message {
// Match on your own message types ...
ClientMessage::Join { username} => {
// Send a messsage to 1 client
endpoint.send_message(client_id, ServerMessage::InitClient {/*...*/}).unwrap();
/*...*/
}
ClientMessage::Disconnect { } => {
// Disconnect a client
endpoint.disconnect_client(client_id);
/*...*/
}
ClientMessage::ChatMessage { message } => {
// Send a message to a group of clients
endpoint.send_group_message(
client_group, // Iterator of ClientId
ServerMessage::ChatMessage {/*...*/}
)
.unwrap();
/*...*/
}
}
}
}
You can also use endpoint.broadcast_message, which will send a message to all connected clients. "Connected" here means connected to the server plugin, which happens before your own app handshakes/verifications if you have any. Use send_group_message if you want to control the recipients.
Bevy Quinnet (through Quinn & QUIC) uses TLS 1.3 for authentication, the server needs to provide the client with a certificate confirming its identity, and the client must be configured to trust the certificates it receives from the server.
Here are the current options available to the server and client plugins for the server authentication: - Client : - [x] Skip certificate verification (messages are still encrypted, but the server is not authentified) - [x] Accept certificates issued by a Certificate Authority (implemented in Quinn, using rustls) - [x] [Trust on first use](https://en.wikipedia.org/wiki/Trustonfirst_use) certificates (implemented in Quinnet, using rustls) - Server: - [x] Generate and issue a self-signed certificate - [x] Issue an already existing certificate (CA or self-signed)
On the client:
rust
// To accept any certificate
client.open_connection(/*...*/, CertificateVerificationMode::SkipVerification);
// To only accept certificates issued by a Certificate Authority
client.open_connection(/*...*/, CertificateVerificationMode::SignedByCertificateAuthority);
// To use the default configuration of the Trust on first use authentication scheme
client.open_connection(/*...*/, CertificateVerificationMode::TrustOnFirstUse(TrustOnFirstUseConfig {
// You can configure TrustOnFirstUse through the TrustOnFirstUseConfig:
// Provide your own fingerprint store variable/file,
// or configure the actions to apply for each possible certificate verification status.
..Default::default()
}),
);
On the server:
rust
// To generate a new self-signed certificate on each startup
server.start_endpoint(/*...*/, CertificateRetrievalMode::GenerateSelfSigned);
// To load a pre-existing one from files
server.start_endpoint(/*...*/, CertificateRetrievalMode::LoadFromFile {
cert_file: "./certificates.pem".into(),
key_file: "./privkey.pem".into(),
});
// To load one from files, or to generate a new self-signed one if the files do not exist.
server.start_endpoint(/*...*/, CertificateRetrievalMode::LoadFromFileOrGenerateSelfSigned {
cert_file: "./certificates.pem".into(),
key_file: "./privkey.pem".into(),
save_on_disk: true, // To persist on disk if generated
});
See more about certificates in the certificates readme
For logs configuration, see the unoffical bevy cheatbook.
Chat example
This demo comes with an headless server, a terminal client and a shared protocol.
Start the server with cargo run --example chat-server and as many clients as needed with cargo run --example chat-client. Type quit to disconnect with a client.
Breakout versus example
This demo is a modification of the classic Bevy breakout example to turn it into a 2 players versus game.
It hosts a local server from inside a client, instead of a dedicated headless server as in the chat demo. You can find a server module, a client module, a shared protocol and the bevy app schedule.
Start two clients with cargo run --example breakout, "Host" on one and "Join" on the other.
Examples can be found in the examples directory.
Compatibility of bevy_quinnet versions:
| bevy_quinnet | bevy |
| :------------- | :----- |
| 0.1 | 0.8 |
| 0.2 | 0.9 |
Thanks to the Renet crate for the inspiration on the high level API.
bevy-quinnet is free and open source! All code in this repository is dual-licensed under either:
at your option. This means you can select the license you prefer! This dual-licensing approach is the de-facto standard in the Rust ecosystem and there are very good reasons to include both.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.