hyperion::world

Struct World

Source 
pub struct World { /* private fields */ }
Expand description

The ECS world, managing entities and their components.

§Fields

  • entity_allocator: Allocator tracking entity ids and generations.
  • storages: Type-erased component storages keyed by their TypeId.
  • resource_registry: Type-erased registry for arbitrary resources (including unique ones).

§Safety

  • All public APIs enforce Rust’s borrowing rules across component storages.
  • Type erasure is limited to internal maps; downcasting is guarded by TypeId checks in accessor methods to prevent type confusion.

Implementations§

Source§

impl World

Source

pub fn new() -> Self

Creates a new empty world.

§Returns
  • World: A new world with no entities, components, or resources.
Source

pub fn purge(&mut self)

Purges the world: removes all components and resets the entity allocator. After purge, no entities are alive and the next created entity will start from id 0 with generation 0.

§Effects
  • Clears all component storages and resources.
  • Resets the entity allocator (no free ids, no generations).
§Notes
  • Any previously held Entity values are invalid after purge.
Source

pub fn entity_count(&self) -> usize

Gets the current number of alive entities.

§Returns
  • usize: Count of currently alive entities.
Source

pub fn free_id_count(&self) -> usize

Returns the number of IDs ready to be recycled.

§Returns
  • usize: Count of free IDs currently available for reuse.
Source

pub fn create_entity(&mut self) -> Entity

Creates a new entity.

§Returns
  • Entity: The newly created entity identifier.
Source

pub fn create_entity_and_add_component<T: Component>( &mut self, component: T, ) -> Entity

Creates a new entity and adds the provided component to it.

§Type Parameters
  • T: The component type to add to the new entity.
§Parameters
  • component: The component instance to attach to the newly created entity.
§Returns
  • Entity: The newly created entity.
Source

pub fn destroy_entity(&mut self, entity: Entity)

Destroys an entity, marking it dead and removing all components associated with it.

§Parameters
  • entity: The entity to destroy. Safe to call multiple times; additional calls are no-ops.
Source

pub fn add_component<T: Component>(&mut self, entity: Entity, component: T)

Adds a component of type T to an entity, creating storage if necessary.

§Type Parameters
  • T: The component type to insert. Must implement Component and be 'static.
§Parameters
  • entity: The target entity to receive the component.
  • component: The component instance to add (replaces existing component of T on this entity).
§Effects
  • Creates the component storage for T if it does not yet exist.
  • If the entity already has a T, it is replaced with the new value.
Source

pub fn entity_has_component<T: Component>(&self, entity: Entity) -> bool

Checks whether an entity has a component of type T.

§Type Parameters
  • T: The component type to check for.
§Parameters
  • entity: The entity to query.
§Returns
  • bool: true if the entity currently has a T component; otherwise false.
Source

pub fn get_component<T: Component>(&self, entity: Entity) -> Option<&T>

Retrieves an immutable reference to a component of type T for an entity.

§Type Parameters
  • T: The component type to retrieve.
§Parameters
  • entity: The entity whose component is being requested.
§Returns
  • Option<&T>: Some(&T) if the entity currently has a T component; None otherwise.
Source

pub fn get_component_mut<T: Component>( &mut self, entity: Entity, ) -> Option<&mut T>

Retrieves a mutable reference to a component of type T for an entity.

§Type Parameters
  • T: The component type to retrieve mutably.
§Parameters
  • entity: The entity whose component is being requested mutably.
§Returns
  • Option<&mut T>: Some(&mut T) if the entity currently has a T component; None otherwise.
§Notes
  • Borrowing rules apply across all storages; this method requires &mut self to ensure mutable aliasing rules are respected.
Source

pub fn get_all_components_with_entities<T: Component>( &self, ) -> Vec<(Entity, &T)>

Returns all components of type T paired with their owning entities.

§Type Parameters
  • T: The component type to iterate over.
§Returns
  • Vec<(Entity, &T)>: A vector of (Entity, &T) pairs for every T stored.
§Ordering
  • Follows the dense storage order of ComponentStorage<T>, which is generally insertion order preserved via swap-remove when deletions occur.
Source

pub fn get_all_components_with_entities_mut<T: Component>( &mut self, ) -> Vec<(Entity, &mut T)>

Returns all components of type T mutably paired with their owning entities.

§Type Parameters
  • T: The component type to iterate over mutably.
§Returns
  • Vec<(Entity, &mut T)>: A vector of (Entity, &mut T) pairs for every T stored.
§Ordering
  • Follows the dense storage order of ComponentStorage<T>;
§Notes
  • Requires &mut self to guarantee sound mutable access to components.
Source

pub fn get_entities_for<T: Component>(&self) -> Vec<Entity>

Returns the list of entities that have component T.

§Type Parameters
  • T: The component type to search for.
