Struct Client

pub struct Client<T: Transceiver, Ctx = ()> { /* private fields */ }

The netcode client.

To create a client one should obtain a connection token from a web backend (by REST API or other means).
The client will use this token to connect to the dedicated netcode server.

While the client is connected, it can send and receive packets to and from the server.
Similarly to the server, the client should be updated at a fixed rate (e.g., 60Hz) to process incoming packets and send outgoing packets.

Example

let mut client = Client::new(&token_bytes).unwrap();
client.connect();

let start = Instant::now();
let tick_rate = Duration::from_secs_f64(1.0 / 60.0);
loop {
    client.update(start.elapsed().as_secs_f64());
    if client.is_connected() {
        client.send(b"Hello World!").unwrap();
    }
    if let Some(packet) = client.recv() {
        println!("received packet: {:?}", packet);
    }
    thread::sleep(tick_rate);
}

Implementations

impl Client<NetcodeSocket>

pub fn new(token_bytes: &[u8]) -> Result<Self>

Create a new client with a default configuration.

Example

// Generate a connection token for the client
let private_key = netcode::generate_key();
let token_bytes = ConnectToken::build("127.0.0.1:0", 0, 0, private_key)
    .generate()
    .unwrap()
    .try_into_bytes()
    .unwrap();

let mut client = Client::new(&token_bytes).unwrap();

impl<Ctx> Client<NetcodeSocket, Ctx>

pub fn with_config(token_bytes: &[u8], cfg: ClientConfig<Ctx>) -> Result<Self>

Create a new client with a custom configuration.
Callbacks with context can be registered with the client to be notified when the client changes states.
See ClientConfig for more details.

Example

struct MyContext {};
let cfg = ClientConfig::with_context(MyContext {}).on_state_change(|from, to, _ctx| {
   assert_eq!(from, ClientState::Disconnected);
   assert_eq!(to, ClientState::SendingConnectionRequest);
});

let mut client = Client::with_config(&token_bytes, cfg).unwrap();

impl<T: Transceiver, Ctx> Client<T, Ctx>

pub fn with_config_and_transceiver( token_bytes: &[u8], cfg: ClientConfig<Ctx>, trx: T, ) -> Result<Self>

Creates a new client instance with the given configuration and transceiver.

This is useful if you want to use a custom transceiver implementation, in any other case you should use Client::new or Client::with_config.

Examples

use netcode::{Client, ClientConfig, ConnectToken, Transceiver};

struct MyTransceiver {
   // ...
};

impl Transceiver for MyTransceiver {
   // ...
}

let cfg = ClientConfig::default();
let trx = MyTransceiver { /* .. */ };

let client = Client::with_config_and_transceiver(&token_bytes, cfg, trx).unwrap();

pub fn connect(&mut self)

Prepares the client to connect to the server.

This function does not perform any IO, it only readies the client to send/receive packets on the next call to update.

pub fn update(&mut self, time: f64)

Updates the client.

• Updates the client’s elapsed time.
• Receives packets from the server, any received payload packets will be queued.
• Sends keep-alive or request/response packets to the server to establish/maintain a connection.
• Updates the client’s state - checks for timeouts, errors and transitions to new states.

This method should be called regularly, probably at a fixed rate (e.g., 60Hz).

Panics

Panics if the client can’t send or receive packets. For a non-panicking version, use try_update.

pub fn try_update(&mut self, time: f64) -> Result<()>

The fallible version of update.

Returns an error if the client can’t send or receive packets.

pub fn recv(&mut self) -> Option<Vec<u8>>

Receives a packet from the server, if one is available in the queue.

The packet will be returned as a Vec<u8>.

If no packet is available, None will be returned.

Example

let mut client = Client::new(&token_bytes).unwrap();
client.connect();

let start = Instant::now();
let tick_rate = Duration::from_secs_f64(1.0 / 60.0);
loop {
    client.update(start.elapsed().as_secs_f64());
    if let Some(packet) = client.recv() {
        // ...
    }
    thread::sleep(tick_rate);
}

pub fn send(&mut self, buf: &[u8]) -> Result<()>

Sends a packet to the server.

The provided buffer must be smaller than MAX_PACKET_SIZE.

pub fn disconnect(&mut self) -> Result<()>

Disconnects the client from the server.

The client will send a number of redundant disconnect packets to the server before transitioning to Disconnected.

pub fn addr(&self) -> SocketAddr

Gets the local SocketAddr that the client is bound to.

pub fn state(&self) -> ClientState

Gets the current state of the client.

pub fn is_error(&self) -> bool

Returns true if the client is in an error state.

pub fn is_pending(&self) -> bool

Returns true if the client is in a pending state.

pub fn is_connected(&self) -> bool

Returns true if the client is connected to a server.

pub fn is_disconnected(&self) -> bool

Returns true if the client is disconnected from the server.