Struct legion::world::World

pub struct World { /* fields omitted */ }

Contains queryable collections of data associated with Entitys.

Implementations

impl World

pub const DEFAULT_COMMAND_BUFFER_SIZE: usize

pub fn new() -> World

Create a new World independent of any Universe.

Entity IDs in such a world will only be unique within that world. See also Universe::create_world.

pub fn command_buffer_size(&self) -> usize

pub fn set_command_buffer_size(&mut self, command_buffer_size: usize)

pub fn subscribe<T>(&mut self, sender: Sender<Event>, filter: T) where
    T: 'static + EntityFilter + Sync, 

Subscribes to event notifications.

A filter determines which events are of interest. Use any() to listen to all events.

Examples

let (sender, receiver) = crossbeam_channel::unbounded();
world.subscribe(sender, component::<Position>() | tag::<Model>());

for event in receiver.try_iter() {
    println!("{:?}", event);
}

pub fn storage(&self) -> &Storage

pub fn storage_mut(&mut self) -> &mut Storage

pub fn id(&self) -> WorldId

Gets the unique ID of this world within its universe.

pub fn get_entity_location(&self, entity: Entity) -> Option<EntityLocation>

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

Iterate all entities in existence. Internally this iterates archetypes instead of entity allocators because the data structures contains a list of free entities instead of allocated entities

pub fn insert<T, C>(&mut self, tags: T, components: C) -> &[Entity] where
    C: IntoComponentSource,
    T: TagSet + TagLayout + for<'a> Filter<ChunksetFilterData<'a>>, 

Inserts new entities into the world. This insertion method should be preferred, as it performs no movement of components for inserting multiple entities and components.

Examples

Inserting entity tuples:

let tags = (model, color);
let data = vec![
    (Position(0.0), Rotation(0.0)),
    (Position(1.0), Rotation(1.0)),
    (Position(2.0), Rotation(2.0)),
];
world.insert(tags, data);

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

Removes the given Entity from the World.

Returns true if the entity was deleted; else false.

pub fn delete_all(&mut self)

Delete all entity data. This leaves subscriptions and the command buffer intact.

pub fn add_component<T>(
    &mut self,
    entity: Entity,
    component: T
) -> Result<(), EntityMutationError> where
    T: Component, 

Adds a component to an entity, or sets its value if the component is already present.

Notes

This function has the overhead of moving the entity to either an existing or new archetype, causing a memory copy of the entity to a new location. This function should not be used multiple times in successive order.

pub fn remove_component<T>(
    &mut self,
    entity: Entity
) -> Result<(), EntityMutationError> where
    T: Component, 

Removes a component from an entity.

Notes

This function has the overhead of moving the entity to either an existing or new archetype, causing a memory copy of the entity to a new location. This function should not be used multiple times in successive order.

World::remove_components should be used for adding multiple omponents to an entity at once.

pub fn remove_components<T>(
    &mut self,
    entity: Entity
) -> Result<(), EntityMutationError> where
    T: ComponentTypeTupleSet, 

Removes

Notes

This function is provided for bulk deleting components from an entity. This difference between this function and remove_component is this allows us to remove multiple components and still only perform a single move operation of the entity.

pub fn add_tag<T>(
    &mut self,
    entity: Entity,
    tag: T
) -> Result<(), EntityMutationError> where
    T: Tag, 

Adds a tag to an entity, or sets its value if the tag is already present.

pub fn remove_tag<T>(
    &mut self,
    entity: Entity
) -> Result<(), EntityMutationError> where
    T: Tag, 

Removes a tag from an entity.

pub fn has_component_by_id(
    &self,
    entity: Entity,
    component: ComponentTypeId
) -> bool

Checks that the provided ComponentTypeId is present on a given entity.

Returns true if it exists, otherwise false.

pub fn has_component<T>(&self, entity: Entity) -> bool where
    T: Component, 

Checks that the provided Component is present on a given entity.

Returns true if it exists, otherwise false.

pub fn entity_component_types(
    &self,
    entity: Entity
) -> Option<&[(ComponentTypeId, ComponentMeta)]>

