[−][src]Struct bevy_ecs::prelude::World
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>
Implementations
impl World
[src]
pub fn new() -> Self
[src]
Create an empty world
pub fn spawn(&mut self, bundle: impl DynamicBundle) -> Entity
[src]
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::IntoIter>ⓘNotable traits for SpawnBatchIter<'_, I>
impl<I, '_> Iterator for SpawnBatchIter<'_, I> where
I: Iterator,
I::Item: Bundle, type Item = Entity;
where
I: IntoIterator,
I::Item: Bundle,
[src]
Notable traits for SpawnBatchIter<'_, I>
impl<I, '_> Iterator for SpawnBatchIter<'_, I> where
I: Iterator,
I::Item: Bundle, type Item = Entity;
I: IntoIterator,
I::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>
[src]
Destroy an entity and all its components
pub fn reserve<T: Bundle>(&mut self, additional: u32)
[src]
Ensure additional
entities with exact components T
can be spawned without reallocating
pub fn reserve_entity(&self) -> Entity
[src]
Reserves an entity.
pub fn clear(&mut self)
[src]
Despawn all entities
Preserves allocated storage for reuse.
pub fn contains(&self, entity: Entity) -> bool
[src]
Whether entity
still exists
pub fn has_component_type(&self, entity: Entity, ty: TypeId) -> bool
[src]
Returns true if the given entity has a component with the given type id.
pub fn query<Q: WorldQuery>(&self) -> QueryIter<'_, Q, ()>ⓘNotable traits for QueryIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for QueryIter<'w, Q, F> type Item = <Q::Fetch as Fetch<'w>>::Item;
where
Q::Fetch: ReadOnlyFetch,
[src]
Notable traits for QueryIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for QueryIter<'w, Q, F> type Item = <Q::Fetch as Fetch<'w>>::Item;
Q::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: WorldQuery, F: QueryFilter>(
&self
) -> QueryIter<'_, Q, F>ⓘNotable traits for QueryIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for QueryIter<'w, Q, F> type Item = <Q::Fetch as Fetch<'w>>::Item;
where
Q::Fetch: ReadOnlyFetch,
[src]
&self
) -> QueryIter<'_, Q, F>ⓘ
Notable traits for QueryIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for QueryIter<'w, Q, F> type Item = <Q::Fetch as Fetch<'w>>::Item;
Q::Fetch: ReadOnlyFetch,
pub fn query_mut<Q: WorldQuery>(&mut self) -> QueryIter<'_, Q, ()>ⓘNotable traits for QueryIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for QueryIter<'w, Q, F> type Item = <Q::Fetch as Fetch<'w>>::Item;
[src]
Notable traits for QueryIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for QueryIter<'w, Q, F> type Item = <Q::Fetch as Fetch<'w>>::Item;
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: WorldQuery, F: QueryFilter>(
&mut self
) -> QueryIter<'_, Q, F>ⓘNotable traits for QueryIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for QueryIter<'w, Q, F> type Item = <Q::Fetch as Fetch<'w>>::Item;
[src]
&mut self
) -> QueryIter<'_, Q, F>ⓘ
Notable traits for QueryIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for QueryIter<'w, Q, F> type Item = <Q::Fetch as Fetch<'w>>::Item;
pub fn query_batched<Q: WorldQuery>(
&self,
batch_size: usize
) -> BatchedIter<'_, Q, ()>ⓘNotable traits for BatchedIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for BatchedIter<'w, Q, F> type Item = Batch<'w, Q, F>;
where
Q::Fetch: ReadOnlyFetch,
[src]
&self,
batch_size: usize
) -> BatchedIter<'_, Q, ()>ⓘ
Notable traits for BatchedIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for BatchedIter<'w, Q, F> type Item = Batch<'w, Q, F>;
Q::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: WorldQuery, F: QueryFilter>(
&self,
batch_size: usize
) -> BatchedIter<'_, Q, F>ⓘNotable traits for BatchedIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for BatchedIter<'w, Q, F> type Item = Batch<'w, Q, F>;
where
Q::Fetch: ReadOnlyFetch,
[src]
&self,
batch_size: usize
) -> BatchedIter<'_, Q, F>ⓘ
Notable traits for BatchedIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for BatchedIter<'w, Q, F> type Item = Batch<'w, Q, F>;
Q::Fetch: ReadOnlyFetch,
pub fn query_batched_mut<Q: WorldQuery>(
&mut self,
batch_size: usize
) -> BatchedIter<'_, Q, ()>ⓘNotable traits for BatchedIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for BatchedIter<'w, Q, F> type Item = Batch<'w, Q, F>;
[src]
&mut self,
batch_size: usize
) -> BatchedIter<'_, Q, ()>ⓘ
Notable traits for BatchedIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for BatchedIter<'w, Q, F> type Item = Batch<'w, Q, F>;
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: WorldQuery, F: QueryFilter>(
&mut self,
batch_size: usize
) -> BatchedIter<'_, Q, F>ⓘNotable traits for BatchedIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for BatchedIter<'w, Q, F> type Item = Batch<'w, Q, F>;
[src]
&mut self,
batch_size: usize
) -> BatchedIter<'_, Q, F>ⓘ
Notable traits for BatchedIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for BatchedIter<'w, Q, F> type Item = Batch<'w, Q, F>;
pub unsafe fn query_unchecked<Q: WorldQuery, F: QueryFilter>(
&self
) -> QueryIter<'_, Q, F>ⓘNotable traits for QueryIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for QueryIter<'w, Q, F> type Item = <Q::Fetch as Fetch<'w>>::Item;
[src]
&self
) -> QueryIter<'_, Q, F>ⓘ
Notable traits for QueryIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for QueryIter<'w, Q, F> type Item = <Q::Fetch as Fetch<'w>>::Item;
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: WorldQuery, F: QueryFilter>(
&self,
batch_size: usize
) -> BatchedIter<'_, Q, F>ⓘNotable traits for BatchedIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for BatchedIter<'w, Q, F> type Item = Batch<'w, Q, F>;
[src]
&self,
batch_size: usize
) -> BatchedIter<'_, Q, F>ⓘ
Notable traits for BatchedIter<'w, Q, F>
impl<'w, Q: WorldQuery, F: QueryFilter> Iterator for BatchedIter<'w, Q, F> type Item = Batch<'w, Q, F>;
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: WorldQuery>(
&self,
entity: Entity
) -> Result<<Q::Fetch as Fetch<'_>>::Item, NoSuchEntity> where
Q::Fetch: ReadOnlyFetch,
[src]
&self,
entity: Entity
) -> Result<<Q::Fetch as Fetch<'_>>::Item, NoSuchEntity> where
Q::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: WorldQuery, F: QueryFilter>(
&self,
entity: Entity
) -> Result<<Q::Fetch as Fetch<'_>>::Item, NoSuchEntity> where
Q::Fetch: ReadOnlyFetch,
[src]
&self,
entity: Entity
) -> Result<<Q::Fetch as Fetch<'_>>::Item, NoSuchEntity> where
Q::Fetch: ReadOnlyFetch,
pub fn query_one_mut<Q: WorldQuery>(
&mut self,
entity: Entity
) -> Result<<Q::Fetch as Fetch<'_>>::Item, NoSuchEntity>
[src]
&mut self,
entity: Entity
) -> Result<<Q::Fetch as Fetch<'_>>::Item, NoSuchEntity>
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: WorldQuery, F: QueryFilter>(
&mut self,
entity: Entity
) -> Result<<Q::Fetch as Fetch<'_>>::Item, NoSuchEntity>
[src]
&mut self,
entity: Entity
) -> Result<<Q::Fetch as Fetch<'_>>::Item, NoSuchEntity>
pub unsafe fn query_one_unchecked<Q: WorldQuery, F: QueryFilter>(
&self,
entity: Entity
) -> Result<<Q::Fetch as Fetch<'_>>::Item, NoSuchEntity>
[src]
&self,
entity: Entity
) -> Result<<Q::Fetch as Fetch<'_>>::Item, NoSuchEntity>
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: Component>(&self, entity: Entity) -> Result<&T, ComponentError>
[src]
Borrow the T
component of entity
pub fn get_mut<T: Component>(
&mut self,
entity: Entity
) -> Result<Mut<'_, T>, ComponentError>
[src]
&mut self,
entity: Entity
) -> Result<Mut<'_, T>, ComponentError>
Mutably borrow the T
component of entity
pub fn entity(&mut self, entity: Entity) -> Result<EntityRef<'_>, NoSuchEntity>
[src]
Access an entity regardless of its component types
Does not immediately borrow any component.
pub unsafe fn get_mut_unchecked<T: Component>(
&self,
entity: Entity
) -> Result<Mut<'_, T>, ComponentError>
[src]
&self,
entity: Entity
) -> Result<Mut<'_, T>, ComponentError>
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<'_>
[src]
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: Component>(&self) -> &[Entity]
[src]
pub fn insert(
&mut self,
entity: Entity,
bundle: impl DynamicBundle
) -> Result<(), NoSuchEntity>
[src]
&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>
[src]
&mut self,
entity: Entity,
component: impl Component
) -> Result<(), NoSuchEntity>
Add component
to entity
See insert
.
pub fn remove<T: Bundle>(&mut self, entity: Entity) -> Result<T, ComponentError>
[src]
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: Bundle>(
&mut self,
entity: Entity
) -> Result<(), ComponentError>
[src]
&mut self,
entity: Entity
) -> Result<(), ComponentError>
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: Component>(
&mut self,
entity: Entity
) -> Result<T, ComponentError>
[src]
&mut self,
entity: Entity
) -> Result<T, ComponentError>
Remove the T
component from entity
See remove
.
pub unsafe fn get_ref_at_location_unchecked<T: Component>(
&self,
location: Location
) -> Result<Ref<'_, T>, ComponentError>
[src]
&self,
location: Location
) -> Result<Ref<'_, T>, ComponentError>
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: Component>(
&self,
location: Location
) -> Result<RefMut<'_, T>, ComponentError>
[src]
&self,
location: Location
) -> Result<RefMut<'_, T>, ComponentError>
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: Component>(
&self,
location: Location
) -> Result<&T, ComponentError>
[src]
&self,
location: Location
) -> Result<&T, ComponentError>
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: Component>(
&self,
location: Location
) -> Result<Mut<'_, T>, ComponentError>
[src]
&self,
location: Location
) -> Result<Mut<'_, T>, ComponentError>
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: Component>(
&self,
entity: Entity
) -> Result<&mut T, ComponentError>
[src]
&self,
entity: Entity
) -> Result<&mut T, ComponentError>
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)
[src]
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<Item = &Archetype> + '_
[src]
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
[src]
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>
[src]
Retrieves the entity's current location, if it exists
pub fn clear_trackers(&mut self)
[src]
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
[src]
Gets an entity reserver, which can be used to reserve entity ids in a multi-threaded context.
Trait Implementations
impl Debug for World
[src]
impl Default for World
[src]
impl<A: DynamicBundle> Extend<A> for World
[src]
pub fn extend<T>(&mut self, iter: T) where
T: IntoIterator<Item = A>,
[src]
T: IntoIterator<Item = A>,
pub fn extend_one(&mut self, item: A)
[src]
pub fn extend_reserve(&mut self, additional: usize)
[src]
impl<A: DynamicBundle> FromIterator<A> for World
[src]
pub fn from_iter<I: IntoIterator<Item = A>>(iter: I) -> Self
[src]
impl<'a> IntoIterator for &'a mut World
[src]
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>
[src]
impl Send for World
[src]
impl Sync for World
[src]
impl WorldBuilderSource for World
[src]
pub fn build(&mut self) -> WorldBuilder<'_>
[src]
Auto Trait Implementations
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Downcast for T where
T: Any,
[src]
T: Any,
pub fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
[src]
pub fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
[src]
pub fn as_any(&self) -> &(dyn Any + 'static)
[src]
pub fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
[src]
impl<T> DowncastSync for T where
T: Send + Sync + Any,
[src]
T: Send + Sync + Any,
impl<T> From<T> for T
[src]
impl<T> Instrument for T
[src]
pub fn instrument(self, span: Span) -> Instrumented<Self>
[src]
pub fn in_current_span(self) -> Instrumented<Self>
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
V: MultiLane<T>,