naia_shared/world/component/replicate.rs
1use std::{any::Any, collections::HashSet};
2
3use naia_serde::{BitReader, BitWrite, SerdeErr};
4
5use crate::world::update::component_update::ComponentUpdate;
6use crate::world::update::diff_mask::DiffMask;
7use crate::{
8 named::Named,
9 world::{
10 component::{
11 component_kinds::{ComponentKind, ComponentKinds},
12 property_mutate::PropertyMutator,
13 replica_ref::{ReplicaDynMut, ReplicaDynRef},
14 },
15 delegation::auth_channel::EntityAuthAccessor,
16 entity::entity_converters::LocalEntityAndGlobalEntityConverter,
17 },
18 ComponentFieldUpdate, LocalEntityAndGlobalEntityConverterMut, RemoteEntity,
19};
20
21/// Result of splitting a component update into a waiting set (unresolved entity refs) and a ready payload.
22pub type SplitUpdateResult = Result<
23 (
24 Option<Vec<(RemoteEntity, ComponentFieldUpdate)>>,
25 Option<ComponentUpdate>,
26 ),
27 SerdeErr,
28>;
29
30/// Factory trait for deserializing a concrete `Replicate` component or its partial updates from raw bits.
31pub trait ReplicateBuilder: Send + Sync + Named {
32 /// Returns true if the component type is marked `#[replicate(immutable)]`.
33 fn is_immutable(&self) -> bool {
34 false
35 }
36 /// Create new Component from incoming bit stream
37 fn read(
38 &self,
39 reader: &mut BitReader,
40 converter: &dyn LocalEntityAndGlobalEntityConverter,
41 ) -> Result<Box<dyn Replicate>, SerdeErr>;
42 /// Create new Component Update from incoming bit stream
43 fn read_create_update(&self, reader: &mut BitReader) -> Result<ComponentUpdate, SerdeErr>;
44 /// Split a Component update into Waiting and Ready updates
45 fn split_update(
46 &self,
47 converter: &dyn LocalEntityAndGlobalEntityConverter,
48 update: ComponentUpdate,
49 ) -> SplitUpdateResult;
50
51 /// Returns a heap-allocated clone of this builder.
52 fn box_clone(&self) -> Box<dyn ReplicateBuilder>;
53}
54
55/// A struct that implements Replicate is a Component, or otherwise,
56/// a container of Properties that can be scoped, tracked, and synced, with a
57/// remote host
58pub trait Replicate: Sync + Send + 'static + Named + Any {
59 /// Returns true if this component type never sends mutation updates.
60 /// Immutable components are written once on spawn and never diff-tracked.
61 /// Override in the derive macro by adding `#[replicate(immutable)]`.
62 fn is_immutable(&self) -> bool {
63 false
64 }
65 /// Gets the ComponentKind of this type
66 fn kind(&self) -> ComponentKind;
67 /// Returns a shared `Any` reference for downcasting.
68 fn to_any(&self) -> &dyn Any;
69 /// Returns a mutable `Any` reference for downcasting.
70 fn to_any_mut(&mut self) -> &mut dyn Any;
71 /// Converts this boxed component into a `Box<dyn Any>` for downcasting.
72 fn to_boxed_any(self: Box<Self>) -> Box<dyn Any>;
73 /// Returns a heap-allocated clone of this component as a trait object.
74 fn copy_to_box(&self) -> Box<dyn Replicate>;
75 /// Creates the `ReplicateBuilder` used to deserialize instances of this type.
76 fn create_builder() -> Box<dyn ReplicateBuilder>
77 where
78 Self: Sized;
79 /// Gets the number of bytes of the Component's DiffMask
80 fn diff_mask_size(&self) -> u8;
81 /// Get an immutable reference to the inner Component as a Replicate trait object
82 fn dyn_ref(&self) -> ReplicaDynRef<'_>;
83 /// Get an mutable reference to the inner Component as a Replicate trait object
84 fn dyn_mut(&mut self) -> ReplicaDynMut<'_>;
85 /// Sets the current Component to the state of another Component of the
86 /// same type
87 fn mirror(&mut self, other: &dyn Replicate);
88 /// Mirror a SINGLE Property field from `other` into `self`, identified
89 /// by its 0-based property index (the same index used by the diff-mask
90 /// bit positions). Calls `Property::mirror` on exactly one field —
91 /// fires that field's PropertyMutator without touching any others.
92 ///
93 /// Used by the Replicated Resources Mode B mirror system to propagate
94 /// per-field changes from the user-facing bevy `Resource` storage to
95 /// the entity-component without over-replicating untouched fields.
96 ///
97 /// **Out-of-range indices are silently no-op'd** (schema evolution
98 /// across protocol versions may produce stale dirty indices; we
99 /// tolerate that without panicking).
100 ///
101 /// **Type mismatch** (`other` is not the same concrete type as
102 /// `self`) is a programming error: the derive-macro impl
103 /// `debug_assert!`s in debug builds and silently no-ops in release.
104 /// This is hostile to ignore but a hot per-tick sync system shouldn't
105 /// panic in production.
106 fn mirror_single_field(&mut self, field_index: u8, other: &dyn Replicate);
107 /// Set the Component's PropertyMutator, which keeps track
108 /// of which Properties have been mutated, necessary to sync only the
109 /// Properties that have changed with the client
110 fn set_mutator(&mut self, mutator: &PropertyMutator);
111 /// Writes data into an outgoing byte stream, sufficient to completely
112 /// recreate the Component on the client
113 fn write(
114 &self,
115 component_kinds: &ComponentKinds,
116 writer: &mut dyn BitWrite,
117 converter: &mut dyn LocalEntityAndGlobalEntityConverterMut,
118 );
119 /// Write data into an outgoing byte stream, sufficient only to update the
120 /// mutated Properties of the Component on the client
121 fn write_update(
122 &self,
123 diff_mask: &DiffMask,
124 writer: &mut dyn BitWrite,
125 converter: &mut dyn LocalEntityAndGlobalEntityConverterMut,
126 );
127 /// Reads data from an incoming packet, sufficient to sync the in-memory
128 /// Component with it's replica on the Server
129 fn read_apply_update(
130 &mut self,
131 converter: &dyn LocalEntityAndGlobalEntityConverter,
132 update: ComponentUpdate,
133 ) -> Result<(), SerdeErr>;
134 /// Applies a single-field update from the network, updating the corresponding property in-place.
135 fn read_apply_field_update(
136 &mut self,
137 converter: &dyn LocalEntityAndGlobalEntityConverter,
138 update: ComponentFieldUpdate,
139 ) -> Result<(), SerdeErr>;
140 /// Returns a list of LocalEntities contained within the Component's EntityProperty fields, which are waiting to be converted to GlobalEntities
141 fn relations_waiting(&self) -> Option<HashSet<RemoteEntity>>;
142 /// Converts any LocalEntities contained within the Component's EntityProperty fields to GlobalEntities
143 fn relations_complete(&mut self, converter: &dyn LocalEntityAndGlobalEntityConverter);
144 /// Publish Replicate
145 fn publish(&mut self, mutator: &PropertyMutator);
146 /// Unpublish Replicate
147 fn unpublish(&mut self);
148 /// Enable Delegation Replicate
149 fn enable_delegation(
150 &mut self,
151 accessor: &EntityAuthAccessor,
152 mutator_opt: Option<&PropertyMutator>,
153 );
154 /// Disable Delegation Replicate
155 fn disable_delegation(&mut self);
156 /// Convert to Local Replicate
157 fn localize(&mut self);
158}
159
160cfg_if! {
161 if #[cfg(feature = "bevy_support")]
162 {
163 // Require that Bevy Component to be implemented
164 use bevy_ecs::component::{Component, Mutable};
165
166 /// Marker trait combining `Replicate` with the Bevy `Component` bound; auto-implemented.
167 pub trait ReplicatedComponent: Replicate + Component<Mutability = Mutable> {}
168 impl<T: Replicate + Component<Mutability = Mutable>> ReplicatedComponent for T {}
169 }
170 else
171 {
172 /// Marker trait equivalent to `Replicate`; auto-implemented for all `Replicate` types when Bevy is not in use.
173 pub trait ReplicatedComponent: Replicate {}
174 impl<T: Replicate> ReplicatedComponent for T {}
175 }
176}