Inconsistency between Debug and serialized representation of Entity

[Zeenobit]

Bevy version

0.13

What went wrong

There is an inconsistency between the Debug representation of an Entity:

impl fmt::Debug for Entity {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}v{}", self.index(), self.generation())
    }
}

And its Serialize representation:

impl Serialize for Entity {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_u64(self.to_bits())
    }
}

This makes it difficult to debug serialized outputs, since the serialized entity IDs cannot be easily mapped to runtime entities via human inspection. Ideally, these representations should be consistent for easier debugging.

Additional information

I wanted to just open a PR on this, but I think the issue warrants some discussion. Mainly on two points:

• Which representation is "correct"?
• If we swap to #v# format for serialized data, are we ok with invalidating existing scenes?

[alice-i-cecile]

Ah: I know what we should do. The serialized representation should stay the same, optimized for information density. This is just an opaque identifier. However, we should make the debug representation more verbose, and report index, generation and raw_bits separately.

In the future, we will be packing more information into here (e.g. entity disabling) that we want to add to the debug output, but we should avoid adding bloat (or semantic meaning) to the serialized representation. Displaying the raw bits separately gives us the best of both worlds, as users will be able to make this correspondence themselves.

[Zeenobit]

I like that idea.

My only concern there is that the current "#v#" format for Debug is very compact. This makes it very useful for log messages, since the user can just do info!("{entity:?} is a cool entity!").
This would output something like:
"2v2 is a cool entity"

I'm concerned if we make the Debug more verbose, we'd lose this feature. This would open the door to people using either the entity index/generation or the raw bits in log messages, which would produce highly inconsistent log outputs overall.

[alice-i-cecile]

I'm concerned if we make the Debug more verbose, we'd lose this feature. This would open the door to people using either the entity index/generation or the raw bits in log messages, which would produce highly inconsistent log outputs overall.

That seems like a prime case for a Display impl then: "pretty, humand-readable output" is what belongs there. Debug should be maximally clear and helpful IMO.

[Zeenobit]

Just a random idea I had on this topic:

If we take this approach, we could make the Debug impl compact as well. Maybe if we pick a format like: #v#[raw_bits]
So then Display could look like 12v7. And Debug could look like 12v7[12345678] or 12v7.12345678

Alternatively, we could make Display use the 12v7.12345678 format, and Debug to be even more verbose with field names as needed.

[alice-i-cecile]

I like 12v7[12345678] for the display impl, and then a properly verbose Debug impl :)

[Zeenobit]

@alice-i-cecile I want to re-open this issue. I don't think the fmt::Debug and fmt::Display implementation we proposed in the discussions here actually solves the initial problem. Additionally, it introduces a new issue that I was originally concerned about.

The Problem

The serialized output of Bevy scenes uses the raw bit representation of entities, i.e. 4294967303.
Many systems, including internal Bevy code, currently log entities using fmt::Debug (i.e. {:?}).
This is because previously, fmt::Debug has format #v#, which was short and concise, but didn't include the raw bits.

After this change, the fmt::Debug implementation is now derived. This means now any log that uses {:?} now displays:
Entity Entity { index: 16, generation: 3 } does not exist
Unless we retroactively fix existing log outputs, this is currently producing very ugly logs, not just for Bevy, but for everyone downstream!

Additionally, this still doesn't fix the initial problem, because fmt::Debug still doesn't include the raw bits.
I can't easily map Entity { index: 16, generation: 3 } to 4294967303.

My Proposal

To me, Entity should not have a fmt::Display implementation.
99.9% of the time an entity is only being displaying for debug purposes.
Because of this, I propose fmt::Debug should be what fmt::Display is now, in addition to the raw bits: i.e. #v#[rawbits]

This not only avoids the need to retroactively fix logs, but also solves the initial problem by including the raw bits into the debug output.

Any specialized debugger that needs to show additional data for the entity most likely would need to format it explicitly. Trying to implement fmt::Display as a "pretty debug" output is not something I believe Bevy should handle.

---

The only other alternative I see around this issue is that we retroactively fix existing log locations to use {} instead of {:?} and include the raw bits where appropriate. To me, this is a much more intrusive change.