Skip to content

Commit

Permalink
add a more helpful error to help debug panicking command on despawned…
Browse files Browse the repository at this point in the history
… entity (bevyengine#5198)

# Objective

- Help users fix issue when their app panic when executing a command on a despawned entity

## Solution

- Add an error code and a page describing how to debug the issue
  • Loading branch information
mockersf authored and inodentry committed Aug 8, 2022
1 parent 3176ef8 commit c0c60e8
Show file tree
Hide file tree
Showing 3 changed files with 97 additions and 9 deletions.
12 changes: 3 additions & 9 deletions crates/bevy_ecs/src/system/commands/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -712,9 +712,7 @@ pub struct Despawn {
impl Command for Despawn {
fn write(self, world: &mut World) {
if !world.despawn(self.entity) {
warn!("Could not despawn entity {:?} because it doesn't exist in this World.\n\
If this command was added to a newly spawned entity, ensure that you have not despawned that entity within the same stage.\n\
This may have occurred due to system order ambiguity, or if the spawning system has multiple command buffers", self.entity);
warn!("error[B0003]: Could not despawn entity {:?} because it doesn't exist in this World.", self.entity);
}
}
}
Expand All @@ -732,9 +730,7 @@ where
if let Some(mut entity) = world.get_entity_mut(self.entity) {
entity.insert_bundle(self.bundle);
} else {
panic!("Could not insert a bundle (of type `{}`) for entity {:?} because it doesn't exist in this World.\n\
If this command was added to a newly spawned entity, ensure that you have not despawned that entity within the same stage.\n\
This may have occurred due to system order ambiguity, or if the spawning system has multiple command buffers", std::any::type_name::<T>(), self.entity);
panic!("error[B0003]: Could not insert a bundle (of type `{}`) for entity {:?} because it doesn't exist in this World.", std::any::type_name::<T>(), self.entity);
}
}
}
Expand All @@ -753,9 +749,7 @@ where
if let Some(mut entity) = world.get_entity_mut(self.entity) {
entity.insert(self.component);
} else {
panic!("Could not add a component (of type `{}`) to entity {:?} because it doesn't exist in this World.\n\
If this command was added to a newly spawned entity, ensure that you have not despawned that entity within the same stage.\n\
This may have occurred due to system order ambiguity, or if the spawning system has multiple command buffers", std::any::type_name::<T>(), self.entity);
panic!("error[B0003]: Could not add a component (of type `{}`) to entity {:?} because it doesn't exist in this World.", std::any::type_name::<T>(), self.entity);
}
}
}
Expand Down
91 changes: 91 additions & 0 deletions errors/B0003.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# B0003

As commands are executed asynchronously, it is possible to issue a command on an entity that will no longer exist at the time of the command execution.

Erroneous code example:

```rust,should_panic
use bevy::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_startup_system(setup)
.add_system(despawning)
.add_system(use_entity.after(despawning))
.run();
}
struct MyEntity(Entity);
#[derive(Component)]
struct Hello;
fn setup(mut commands: Commands) {
let entity = commands.spawn().id();
commands.insert_resource(MyEntity(entity));
}
fn despawning(mut commands: Commands, entity: Option<Res<MyEntity>>) {
if let Some(my_entity) = entity {
commands.entity(my_entity.0).despawn();
commands.remove_resource::<MyEntity>();
}
}
fn use_entity(mut commands: Commands, entity: Option<Res<MyEntity>>) {
if let Some(my_entity) = entity {
commands.entity(my_entity.0).insert(Hello);
}
}
```

This will panic, as system `use_entity` is executed after system `despawning`. Without the system ordering specified here, the ordering would be random and this code would panic half the time.

The default panic message is telling you the entity id (`0v0`) and the command that failed (adding a component `Hello`):

```text
thread 'main' panicked at 'error[B0003]: Could not add a component (of type `use_entity_after_despawn::Hello`) to entity 0v0 because it doesn't exist in this World.', /bevy/crates/bevy_ecs/src/system/commands/mod.rs:752:13
```

But you don't know which system tried to add a component, and which system despawned the entity.

To get the system that created the command that panics, you can enable the `trace` feature of Bevy. This will add a panic handler that will print more informations:

```text
0: bevy_ecs::schedule::stage::system_commands
with name="use_entity_after_despawn::use_entity"
at crates/bevy_ecs/src/schedule/stage.rs:880
1: bevy_ecs::schedule::stage
with name=Update
at crates/bevy_ecs/src/schedule/mod.rs:337
2: bevy_app::app::frame
at crates/bevy_app/src/app.rs:113
3: bevy_app::app::bevy_app
at crates/bevy_app/src/app.rs:126
thread 'main' panicked at 'error[B0003]: Could not add a component (of type `use_entity_after_despawn::Hello`) to entity 0v0 because it doesn't exist in this World.', /bevy/crates/bevy_ecs/src/system/commands/mod.rs:752:13
```

From the first two lines, you now know that it panics while executing a command from the system `use_entity`.

To get the system that created the despawn command, you can enable DEBUG logs for crate `bevy_ecs`, for example by setting the environment variable `RUST_LOG=bevy_ecs=debug`. This will log:

```text
DEBUG stage{name=Update}:system_commands{name="use_entity_after_despawn::despawning"}: bevy_ecs::world: Despawning entity 0v0
thread 'main' panicked at 'error[B0003]: Could not add a component (of type `use_entity_after_despawn::Hello`) to entity 0v0 because it doesn't exist in this World.', /bevy/crates/bevy_ecs/src/system/commands/mod.rs:752:13
```

From the first line, you know the entity `0v0` was despawned when executing a command from system `despawning`. In a real case, you could have many log lines, you will need to search for the exact entity from the panic message.

Combining those two, you should get enough informations to understand why this panic is happening and how to fix it:

```text
DEBUG stage{name=Update}:system_commands{name="use_entity_after_despawn::despawning"}: bevy_ecs::world: Despawning entity 0v0
0: bevy_ecs::schedule::stage::system_commands
with name="use_entity_after_despawn::use_entity"
at crates/bevy_ecs/src/schedule/stage.rs:880
1: bevy_ecs::schedule::stage
with name=Update
at crates/bevy_ecs/src/schedule/mod.rs:337
thread 'main' panicked at 'error[B0003]: Could not add a component (of type `use_entity_after_despawn::Hello`) to entity 0v0 because it doesn't exist in this World.', /bevy/crates/bevy_ecs/src/system/commands/mod.rs:752:13
```
3 changes: 3 additions & 0 deletions errors/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,6 @@ pub struct B0001;

#[doc = include_str!("../B0002.md")]
pub struct B0002;

#[doc = include_str!("../B0003.md")]
pub struct B0003;

0 comments on commit c0c60e8

Please sign in to comment.