§Returns
  • Vec<Entity>: All entities that currently have a T component.
Source

pub fn get_entities_with_2<T1: Component, T2: Component>(&self) -> Vec<Entity>

Returns entities that have both component types T1 and T2.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
§Returns
  • Vec<Entity>: Entities that contain both T1 and T2.
Source

pub fn get_entities_with_3<T1: Component, T2: Component, T3: Component>( &self, ) -> Vec<Entity>

Returns entities that have component types T1, T2, and T3.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
  • T3: Third component type.
§Returns
  • Vec<Entity>: Entities that contain T1, T2, and T3.
Source

pub fn get_entities_with_4<T1: Component, T2: Component, T3: Component, T4: Component>( &self, ) -> Vec<Entity>

Returns entities that have component types T1, T2, T3, and T4.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
  • T3: Third component type.
  • T4: Fourth component type.
§Returns
  • Vec<Entity>: Entities that contain T1, T2, T3, and T4.
Source

pub fn get_entities_with_5<T1: Component, T2: Component, T3: Component, T4: Component, T5: Component>( &self, ) -> Vec<Entity>

Returns entities that have component types T1, T2, T3, T4, and T5.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
  • T3: Third component type.
  • T4: Fourth component type.
  • T5: Fifth component type.
§Returns
  • Vec<Entity>: Entities that contain T1, T2, T3, T4, and T5.
Source

pub fn get_entities_and_components_with_2<T1: Component, T2: Component>( &self, ) -> Vec<(Entity, &T1, &T2)>

Returns entities with both components and their component references.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
§Returns
  • Vec<(Entity, &T1, &T2)>: Tuples of the entity and references to both components.
§Ordering
  • The iteration order follows the dense storage of T1.
Source

pub fn get_entities_and_components_with_3<T1: Component, T2: Component, T3: Component>( &self, ) -> Vec<(Entity, &T1, &T2, &T3)>

Returns entities with components T1, T2, and T3 and their references.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
  • T3: Third component type.
§Returns
  • Vec<(Entity, &T1, &T2, &T3)>: Tuples of the entity and three component references.
§Ordering
  • The iteration order follows the dense storage of T1.
Source

pub fn get_entities_and_components_with_4<T1: Component, T2: Component, T3: Component, T4: Component>( &self, ) -> Vec<(Entity, &T1, &T2, &T3, &T4)>

Returns entities with components T1, T2, T3, and T4 and their references.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
  • T3: Third component type.
  • T4: Fourth component type.
§Returns
  • Vec<(Entity, &T1, &T2, &T3, &T4)>: Tuples of the entity and four component references.
§Ordering
  • The iteration order follows the dense storage of T1.
Source

pub fn get_entities_and_components_with_5<T1: Component, T2: Component, T3: Component, T4: Component, T5: Component>( &self, ) -> Vec<(Entity, &T1, &T2, &T3, &T4, &T5)>

Returns entities with components T1, T2, T3, T4, and T5 and their references.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
  • T3: Third component type.
  • T4: Fourth component type.
  • T5: Fifth component type.
§Returns
  • Vec<(Entity, &T1, &T2, &T3, &T4, &T5)>: Tuples of the entity and five component references.
§Ordering
  • The iteration order follows the dense storage of T1.
Source

pub fn get_components_with_2<T1: Component, T2: Component>( &self, ) -> (Vec<&T1>, Vec<&T2>)

Returns only components for entities that have both components, aligned by entity.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
§Returns
  • (Vec<&T1>, Vec<&T2>): Two vectors with matching indices corresponding to the same entity.
§Ordering
  • The ordering follows the dense storage order of T1 filtered by presence in T2.
Source

pub fn get_components_with_3<T1: Component, T2: Component, T3: Component>( &self, ) -> (Vec<&T1>, Vec<&T2>, Vec<&T3>)

Returns only components for entities that have all three components, aligned by entity.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
  • T3: Third component type.
§Returns
  • (Vec<&T1>, Vec<&T2>, Vec<&T3>): Three vectors with matching indices for the same entities.
§Ordering
  • The ordering follows the dense storage of T1 filtered by entities also having T2 and T3.
Source

pub fn get_components_with_4<T1: Component, T2: Component, T3: Component, T4: Component>( &self, ) -> (Vec<&T1>, Vec<&T2>, Vec<&T3>, Vec<&T4>)

Returns only components for entities that have all four components, aligned by entity.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
  • T3: Third component type.
  • T4: Fourth component type.
§Returns
  • (Vec<&T1>, Vec<&T2>, Vec<&T3>, Vec<&T4>): Four vectors with matching indices for the same entities.
§Ordering
  • The ordering follows the dense storage of T1 filtered by entities also having T2, T3, and T4.
Source

