Struct bevy::ecs::World

pub struct World {
    pub archetypes: Vec<Archetype, Global>,
    // some fields omitted
}

An unordered collection of entities, each having any number of distinctly typed components

Similar to HashMap<Entity, Vec<Box<dyn Any>>> where each Vec never contains two of the same type, but far more efficient to traverse.

The components of entities who have the same set of component types are stored in contiguous runs, allowing for extremely fast, cache-friendly iteration.

Fields

archetypes: Vec<Archetype, Global>

Implementations

impl World

pub fn new() -> World

Create an empty world

pub fn spawn(&mut self, bundle: impl DynamicBundle) -> Entity

Create an entity with certain components

Returns the ID of the newly created entity.

Arguments can be tuples, structs annotated with #[derive(Bundle)], or the result of calling build on an EntityBuilder, which is useful if the set of components isn't statically known. To spawn an entity with only one component, use a one-element tuple like (x,).

Any type that satisfies Send + Sync + 'static can be used as a component.

Example

let mut world = World::new();
let a = world.spawn((123, "abc"));
let b = world.spawn((456, true));

pub fn spawn_batch<I>(
    &mut self,
    iter: I
) -> SpawnBatchIter<'_, <I as IntoIterator>::IntoIter> where
    I: IntoIterator,
    <I as IntoIterator>::Item: Bundle, 

Efficiently spawn a large number of entities with the same components

Faster than calling spawn repeatedly with the same components.

Example

let mut world = World::new();
let entities = world.spawn_batch((0..1_000).map(|i| (i, "abc"))).collect::<Vec<_>>();
for i in 0..1_000 {
    assert_eq!(*world.get::<i32>(entities[i]).unwrap(), i as i32);
}

pub fn despawn(&mut self, entity: Entity) -> Result<(), NoSuchEntity>

Destroy an entity and all its components

pub fn reserve<T>(&mut self, additional: u32) where
    T: Bundle, 

Ensure additional entities with exact components T can be spawned without reallocating

pub fn reserve_entity(&self) -> Entity

Reserves an entity.

pub fn clear(&mut self)

Despawn all entities

Preserves allocated storage for reuse.

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

Whether entity still exists

pub fn has_component_type(&self, entity: Entity, ty: TypeId) -> bool

Returns true if the given entity has a component with the given type id.

pub fn query<Q>(&self) -> QueryIter<'_, Q, ()> where
    Q: WorldQuery,
    <Q as WorldQuery>::Fetch: ReadOnlyFetch, 

Efficiently iterate over all entities that have certain components

Calling iter on the returned value yields (Entity, Q) tuples, where Q is some query type. A query type is &T, &mut T, a tuple of query types, or an Option wrapping a query type, where T is any component type. Components queried with &mut must only appear once. Entities which do not have a component type referenced outside of an Option will be skipped.

Entities are yielded in arbitrary order.

Example

let mut world = World::new();
let a = world.spawn((123, true, "abc"));
let b = world.spawn((456, false));
let c = world.spawn((42, "def"));
let entities = world.query::<(Entity, &i32, &bool)>()
    .map(|(e, &i, &b)| (e, i, b)) // Copy out of the world
    .collect::<Vec<_>>();
assert_eq!(entities.len(), 2);
assert!(entities.contains(&(a, 123, true)));
assert!(entities.contains(&(b, 456, false)));

pub fn query_filtered<Q, F>(&self) -> QueryIter<'_, Q, F> where
    F: QueryFilter,
    Q: WorldQuery,
    <Q as WorldQuery>::Fetch: ReadOnlyFetch, 

pub fn query_mut<Q>(&mut self) -> QueryIter<'_, Q, ()> where
    Q: WorldQuery, 

Efficiently iterate over all entities that have certain components

Calling iter on the returned value yields (Entity, Q) tuples, where Q is some query type. A query type is &T, &mut T, a tuple of query types, or an Option wrapping a query type, where T is any component type. Components queried with &mut must only appear once. Entities which do not have a component type referenced outside of an Option will be skipped.

