Minor doc updates (#439)

* Document visibility better

- Move example to the component.
- Clarify that it's a component for replicated clients.

* Update documentation on identifiers

Some backends don't have IDs that are persistent across reconnects.

* Clarify that `ClientEntityMap` inserted only after replication is started.

* Clarify that not all components are present on connected clients

* Clarify how to run examples

Author: Shatur

CHANGELOG.md

@@ -18,7 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Connected clients are now represented as entities with `ConnectedClient` components. Backends are responsible for spawning and despawning entities with this component. `ClientId` is accessible from `ConnectedClient::id` in case you need an identifier that is persistent across reconnects.
+- Connected clients are now represented as entities with `ConnectedClient` components. Backends are responsible for spawning and despawning entities with this component. `ClientId` is accessible from `ConnectedClient::id` in case you need to identify which client belongs to which connection.
 - Statistics for connected clients now accessible via `ClientStats` component.
 - Replicated entities now represented by connected clients with `ReplicatedClient` component.
 - To access visibility, use `ClientVisibility` component on replicated entities.

bevy_replicon_example_backend/README.md

@@ -10,3 +10,6 @@ To run an [example](examples) use the following command:
 ```bash
 cargo run -p bevy_replicon_example_backend --example <example name>
 ```
+
+In all examples, you need to start the server first since connecting via TCP in the Rust standard library is blocking.
+You won't have this issue with a real backend.

src/core/connected_client.rs

@@ -48,8 +48,7 @@ impl ConnectedClient {
 
     /// Returns client ID provided by backend.
     ///
-    /// Unlike [`Entity`], it's a persistent identifier that could
-    /// be used to identify the same client after reconnects.
+    /// Can be used to identify which client belongs to which connection.
     ///
     /// See also [`ClientIdMap`].
     pub fn id(&self) -> ClientId {

src/lib.rs

@@ -53,7 +53,9 @@ If you need to send information from clients to the server, use
 [events](#network-events-and-triggers).
 
 Replication is enabled by default for all connected clients via [`ReplicatedClient`] component.
-It can be disabled via [`ServerPlugin::replicate_after_connect`] is set to `false`.
+It can be disabled by setting [`ServerPlugin::replicate_after_connect`] to `false`. Note that
+some components on connected clients are only present after replication starts.
+See the required components for [`ReplicatedClient`].
 
 For implementation details see [`ReplicationChannel`](core::channels::ReplicationChannel).
 
@@ -449,45 +451,8 @@ basis.
 You can control which parts of the world are visible for each client by setting visibility policy
 in [`ServerPlugin`] to [`VisibilityPolicy::Whitelist`] or [`VisibilityPolicy::Blacklist`].
 
-In order to set which entity is visible, you need to use the [`ClientVisibility`] component
-on replicated clients.
-
-```
-# use bevy::prelude::*;
-# use bevy_replicon::prelude::*;
-# let mut app = App::new();
-app.add_plugins((
-    MinimalPlugins,
-    RepliconPlugins.set(ServerPlugin {
-        visibility_policy: VisibilityPolicy::Whitelist, // Makes all entities invisible for clients by default.
-        ..Default::default()
-    }),
-))
-.add_systems(Update, update_visibility.run_if(server_running));
-
-/// Disables the visibility of other players' entities that are further away than the visible distance.
-fn update_visibility(
-    mut clients: Query<&mut ClientVisibility>,
-    moved_players: Query<(&Transform, &PlayerOwner), Changed<Transform>>,
-    other_players: Query<(Entity, &Transform, &PlayerOwner)>,
-) {
-    for (moved_transform, &owner) in &moved_players {
-        let mut visibility = clients.get_mut(*owner).unwrap();
-        for (entity, transform, _) in other_players
-            .iter()
-            .filter(|(.., &other_owner)| *other_owner != *owner)
-        {
-            const VISIBLE_DISTANCE: f32 = 100.0;
-            let distance = moved_transform.translation.distance(transform.translation);
-            visibility.set_visibility(entity, distance < VISIBLE_DISTANCE);
-        }
-    }
-}
-
-/// Points to client entity.
-#[derive(Component, Deref, Clone, Copy)]
-struct PlayerOwner(Entity);
-```
+To set which entity is visible, you need to use the [`ClientVisibility`] component
+on replicated clients (not to be confused with replicated entities).
 
 Check also the [corresponding section](https://github.com/projectharmonia/bevy_replicon#visibility)
 in our README for more high-level abstractions.

src/server/client_entity_map.rs

@@ -18,7 +18,10 @@ be inserted into the client's [`ServerEntityMap`](crate::core::server_entity_map
 to propagate the mappings ensures any replication messages related to the pre-mapped
 server entities will synchronize with updating the client's [`ServerEntityMap`](crate::core::server_entity_map::ServerEntityMap).
 
-### Example:
+It's a required component for [`ReplicatedClient`](super::ReplicatedClient). So if you want to map entities before enabling
+replication, you need to insert this component, already filled with entities.
+
+### Examples
 
 ```
 use bevy::prelude::*;

src/server/client_visibility.rs

@@ -8,7 +8,47 @@ use super::VisibilityPolicy;
 
 /// Entity visibility settings for a client.
 ///
-/// Present on connected clients after [`ReplicatedClient`](super::ReplicatedClient) insertion.
+/// Dynamically marked as required for [`ReplicatedClient`](super::ReplicatedClient)
+/// based on the value from [`ServerPlugin::visibility_policy`](super::ServerPlugin::visibility_policy).
+///
+/// # Examples
+///
+/// ```
+/// # use bevy::prelude::*;
+/// # use bevy_replicon::prelude::*;
+/// # let mut app = App::new();
+/// app.add_plugins((
+///     MinimalPlugins,
+///     RepliconPlugins.set(ServerPlugin {
+///         visibility_policy: VisibilityPolicy::Whitelist, // Makes all entities invisible for clients by default.
+///         ..Default::default()
+///     }),
+/// ))
+/// .add_systems(Update, update_visibility.run_if(server_running));
+///
+/// /// Disables the visibility of other players' entities that are further away than the visible distance.
+/// fn update_visibility(
+///     mut clients: Query<&mut ClientVisibility>,
+///     moved_players: Query<(&Transform, &PlayerOwner), Changed<Transform>>,
+///     other_players: Query<(Entity, &Transform, &PlayerOwner)>,
+/// ) {
+///     for (moved_transform, &owner) in &moved_players {
+///         let mut visibility = clients.get_mut(*owner).unwrap();
+///         for (entity, transform, _) in other_players
+///             .iter()
+///             .filter(|(.., &other_owner)| *other_owner != *owner)
+///         {
+///             const VISIBLE_DISTANCE: f32 = 100.0;
+///             let distance = moved_transform.translation.distance(transform.translation);
+///             visibility.set_visibility(entity, distance < VISIBLE_DISTANCE);
+///         }
+///     }
+/// }
+///
+/// /// Points to client entity.
+/// #[derive(Component, Deref, Clone, Copy)]
+/// struct PlayerOwner(Entity);
+/// ```
 #[derive(Component)]
 pub struct ClientVisibility {
     /// Wrapped enum to make its fields private.