You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Write the same logic that works for both multiplayer and single-player. The crate provides synchronization of components and events between the server and clients using the [Renet](https://github.com/lucaspoffo/renet) library for the [Bevy game engine](https://bevyengine.org).
5
+
Write the same logic that works for both multiplayer and single-player. The crate provides synchronization of components and network events between the server and clients using the [Renet](https://github.com/lucaspoffo/renet) library for the [Bevy game engine](https://bevyengine.org).
6
6
7
7
## Initialization
8
8
@@ -17,7 +17,7 @@ app.add_plugins(MinimalPlugins)
17
17
.add_plugins(ReplicationPlugins);
18
18
```
19
19
20
-
This group contains necessary replication stuff and setups server and client plugins to let you host and join games from the same application. If you planning to separate client and server you can use [`PluginGroupBuilder::disable`] to disable [`ClientPlugin`] or [`ServerPlugin`]. You can also configure how often updates are sent from server to clients:
20
+
This group contains necessary replication stuff and setups server and client plugins to let you host and join games from the same application. If you planning to separate client and server you can use [`PluginGroupBuilder::disable()`] to disable [`ClientPlugin`] or [`ServerPlugin`]. You can also configure how often updates are sent from server to clients:
21
21
22
22
```rust
23
23
# usebevy::prelude::*;
@@ -41,7 +41,7 @@ It's a process of sending component changes from server to clients in order to k
41
41
42
42
By default, no components are replicated. To start replication, you need two things:
43
43
44
-
1. Mark component type for replication. Component should implement [`Reflect`], have `#[reflect(Component)]`. You can use [`replication_core::AppReplicationExt::replicate`] to mark the component for replication:
44
+
1. Mark component type for replication. Component should implement [`Reflect`], have `#[reflect(Component)]`. You can use [`AppReplicationExt::replicate()`] to mark the component for replication:
This also automatically registers the specified type in [`bevy::reflect::TypeRegistryInternal`], so you don't need to call [`App::register_type()`] if you replicating the type.
58
+
This also automatically registers the specified type, so you don't need to call [`App::register_type()`] if you replicating the type.
59
59
60
-
If your component contains [`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 and reflect [`bevy::ecs::entity::MapEntities`]:
60
+
If your component contains [`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 [`bevy::ecs::entity::MapEntities`] and have `#[reflect(MapEntity)]`:
@@ -84,7 +84,7 @@ impl FromWorld for MappedComponent {
84
84
}
85
85
```
86
86
87
-
2. You need to choose entities you want to replicate using [`replication_core::Replication`] component. Just insert it to the entity you want to replicate. Only components marked for replication through [`replication_core::AppReplicationExt::replicate`] will be replicated.
87
+
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.
88
88
89
89
If you need more control, you add special rules. For example, if you don't want to replicate [`Transform`] on entities marked for replication if your special component is present, you can do the following:
90
90
@@ -139,19 +139,19 @@ fn player_init_system(
139
139
structPlayer;
140
140
```
141
141
142
-
If your game have save states you probably want to re-use the same logic to keep you saves clean. Also, although `Handle<T>` can technically be serialized, they won't be valid after deserialization.
142
+
If your game have save states you probably want to re-use the same logic to keep you saves clean. Also, although things like `Handle<T>` can technically be serialized, they won't be valid after deserialization.
143
143
144
144
### Component relations
145
145
146
-
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 [`parent_sync::ParentSync`] component that does just that for Bevy hierarchy. For your custom components with relations you need to write your own with a similar pattern.
146
+
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 does just that for Bevy hierarchy. For your custom components with relations you need to write your own with a similar pattern.
147
147
148
-
## Event replication
148
+
## Network events
149
149
150
-
Event replication replace RPCs (remote procedure calls) in other engines and, unlike components, can be sent both from server to clients and from clients to server.
150
+
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.
151
151
152
152
### From client to server
153
153
154
-
To replicate your event from client to server just create your event as a client event. These events will be replicated to server as [`network_event::client_event::FromClient<T>`] wrapper that contains sender ID and the replicated event. If you are not a client (a single-player session or you are host), the [`network_event::client_event::FromClient<T>`] will also be emitted with[`server::SERVER_ID`]as sender ID. This way your game logic will work the same on client, server and in single-player session.
154
+
To send specific events from server to client, you need to register the event with [`ClientEventAppExt::add_client_event()`] instead of [`App::add_event()`]. These events will appear on server as [`FromClient`] wrapper event that contains sender ID and the sent event. We consider authority machine (a single-player session or you are server) and as a client with ID [`SERVER_ID`], so in this case the[`FromClient`] will will be emitted too. This way your game logic will work the same on client, server and in single-player session.
Just like components, if an event contains [`Entity`], then the client should map it before sending it to the server. To do this, use `add_mapped_client_event`:
179
+
Just like components, if an event contains [`Entity`], then the client should map it before sending it to the server. To do this, use [`ClientEventAppExt::add_mapped_client_event()`]:
180
180
181
181
```rust
182
182
# usebevy_replicon::prelude::*;
@@ -199,7 +199,7 @@ impl MapEntities for MappedEvent {
199
199
200
200
### From server to client
201
201
202
-
A similar technique is used to replicate an event from server to clients. To do this, create a server event and send it from server using [`network_event::server_event::ToClients<T>`]. 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::SERVER_ID`] is not excluded from the send list):
202
+
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):
Just like with client events, if the event contains [`Entity`], then `add_mapped_server_event` should be used instead.
230
+
Just like with client events, if the event contains [`Entity`], then [`ServerEventAppExt::add_mapped_server_event()`] should be used instead.
231
231
232
232
## Server and client creation
233
233
234
-
To connect to the server or create it, you need to initialize the [`bevy_renet::renet::RenetClient`] or [`bevy_renet::renet::RenetServer`] resource from Renet. All Renet API is re-exported from this plugin.
234
+
To connect to the server or create it, you need to initialize the [`renet::RenetClient`] or [`renet::RenetServer`] resource from Renet. All Renet API is re-exported from this plugin.
235
235
236
-
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 [`replication_core::NetworkChannels`] resource. So when creating server you need to initialize [`bevy_renet::renet::RenetConnectionConfig`] like this:
236
+
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 [`renet::RenetConnectionConfig`] like this:
237
237
238
238
```rust
239
239
# usebevy::prelude::*;
@@ -248,15 +248,15 @@ let connection_config = RenetConnectionConfig {
248
248
};
249
249
```
250
250
251
-
For client you need to swap [`replication_core::NetworkChannels::server_channels`] and [`replication_core::NetworkChannels::client_channels()`].
251
+
For client you need to swap [`NetworkChannels::server_channels()`] and [`NetworkChannels::client_channels()`].
252
252
253
253
For full example of how to initialize server or client see the example in the repository.
254
254
255
255
## System sets and states
256
256
257
-
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 your systems to the [`server::ServerSet::Authority`] system set. If you want your systems to run only on frames when server send updates to clients use [`server::ServerSet::Tick`].
257
+
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 your systems to the [`ServerSet::Authority`] system set. If you want your systems to run only on frames when server send updates to clients use [`ServerSet::Tick`].
258
258
259
-
We also have states for server and client: [`server::ServerState`] or [`client::ClientState`]. 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.
259
+
We also have states for server and client: [`ServerState`] or [`ClientState`]. 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.
0 commit comments