Struct legion::World

pub struct World { /* fields omitted */ }

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

impl World

pub fn new(options: WorldOptions) -> Self

Creates a new world with the given options,

pub fn id(&self) -> WorldId

Returns the world's unique ID.

pub fn len(&self) -> usize

Returns the number of entities in the world.

pub fn is_empty(&self) -> bool

Returns true if the world contains no entities.

pub fn contains(&self, entity: Entity) -> bool

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

pub fn push_with_id<T>(&mut self, entity_id: Entity, components: T) where
    Option<T>: IntoComponentSource, 

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

pub fn push<T>(&mut self, components: T) -> Entity where
    Option<T>: IntoComponentSource, 

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,));

pub fn extend(&mut self, components: impl IntoComponentSource) -> &[Entity]

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.

pub fn remove(&mut self, entity: Entity) -> bool

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

pub fn clear(&mut self)

Removes all entities from the world.

pub fn entry(&mut self, entity: Entity) -> Option<Entry<'_>>

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);
}

pub fn subscribe<T, S>(&mut self, sender: S, filter: T) where
    T: LayoutFilter + Send + Sync + 'static,
    S: EventSender + 'static, 

Subscribes to entity events.

pub fn pack(&mut self, options: PackOptions)

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

pub fn components(&self) -> &Components

Returns the raw component storage.

pub fn split<T: IntoView>(&mut self) -> (SubWorld<'_>, SubWorld<'_>)

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.

pub fn split_for_query<'q, V: IntoView, F: EntityFilter>(
    &mut self,
    _: &'q Query<V, F>
) -> (SubWorld<'_>, SubWorld<'_>)

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.

pub fn move_from<F: LayoutFilter>(&mut self, source: &mut World, filter: &F)

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

pub fn clone_from<F: LayoutFilter, M: Merger>(
    &mut self,
    source: &World,
    filter: &F,
    merger: &mut M
) -> HashMap<Entity, Entity, EntityHasher>

Clones the entities from a world into this world.

A filter 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);

pub fn clone_from_single<M: Merger>(
    &mut self,
    source: &World,
    entity: Entity,
    merger: &mut M
) -> Entity

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

pub fn as_serializable<'a, F: LayoutFilter, W: WorldSerializer>(
    &'a self,
    filter: F,
    world_serializer: &'a W
) -> SerializableWorld<'a, F, W>

Creates a serde serializable representation of the world.

A filter selects which entities shall be serialized.
A world serializer 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 json = serde_json::to_value(&world.as_serializable(component::<Position>(), &registry)).unwrap();
println!("{:#}", json);

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

Trait Implementations

impl Debug for World

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for World

fn default() -> Self

Returns the "default value" for a type.

impl EntityStore for World

fn entry_ref(&self, entity: Entity) -> Result<EntryRef<'_>, EntityAccessError>

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

fn entry_mut(
    &mut self,
    entity: Entity
) -> Result<EntryMut<'_>, EntityAccessError>

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

fn get_component_storage<V: for<'b> View<'b>>(
    &self
) -> Result<StorageAccessor<'_>, EntityAccessError>

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

fn id(&self) -> WorldId

Returns the world's unique ID.

impl<'a> From<&'a mut World> for SubWorld<'a>

fn from(world: &'a mut World) -> Self

Performs the conversion.