naia_client/world/
entity_mut.rs

1use std::hash::Hash;
2
3use naia_shared::{
4    AuthorityError, EntityAuthStatus, ReplicaMutWrapper, ReplicatedComponent, WorldMutType,
5};
6
7use crate::{world::entity_owner::EntityOwner, Client};
8use naia_shared::Publicity;
9
10/// Scoped mutable handle for a client-owned entity.
11///
12/// Obtained from [`Client::entity_mut`]. Borrows `Client` for the duration of
13/// the handle, so only one `EntityMut` can be live at a time.
14///
15/// Unlike the server counterpart, the client has no static-entity concept —
16/// components may be inserted or removed freely while the client holds
17/// authority over the entity.
18pub struct EntityMut<'s, E: Copy + Eq + Hash + Send + Sync, W: WorldMutType<E>> {
19    client: &'s mut Client<E>,
20    world: W,
21    entity: E,
22}
23
24impl<'s, E: Copy + Eq + Hash + Send + Sync, W: WorldMutType<E>> EntityMut<'s, E, W> {
25    pub(crate) fn new(client: &'s mut Client<E>, world: W, entity: &E) -> Self {
26        Self {
27            client,
28            world,
29            entity: *entity,
30        }
31    }
32
33    /// Returns the underlying entity identifier.
34    pub fn id(&self) -> E {
35        self.entity
36    }
37
38    /// Despawns the entity locally and removes it from the replication layer.
39    pub fn despawn(&mut self) {
40        self.client.despawn_entity(&mut self.world, &self.entity);
41    }
42
43    // Components
44
45    /// Returns `true` if the entity currently carries component `R`.
46    pub fn has_component<R: ReplicatedComponent>(&self) -> bool {
47        self.world.has_component::<R>(&self.entity)
48    }
49
50    /// Returns a mutable accessor for component `R`, or `None` if the entity
51    /// does not carry it.
52    pub fn component<R: ReplicatedComponent>(&'_ mut self) -> Option<ReplicaMutWrapper<'_, R>> {
53        self.world.component_mut::<R>(&self.entity)
54    }
55
56    /// Inserts component `R` onto the entity and registers it for replication.
57    pub fn insert_component<R: ReplicatedComponent>(&mut self, component_ref: R) -> &mut Self {
58        self.client
59            .insert_component(&mut self.world, &self.entity, component_ref);
60
61        self
62    }
63
64    /// Removes component `R` from the entity, returning its value if present.
65    pub fn remove_component<R: ReplicatedComponent>(&mut self) -> Option<R> {
66        self.client
67            .remove_component::<R, W>(&mut self.world, &self.entity)
68    }
69
70    // Authority / Config
71
72    /// Updates the [`Publicity`] for this entity. Returns `&mut Self` for
73    /// chaining.
74    pub fn configure_replication(&mut self, config: Publicity) -> &mut Self {
75        self.client
76            .configure_entity_replication(&mut self.world, &self.entity, config);
77
78        self
79    }
80
81    /// Returns the current [`Publicity`], or `None` if the entity is not
82    /// registered with the replication layer.
83    pub fn replication_config(&self) -> Option<Publicity> {
84        self.client.entity_replication_config(&self.entity)
85    }
86
87    /// Returns the current authority status for this entity, or `None` if the
88    /// entity is not configured as `Delegated`.
89    pub fn authority(&self) -> Option<EntityAuthStatus> {
90        self.client.entity_authority_status(&self.entity)
91    }
92
93    /// Returns the current [`EntityOwner`] — who holds authoritative control
94    /// over this entity right now.
95    pub fn owner(&self) -> EntityOwner {
96        self.client.entity_owner(&self.entity)
97    }
98
99    /// Sends an authority request to the server for this delegated entity.
100    ///
101    /// The server responds asynchronously with an `EntityAuthGrantedEvent` or
102    /// `EntityAuthDeniedEvent`.
103    ///
104    /// # Errors
105    ///
106    /// Returns [`AuthorityError`] if the entity is not in a requestable state.
107    pub fn request_authority(&mut self) -> Result<&mut Self, AuthorityError> {
108        self.client.entity_request_authority(&self.entity)?;
109        Ok(self)
110    }
111
112    /// Releases the client's authority over this entity back to the server.
113    ///
114    /// # Errors
115    ///
116    /// Returns [`AuthorityError`] if the entity is not currently
117    /// client-authoritative.
118    pub fn release_authority(&mut self) -> Result<&mut Self, AuthorityError> {
119        self.client.entity_release_authority(&self.entity)?;
120        Ok(self)
121    }
122}
123
124cfg_if! {
125    if #[cfg(feature = "interior_visibility")] {
126
127        use naia_shared::LocalEntity;
128
129        impl<'s, E: Copy + Eq + Hash + Send + Sync, W: WorldMutType<E>> EntityMut<'s, E, W> {
130
131            /// Returns the [`LocalEntity`] id the server assigned to this
132            /// entity, if it is currently in scope.
133            ///
134            /// Only available with the `interior_visibility` feature.
135            pub fn local_entity(&self) -> Option<LocalEntity> {
136                self.client.world_to_local_entity(&self.entity)
137            }
138        }
139    }
140}
naia_client/world/entity_mut.rs

naia_client/world/
entity_mut.rs
