Expand description
Entity replication layer for lightyear, built on top of bevy_replicon.
This crate handles replicating ECS entities and their components across the
network. It wraps bevy_replicon’s low-level replication machinery and adds
lightyear-specific features: prediction/interpolation targets, network
visibility, authority, hierarchy propagation, and pre-spawning.
§Getting started
Add Replicate to an entity to start replicating it. On the server, you
typically specify which clients should receive the entity:
commands.spawn((
Replicate::to_clients(NetworkTarget::All),
PredictionTarget::to_clients(NetworkTarget::Single(client_id)),
InterpolationTarget::to_clients(NetworkTarget::AllExceptSingle(client_id)),
MyComponent(42),
));§Key concepts
§Replication targets
Replicate (alias for ReplicationTarget<()>) controls which peers
receive an entity. PredictionTarget and InterpolationTarget further
control which clients run prediction or interpolation for that entity.
Each target uses a ReplicationMode to specify the set of recipients.
A ReplicationSender component must be present on the link entity
(the entity that represents the connection to a remote peer) to enable
outgoing replication through that link.
§Hierarchy propagation
When an entity with Replicate has children (via ChildOf), those
children automatically receive a ReplicateLike component pointing back
to the root. This clones the root’s replication configuration onto the
child so the entire hierarchy replicates with the same visibility rules.
Use DisableReplicateHierarchy on a child to opt out.
You can also manually add ReplicateLike on any entity.
§Visibility
VisibilityExt::gain_visibility and VisibilityExt::lose_visibility
let you dynamically show or hide an entity for a specific client.
Visibility changes propagate through ReplicateLikeChildren so that
hiding a parent also hides its replicated descendants.
For interest management based on spatial regions, see RoomPlugin.
§Authority and control
ControlledBy marks which link entity “owns” a replicated entity.
HasAuthority indicates the local peer currently has authority.
See AuthorityBroker for tracking authority across the replication
hierarchy.
Authority is currently not working since replicon only supports server to client replication.
§Pre-spawning
PreSpawned allows both client and server to spawn the same entity
independently, then match them via a deterministic hash. This enables
zero-latency predicted spawns (e.g. bullets, projectiles).
Modules§
- authority
- Module related to the concept of
Authority - channels
- checkpoint
- Maps Replicon delivery checkpoints onto Lightyear simulation time.
- client
- control
- delta
- Logic related to delta compression (sending only the changes between two states, instead of the new state)
- hierarchy
- This module is responsible for making sure that parent-children hierarchies are replicated correctly.
- metadata
- prelude
- prespawn
- Handles spawning entities that are predicted
- receive
- registry
- send
- Replication send-side: target components, visibility rules, and replication state.
- server
- visibility