Don't panic when despawning hierarchy with signatures

Author: Shatur

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Don't panic when despawning hierarchy with signatures.
+
 ## [0.39.0] - 2026-02-24
 
 ### Added

src/client.rs

@@ -437,16 +437,16 @@ fn apply_despawn(
     // with the last replication message, but the server might not yet have received confirmation
     // from the client and could include the deletion in the this message.
     let server_entity = postcard_utils::entity_from_buf(message)?;
-    if let Some(client_entity) = params
-        .entity_map
-        .server_entry(server_entity)
-        .remove()
-        .and_then(|entity| world.get_entity_mut(entity).ok())
-    {
-        trace!("applying despawn for `{}`", client_entity.id());
-        params.signature_map.remove(client_entity.id()); // Requires manual removal since the map is removed from the world and inaccessible to triggers.
-        let ctx = DespawnCtx { message_tick };
-        (params.registry.despawn)(&ctx, client_entity);
+    if let Some(client_entity) = params.entity_map.server_entry(server_entity).remove() {
+        // Requires manual removal since the map is removed from the world and inaccessible to triggers.
+        // The entity can also be despawned via a relationship when applying
+        // despawn to another entity, so we always need to remove it from the map.
+        params.signature_map.remove(client_entity);
+        if let Ok(client_entity) = world.get_entity_mut(client_entity) {
+            trace!("applying despawn for `{}`", client_entity.id());
+            let ctx = DespawnCtx { message_tick };
+            (params.registry.despawn)(&ctx, client_entity);
+        }
     }
 
     Ok(())

tests/despawn.rs

@@ -156,6 +156,76 @@ fn signature() {
     assert!(client_app.world().get_entity(client_entity).is_err());
 }
 
+#[test]
+fn signature_with_hierarchy() {
+    let mut server_app = App::new();
+    let mut client_app = App::new();
+    for app in [&mut server_app, &mut client_app] {
+        app.add_plugins((
+            MinimalPlugins,
+            StatesPlugin,
+            RepliconPlugins.set(ServerPlugin::new(PostUpdate)),
+        ))
+        .replicate::<TestComponent>()
+        .finish();
+    }
+
+    server_app.connect_client(&mut client_app);
+
+    let client_parent = client_app
+        .world_mut()
+        .spawn((Replicated, Signature::from(0)))
+        .id();
+    let client_child = client_app
+        .world_mut()
+        .spawn((Replicated, Signature::from(1), ChildOf(client_parent)))
+        .id();
+
+    let server_parent = server_app
+        .world_mut()
+        .spawn((Replicated, Signature::from(0)))
+        .id();
+    server_app
+        .world_mut()
+        .spawn((Replicated, Signature::from(1), ChildOf(server_parent)));
+
+    server_app.update();
+    server_app.exchange_with_client(&mut client_app);
+    client_app.update();
+    server_app.exchange_with_client(&mut client_app);
+
+    assert!(client_app.world().get_entity(client_parent).is_ok());
+    assert!(client_app.world().get_entity(client_child).is_ok());
+
+    server_app.world_mut().despawn(server_parent);
+
+    server_app.update();
+    server_app.exchange_with_client(&mut client_app);
+    client_app.update();
+
+    assert!(client_app.world().get_entity(client_parent).is_err());
+    assert!(client_app.world().get_entity(client_child).is_err());
+
+    let server_parent = server_app
+        .world_mut()
+        .spawn((Replicated, Signature::from(0)))
+        .id();
+    server_app
+        .world_mut()
+        .spawn((Replicated, Signature::from(1), ChildOf(server_parent)));
+
+    server_app.update();
+    server_app.exchange_with_client(&mut client_app);
+    client_app.update();
+
+    let mut remote = client_app.world_mut().query::<&Remote>();
+    assert_eq!(
+        remote.iter(client_app.world()).count(),
+        2,
+        "entities should be replicated as new due to removal from the signature map"
+    );
+}
+
 #[test]
 fn hidden_entity() {
     let mut server_app = App::new();