Trait bevy_replicon::core::replication_rules::AppRuleExt

pub trait AppRuleExt {
    // Required methods
    fn replicate_with<C>(&mut self, rule_fns: RuleFns<C>) -> &mut Self
       where C: Component;
    fn replicate_group<C: GroupReplication>(&mut self) -> &mut Self;

    // Provided methods
    fn replicate<C>(&mut self) -> &mut Self
       where C: Component + Serialize + DeserializeOwned { ... }
    fn replicate_mapped<C>(&mut self) -> &mut Self
       where C: Component + Serialize + DeserializeOwned + MapEntities { ... }
}

Replication functions for App.

Required Methods

fn replicate_with<C>(&mut self, rule_fns: RuleFns<C>) -> &mut Self

where C: Component,

Same as Self::replicate, but uses the specified functions for serialization and deserialization.

Can be used to customize how the component will be passed over the network or for components that don’t implement Serialize or DeserializeOwned.

You can also override how the component will be written, see AppMarkerExt.

Examples

use std::io::Cursor;

use bevy::prelude::*;
use bevy_replicon::{
    core::{
        ctx::{SerializeCtx, WriteCtx},
        replication_registry::rule_fns::RuleFns,
    },
    prelude::*,
};

app.replicate_with(RuleFns::new(
    serialize_translation,
    deserialize_translation,
));

/// Serializes only `translation` from [`Transform`].
fn serialize_translation(
    _ctx: &SerializeCtx,
    transform: &Transform,
    cursor: &mut Cursor<Vec<u8>>,
) -> bincode::Result<()> {
    bincode::serialize_into(cursor, &transform.translation)
}

/// Deserializes `translation` and creates [`Transform`] from it.
fn deserialize_translation(
    _ctx: &mut WriteCtx,
    cursor: &mut Cursor<&[u8]>,
) -> bincode::Result<Transform> {
    let translation: Vec3 = bincode::deserialize_from(cursor)?;
    Ok(Transform::from_translation(translation))
}

fn replicate_group<C: GroupReplication>(&mut self) -> &mut Self

Creates a replication rule for a group of components.

A group will only be replicated if all its components are present on the entity.

If a group contains a single component, it will work the same as Self::replicate.

If an entity matches multiple groups, functions from a group with higher priority will take precedence for overlapping components. For example, a rule with Transform and a Player marker will take precedence over a single Transform rule.

If you remove a single component from a group, only a single removal will be sent to clients. Other group components will continue to be present on both server and clients. Replication for them will be stopped, unless they match other rules.

We provide blanket impls for tuples to replicate them as-is, but a user could manually implement the trait to customize how components will be serialized and deserialized. For details see GroupReplication.

Panics

Panics if debug_assertions are enabled and any rule is a subset of another.

Examples

Replicate Transform and user’s Player marker only if both of them are present on an entity:

use bevy::prelude::*;
use bevy_replicon::prelude::*;
use serde::{Deserialize, Serialize};

app.replicate_group::<(Transform, Player)>();

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

Provided Methods

fn replicate<C>(&mut self) -> &mut Self

where C: Component + Serialize + DeserializeOwned,

Creates a replication rule for a single component.

The component will be replicated if its entity contains the Replicated marker component.

Component will be serialized and deserialized as-is using bincode. To customize it, use Self::replicate_group.

If your component contains any Entity inside, use Self::replicate_mapped.

See also Self::replicate_with and the section on components from the quick start guide.

fn replicate_mapped<C>(&mut self) -> &mut Self

where C: Component + Serialize + DeserializeOwned + MapEntities,

Same as Self::replicate, but additionally maps server entities to client inside the component after receiving.

Always use it for components that contain entities.

See also Self::replicate.

Examples

app.replicate_mapped::<MappedComponent>();

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

impl MapEntities for MappedComponent {
    fn map_entities<T: EntityMapper>(&mut self, mapper: &mut T) {
        self.0 = mapper.map_entity(self.0);
    }
}

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl AppRuleExt for App

fn replicate_with<C>(&mut self, rule_fns: RuleFns<C>) -> &mut Self

where C: Component,

fn replicate_group<C: GroupReplication>(&mut self) -> &mut Self

Implementors