bevy/crates/bevy_ecs/src/identifier/kinds.rs

/// The kinds of ID that [`super::Identifier`] can represent. Each
/// variant imposes different usages of the low/high segments
/// of the ID.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u8)]
pub enum IdKind {
    /// An ID variant that is compatible with [`crate::entity::Entity`].
    Entity = 0,
    /// A future ID variant.
    Placeholder = 0b1000_0000,
}
Unified identifer for entities & relations (#9797) # Objective The purpose of this PR is to begin putting together a unified identifier structure that can be used by entities and later components (as entities) as well as relationship pairs for relations, to enable all of these to be able to use the same storages. For the moment, to keep things small and focused, only `Entity` is being changed to make use of the new `Identifier` type, keeping `Entity`'s API and serialization/deserialization the same. Further changes are for follow-up PRs. ## Solution `Identifier` is a wrapper around `u64` split into two `u32` segments with the idea of being generalised to not impose restrictions on variants. That is for `Entity` to do. Instead, it is a general API for taking bits to then merge and map into a `u64` integer. It exposes low/high methods to return the two value portions as `u32` integers, with then the MSB masked for usage as a type flag, enabling entity kind discrimination and future activation/deactivation semantics. The layout in this PR for `Identifier` is described as below, going from MSB -> LSB. ``` \|F\| High value \| Low value \| \|_\|_______________________________\|________________________________\| \|1\| 31 \| 32 \| F = Bit Flags ``` The high component in this implementation has only 31 bits, but that still leaves 2^31 or 2,147,483,648 values that can be stored still, more than enough for any generation/relation kinds/etc usage. The low part is a full 32-bit index. The flags allow for 1 bit to be used for entity/pair discrimination, as these have different usages for the low/high portions of the `Identifier`. More bits can be reserved for more variants or activation/deactivation purposes, but this currently has no use in bevy. More bits could be reserved for future features at the cost of bits for the high component, so how much to reserve is up for discussion. Also, naming of the struct and methods are also subject to further bikeshedding and feedback. Also, because IDs can have different variants, I wonder if `Entity::from_bits` needs to return a `Result` instead of potentially panicking on receiving an invalid ID. PR is provided as an early WIP to obtain feedback and notes on whether this approach is viable. --- ## Changelog ### Added New `Identifier` struct for unifying IDs. ### Changed `Entity` changed to use new `Identifier`/`IdentifierMask` as the underlying ID logic. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: vero <email@atlasdostal.com> 2024-01-13 01:09:32 +00:00			/// The kinds of ID that [`super::Identifier`] can represent. Each
			`/// variant imposes different usages of the low/high segments`
			`/// of the ID.`
			`#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]`
			`#[repr(u8)]`
			`pub enum IdKind {`
			/// An ID variant that is compatible with [`crate::entity::Entity`].
			`Entity = 0,`
			`/// A future ID variant.`
			`Placeholder = 0b1000_0000,`
			`}`