forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
Elliott Pierce 2025-05-31 11:58:20 -04:00
parent ea9a3bee7f
commit 0c1c9c3fa4
1 changed files with 15 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
crates/bevy_ecs/src/entity/mod.rs
View File

@ -1,12 +1,6 @@
//! Entity handling types. //! Entity handling types.
//! //!
//! An **entity** exclusively owns zero or more [component] instances, all of different types, and can dynamically acquire or lose them over its lifetime. //! An **entity** exclusively owns zero or more [component] instances, all of different types, and can dynamically acquire or lose them over its lifetime.
//!
//! **empty entity**: Entity with zero components.
//! **pending entity**: Entity reserved, but not flushed yet (see [`Entities::flush`] docs for reference).
//! **reserved entity**: same as **pending entity**.
//! **invalid entity**: **pending entity** flushed with invalid (see [`Entities::flush_as_invalid`] docs for reference).
//!
//! See [`Entity`] to learn more. //! See [`Entity`] to learn more.
//! //!
//! [component]: crate::component::Component //! [component]: crate::component::Component
@ -278,6 +272,20 @@ impl Ord for EntityGeneration {
/// ///
/// [generational index]: https://lucassardois.medium.com/generational-indices-guide-8e3c5f7fd594 /// [generational index]: https://lucassardois.medium.com/generational-indices-guide-8e3c5f7fd594
/// ///
/// # Entity ids
///
/// It is important to keep in mind that an [`Entity`] is just an id for a conceptual entity.
/// Conceptual entities are just a collection of zero or more components,
/// but [`Entity`] ids may or may not correspond to a conceptual entity.
///
/// Each [`EntityRow`] corresponds to a potential conceptual entity.
/// This can happen if, for example, the row has not been allocated, or it has been allocated and has not been [`constructed`](World::construct), or it has been since [destructed](World::destruct).
/// Entity rows may also be pending reuse, etc.
///
/// For a [`Entity`] id to correspond to a conceptual entity, its row must do so, and it must have the most up to date generation of that row.
/// This can be un-intuitive sometimes, because an allocated [`Entity`] id that is perfectly correct but not constructed yet, still does not correspond to a conceptual entity.
/// This is why spawning an entity from commands will provide an [`Entity`] that, technically, does not exist yet; it's just that it is *queued* to exist soon.
///
/// # Aliasing /// # Aliasing
/// ///
/// Once an entity is despawned, it ceases to exist. /// Once an entity is despawned, it ceases to exist.
@ -899,7 +907,7 @@ impl Entities {
/// Get the [`Entity`] with a given id, if it exists in this [`Entities`] collection. /// Get the [`Entity`] with a given id, if it exists in this [`Entities`] collection.
/// Returns `None` if this [`Entity`] is outside of the range of currently declared conceptual entities /// Returns `None` if this [`Entity`] is outside of the range of currently declared conceptual entities
/// ///
/// Note: This method may or may not return `None` for rows that have never had their location [`declared`](Self::declare). /// Note: This method may or may not return `None` for rows that have never had their location declared.
pub fn resolve_from_id(&self, row: EntityRow) -> Option<Entity> { pub fn resolve_from_id(&self, row: EntityRow) -> Option<Entity> {
self.meta self.meta
.get(row.index() as usize) .get(row.index() as usize)