Track source location in change detection

[aevyrie]

Objective

• Make it possible to know what changed your component or resource.
• Common need when debugging, when you want to know the last code location that mutated a value in the ECS.
• This feature would be very useful for the editor alongside system stepping.

Solution

• Adds the caller location to column data.

Testing

• The component_change_detection example now shows where the component was mutated:

2024-06-26T06:56:42.980958Z  INFO component_change_detection: Entity { index: 1, generation: 1 } changed: Ref(MyComponent(2.0)) from: "examples/ecs/component_change_detection.rs:34:23"

---

Changelog

• Added source locations to ECS change detection.

Migration Guide

• Added caller field to many internal ECS functions used with change detection. Use Location::caller() to provide the source of the function call.

[cart]

Mut is one of the hottest paths in Bevy. I'm concerned about the performance implications of introducing anything (even the cheapest ops) to it. I'd like to either see compelling evidence that this won't meaningfully affect performance, especially given that this is a "debugging tool". I'd feel much more comfortable if this was behind a feature flag.

[alice-i-cecile]

I really like this feature and think it'll be very useful, but I'll second the request for putting it behind an off-by-default feature flag.

[aevyrie]

Yup, I assumed as much. I was hoping to get a read on whether this is even an acceptable approach to take for the feature. Before going down the path of adding feature flags.

[Brezak]

Is there a reason you're de referencing the static reference you get from Location::caller? Couldn't you just pass the reference around?

[BD103]

Is there a reason you're de referencing the static reference you get from Location::caller? Couldn't you just pass the reference around?

Location is two u32s and one &str, making it 16 bytes on 64-bit platforms. Storing a reference instead would bring it down to 8 bytes, which might have some mild performance gains because it would fit in a register.

Furthermore, why do you use core::panic::Location as compared with the std variant?

[aevyrie]

• static reference: I started with this, but was having trouble with the deref making it hard to update the field, so I switched to an owned value to get it working. I agree it should be fixed if this is going to be merged.
• using core: because it can't hurt? I wasn't sure if bevy_ecs was ever intended to be used in a no_std context, and figured it would be safer to use core for a type so ubiquitous.

The answer to most questions is probably going to be "because this is a proof of concept". 😄
I wasn't sure if this was going to be possible or if it would return any useful information, so I'm mostly just happy to see that it's doable. The useful findings from this are:

1. It's possible to get line and column level tracing for change detection, which is super useful
2. Changes from commands completely break this approach because commands are deferred, and the call stack can't be traced to the calling location by the time the command is actually executed.

For 2, it seems like it should be possible to get information from tracing to figure out what system the commands are being executed for. Not quite sure how to do that though, might need to replace Location with a new struct that also contains the Location as well as the current system span.

[BD103]

2. Changes from commands completely break this approach because commands are deferred, and the call stack can't be traced to the calling location by the time the command is actually executed.

Is it possible to find the Location in Commands::insert, then pass that forward to the actual command?

[alice-i-cecile]

using core: because it can't hurt? I wasn't sure if bevy_ecs was ever intended to be used in a no_std context, and figured it would be safer to use core for a type so ubiquitous.

I would like this, one day :) Probably core + alloc, but still! Not a priority, but might as well do it when there's no cost to it.