pub fn get_components_with_5<T1: Component, T2: Component, T3: Component, T4: Component, T5: Component>( &self, ) -> (Vec<&T1>, Vec<&T2>, Vec<&T3>, Vec<&T4>, Vec<&T5>)

Returns only components for entities that have all five components, aligned by entity.

§Type Parameters
  • T1: First component type.
  • T2: Second component type.
  • T3: Third component type.
  • T4: Fourth component type.
  • T5: Fifth component type.
§Returns
  • (Vec<&T1>, Vec<&T2>, Vec<&T3>, Vec<&T4>, Vec<&T5>): Five vectors with matching indices for the same entities.
§Ordering
  • The ordering follows the dense storage of T1 filtered by entities also having T2, T3, T4, and T5.
Source

pub fn get_all_components<T: Component>(&self) -> Vec<&T>

Returns immutable references to all components of type T currently stored in the world.

§Type Parameters
  • T: The component type to retrieve.
§Returns
  • Vec<&T>: All components of type T. Empty if no storage exists.
§Ordering
  • Follows the dense storage order of ComponentStorage<T>.
Source

pub fn get_all_components_mut<T: Component>(&mut self) -> Vec<&mut T>

Returns mutable references to all components of type T currently stored in the world.

§Type Parameters
  • T: The component type to retrieve mutably.
§Returns
  • Vec<&mut T>: All components of type T as mutable references. Empty if no storage exists.
§Ordering
  • Follows the dense storage order of ComponentStorage<T>.
§Notes
  • Requires &mut self to ensure sound mutable access across all storages.
Source

pub fn get_entity_for<T: Component>(&self, component: &T) -> Option<Entity>

Given a reference to a component of type T, returns the owning Entity.

§Type Parameters
  • T: The component type of the provided reference.
§Parameters
  • component: A reference to a component previously obtained from the world.
§Returns
  • Option<Entity>: The entity that owns the component, if found.
§Complexity
  • O(n) in the number of T components; implemented by pointer-identity scan of the dense storage.
§Notes
  • Intended for convenience or debugging; prefer entity-centric access patterns when possible.
Source

pub fn register_resource<T: 'static>(&mut self, res: T) -> ResourceHandle

Registers a resource of any type T into the resource registry. Returns a ResourceHandle that can be used to retrieve the resource later.

§Type Parameters
  • T: The type of the resource. Must be 'static so it can be stored in a type-erased container.
§Parameters
  • res: The resource instance to register.
§Returns
  • ResourceHandle: A unique handle used to retrieve or mutate the resource later.
Source

pub fn get_resource<T: 'static>(&self, handle: ResourceHandle) -> Option<&T>

Retrieves an immutable reference to a registered resource of type T using its ResourceHandle.

§Type Parameters
  • T: The expected type of the resource. Must match the type used in register_resource.
§Parameters
  • handle: The handle returned by register_resource.
§Returns
  • Option<&T>: Some(&T) if the handle is valid and the type matches, otherwise None.
Source

pub fn get_resource_mut<T: 'static>( &mut self, handle: ResourceHandle, ) -> Option<&mut T>

Retrieves a mutable reference to a registered resource of type T using its ResourceHandle.

§Type Parameters
  • T: The expected type of the resource. Must match the type used in register_resource.
§Parameters
  • handle: The handle returned by register_resource.
§Returns
  • Option<&mut T>: Some(&mut T) if the handle is valid and the type matches, otherwise None.
Source

pub fn remove_resource<T: 'static>( &mut self, handle: ResourceHandle, ) -> Option<T>

Removes a resource of type T from the world’s resource registry.

§Type Parameters
  • T: The type of the resource to remove.
§Parameters
  • handle: The handle associated with the resource to be removed.
§Returns
  • Some(T): If the resource was successfully removed.
  • None: If the handle was invalid or the type mismatched.
Source

pub fn register_unique<T: 'static>(&mut self, resource: T)

Registers or overwrites the unique resource of type T in the world.

§Parameters
  • resource: The resource instance to register as unique.
Source

pub fn get_unique<T: 'static>(&self) -> Option<&T>

Gets an immutable reference to the unique resource of type T from the world.

§Returns
  • Option<&T>: Some reference if the unique resource is present, None otherwise.
Source

pub fn get_unique_mut<T: 'static>(&mut self) -> Option<&mut T>

Gets a mutable reference to the unique resource of type T from the world.

§Returns
  • Option<&mut T>: Some mutable reference if the unique resource is present, None otherwise.
Source

pub fn remove_unique<T: 'static>(&mut self) -> Option<T>

Removes the unique resource of type T from the world and returns it.

§Returns
  • Option<T>: The removed resource if it was present, None otherwise.

Auto Trait Implementations§

§

impl Freeze for World

§

impl !RefUnwindSafe for World

§

impl !Send for World

§

impl !Sync for World

§

impl Unpin for World

§

impl !UnwindSafe for World

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.