Struct World

pub struct World { /* private fields */ }

The central container for the entire ECS, holding all entities, components, and metadata.

The World orchestrates the CRPECS architecture. It owns all ECS data and provides the main API for creating and destroying entities, and for querying their component data.

Implementations

impl World

pub fn new() -> Self

Creates a new, empty World with pre-registered internal component types.

pub fn spawn<B: ComponentBundle>(&mut self, bundle: B) -> EntityId

Spawns a new entity with the given bundle of components.

This is the primary method for creating entities. It orchestrates the entire process:

1. Allocates a new EntityId.
2. Finds or creates a suitable ComponentPage for the component bundle.
3. Pushes the component data into the page’s columns.
4. Updates the entity’s metadata to point to the new data’s location.

Returns the EntityId of the newly created entity.

pub fn despawn(&mut self, entity_id: EntityId) -> bool

Despawns an entity, removing all its components and freeing its ID for recycling.

This method performs the following steps:

1. Verifies that the EntityId is valid by checking its index and generation.
2. Removes the entity’s component data from all pages where it is stored.
3. Marks the entity’s metadata slot as vacant and adds its index to the free list.

Returns true if the entity was valid and despawned, false otherwise.

pub fn query<'a, Q: WorldQuery>(&'a self) -> Query<'a, Q>

Creates an iterator that queries the world for entities matching a set of components and filters.

This is the primary method for reading and writing data in the ECS. The query Q is specified as a tuple via turbofish syntax. It can include component references (e.g., &Position, &mut Velocity) and filters (e.g., Without<Parent>).

This method is very cheap to call. It performs an efficient search to identify all ComponentPages that satisfy the query’s criteria. The returned iterator then efficiently iterates over the data in only those pages.

Examples

// Find all entities with a `Transform` and `GlobalTransform`.
for (transform, global) in world.query::<(&Transform, &GlobalTransform)>() {
    // ...
}

// Find all root entities (those with a `Transform` but without a `Parent`).
for (transform,) in world.query::<(&Transform, Without<Parent>)>() {
    // ...
}

pub fn get_mut<T: Component>(&mut self, entity_id: EntityId) -> Option<&mut T>

Gets a mutable reference to a single component T for a given entity.

This provides direct, “random” access to a component, which can be less performant than querying but is useful for targeted modifications.

Returns

None if the entity is not alive or does not have the requested component.

pub fn get<T: Component>(&self, entity_id: EntityId) -> Option<&T>

Gets an immutable reference to a single component T for a given entity.

This provides direct, “random” access to a component.

Returns

None if the entity is not alive or does not have the requested component.

pub fn register_component<T: Component>(&mut self, domain: SemanticDomain)

Registers a component type with a specific semantic domain.

This is a crucial setup step. Before a component of type T can be used in a bundle, it must be registered with the world to define which semantic page group its data will be stored in.

Trait Implementations

impl Default for World

fn default() -> Self

Creates a new, empty World via World::new().