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 query_mut<'a, Q: WorldQuery>(&'a mut self) -> QueryMut<'a, Q>

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

This method is similar to query, but it allows mutable access to the components. The same filtering logic applies, ensuring that only pages containing the required

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.

pub fn add_component<C: Component>( &mut self, entity_id: EntityId, component: C, ) -> Result<Option<PageIndex>, AddComponentError>

Adds a new component C to an existing entity, migrating its domain data.

This operation is designed to be fast. It performs the necessary data migration to move the entity’s components for the given SemanticDomain to a new ComponentPage that matches the new layout.

Crucially, it does NOT clean up the “hole” left in the old page. Instead, it returns the location of the orphaned data, delegating the cleanup task to an asynchronous garbage collection system.

Returns

• Ok(Option<PageIndex>): On success. The Option contains the location of orphaned data if a migration occurred, which should be sent to a garbage collector. It is None if no migration was needed (e.g., adding to a new domain).
• Err(AddComponentError): If the operation failed (e.g., entity not alive, component not registered, or component already present).

pub fn remove_component_domain<C: Component>( &mut self, entity_id: EntityId, ) -> Option<PageIndex>

Logically removes all components belonging to a specific SemanticDomain from an entity.

This is an extremely fast, O(1) operation that only modifies the entity’s metadata. It does not immediately deallocate or move any component data. The component data is “orphaned” and will be cleaned up later by a garbage collection process.

This method is generic over a component C to determine which domain to remove.

Returns

• Some(PageIndex): Contains the location of the orphaned data if the components were successfully removed. This can be sent to a garbage collector.
• None: If the entity is not alive or did not have any components in the specified SemanticDomain.

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 iter_entities(&self) -> impl Iterator<Item = EntityId> + '_

Returns an iterator over all currently living EntityIds in the world.

pub fn serialize_archetype(&self) -> Result<Vec<u8>, EncodeError>

Serializes the entire World state using a direct memory layout strategy.

This method is highly unsafe as it reads raw component memory.

pub fn deserialize_archetype(&mut self, data: &[u8]) -> Result<(), DecodeError>

Deserializes and completely replaces the World state from a memory layout.

This method is highly unsafe as it writes raw bytes into component vectors.

Trait Implementations

impl Default for World

fn default() -> Self

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

impl WorldMaintenance for World

fn cleanup_orphan_at(&mut self, location: PageIndex, domain: SemanticDomain)

Cleans up an orphaned data slot in a page.