Bevy Replicon

The ServerSystems enum defines the various system sets used by the server-side replication logic. Understanding these helps in placing custom systems correctly within the replication lifecycle:

• ReceivePackets: (Runs in PreUpdate) Used by the messaging backend to receive packets and update ServerState.
• Receive: (Runs in PreUpdate) Systems that read data from ServerMessages.
• ReadRelations: (Runs in OnEnter for ServerState::Running) Builds the initial graph of related entities.
• IncrementTick: (Runs in ServerPlugin::tick_schedule) Increments the ServerTick.
• Send: (Runs in PostUpdate if ServerTick changes) Systems that write data to ServerMessages.
• SendPackets: (Runs in PostUpdate if ServerTick changes) Used by the messaging backend to send packets.

use bevy_replicon::server::ServerSystems;

// Example: Adding a system to the server's receive phase
app.add_systems(PreUpdate, my_custom_receive_system.in_set(ServerSystems::Receive));
// Example: Adding a system to the server's send phase
app.add_systems(PostUpdate, my_custom_send_system.in_set(ServerSystems::Send));

You can control how often mutations (component changes) are sent for entities to optimize network bandwidth. This is achieved through an accumulation mechanism: the difference between the last acknowledged tick and the current ServerTick is multiplied by the priority. When the result is $\ge 1.0$, the mutation is sent.

There are two ways to apply this:

1. Per-Entity (ReplicatePriority): Attach this component to a specific entity to set its base replication frequency. A priority of 0.5 means mutations are sent at most once every 2 ticks. A priority of 1.0 (default) sends mutations every tick.
2. Per-Client (PriorityMap): Attach this to an AuthorizedClient entity. It maps specific entities to priority values. This allows you to give certain clients higher or lower update rates for specific objects (e.g., a player sees their own character more frequently than distant NPCs).

Note: This only affects mutations. Component insertions and removals are always sent via ServerChannel::Updates immediately.

use bevy_replicon::server::{ReplicatePriority, PriorityMap};

// Set a low priority for a distant object (updates every 10 ticks)
commands.entity(entity).insert(ReplicatePriority(0.1));

// Or, override priorities for a specific client
commands.entity(client_entity).insert(PriorityMap::from_iter([(entity, 1.0), (other_entity, 0.2)]));

Bevy Replicon provides ClientState and ServerState as Bevy States. These are managed by your messaging backend and allow you to control when specific systems run based on the connection status.

Common States

• ClientState::Connecting / ClientState::Connected / ClientState::Disconnected
• ServerState::Running

Usage Patterns

• Continuous systems: Use .run_if(in_state(...)) to run systems every frame while in a specific state.
• Lifecycle systems: Use OnEnter(State) or OnExit(State) schedules to react to state transitions.
• Entity lifetimes: Use DespawnOnExit with these states to control entity lifetimes.

// Running systems based on state
app.add_systems(
    Update,
    (
        apply_damage.run_if(in_state(ServerState::Running)), // Server-only logic
        display_vfx.run_if(in_state(ClientState::Connected)), // Client-only logic
    ),
);

// Reacting to state changes
app.add_systems(OnEnter(ClientState::Connecting), display_connection_message)
   .add_systems(OnExit(ClientState::Connected), show_disconnected_message)
   .add_systems(OnEnter(ServerState::Running), initialize_match);

RepliconChannels is a resource that manages the communication channels used by Replicon. It distinguishes between channels used for sending and receiving based on whether the application is running as a client or a server.

Directionality

• On a Client:
  • RepliconChannels::client_channels() are used for sending data to the server.
  • RepliconChannels::server_channels() are used for receiving data from the server.
• On a Server:
  • RepliconChannels::server_channels() are used for sending data to clients.
  • RepliconChannels::client_channels() are used for receiving data from clients.

Note: If your backend does not distinguish between sending and receiving, you should create channels for both client and server by chaining them.

Custom Channels

Backends can define their own channels by writing an extension trait for RepliconChannels. Any custom channels created should have a delivery guarantee equal to or stronger than the ones they are replacing.

Reserved Channels

Replicon uses specific reserved channels for core replication logic:

Server-to-Client (ServerChannel)

• ServerChannel::Updates: An ordered reliable channel used for entity mappings, inserts, removals, and despawns. This ensures atomic updates and prevents outdated state.
• ServerChannel::Mutations: An unreliable channel used for component mutations. This allows for eventual consistency where the latest values are prioritized over missing intermediate ticks.

Client-to-Server (ClientChannel)

• ClientChannel::MutationAcks: An ordered reliable channel used by the client to acknowledge mutation messages received via ServerChannel::Mutations.

Channel Delivery Guarantees

All channels are defined by a Channel type specifying their reliability and ordering:

• Channel::Unreliable: Unreliable and unordered.
• Channel::Unordered: Reliable and unordered.
• Channel::Ordered: Reliable and ordered.

// Example of accessing channels (conceptual usage)
fn check_channels(channels: Res<RepliconChannels>) {
    let server_to_client = channels.server_channels();
    let client_to_server = channels.client_channels();
}

To integrate a custom messaging layer (like Renet or a custom UDP implementation) with Bevy Replicon, you must implement a backend that manages the communication flow between client and server. Because of Rust's orphan rules, Bevy Replicon does not provide a trait to implement; instead, your backend must interact with the following components:

1. Channels: Create channels defined in the RepliconChannels resource. You typically use an extension trait to convert your backend's configuration into the required channels.
2. State Management: Manage the ClientState (on the client) and ServerState (on the server).
3. Message Buffering: Update the ServerMessages and ClientMessages resources to move data between the network and the Replicon systems.
4. Client Lifecycle: Spawn and despawn entities with the ConnectedClient component.
5. Disconnection: React to DisconnectRequest messages sent by the server to queue a disconnection for a specific client.
6. Statistics (Optional): Update the ClientStats resource and ConnectedClientStats components to provide network telemetry.

Best Practices:

• Split your integration into separate client and server plugins.
• Use server and client features to allow users to disable unused parts at compile time.
• Refer to bevy_replicon_renet for a production-grade implementation reference.