Returns the entity's component types, if the entity exists.

pub fn entity_tag_types(
    &self,
    entity: Entity
) -> Option<&[(TagTypeId, TagMeta)]>

Returns the entity's tag types, if the entity exists.

pub fn defrag(&mut self, budget: Option<usize>)

Iteratively defragments the world's internal memory.

This compacts entities into fewer more continuous chunks.

budget describes the maximum number of entities that can be moved in one call. Subsequent calls to defrag will resume progress from the previous call.

pub fn move_from(&mut self, world: World)

Move entities from a world to this world, copying all appropriate archetypes, tags entities and components into this world.

pub fn clone_from<'s, CloneImplT, CloneImplResultT, EntityReplacePolicyT>(
    &mut self,
    src_world: &World,
    clone_impl: &CloneImplT,
    clone_impl_result: &mut CloneImplResultT,
    entity_replace_policy: &'s EntityReplacePolicyT
) where
    CloneImplResultT: CloneImplResult,
    CloneImplT: CloneImpl,
    EntityReplacePolicyT: EntityReplacePolicy<'s>, 

This will copy the data from src_world into this world. The logic to do the copy is delegated to the clone_impl provided by the user. In addition to simple copying, it's also possible to transform from one type to another. This is useful for cases where you want to read from serializable data (like a physics shape definition) and construct something that isn't serializable (like a handle to a physics body)

By default, all entities in the new world will be assigned a new Entity. result_mappings (if not None) will be populated with the old/new Entities, which allows for mapping data between the old and new world.

If you want to replace existing entities (for example to hot-reload data from a file,) populate replace_mappings. For every entry in this map, the key must exist in the source world and the value must exist in the destination world. All entities in the destination world referenced by this map will be deleted, and the entities copied over will be assigned the same entity. If these constraints are not met, this function will panic.

pub fn clone_from_single<C>(
    &mut self,
    src_world: &World,
    src_entity: Entity,
    clone_impl: &C,
    replace_mapping: Option<Entity>
) -> Entity where
    C: CloneImpl, 

This will copy the src_entity from src_world into this world. The logic to do the copy is delegated to the clone_impl provided by the user. In addition to simple copying, it's also possible to transform from one type to another. This is useful for cases where you want to read from serializable data (like a physics shape definition) and construct something that isn't serializable (like a handle to a physics body)

By default, the entity in the new world will be assigned a new Entity. The return value indicates the Entity in the new world, which allows for mapping data the old and new world.

If you want to replace an existing entity (for example to hot-reload data from a file,) populate replace_mapping. This entity must exist in the destination world. The entity in the destination world will be deleted, and the entity copied over will be assigned the same entity. If these constraints are not met, this function will panic.

pub fn split<T>(&mut self) -> (SubWorld, SubWorld) where
    T: for<'v> View<'v>, 

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.

pub fn split_for_query<V, F>(&mut self, &'q Query<V, F>) -> (SubWorld, SubWorld) where
    F: EntityFilter,
    V: for<'v> View<'v>, 

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.

Trait Implementations

impl Default for World

fn default() -> World

Returns the "default value" for a type.

impl EntityStore for World

fn get_component<T>(&self, entity: Entity) -> Option<Ref<T>> where
    T: Component, 

Borrows component data for the given entity.

unsafe fn get_component_mut_unchecked<T>(
    &self,
    entity: Entity
) -> Option<RefMut<T>> where
    T: Component, 

Borrows component data for the given entity. Does not perform static borrow checking.

fn get_tag<T>(&self, entity: Entity) -> Option<&T> where
    T: Tag, 

Gets tag data for the given entity.

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

Determines if the given Entity is alive within this World.

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

Gets the entity component storage. Validates that the world can provide access to everything needed by the view.

fn get_component_mut<T>(&mut self, entity: Entity) -> Option<RefMut<T>> where
    T: Component, 

Mutably borrows entity data for the given entity.

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

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

Performs the conversion.

impl Send for World

impl Sync for World