Crate bevy_replicon

Quick start

Write the same logic that works for both multiplayer and single-player. The crate provides synchronization of components and network events between server and clients using the Renet library for the Bevy game engine.

Initialization

You need to add ReplicationPlugins to your app:

use bevy::prelude::*;
use bevy_replicon::prelude::*;

let mut app = App::new();
app.add_plugins(MinimalPlugins)
    .add_plugins(ReplicationPlugins);

This group contains necessary replication stuff and sets up the server and client plugins to let you host and join games from the same application.

If you are planning to separate client and server you can use disable() to disable ClientPlugin or ServerPlugin. You can also configure how often updates are sent from server to clients with ServerPlugin’s TickPolicy.:

app.add_plugins(MinimalPlugins).add_plugins(
    ReplicationPlugins
        .build()
        .disable::<ClientPlugin>()
        .set(ServerPlugin::new(TickPolicy::MaxTickRate(60))),
);

The plugin handles Renet initialization, you don’t need to add its plugins.

Component replication

It’s a process of sending component changes from server to clients in order to keep the world in sync.

Marking for replication

By default, no components are replicated. A component will be replicated if it has been registered for replication and its entity has the Replication component.

In other words you need two things to start replication :

1. Register component type for replication. Component should implement serde::Serialize and serde::Deserialize. You can use AppReplicationExt::replicate() to register the component for replication:

app.replicate::<DummyComponent>();

#[derive(Component, Deserialize, Serialize)]
struct DummyComponent;

If your component contains an entity then it cannot be deserialized as is because entity IDs are different on server and client. The client should do the mapping. Therefore, to replicate such components properly, they need implement MapNetworkEntities and registered using AppReplicationExt::replicate_mapped():

#[derive(Component, Deserialize, Serialize)]
struct MappedComponent(Entity);

impl MapNetworkEntities for MappedComponent {
    fn map_entities<T: Mapper>(&mut self, mapper: &mut T) {
        self.0 = mapper.map(self.0);
    }
}

By default all components serialized with bincode using bincode::DefaultOptions. If your component doesn’t implement serde traits or you want to serialize it partially you can use AppReplicationExt::replicate_with:

app.replicate_with::<Transform>(serialize_transform, deserialize_transform, replication_rules::remove_component::<Transform>);

/// Serializes only translation.
fn serialize_transform(
    component: Ptr,
    cursor: &mut Cursor<Vec<u8>>,
) -> Result<(), bincode::Error> {
    // SAFETY: Function called for registered `ComponentId`.
    let transform: &Transform = unsafe { component.deref() };
    bincode::serialize_into(cursor, &transform.translation)
}

/// Deserializes translation and creates [`Transform`] from it.
fn deserialize_transform(
    entity: &mut EntityMut,
    _entity_map: &mut ServerEntityMap,
    cursor: &mut Cursor<Bytes>,
    _tick: RepliconTick,
) -> Result<(), bincode::Error> {
    let translation: Vec3 = bincode::deserialize_from(cursor)?;
    entity.insert(Transform::from_translation(translation));

    Ok(())
}

2. You need to choose entities you want to replicate using Replication component. Just insert it to the entity you want to replicate. Only components marked for replication through AppReplicationExt::replicate() will be replicated.

If you need to disable replication for specific component for specific entity, you can insert Ignored<T> component and replication will be skipped for T.

Tick and fixed timestep games

The ServerPlugin sends replication data in PostUpdate any time the RepliconTick resource changes. By default, its incremented in PostUpdate per the TickPolicy.

If you set TickPolicy::Manual, you can increment RepliconTick at the start of your FixedTimestep game loop. This value can represent your simulation step, and is made available to the client in the custom deserialization, despawn and component removal functions.

One use for this is rollback networking: you may want to rollback time and apply the update for the tick frame, which is in the past, then resimulate.

Mapping to existing client entities

If you want the server to replicate an entity into a client entity that was already spawned on a client, see ClientEntityMap.

This can be useful for certain types of game. For example, spawning bullets on the client immediately without waiting on replication.

“Blueprints” pattern

The idea was borrowed from iyes_scene_tools. You don’t want to replicate all components because not all of them are necessary to send over the network. Components that computed based on other components (like GlobalTransform) can be inserted after replication. This can be easily done using a system with an Added query filter. This way, you detect when such entities are spawned into the world, and you can do any additional setup on them using code. For example, if you have a character with mesh, you can replicate only your Player component and insert necessary components after replication. If you want to avoid one frame delay, put your initialization systems to ClientSet::Receive:

app.replicate_with::<Transform>(serialize_transform, deserialize_transform, replication_rules::remove_component::<Transform>)
    .replicate::<Player>()
    .add_systems(PreUpdate, player_init_system.after(ClientSet::Receive));

fn player_init_system(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<ColorMaterial>>,
    spawned_players: Query<Entity, Added<Player>>,
) {
    for entity in &spawned_players {
        commands.entity(entity).insert((
            GlobalTransform::default(),
            Visibility::default(),
            ComputedVisibility::default(),
            meshes.add(Mesh::from(shape::Capsule::default())),
            materials.add(Color::AZURE.into()),
        ));
    }
}

#[derive(Component, Deserialize, Serialize)]
struct Player;

This pairs nicely with server state serialization and keeps saves clean. You can use replicate_into_scene to fill DynamicScene with replicated entities and their components.

Component relations

