Struct bevy_replicon::server::client_entity_map::ClientEntityMap

pub struct ClientEntityMap(/* private fields */);

A resource that exists on the server for mapping server entities to entities that clients have already spawned. The mappings are sent to clients as part of replication and injected into the client’s ServerEntityMap.

Sometimes you don’t want to wait for the server to spawn something before it appears on the client – when a client performs an action, they can immediately simulate it on the client, then match up that entity with the eventual replicated server spawn, rather than have replication spawn a brand new entity on the client.

In this situation, the client can send the server its pre-spawned entity id, then the server can spawn its own entity and inject the ClientMapping into its ClientEntityMap.

Replication packets will send a list of such mappings to clients, which will be inserted into the client’s ServerEntityMap. Using replication to propagate the mappings ensures any replication messages related to the pre-mapped server entities will synchronize with updating the client’s ServerEntityMap.

Example:

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

#[derive(Event)]
struct SpawnBullet(Entity);

#[derive(Component)]
struct Bullet;

/// System that shoots a bullet and spawns it on the client.
fn shoot_bullet(mut commands: Commands, mut bullet_events: EventWriter<SpawnBullet>) {
    let entity = commands.spawn(Bullet).id();
    bullet_events.send(SpawnBullet(entity));
}

/// Validation to check if client is not cheating or the simulation is correct.
///
/// Depending on the type of game you may want to correct the client or disconnect it.
/// In this example we just always confirm the spawn.
fn confirm_bullet(
    mut commands: Commands,
    mut bullet_events: EventReader<FromClient<SpawnBullet>>,
    mut entity_map: ResMut<ClientEntityMap>,
) {
    for FromClient { client_id, event } in bullet_events.read() {
        let server_entity = commands.spawn(Bullet).id(); // You can insert more components, they will be sent to the client's entity correctly.

        entity_map.insert(
            *client_id,
            ClientMapping {
                server_entity,
                client_entity: event.0,
            },
        );
    }
}

If the client is connected and receives the replication data for the server entity mapping, replicated data will be applied to the client’s original entity instead of spawning a new one. You can detect when the mapping is replicated by querying for Added<Replicated> on your original client entity.

If client’s original entity is not found, a new entity will be spawned on the client, just the same as when no client entity is provided.

Implementations

impl ClientEntityMap

pub fn insert(&mut self, client_id: ClientId, mapping: ClientMapping)

Registers mapping for a client entity pre-spawned by the specified client.

This will be sent as part of replication data and added to the client’s ServerEntityMap.

Trait Implementations

impl Debug for ClientEntityMap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ClientEntityMap

fn default() -> ClientEntityMap

Returns the “default value” for a type.

impl Deref for ClientEntityMap

type Target = HashMap<ClientId, Vec<ClientMapping>>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Resource for ClientEntityMap

where Self: Send + Sync + 'static,