Ignore mutations for client-despawned entities (#623)

Author: Shatur

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Ignore received replication for entities that was despawned by the client.
+
 ## [0.37.0] - 2025-12-03
 
 ### Added

src/client.rs

@@ -460,20 +460,23 @@ fn apply_removals(
     message_tick: RepliconTick,
 ) -> Result<()> {
     let server_entity = postcard_utils::entity_from_buf(message)?;
+    let data_size: usize = postcard_utils::from_buf(message)?;
 
-    let mut client_entity = match params.entity_map.server_entry(server_entity) {
-        EntityEntry::Occupied(entry) => {
-            DeferredEntity::new(world.get_entity_mut(entry.get())?, params.changes)
-        }
-        EntityEntry::Vacant(entry) => {
-            // It's possible to receive a removal when an entity is spawned and has a component removed in the same tick.
-            // We could serialize the size of the removals instead of the total number of removals and just advance the cursor,
-            // but it's a very rare case and not worth optimizing for.
-            let mut client_entity = DeferredEntity::new(world.spawn_empty(), params.changes);
-            client_entity.insert(Replicated);
-            entry.insert(client_entity.id());
-            client_entity
-        }
+    // Server never sends removals for entities that weren't received by the client.
+    let client_entity = *params
+        .entity_map
+        .to_client()
+        .get(&server_entity)
+        .ok_or_else(|| format!("received removal for unknown server's `{server_entity}`"))?;
+
+    let Ok(mut client_entity) = world
+        .get_entity_mut(client_entity)
+        .map(|entity| DeferredEntity::new(entity, params.changes))
+    else {
+        // Client could predict despawn.
+        debug!("ignoring removals for despawned `{client_entity}`");
+        message.advance(data_size);
+        return Ok(());
     };
 
     params
@@ -482,8 +485,9 @@ fn apply_removals(
 
     confirm_tick(&mut client_entity, params.replicated, message_tick);
 
-    let len = apply_array(ArrayKind::Sized, message, |message| {
-        let fns_id = postcard_utils::from_buf(message)?;
+    let mut data = message.split_to(data_size);
+    let len = apply_array(ArrayKind::Dynamic, &mut data, |data| {
+        let fns_id = postcard_utils::from_buf(data)?;
         let (_, component_id, fns) = params.registry.get(fns_id);
         let mut ctx = RemoveCtx {
             message_tick,
@@ -516,6 +520,7 @@ fn apply_changes(
     message_tick: RepliconTick,
 ) -> Result<()> {
     let server_entity = postcard_utils::entity_from_buf(message)?;
+    let data_size: usize = postcard_utils::from_buf(message)?;
 
     let world_cell = world.as_unsafe_world_cell();
     let entities = world_cell.entities();
@@ -525,7 +530,14 @@ fn apply_changes(
 
     let mut client_entity = match params.entity_map.server_entry(server_entity) {
         EntityEntry::Occupied(entry) => {
-            DeferredEntity::new(world.get_entity_mut(entry.get())?, params.changes)
+            let Ok(client_entity) = world.get_entity_mut(entry.get()) else {
+                // Client could predict despawn.
+                debug!("ignoring changes for despawned `{}`", entry.get());
+                message.advance(data_size);
+                return Ok(());
+            };
+
+            DeferredEntity::new(client_entity, params.changes)
         }
         EntityEntry::Vacant(entry) => {
             let mut client_entity = DeferredEntity::new(world.spawn_empty(), params.changes);
@@ -541,8 +553,9 @@ fn apply_changes(
 
     confirm_tick(&mut client_entity, params.replicated, message_tick);
 
-    let len = apply_array(ArrayKind::Sized, message, |message| {
-        let fns_id = postcard_utils::from_buf(message)?;
+    let mut data = message.split_to(data_size);
+    let len = apply_array(ArrayKind::Dynamic, &mut data, |data| {
+        let fns_id = postcard_utils::from_buf(data)?;
         let (_, component_id, fns) = params.registry.get(fns_id);
         let mut ctx = WriteCtx {
             entity_map: params.entity_map,
@@ -557,7 +570,7 @@ fn apply_changes(
             client_entity.id(),
         );
 
-        fns.write(&mut ctx, params.entity_markers, &mut client_entity, message)?;
+        fns.write(&mut ctx, params.entity_markers, &mut client_entity, data)?;
 
         Ok(())
     })?;
@@ -645,8 +658,16 @@ fn apply_mutations(
     // The latter won't apply any structural changes until `flush`, and `Entities` won't be used afterward.
     let world = unsafe { world_cell.world_mut() };
 
-    let mut client_entity =
-        DeferredEntity::new(world.get_entity_mut(client_entity)?, params.changes);
+    let Ok(mut client_entity) = world
+        .get_entity_mut(client_entity)
+        .map(|entity| DeferredEntity::new(entity, params.changes))
+    else {
+        // Client could predict despawn.
+        debug!("ignoring mutations for despawned `{client_entity}`");
+        message.advance(data_size);
+        return Ok(());
+    };
+
     params
         .entity_markers
         .read(params.command_markers, &*client_entity);

src/server/replication_messages.rs

@@ -1,4 +1,4 @@
-mod change_ranges;
+mod entity_ranges;
 pub(super) mod mutations;
 pub(super) mod serialized_data;
 pub(super) mod updates;

src/server/replication_messages/change_ranges.rs

@@ -0,0 +1,48 @@
+use alloc::vec::Vec;
+use core::ops::Range;
+
+use bevy::prelude::*;
+use postcard::experimental::serialized_size;
+
+/// Component insertions, mutations or removals for an entity in form of serialized ranges
+/// from [`SerializedData`](super::serialized_data::SerializedData).
+///
+/// Used inside [`Updates`](super::updates::Updates) and
+/// [`Mutations`](super::mutations::Mutations).
+///
+/// For data, we serialize the size in bytes rather than the number of elements to
+/// allow entities to be skipped during deserialization. For example, received mutations
+/// might be outdated, or the entity might have been despawned via client-side prediction.
+pub(super) struct EntityRanges {
+    pub(super) entity: Range<usize>,
+    pub(super) data: Vec<Range<usize>>,
+}
+
+impl EntityRanges {
+    /// Returns serialized size.
+    pub(super) fn size(&self) -> Result<usize> {
+        let data_size = self.data_size();
+        let len_size = serialized_size(&data_size)?;
+        Ok(self.entity.len() + len_size + data_size)
+    }
+
+    pub(super) fn data_size(&self) -> usize {
+        self.data.iter().map(|range| range.len()).sum()
+    }
+
+    pub(super) fn add_data(&mut self, data: Range<usize>) {
+        if let Some(last) = self.data.last_mut() {
+            // Append to previous range if possible.
+            if last.end == data.start {
+                last.end = data.end;
+                return;
+            }
+        }
+
+        self.data.push(data);
+    }
+
+    pub(super) fn extend(&mut self, other: &Self) {
+        self.data.extend(other.data.iter().cloned());
+    }
+}

src/server/replication_messages/entity_ranges.rs

@@ -4,7 +4,7 @@ use bevy::{ecs::component::Tick, prelude::*};
 use log::trace;
 use postcard::experimental::{max_size::MaxSize, serialized_size};
 
-use super::{change_ranges::ChangeRanges, serialized_data::SerializedData};
+use super::{entity_ranges::EntityRanges, serialized_data::SerializedData};
 use crate::{
     postcard_utils,
     prelude::*,
@@ -67,10 +67,9 @@ impl Mutations {
     ) {
         let mutations = EntityMutations {
             entity,
-            ranges: ChangeRanges {
+            ranges: EntityRanges {
                 entity: entity_range,
-                components_len: 0,
-                components: pools.take_ranges(),
+                data: pools.take_ranges(),
             },
             components: pools.take_components(),
         };
@@ -97,7 +96,7 @@ impl Mutations {
             })
             .expect("entity should be written before adding components");
 
-        mutations.ranges.add_component(component);
+        mutations.ranges.add_data(component);
     }
 
     /// Removes last added entity from [`Self::add_entity`] and returns it.
@@ -164,7 +163,7 @@ impl Mutations {
         for chunk in chunks.iter_mut() {
             let mut mutations_size = 0;
             for mutations in &mut *chunk {
-                mutations_size += mutations.ranges.size_with_components_size()?;
+                mutations_size += mutations.ranges.size()?;
             }
 
             // Try to pack back first, then try to pack forward.
@@ -233,8 +232,8 @@ impl Mutations {
             postcard_utils::to_extend_mut(&split.mutate_index, &mut message)?;
             for mutations in chunks.iter_flatten(split.chunks_range.clone()) {
                 message.extend_from_slice(&serialized[mutations.ranges.entity.clone()]);
-                postcard_utils::to_extend_mut(&mutations.ranges.components_size(), &mut message)?;
-                for component in &mutations.ranges.components {
+                postcard_utils::to_extend_mut(&mutations.ranges.data_size(), &mut message)?;
+                for component in &mutations.ranges.data {
                     message.extend_from_slice(&serialized[component.clone()]);
                 }
             }
@@ -262,7 +261,7 @@ impl Mutations {
             .iter_mut()
             .chain(iter::once(&mut self.standalone))
         {
-            pools.recycle_ranges(entities.drain(..).map(|m| m.ranges.components));
+            pools.recycle_ranges(entities.drain(..).map(|m| m.ranges.data));
             // We don't take component masks because they are moved to `MutateInfo` during sending.
         }
     }
@@ -294,12 +293,7 @@ pub(crate) struct EntityMutations {
     /// Serialized as a list of pairs of entity chunk and multiple chunks with mutated components.
     /// Components are stored in multiple chunks because some clients may acknowledge mutations,
     /// while others may not.
-    ///
-    /// Unlike with [`Updates`](super::updates::Updates), we serialize the number
-    /// of chunk bytes instead of the number of components. This is because, during deserialization,
-    /// some entities may be skipped if they have already been updated (as mutations are sent until
-    /// the client acknowledges them).
-    pub(super) ranges: ChangeRanges,
+    pub(super) ranges: EntityRanges,
 
     /// Components written in [`Self::ranges`].
     ///