Sometimes components depend on each other. For example, Parent and Children. In this case, you can’t just replicate the Parent because you not only need to add it to the Children of the parent, but also remove it from the Children of the old one. In this case, you need to create a third component that correctly updates the other two when it changes, and only replicate that one. This crate provides ParentSync component that replicates Bevy hierarchy. For your custom components with relations you need to write your own with a similar pattern.

Network events

Network event replace RPCs (remote procedure calls) in other engines and, unlike components, can be sent both from server to clients and from clients to server.

From client to server

To send specific events from client to server, you need to register the event with ClientEventAppExt::add_client_event() instead of add_event(). These events will appear on server as FromClient wrapper event that contains sender ID and the sent event. We consider the authority machine (a single-player session or you are a server) to be a client with ID SERVER_ID, so in this case the FromClient will be emitted too. This way your game logic will work the same on client, server and in single-player session.

Events include SendPolicy to configure delivery guarantees (reliability and ordering). You can alternatively pass in SendType from Renet directly if you need custom configuration for a reliable policy’s resend_time.

app.add_client_event::<DummyEvent>(SendPolicy::Ordered)
    .add_systems(Update, event_sending_system);

fn event_sending_system(mut dummy_events: EventWriter<DummyEvent>) {
    dummy_events.send_default()
}

fn event_receiving_system(mut dummy_events: EventReader<FromClient<DummyEvent>>) {
    for FromClient { client_id, event } in &mut dummy_events {
        info!("received event {event:?} from client {client_id}");
    }
}

#[derive(Debug, Default, Deserialize, Event, Serialize)]
struct DummyEvent;

Just like components, if an event contains an entity, then the client should map it before sending it to the server. To do this, use ClientEventAppExt::add_mapped_client_event() and implement MapNetworkEntities:

use bevy::{prelude::*, utils::HashMap};
app.add_mapped_client_event::<MappedEvent>(SendPolicy::Ordered);

#[derive(Debug, Deserialize, Event, Serialize)]
struct MappedEvent(Entity);

impl MapNetworkEntities for MappedEvent {
    fn map_entities<T: Mapper>(&mut self, mapper: &mut T) {
        self.0 = mapper.map(self.0);
    }
}

There is also ClientEventAppExt::add_client_reflect_event() and ClientEventAppExt::add_mapped_client_reflect_event() for events that require reflection for serialization and deserialization (for example, events that contain Box<dyn Reflect>). To serialize such event you need to write serializer and deserializer manually because for such types you need access to AppTypeRegistry. It’s pretty straigtforward but requires some boilerplate. See BuildEventSerializer, BuildEventDeserializer and module common module in integration tests as example. Don’t forget to check what inside every Box<dyn Reflect> from a client, it could be anything!

From server to client

A similar technique is used to send events from server to clients. To do this, register the event with ServerEventAppExt::add_server_event() server event and send it from server using ToClients. This wrapper contains send parameters and the event itself. Just like events sent from the client, they will be emitted locally on the server (if SERVER_ID is not excluded from the send list):

app.add_server_event::<DummyEvent>(SendPolicy::Ordered)
    .add_systems(Update, event_sending_system);

fn event_sending_system(mut dummy_events: EventWriter<ToClients<DummyEvent>>) {
    dummy_events.send(ToClients {
        mode: SendMode::Broadcast,
        event: DummyEvent,
    });
}

fn event_receiving_system(mut dummy_events: EventReader<DummyEvent>) {
    for event in &mut dummy_events {
        info!("received event {event:?} from server");
    }
}

#[derive(Clone, Copy, Debug, Default, Deserialize, Event, Serialize)]
struct DummyEvent;

Just like with client events, if the event contains an entity, then ServerEventAppExt::add_mapped_server_event() should be used instead.

And for events with Box<dyn Reflect> you can use ServerEventAppExt::add_server_reflect_event() and ServerEventAppExt::add_mapped_server_reflect_event().

Server and client creation

To connect to the server or create it, you need to initialize the RenetClient and NetcodeClientTransport or RenetServer and NetcodeServerTransport resources from Renet. All Renet API is re-exported from this plugin.

Never create client and server resources in the same app for single-player, it will cause replication loop. Use the described pattern instead.

The only part of it that handled by this plugin is channels that used for events and component replication. These channels should be obtained from the NetworkChannels resource. So when creating server you need to initialize ConnectionConfig like this:

let network_channels = app.world.resource::<NetworkChannels>();
let connection_config = ConnectionConfig {
    server_channels_config: network_channels.server_channels(),
    client_channels_config: network_channels.client_channels(),
    ..Default::default()
};

For full example of how to initialize server or client see the example in the repository.

System sets and conditions

When configuring systems for multiplayer game, you often want to run some systems only on when you have authority over the world simulation (on server or in single-player session). For example, damage registration or procedural level generation systems. For this just add has_authority() condition on such system. If you want your systems to run only on frames when server send updates to clients use ServerSet::Send.

To check if you running server or client, you can use conditions based on RenetClient and RenetServer resources. They rarely used for gameplay systems (since you write the same logic for multiplayer and single-player!), but could be used for server creation / connection systems and corresponding UI.

Limits

To reduce packet size there are the following limits per replication update:

• Up to u16::MAX entities that have changed/added components with up to u8::MAX such components.
• Up to u16::MAX entities that have removed components with up to u8::MAX such components.
• Up to u16::MAX entities that were despawned.

Re-exports

• pub use bincode;

Modules

• client
• network_event
• parent_sync
• prelude
• renet
• replicon_core
• server
• transport

Structs

• RenetClientPlugin
• RenetServerPlugin
• ReplicationPlugins
  Plugin Group for all replicon plugins.