Struct Entity 

pub struct Entity { /* private fields */ }

A lightweight identifier for an entity in the ECS.

Entities are the “E” in ECS - they are identifiers that components attach to. An entity by itself has no data; it’s purely an ID used to look up components.

Memory Layout

Entity (8 bytes total):
┌────────────────┬────────────────┐
│  index (u32)   │ generation(u32)│
└────────────────┴────────────────┘

Thread Safety

Entity is Copy, Clone, Send, and Sync. Entity values can be freely shared across threads. However, operations on the ECS world that use entities require appropriate synchronization.

Implementations

impl Entity

pub const PLACEHOLDER: Entity

A placeholder entity that should never be returned by the allocator.

Use this as a sentinel value for “no entity” or uninitialized entity fields. The placeholder uses u32::MAX for the index, which the allocator will never return (it would require 4 billion+ entity allocations first).

Example

use goud_engine::ecs::entity::Entity;

let mut maybe_entity = Entity::PLACEHOLDER;
assert!(maybe_entity.is_placeholder());

// Later, assign a real entity
maybe_entity = Entity::new(0, 1);
assert!(!maybe_entity.is_placeholder());

pub const fn new(index: u32, generation: u32) -> Entity

Creates a new entity with the given index and generation.

This is primarily used by EntityAllocator. Direct construction is possible but not recommended for typical use.

Arguments

• index - The slot index for this entity
• generation - The generation counter for this slot

Example

use goud_engine::ecs::entity::Entity;

let entity = Entity::new(42, 1);
assert_eq!(entity.index(), 42);
assert_eq!(entity.generation(), 1);

pub const fn index(&self) -> u32

Returns the index of this entity.

The index is the slot in the entity allocator’s internal array. Multiple entities may share the same index (at different times), distinguished by their generation.

pub const fn generation(&self) -> u32

Returns the generation of this entity.

The generation increments each time a slot is reused. Comparing generations allows detecting stale entity references.

pub const fn is_placeholder(&self) -> bool

Returns true if this is the placeholder entity.

The placeholder entity should never be used in actual ECS operations. It’s a sentinel value for “no entity” situations.

pub const fn to_bits(&self) -> u64

Packs the entity into a single u64 value.

Format: upper 32 bits = generation, lower 32 bits = index.

This is useful for FFI or when a single integer representation is needed.

Example

use goud_engine::ecs::entity::Entity;

let entity = Entity::new(42, 7);
let packed = entity.to_bits();

// Upper 32 bits: generation (7), Lower 32 bits: index (42)
assert_eq!(packed, (7_u64 << 32) | 42);

// Round-trip
let unpacked = Entity::from_bits(packed);
assert_eq!(entity, unpacked);

pub const fn from_bits(bits: u64) -> Entity

Creates an entity from a packed u64 value.

Format: upper 32 bits = generation, lower 32 bits = index.

Example

use goud_engine::ecs::entity::Entity;

let packed = (3_u64 << 32) | 100;
let entity = Entity::from_bits(packed);

assert_eq!(entity.index(), 100);
assert_eq!(entity.generation(), 3);

Trait Implementations

impl Clone for Entity

fn clone(&self) -> Entity

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Entity

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the entity as Entity(index:generation).

Example

use goud_engine::ecs::entity::Entity;

let entity = Entity::new(42, 3);
assert_eq!(format!("{:?}", entity), "Entity(42:3)");

impl Default for Entity

fn default() -> Entity

Returns the placeholder entity.

Using Default returns PLACEHOLDER, which should be treated as “no entity”.

impl<'de> Deserialize<'de> for Entity

fn deserialize<D>( deserializer: D, ) -> Result<Entity, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Entity

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the entity in a user-friendly way.

Same format as Debug: Entity(index:generation).

impl From<Entity> for Parent

fn from(entity: Entity) -> Parent

Converts to this type from the input type.

impl From<Parent> for Entity

fn from(parent: Parent) -> Entity

Converts to this type from the input type.

impl From<u64> for Entity

fn from(bits: u64) -> Entity

Creates an entity from a packed u64 representation.

impl Hash for Entity

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Hashes the entity by combining index and generation.

Two entities with the same index but different generations will hash differently, which is important for using entities as map keys.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Entity

fn eq(&self, other: &Entity) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Entity

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl WorldQuery for Entity

Entity can be queried to get the entity ID itself.

This is useful when you need the entity ID along with component data, or when iterating over all entities in an archetype.

type Item<'w> = Entity

The type of data this query fetches.

type State = ()

The cached state for this query.

fn init_state(_world: &World) -> <Entity as WorldQuery>::State

Initializes the query state from the world.

fn component_access( _state: &<Entity as WorldQuery>::State, ) -> BTreeSet<ComponentId>

Returns the set of component IDs this query reads.

fn matches_archetype( _state: &<Entity as WorldQuery>::State, _archetype: &Archetype, ) -> bool

Checks whether this query matches the given archetype.

fn fetch<'w>( _state: &<Entity as WorldQuery>::State, world: &'w World, entity: Entity, ) -> Option<<Entity as WorldQuery>::Item<'w>>

Fetches data for a specific entity from the world.

fn fetch_mut<'w>( state: &Self::State, world: &'w mut World, entity: Entity, ) -> Option<Self::Item<'w>>

Fetches data for a specific entity from a mutable world reference.

impl Copy for Entity

impl Eq for Entity

impl ReadOnlyWorldQuery for Entity

impl StructuralPartialEq for Entity