Crate lightyear_netcode

Source
Expand description

Netcode.io protocol to establish a connection on top of an unreliable transport

§netcode

The netcode crate implements the netcode network protocol created by Glenn Fiedler.

netcode is a UDP-based protocol that provides secure, connection-based data transfer.

Since the protocol is meant to be used to implement multiplayer games, its API is designed to be used in a game loop, where the server and client are updated at a fixed rate (e.g., 60Hz).

§Protocol

The three main components of the netcode protocol are:

The protocol does not specify how the web backend should be implemented, but it should probably be a typical HTTPS server that provides a means for clients to authenticate and request connection tokens.

The sequence of operations for a client to connect to a server is as follows:

  1. The Client authenticates with the web backend service. (e.g., by OAuth or some other means)
  2. The authenticated Client requests a connection token from the web backend.
  3. The web backend generates a ConnectToken and sends it to the Client. (e.g., as a JSON response)
  4. The Client uses the token to connect to a dedicated Server.
  5. The Server makes sure the token is valid and allows the Client to connect.
  6. The Client and Server can now exchange encrypted and signed UDP packets.

To learn more about the netcode protocol, see the upstream specification.

§Server

The netcode server is responsible for managing the state of the clients and sending/receiving packets.

The server should run as a part of the game loop, process incoming packets and send updates to the clients.

To create a server:

  • Provide the address you intend to bind to.
  • Provide the protocol id - a u64 that uniquely identifies your app.
  • Provide a private key - a u8 array of length 32. If you don’t have one, you can generate one with netcode::generate_key().
  • Optionally provide a ServerConfig - a struct that allows you to customize the server’s behavior.

§Client

The netcode client connects to the server and communicates using the same protocol.

Like the server, the game client should run in a loop to process incoming data, send updates to the server, and maintain a stable connection.

To create a client:

  • Provide a connect token - a u8 array of length 2048 serialized from a ConnectToken.
  • Optionally provide a ClientConfig - a struct that allows you to customize the client’s behavior.

Re-exports§

pub use client_plugin::NetcodeClient;
pub use server_plugin::NetcodeServer;

Modules§

auth
client
client_plugin
prelude
server_plugin

Structs§

ConnectToken
A token containing all the information required for a client to connect to a server.
ConnectTokenBuilder
A builder that can be used to generate a connect token.
Server
The netcode server.
ServerConfig
Configuration for a server.

Enums§

Error
An error that can occur in the netcode crate.
InvalidTokenError
An error that can occur when de-serializing a connect token from bytes.

Constants§

CONNECT_TOKEN_BYTES
The size of the connect token in bytes.
MAX_PACKET_SIZE
The maximum size of a packet in bytes.
NETCODE_VERSION
The version of the netcode protocol implemented by this crate.
PRIVATE_KEY_BYTES
The size of a private key in bytes.
USER_DATA_BYTES
The size of the user data in a connect token in bytes.

Functions§

generate_key
Generates a random key for encrypting and decrypting packets and connect tokens.
try_generate_key
The fallible version of generate_key.

Type Aliases§

Callback
Key
A 32-byte array, used as a key for encrypting and decrypting packets and connect tokens.
Result
The result type for all the public methods that can return an error in this crate.