Adding `evoke_core` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add evoke-core

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

evoke-core = "0.2.0"

The evoke_core library will be automatically available globally. Read the evoke_core library documentation.

Back to the crate overview.

Readme

evoke - easy netcode

Evoke provides building blocks to add networking capabilities to game engines.

Evoke supports:

Client-Server model with authoritative server

Client-Server

For client-server model Evoke automatically performs state replication with delta compression from server to client
and commands replication from clients to server.

Evoke makes no assumption of components used in the game.
User needs to register server::Descriptor in server and client::Descriptor in client for components that need to be replicated. There're blanket implementations for components that are comparable for equality and serializable.
For server and for client.

Core

Evoke's core provides very abstract client and server sessions, supporting sending and receiving commands like Connect, AddPlayer, SendInput, Update etc with generic payload. Evoke's core is available as separate crate evoke-core and re-exported from this crate as evoke::core

Unlike the evoke crate (this one) evoke-core does not depends on edict and can be used in any game engine, even written in language other than Rust if packed into FFI-ready library.

Usage

To start using Evoke simply configure and run ServerSystem and ClientSystem on server and client respectively.

Server

To configure ServerSystem provide descriptors for components replication and RemotePlayer implementation.

/// Information associated with player.
#[derive(serde::Deserialize)]
struct MyPlayerInfo;

/// Player input serializable representation.
#[derive(serde::Deserialize)]
struct MyPlayerInput;

/// This type drives player lifecycle and input processing.
struct MyRemotePlayer;

impl evoke::server::RemotePlayer for MyRemotePlayer {
    type Info = MyPlayerInfo;
    type Input = MyPlayerInput;

    fn accept(info: MyPlayerInfo, pid: evoke::PlayerId, world: &mut edict::World) -> eyre::Result<Self> {
        // Decide here whether accept new player based on `info` provided.
        // `Ok` signals that player is accepted.
        // `Err` signals that player is rejected.
        Ok(MyRemotePlayer)
    }

    fn apply_input(&mut self, entity: edict::EntityId, world: &mut edict::World, pack: MyPlayerInput) {
        // Input is associated with provided entity.
        // This code should transform input and put it where other systems would be able to consume it properly.
        // Usually it do the reverse of [`client::LocalPlayer::replicate`].
    }
}

/// Component that is own descriptor.
#[derive(Clone, Copy, PartialEq, serde::Serialize)]
pub struct MyComponent;

/// Prepare channel listener.
let listener = tokio::net::TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, 12523)).await?;

/// Build server system.
let mut server = evoke::server::ServerSystem::builder()
    .with_descriptor::<MyComponent>()
    .with_player::<MyRemotePlayer>()
    .build(listener);

let mut world = edict::World::new();
let scope = scoped_arena::Scope::new();

// game loop
loop {
    //
    // Game loop tick
    //

    // Run server every tick.
    server.run(&mut world, &scope);
}

Client

To configure ClientSystem provide descriptors for components replication and LocalPlayer implementation.

/// Information associated with player.
#[derive(serde::Serialize)]
struct MyPlayerInfo;

/// Player input serializable representation.
#[derive(serde::Serialize)]
struct MyPlayerInput;

/// This type drives player lifecycle and input processing.
struct MyLocalPlayer;

impl<'a> evoke::client::LocalPlayerPack<'a> for MyLocalPlayer {
    type Pack = &'a MyPlayerInput;
}

impl evoke::client::LocalPlayer for MyLocalPlayer {
    type Query = &'static MyPlayerInput;

    fn replicate<'a>(item: &'a MyPlayerInput, _scope: &'a scoped_arena::Scope<'_>) -> &'a MyPlayerInput {
        item
    }
}

/// Component that is own descriptor.
#[derive(Clone, Copy, PartialEq, serde::Deserialize)]
pub struct MyComponent;

/// Build client system.
let mut client = evoke::client::ClientSystem::builder()
    .with_descriptor::<MyComponent>()
    .with_player::<MyLocalPlayer>()
    .build();

let mut world = edict::World::new();
let scope = scoped_arena::Scope::new();

client.connect((std::net::Ipv4Addr::LOCALHOST, 12523), &scope).await?;


let player_id: evoke::PlayerId = client.add_player(&MyPlayerInfo, &scope).await?;
// The player can controls all entities to which server attaches same `PlayerId` as component.

// game loop
loop {
    //
    // Game loop tick
    //

    // Run client every tick.
    client.run(&mut world, &scope);
}

License

Licensed under either of

Apache License, Version 2.0, (license/APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (license/MIT or http://opensource.org/licenses/MIT)

at your option.

Contributions

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.

Adding evoke_core library as a dependency

Adding `evoke_core` library as a dependency