Documenting Bevy 🦶 Footguns 🔫

[aevyrie]

Recording some gotchas I've run into:

commands.entity() can panic during evaluation, making debugging extremely difficult

Calling entity() on a command to gain an entity builder will work at the call site where the command is queued, but can panic during command execution. The panic traceback is useless because it points to where the command execution is happening, and not what command queuing operation was the root cause. This can happen when the entity used is despawned.

Solutions: carry callsite data with commands during queuing, for use if the command fails? Provide a fallible version of entity that does not panic?

Command processing can cause frame delays

Because commands aren't processed until the end of the stage, as applications get larger it's easy to end up in a scenario where systems will have to wait a full frame for updates because the source system is in the same stage. This can also compound to multi-frame delays, with the number of frames of delay equaling the number of dependent systems that mutate data with commands.

This is most common when using the marker component pattern, as disabling relies on removing the component through a command. A more reliable alternative is to us a component that holds a single bool that can be toggled and compared.

Solution: Maybe if we could tombstone components, we could still defer removal until stage boundaries, but the removal would appear to be effective immediately for queries.

Change detection is brittle and easy to trigger false positives

Change detection works by tracking dereferences on the ResMut and Mut smart pointers. However, often times you will be inside the scope of a Query in which you have a mutable reference, but you only need to read an immutable reference. This is helped by #5373, but that is a bandaid, not a fix.

You could make the argument to just "be a better programmer", but even this utopian scenario doesn't solve the problem, because if you are building a public API for library users, they can trigger errant changes.

I've found myself preferring message-passing using bevy Events instead. This is much more robust, and sending the events can be restricted to the library crate by making Event constructors private.

Solution: make mutable dereferences explicit. *var could default to creating an immutable deref, but calling some method would explicitly enable mutation, e.g. var.deref_mut().

There are probably more I'm forgetting.

[mockersf]

commands.entity() can panic during evaluation, making debugging extremely difficult

There is actually a way to debug those already in 0.7 but it was undocumented, I added documentation in https://github.com/bevyengine/bevy/blob/main/errors/B0003.md. This error code should be in the panic message.
If you enable the trace feature, you will have the span stack on panic that will indicate where the command is from.
If you also increase log level to debug, you can know which system despawned the entity you're trying to work on.