Entities are yielded in arbitrary order.

Example

let mut world = World::new();
let a = world.spawn((123, true, "abc"));
let b = world.spawn((456, false));
let c = world.spawn((42, "def"));
let entities = world.query_mut::<(Entity, &mut i32, &bool)>()
    .map(|(e, i, &b)| (e, *i, b)) // Copy out of the world
    .collect::<Vec<_>>();
assert_eq!(entities.len(), 2);
assert!(entities.contains(&(a, 123, true)));
assert!(entities.contains(&(b, 456, false)));

pub fn query_filtered_mut<Q, F>(&mut self) -> QueryIter<'_, Q, F> where
    F: QueryFilter,
    Q: WorldQuery, 

pub fn query_batched<Q>(&self, batch_size: usize) -> BatchedIter<'_, Q, ()> where
    Q: WorldQuery,
    <Q as WorldQuery>::Fetch: ReadOnlyFetch, 

Like query, but instead of returning a single iterator it returns a "batched iterator", where each batch is batch_size. This is generally used for parallel iteration.

pub fn query_batched_filtered<Q, F>(
    &self,
    batch_size: usize
) -> BatchedIter<'_, Q, F> where
    F: QueryFilter,
    Q: WorldQuery,
    <Q as WorldQuery>::Fetch: ReadOnlyFetch, 

pub fn query_batched_mut<Q>(
    &mut self,
    batch_size: usize
) -> BatchedIter<'_, Q, ()> where
    Q: WorldQuery, 

Like query, but instead of returning a single iterator it returns a "batched iterator", where each batch is batch_size. This is generally used for parallel iteration.

pub fn query_batched_filtered_mut<Q, F>(
    &mut self,
    batch_size: usize
) -> BatchedIter<'_, Q, F> where
    F: QueryFilter,
    Q: WorldQuery, 

pub unsafe fn query_unchecked<Q, F>(&self) -> QueryIter<'_, Q, F> where
    F: QueryFilter,
    Q: WorldQuery, 

Efficiently iterate over all entities that have certain components

Calling iter on the returned value yields (Entity, Q) tuples, where Q is some query type. A query type is &T, &mut T, a tuple of query types, or an Option wrapping a query type, where T is any component type. Components queried with &mut must only appear once. Entities which do not have a component type referenced outside of an Option will be skipped.

Entities are yielded in arbitrary order.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query.

pub unsafe fn query_batched_unchecked<Q, F>(
    &self,
    batch_size: usize
) -> BatchedIter<'_, Q, F> where
    F: QueryFilter,
    Q: WorldQuery, 

Like query, but instead of returning a single iterator it returns a "batched iterator", where each batch is batch_size. This is generally used for parallel iteration.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query.

pub fn query_one<Q>(
    &self,
    entity: Entity
) -> Result<<<Q as WorldQuery>::Fetch as Fetch<'_>>::Item, NoSuchEntity> where
    Q: WorldQuery,
    <Q as WorldQuery>::Fetch: ReadOnlyFetch, 

Prepare a read only query against a single entity

Handy for accessing multiple components simultaneously.

Example

let mut world = World::new();
let a = world.spawn((123, true, "abc"));
// The returned query must outlive the borrow made by `get`
let (number, flag) = world.query_one::<(&i32, &bool)>(a).unwrap();
assert_eq!(*number, 123);

pub fn query_one_filtered<Q, F>(
    &self,
    entity: Entity
) -> Result<<<Q as WorldQuery>::Fetch as Fetch<'_>>::Item, NoSuchEntity> where
    F: QueryFilter,
    Q: WorldQuery,
    <Q as WorldQuery>::Fetch: ReadOnlyFetch, 

pub fn query_one_mut<Q>(
    &mut self,
    entity: Entity
) -> Result<<<Q as WorldQuery>::Fetch as Fetch<'_>>::Item, NoSuchEntity> where
    Q: WorldQuery, 

Prepare a query against a single entity

