Struct World 

pub struct World { /* private fields */ }

Collection of entities and registered sparse component storages.

Register component types before insertion. Iteration order within a storage changes on removal; use Self::entities for deterministic index order. Built-in engine worlds are initialized by Scene::default.

Implementations

impl World

pub fn new() -> World

Creates an empty world with no registered component types.

pub fn register<T>(&mut self)

where T: Component,

Creates the storage for T. Must be called (by the host) before T is inserted.

pub fn is_registered<T>(&self) -> bool

where T: Component,

Whether the host registered this exact component type.

Panics

Panics if the key belongs to an incompatible component type.

pub fn len(&self) -> usize

Number of living entities, including entities without any components.

pub fn is_empty(&self) -> bool

Whether no living entities remain. Registered storages are not counted.

pub fn spawn(&mut self) -> Entity

Creates a living entity without components, reusing a vacant slot when possible.

pub fn despawn(&mut self, e: Entity)

Removes an entity and all its components. Stale handles are ignored.

This ECS operation does not traverse engine hierarchy relations.

pub fn is_alive(&self, e: Entity) -> bool

Checks both slot occupancy and generation. Handles from other worlds are unsupported.

pub fn entities(&self) -> Vec<Entity>

All living entities in index order.

pub fn iter_entities(&self) -> impl Iterator<Item = Entity>

Borrows all living handles in index order without allocating a snapshot.

pub fn clear(&mut self)

Destroys every entity while preserving registrations and allocated storage. All previously issued handles become stale.

pub fn insert<T>(&mut self, e: Entity, value: T)

where T: Component,

Inserts or replaces a component. Stale entities are ignored.

Panics

Panics if a living entity is used before Self::register for T, or the component key conflicts with an incompatible registered type.

pub fn try_insert<T>( &mut self, entity: Entity, value: T, ) -> Result<Option<T>, T>

where T: Component,

Inserts or replaces a component without panicking for stale entities or unregistered types. On success returns the replaced value, if any; on rejection returns ownership of the supplied value unchanged. Conflicting component-key metadata still panics before any erased cast.

pub fn remove<T>(&mut self, e: Entity) -> Option<T>

where T: Component,

Removes and returns a component, or None for a stale entity or absent component.

pub fn has<T>(&self, e: Entity) -> bool

where T: Component,

Whether a living entity has T.

pub fn get<T>(&self, e: Entity) -> Option<&T>

where T: Component,

Borrows a component; returns None for stale entities and absent types.

pub fn get_mut<T>(&mut self, e: Entity) -> Option<&mut T>

where T: Component,

Mutably borrows a component; returns None for stale entities and absent types.

pub fn get2<A, B>(&self, entity: Entity) -> Option<(&A, &B)>

where A: Component, B: Component,

Borrows two components of one living entity. Repeated component types are allowed.

pub fn get2_mut<A, B>(&mut self, entity: Entity) -> Option<(&mut A, &mut B)>

where A: Component, B: Component,

Mutably borrows two distinct component storages on one living entity. Returns None for stale entities, missing components, unregistered types or identical storage keys (which would otherwise alias mutable references).

Panics

Panics if component metadata conflicts with a registered storage key.

pub fn for_each2_mut<A, B>( &mut self, visit: impl FnMut(Entity, &mut A, &mut B), ) -> usize

where A: Component, B: Component,

Applies a callback to every entity containing two distinct mutable component types. Returns the processed count; identical storage keys process zero entities. Structural changes are intentionally unavailable inside the callback.

pub fn retain<T>(&mut self, keep: impl FnMut(Entity, &mut T) -> bool) -> usize

where T: Component,

Removes T values rejected by a mutable predicate, retaining all entities. Returns the number removed. Dense storage order may change during removals.

pub fn iter<T>(&self) -> impl Iterator<Item = (Entity, &T)>

where T: Component,

Iterates a dense storage without allocation. An unregistered type yields no items.

pub fn iter_mut<T>(&mut self) -> impl Iterator<Item = (Entity, &mut T)>

where T: Component,

Mutably iterates a dense storage; structural world changes require a snapshot instead.

pub fn entities_with<T>(&self) -> Vec<Entity>

where T: Component,

Entities that have component T (snapshot, safe to mutate the world while looping).

pub fn entities_with2<A, B>(&self) -> Vec<Entity>

where A: Component, B: Component,

Entities that have both A and B.

pub fn iter2<A, B>(&self) -> impl Iterator<Item = (Entity, &A, &B)>

where A: Component, B: Component,

Borrows entities containing both component types, in A storage order. Matching a type with itself is supported because both borrows are shared.

pub fn iter3<A, B, C>(&self) -> impl Iterator<Item = (Entity, &A, &B, &C)>

where A: Component, B: Component, C: Component,

Borrows entities containing all three component types, in A storage order.

pub fn entities_with3<A, B, C>(&self) -> Vec<Entity>

where A: Component, B: Component, C: Component,

Snapshot of entities containing all three component types.

pub fn entities_without<A, B>(&self) -> Vec<Entity>

where A: Component, B: Component,

Snapshot of entities with A but without B, in A storage order.

pub fn get_or_insert_with<T>( &mut self, e: Entity, create: impl FnOnce() -> T, ) -> Option<&mut T>

where T: Component,

Inserts a lazily constructed component only when missing, then borrows it. Returns None without invoking create for stale entities.

Panics

Panics if T is unregistered on a living entity.

pub fn clear_components<T>(&mut self)

where T: Component,

Removes every T, preserving entities and the registered storage.

pub fn count<T>(&self) -> usize

where T: Component,

Number of entities with T, or zero for an unregistered type.

Trait Implementations

impl Default for World

fn default() -> World

Returns the “default value” for a type.