lightyear_netcode/
lib.rs

1/*! Netcode.io protocol to establish a connection on top of an unreliable transport
2
3# netcode
4
5 The `netcode` crate implements the [netcode](https://github.com/networkprotocol/netcode)
6 network protocol created by [Glenn Fiedler](https://gafferongames.com).
7
8 `netcode` is a UDP-based protocol that provides secure, connection-based data transfer.
9
10 Since the protocol is meant to be used to implement multiplayer games, its API is designed
11 to be used in a game loop, where the server and client are updated at a fixed rate (e.g., 60Hz).
12
13 ## Protocol
14
15 The three main components of the netcode protocol are:
16 * Dedicated [`Servers`](NetcodeServer).
17 * [`Clients`](NetcodeClient).
18 * The web backend - a service that authenticates clients and generates [`ConnectTokens`](ConnectToken).
19
20 The protocol does not specify how the web backend should be implemented, but it should probably be a typical HTTPS server
21 that provides a means for clients to authenticate and request connection tokens.
22
23 The sequence of operations for a client to connect to a server is as follows:
24
25 1. The `Client` authenticates with the web backend service. (e.g., by OAuth or some other means)
26 2. The authenticated `Client` requests a connection token from the web backend.
27 3. The web backend generates a [`ConnectToken`] and sends it to the `Client`. (e.g., as a JSON response)
28 4. The `Client` uses the token to connect to a dedicated `Server`.
29 5. The `Server` makes sure the token is valid and allows the `Client` to connect.
30 6. The `Client` and `Server` can now exchange encrypted and signed UDP packets.
31
32 To learn more about the netcode protocol, see the upstream [specification](https://github.com/networkprotocol/netcode/blob/master/STANDARD.md).
33
34 ## Server
35
36 The netcode server is responsible for managing the state of the clients and sending/receiving packets.
37
38 The server should run as a part of the game loop, process incoming packets and send updates to the clients.
39
40 To create a server:
41  * Provide the address you intend to bind to.
42  * Provide the protocol id - a `u64` that uniquely identifies your app.
43  * Provide a private key - a `u8` array of length 32. If you don't have one, you can generate one with `netcode::generate_key()`.
44  * Optionally provide a [`ServerConfig`] - a struct that allows you to customize the server's behavior.
45
46 ## Client
47
48The netcode client connects to the server and communicates using the same protocol.
49
50Like the server, the game client should run in a loop to process incoming data,
51send updates to the server, and maintain a stable connection.
52
53To create a client:
54 * Provide a **connect token** - a `u8` array of length 2048 serialized from a [`ConnectToken`].
55 * Optionally provide a [`ClientConfig`](client::ClientConfig) - a struct that allows you to customize the client's behavior.
56*/
57#![no_std]
58
59extern crate alloc;
60extern crate core;
61#[cfg(feature = "std")]
62extern crate std;
63
64#[cfg(feature = "client")]
65pub use client_plugin::NetcodeClient;
66pub use crypto::{Key, generate_key, try_generate_key};
67pub use error::{Error, Result};
68#[cfg(feature = "server")]
69pub use server::{Callback, ConnectCallback, Server, ServerConfig};
70#[cfg(feature = "server")]
71pub use server_plugin::{NetcodeServer, TokenUserData};
72pub use token::{ConnectToken, ConnectTokenBuilder, InvalidTokenError};
73
74/// The client id from a connect token, must be unique for each client.
75pub(crate) type ClientId = u64;
76
77mod bytes;
78#[cfg(feature = "client")]
79pub mod client;
80mod crypto;
81pub(crate) mod error;
82mod packet;
83mod replay;
84#[cfg(feature = "server")]
85mod server;
86mod token;
87mod utils;
88
89#[cfg(feature = "client")]
90pub mod client_plugin;
91
92pub mod auth;
93#[cfg(feature = "server")]
94pub mod server_plugin;
95
96pub mod prelude {
97    pub use crate::auth::Authentication;
98
99    #[cfg(feature = "client")]
100    pub mod client {
101        pub use crate::client_plugin::{NetcodeClient, NetcodeClientPlugin, NetcodeConfig};
102    }
103
104    #[cfg(feature = "server")]
105    pub mod server {
106        pub use crate::server_plugin::{
107            NetcodeConfig, NetcodeServer, NetcodeServerPlugin, TokenUserData,
108        };
109    }
110}
111
112pub(crate) const MAC_BYTES: usize = 16;
113pub(crate) const MAX_PKT_BUF_SIZE: usize = 1300;
114pub(crate) const CONNECTION_TIMEOUT_SEC: i32 = 15;
115pub(crate) const PACKET_SEND_RATE_SEC: f64 = 1.0 / 10.0;
116
117/// The size of a private key in bytes.
118pub const PRIVATE_KEY_BYTES: usize = 32;
119/// The size of the user data in a connect token in bytes.
120pub const USER_DATA_BYTES: usize = 256;
121/// The size of the connect token in bytes.
122pub const CONNECT_TOKEN_BYTES: usize = 2048;
123/// The maximum size of a packet in bytes.
124pub const MAX_PACKET_SIZE: usize = 1200;
125/// The version of the netcode protocol implemented by this crate.
126pub const NETCODE_VERSION: &[u8; 13] = b"NETCODE 1.02\0";
lightyear_netcode/lib.rs

lightyear_netcode/
lib.rs
