2 stable releases

1.4.0 Aug 17, 2024
1.3.0 Feb 8, 2024

#1209 in Network programming

21 downloads per month

MIT license

165KB
3.5K SLoC

netcode rust implementation
ci license crate

demo

Protocol

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

netcode is a simple connection based client/server protocol built on top of UDP.

See the official upstream specification to learn more about how the protocol works.

Install

Run the following Cargo command in your project directory:

cargo add netcode-rs

Or add the following line to your Cargo.toml:

[dependencies]
netcode-rs = "1.4.0"

NOTE: While the crate name is netcode-rs, the library name is actually netcode.
This means that even though you used cargo add netcode-rs to add the dependency, you will need to write use netcode::* (and not use netcode_rs::*) to use it.

I know this is confusing, and I know that -rs crate names are frowned upon.
Unfortunately the original netcode crate is unmaintained and its maintainer is unreachable, so I could not get the ownership for the crate name. I didn't want to use names like netcode2 to avoid confusion with the netcode protocol versions.

Examples

server

use std::{thread, time::{Instant, Duration}};
use netcode::{Server, MAX_PACKET_SIZE};

// Create a server
let protocol_id = 0x11223344u64; // a unique number that must match the client's protocol id
let private_key = netcode::generate_key(); // you can also provide your own key
let mut server = Server::new("0.0.0.0:5555", protocol_id, private_key).unwrap();

// Run the server at 60Hz
let start = Instant::now();
let tick_rate = Duration::from_secs_f64(1.0 / 60.0);
loop {
    let elapsed = start.elapsed().as_secs_f64();
    server.update(elapsed);
    while let Some((packet, from)) = server.recv() {
       // ...
    }
    thread::sleep(tick_rate);
}

client

use std::{thread, time::{Instant, Duration}};
use netcode::{ConnectToken, Client, MAX_PACKET_SIZE};

// Generate a connection token for the client
let protocol_id = 0x11223344u64; // a unique number that must match the server's protocol id
let private_key = netcode::generate_key(); // you can also provide your own key
let client_id = 123u64; // globally unique identifier for an authenticated client
let server_address = "my-domain.com:5555"; // the server's public address (can also be multiple addresses)
let connect_token = ConnectToken::build(server_address, protocol_id, client_id, private_key).generate().unwrap();

// Start the client
let token_bytes = connect_token.try_into_bytes().unwrap();
let mut client = Client::new(&token_bytes).unwrap();
client.connect();

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

See examples for more.

Planned Features

Dependencies

~1.5–8.5MB
~76K SLoC