Handy for accessing multiple components simultaneously.

Example

let mut world = World::new();
let a = world.spawn((123, true, "abc"));
// The returned query must outlive the borrow made by `get`
let (mut number, flag) = world.query_one_mut::<(&mut i32, &bool)>(a).unwrap();
if *flag { *number *= 2; }
assert_eq!(*number, 246);

pub fn query_one_filtered_mut<Q, F>(
    &mut self,
    entity: Entity
) -> Result<<<Q as WorldQuery>::Fetch as Fetch<'_>>::Item, NoSuchEntity> where
    F: QueryFilter,
    Q: WorldQuery, 

pub unsafe fn query_one_unchecked<Q, F>(
    &self,
    entity: Entity
) -> Result<<<Q as WorldQuery>::Fetch as Fetch<'_>>::Item, NoSuchEntity> where
    F: QueryFilter,
    Q: WorldQuery, 

Prepare a query against a single entity, without checking the safety of mutable queries

Handy for accessing multiple components simultaneously.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query.

pub fn get<T>(&self, entity: Entity) -> Result<&T, ComponentError> where
    T: Component, 

Borrow the T component of entity

pub fn get_mut<T>(
    &mut self,
    entity: Entity
) -> Result<Mut<'_, T>, ComponentError> where
    T: Component, 

Mutably borrow the T component of entity

pub fn entity(&mut self, entity: Entity) -> Result<EntityRef<'_>, NoSuchEntity>

Access an entity regardless of its component types

Does not immediately borrow any component.

pub unsafe fn get_mut_unchecked<T>(
    &self,
    entity: Entity
) -> Result<Mut<'_, T>, ComponentError> where
    T: Component, 

Borrow the T component of entity without checking if it can be mutated

Safety

This does not check for mutable access correctness. To be safe, make sure this is the only thing accessing this entity's T component.

pub fn iter(&mut self) -> Iter<'_>

Iterate over all entities in the world

Entities are yielded in arbitrary order. Prefer World::query for better performance when components will be accessed in predictable patterns.

Example

let mut world = World::new();
let a = world.spawn(());
let b = world.spawn(());
let ids = world.iter().map(|(id, _)| id).collect::<Vec<_>>();
assert_eq!(ids.len(), 2);
assert!(ids.contains(&a));
assert!(ids.contains(&b));

pub fn removed<C>(&self) -> &[Entity] where
    C: Component, 

pub fn insert(
    &mut self,
    entity: Entity,
    bundle: impl DynamicBundle
) -> Result<(), NoSuchEntity>

Add components to entity

Computational cost is proportional to the number of components entity has. If an entity already has a component of a certain type, it is dropped and replaced.

When inserting a single component, see insert_one for convenience.

Example

let mut world = World::new();
let e = world.spawn((123, "abc"));
world.insert(e, (456, true));
assert_eq!(*world.get::<i32>(e).unwrap(), 456);
assert_eq!(*world.get::<bool>(e).unwrap(), true);

pub fn insert_one(
    &mut self,
    entity: Entity,
    component: impl Component
) -> Result<(), NoSuchEntity>

Add component to entity

See insert.

pub fn remove<T>(&mut self, entity: Entity) -> Result<T, ComponentError> where
    T: Bundle, 

Remove components from entity

Computational cost is proportional to the number of components entity has. The entity itself is not removed, even if no components remain; use despawn for that. If any component in T is not present in entity, no components are removed and an error is returned.

When removing a single component, see remove_one for convenience.

Example

let mut world = World::new();
let e = world.spawn((123, "abc", true));
assert_eq!(world.remove::<(i32, &str)>(e), Ok((123, "abc")));
assert!(world.get::<i32>(e).is_err());
assert!(world.get::<&str>(e).is_err());
assert_eq!(*world.get::<bool>(e).unwrap(), true);

pub fn remove_one_by_one<T>(
    &mut self,
    entity: Entity
) -> Result<(), ComponentError> where
    T: Bundle, 

Remove components from entity

