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

A container of entities.

Each entity stored inside a world is uniquely identified by an Entity ID and may have an arbitrary collection of Components attached.

The entities in a world may be efficiently searched and iterated via queries.

Implementations

Creates a new world with the given options,

Returns the world’s unique ID.

Returns the number of entities in the world.

Returns true if the world contains no entities.

Returns true if the world contains an entity with the given ID.

Appends a named entity to the word, replacing any existing entity with the given ID.

Appends a new entity to the world. Returns the ID of the new entity. components should be a tuple of components to attach to the entity.

Examples

Pushing an entity with three components:

let mut world = World::default();
let _entity = world.push((1usize, false, 5.3f32));

Pushing an entity with one component (note the tuple syntax):

let mut world = World::default();
let _entity = world.push((1usize,));

Appends a collection of entities to the world. Returns the IDs of the new entities.

Examples

Inserting a vector of component tuples:

let mut world = World::default();
let _entities = world.extend(vec![
    (1usize, false, 5.3f32),
    (2usize, true, 5.3f32),
    (3usize, false, 5.3f32),
]);

Inserting a tuple of component vectors:

let mut world = World::default();
let _entities = world.extend(
    (
        vec![1usize, 2usize, 3usize],
        vec![false, true, false],
        vec![5.3f32, 5.3f32, 5.2f32],
    )
        .into_soa(),
);

SoA inserts require all vectors to have the same length. These inserts are faster than inserting via an iterator of tuples.

Removes the specified entity from the world. Returns true if an entity was removed.

Removes all entities from the world.

Gets an Entry for an entity, allowing manipulation of the entity.

Examples

Adding a component to an entity:

let mut world = World::default();
let entity = world.push((true, 0isize));
if let Some(mut entry) = world.entry(entity) {
    entry.add_component(0.2f32);
}

Subscribes to entity Events.

Packs the world’s internal component storage to optimise iteration performance for queries which match a GroupDef defined when this world was created.

Returns the raw component storage.

Splits the world into two. The left world allows access only to the data declared by the view; the right world allows access to all else.

Examples
let (left, right) = world.split::<&mut Position>();

With the above, ‘left’ contains a sub-world with access only to &Position and &mut Position, and right contains a sub-world with access to everything but &Position and &mut Position.

let (left, right) = world.split::<&Position>();

In this second example, left is provided access only to &Position. right is granted permission to everything but &mut Position.

Splits the world into two. The left world allows access only to the data declared by the query’s view; the right world allows access to all else.

Merges the given world into this world by moving all entities out of the source world.

Clones the entities from a world into this world.

A LayoutFilter selects which entities to merge. A Merger describes how to perform the merge operation.

If any entity IDs are remapped by the policy, their mappings will be returned in the result.

More advanced operations such as component type transformations can be performed with the Duplicate merger.

Examples

Cloning all entities from the source world, converting all i32 components to f64 components.

let mut world_a = World::default();
let mut world_b = World::default();

// any component types not registered with Duplicate will be ignored during the merge
let mut merger = Duplicate::default();
merger.register_copy::<isize>(); // copy is faster than clone
merger.register_clone::<String>();
merger.register_convert(|comp: &i32| *comp as f32);

let _ = world_a.clone_from(&world_b, &any(), &mut merger);

Clones a single entity from the source world into the destination world.

Creates a serde serializable representation of the world.

A LayoutFilter selects which entities shall be serialized. A WorldSerializer describes how components will be serialized.

As component types are not known at compile time, the world must be provided with the means to serialize each component. This is provided by the WorldSerializer implementation. This implementation also describes how ComponentTypeIds (which are not stable between compiles) are mapped to stable type identifiers. Components that are not known to the serializer will be omitted from the serialized output.

The Registry provides a WorldSerializer implementation suitable for most situations.

Examples

Serializing all entities with a Position component to JSON.

// create a registry which uses strings as the external type ID
let mut registry = Registry::<String>::default();
registry.register::<Position>("position".to_string());
registry.register::<f32>("f32".to_string());
registry.register::<bool>("bool".to_string());

// serialize entities with the `Position` component
let entity_serializer = Canon::default();
let json = serde_json::to_value(&world.as_serializable(
    component::<Position>(),
    &registry,
    &entity_serializer,
))
.unwrap();
println!("{:#}", json);

// registries can also be used to deserialize
use serde::de::DeserializeSeed;
let world: World = registry
    .as_deserialize(&entity_serializer)
    .deserialize(json)
    .unwrap();

Trait Implementations

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Returns an entity entry which can be used to access entity metadata and components.

Returns a mutable entity entry which can be used to access entity metadata and components.

Returns a component storage accessor for component types declared in the specified View.

Returns the world’s unique ID.

Performs the conversion.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait. Read more

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait. Read more

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s. Read more

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s. Read more

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait. Read more

Returns the argument unchanged.

Calls U::from(self).

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

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.