Fallback method for remove when one of the component in T is not present in entity. In this case, the missing component will be skipped.

See remove.

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

Remove the T component from entity

See remove.

pub unsafe fn get_ref_at_location_unchecked<T>(
    &self,
    location: Location
) -> Result<Ref<'_, T>, ComponentError> where
    T: Component, 

Borrow the T component at the given location, without safety checks

Safety

This does not check that the location is within bounds of the archetype.

pub unsafe fn get_ref_mut_at_location_unchecked<T>(
    &self,
    location: Location
) -> Result<RefMut<'_, T>, ComponentError> where
    T: Component, 

Borrow the T component at the given location, without safety checks

Safety

This does not check that the location is within bounds of the archetype. It also does not check for mutable access correctness. To be safe, make sure this is the only thing accessing this entity's T component.

pub unsafe fn get_at_location_unchecked<T>(
    &self,
    location: Location
) -> Result<&T, ComponentError> where
    T: Component, 

Borrow the T component at the given location, without safety checks

Safety

This does not check that the location is within bounds of the archetype.

pub unsafe fn get_mut_at_location_unchecked<T>(
    &self,
    location: Location
) -> Result<Mut<'_, T>, ComponentError> where
    T: Component, 

Borrow the T component at the given location, without safety checks

Safety

This does not check that the location is within bounds of the archetype. It also does not check for mutable access correctness. To be safe, make sure this is the only thing accessing this entity's T component.

pub unsafe fn get_unchecked_mut<T>(
    &self,
    entity: Entity
) -> Result<&mut T, ComponentError> where
    T: Component, 

Uniquely borrow the T component of entity without safety checks

Should only be used as a building block for safe abstractions.

Safety

entity must have been previously obtained from this World, and no borrow of the same component of entity may be live simultaneous to the returned reference.

pub fn flush(&mut self)

Convert all reserved entities into empty entities that can be iterated and accessed

Invoked implicitly by spawn, despawn, insert, and remove.

pub fn archetypes(&self) -> impl ExactSizeIterator

Inspect the archetypes that entities are organized into

Useful for dynamically scheduling concurrent queries by checking borrows in advance. Does not provide access to entities.

pub fn archetypes_generation(&self) -> ArchetypesGeneration

Returns a distinct value after archetypes is changed

Store the current value after deriving information from archetypes, then check whether the value returned by this function differs before attempting an operation that relies on its correctness. Useful for determining whether e.g. a concurrent query execution plan is still correct.

The generation may be, but is not necessarily, changed as a result of adding or removing any entity or component.

Example

let mut world = World::new();
let initial_gen = world.archetypes_generation();
world.spawn((123, "abc"));
assert_ne!(initial_gen, world.archetypes_generation());

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

Retrieves the entity's current location, if it exists

pub fn clear_trackers(&mut self)

Clears each entity's tracker state. For example, each entity's component "mutated" state will be reset to false.

pub fn get_entity_reserver(&self) -> EntityReserver

Gets an entity reserver, which can be used to reserve entity ids in a multi-threaded context.

Trait Implementations

impl Debug for World

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

Formats the value using the given formatter.

impl Default for World

pub fn default() -> World

Returns the "default value" for a type.

impl<A> Extend<A> for World where
    A: DynamicBundle, 

pub fn extend<T>(&mut self, iter: T) where
    T: IntoIterator<Item = A>, 

Extends a collection with the contents of an iterator.

pub fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

pub fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<A> FromIterator<A> for World where
    A: DynamicBundle, 

pub fn from_iter<I>(iter: I) -> World where
    I: IntoIterator<Item = A>, 

Creates a value from an iterator.

impl<'a> IntoIterator for &'a mut World

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

type Item = (Entity, EntityRef<'a>)

The type of the elements being iterated over.

pub fn into_iter(self) -> Iter<'a>

Creates an iterator from a value.

impl Send for World

impl Sync for World

impl WorldBuilderSource for World

pub fn build(&mut self) -> WorldBuilder<'_>