pub struct DeferredWorld<'w> { /* private fields */ }
Expand description
A World
reference that disallows structural ECS changes.
This includes initializing resources, registering components or spawning entities.
Implementations§
Source§impl<'w> DeferredWorld<'w>
impl<'w> DeferredWorld<'w>
Sourcepub fn reborrow(&mut self) -> DeferredWorld<'_>
pub fn reborrow(&mut self) -> DeferredWorld<'_>
Reborrow self as a new instance of DeferredWorld
Sourcepub fn commands(&mut self) -> Commands<'_, '_>
pub fn commands(&mut self) -> Commands<'_, '_>
Creates a Commands
instance that pushes to the world’s command queue
Sourcepub fn get_mut<T: Component<Mutability = Mutable>>(
&mut self,
entity: Entity,
) -> Option<Mut<'_, T>>
pub fn get_mut<T: Component<Mutability = Mutable>>( &mut self, entity: Entity, ) -> Option<Mut<'_, T>>
Sourcepub fn get_entity_mut<F: WorldEntityFetch>(
&mut self,
entities: F,
) -> Result<F::DeferredMut<'_>, EntityMutableFetchError>
pub fn get_entity_mut<F: WorldEntityFetch>( &mut self, entities: F, ) -> Result<F::DeferredMut<'_>, EntityMutableFetchError>
Returns EntityMut
s that expose read and write operations for the
given entities
, returning Err
if any of the given entities do not
exist. Instead of immediately unwrapping the value returned from this
function, prefer World::entity_mut
.
This function supports fetching a single entity or multiple entities:
- Pass an
Entity
to receive a singleEntityMut
. - Pass a slice of
Entity
s to receive aVec<EntityMut>
. - Pass an array of
Entity
s to receive an equally-sized array ofEntityMut
s. - Pass an
&EntityHashSet
to receive anEntityHashMap<EntityMut>
.
As DeferredWorld
does not allow structural changes, all returned
references are EntityMut
s, which do not allow structural changes
(i.e. adding/removing components or despawning the entity).
§Errors
- Returns
EntityMutableFetchError::EntityDoesNotExist
if any of the givenentities
do not exist in the world.- Only the first entity found to be missing will be returned.
- Returns
EntityMutableFetchError::AliasedMutability
if the same entity is requested multiple times.
§Examples
For examples, see DeferredWorld::entity_mut
.
Sourcepub fn entity_mut<F: WorldEntityFetch>(
&mut self,
entities: F,
) -> F::DeferredMut<'_>
pub fn entity_mut<F: WorldEntityFetch>( &mut self, entities: F, ) -> F::DeferredMut<'_>
Returns EntityMut
s that expose read and write operations for the
given entities
. This will panic if any of the given entities do not
exist. Use DeferredWorld::get_entity_mut
if you want to check for
entity existence instead of implicitly panicking.
This function supports fetching a single entity or multiple entities:
- Pass an
Entity
to receive a singleEntityMut
. - Pass a slice of
Entity
s to receive aVec<EntityMut>
. - Pass an array of
Entity
s to receive an equally-sized array ofEntityMut
s. - Pass an
&EntityHashSet
to receive anEntityHashMap<EntityMut>
.
As DeferredWorld
does not allow structural changes, all returned
references are EntityMut
s, which do not allow structural changes
(i.e. adding/removing components or despawning the entity).
§Panics
If any of the given entities
do not exist in the world.
§Examples
§Single Entity
#[derive(Component)]
struct Position {
x: f32,
y: f32,
}
let mut world: DeferredWorld = // ...
let mut entity_mut = world.entity_mut(entity);
let mut position = entity_mut.get_mut::<Position>().unwrap();
position.y = 1.0;
assert_eq!(position.x, 0.0);
§Array of Entity
s
#[derive(Component)]
struct Position {
x: f32,
y: f32,
}
let mut world: DeferredWorld = // ...
let [mut e1_ref, mut e2_ref] = world.entity_mut([e1, e2]);
let mut e1_position = e1_ref.get_mut::<Position>().unwrap();
e1_position.x = 1.0;
assert_eq!(e1_position.x, 1.0);
let mut e2_position = e2_ref.get_mut::<Position>().unwrap();
e2_position.x = 2.0;
assert_eq!(e2_position.x, 2.0);
§Slice of Entity
s
#[derive(Component)]
struct Position {
x: f32,
y: f32,
}
let mut world: DeferredWorld = // ...
let ids = vec![e1, e2, e3];
for mut eref in world.entity_mut(&ids[..]) {
let mut pos = eref.get_mut::<Position>().unwrap();
pos.y = 2.0;
assert_eq!(pos.y, 2.0);
}
§&EntityHashSet
#[derive(Component)]
struct Position {
x: f32,
y: f32,
}
let mut world: DeferredWorld = // ...
let ids = EntityHashSet::from_iter([e1, e2, e3]);
for (_id, mut eref) in world.entity_mut(&ids) {
let mut pos = eref.get_mut::<Position>().unwrap();
pos.y = 2.0;
assert_eq!(pos.y, 2.0);
}
Sourcepub fn entities_and_commands(&mut self) -> (EntityFetcher<'_>, Commands<'_, '_>)
pub fn entities_and_commands(&mut self) -> (EntityFetcher<'_>, Commands<'_, '_>)
Simultaneously provides access to entity data and a command queue, which
will be applied when the World
is next flushed.
This allows using borrowed entity data to construct commands where the borrow checker would otherwise prevent it.
See World::entities_and_commands
for the non-deferred version.
§Example
#[derive(Component)]
struct Targets(Vec<Entity>);
#[derive(Component)]
struct TargetedBy(Entity);
let mut world: DeferredWorld = // ...
let (entities, mut commands) = world.entities_and_commands();
let entity = entities.get(eid).unwrap();
for &target in entity.get::<Targets>().unwrap().0.iter() {
commands.entity(target).insert(TargetedBy(eid));
}
Sourcepub fn query<'s, D: QueryData, F: QueryFilter>(
&mut self,
state: &'s mut QueryState<D, F>,
) -> Query<'_, 's, D, F>
pub fn query<'s, D: QueryData, F: QueryFilter>( &mut self, state: &'s mut QueryState<D, F>, ) -> Query<'_, 's, D, F>
Returns Query
for the given QueryState
, which is used to efficiently
run queries on the World
by storing and reusing the QueryState
.
§Panics
If state is from a different world then self
Sourcepub fn resource_mut<R: Resource>(&mut self) -> Mut<'_, R>
pub fn resource_mut<R: Resource>(&mut self) -> Mut<'_, R>
Gets a mutable reference to the resource of the given type
§Panics
Panics if the resource does not exist.
Use get_resource_mut
instead if you want to handle this case.
Sourcepub fn get_resource_mut<R: Resource>(&mut self) -> Option<Mut<'_, R>>
pub fn get_resource_mut<R: Resource>(&mut self) -> Option<Mut<'_, R>>
Gets a mutable reference to the resource of the given type if it exists
Sourcepub fn non_send_resource_mut<R: 'static>(&mut self) -> Mut<'_, R>
pub fn non_send_resource_mut<R: 'static>(&mut self) -> Mut<'_, R>
Gets a mutable reference to the non-send resource of the given type, if it exists.
§Panics
Panics if the resource does not exist.
Use get_non_send_resource_mut
instead if you want to handle this case.
This function will panic if it isn’t called from the same thread that the resource was inserted from.
Sourcepub fn get_non_send_resource_mut<R: 'static>(&mut self) -> Option<Mut<'_, R>>
pub fn get_non_send_resource_mut<R: 'static>(&mut self) -> Option<Mut<'_, R>>
Gets a mutable reference to the non-send resource of the given type, if it exists.
Otherwise returns None
.
§Panics
This function will panic if it isn’t called from the same thread that the resource was inserted from.
Sourcepub fn send_event<E: Event>(&mut self, event: E) -> Option<EventId<E>>
pub fn send_event<E: Event>(&mut self, event: E) -> Option<EventId<E>>
Sourcepub fn send_event_batch<E: Event>(
&mut self,
events: impl IntoIterator<Item = E>,
) -> Option<SendBatchIds<E>>
pub fn send_event_batch<E: Event>( &mut self, events: impl IntoIterator<Item = E>, ) -> Option<SendBatchIds<E>>
Sourcepub fn get_resource_mut_by_id(
&mut self,
component_id: ComponentId,
) -> Option<MutUntyped<'_>>
pub fn get_resource_mut_by_id( &mut self, component_id: ComponentId, ) -> Option<MutUntyped<'_>>
Gets a pointer to the resource with the id ComponentId
if it exists.
The returned pointer may be used to modify the resource, as long as the mutable borrow
of the World
is still valid.
You should prefer to use the typed API World::get_resource_mut
where possible and only
use this in cases where the actual types are not known at compile time.
Sourcepub fn get_non_send_mut_by_id(
&mut self,
component_id: ComponentId,
) -> Option<MutUntyped<'_>>
pub fn get_non_send_mut_by_id( &mut self, component_id: ComponentId, ) -> Option<MutUntyped<'_>>
Gets a !Send
resource to the resource with the id ComponentId
if it exists.
The returned pointer may be used to modify the resource, as long as the mutable borrow
of the World
is still valid.
You should prefer to use the typed API World::get_resource_mut
where possible and only
use this in cases where the actual types are not known at compile time.
§Panics
This function will panic if it isn’t called from the same thread that the resource was inserted from.
Sourcepub fn get_mut_by_id(
&mut self,
entity: Entity,
component_id: ComponentId,
) -> Option<MutUntyped<'_>>
pub fn get_mut_by_id( &mut self, entity: Entity, component_id: ComponentId, ) -> Option<MutUntyped<'_>>
Retrieves a mutable untyped reference to the given entity
’s Component
of the given ComponentId
.
Returns None
if the entity
does not have a Component
of the given type.
You should prefer to use the typed API World::get_mut
where possible and only
use this in cases where the actual types are not known at compile time.
Sourcepub fn trigger_targets(
&mut self,
trigger: impl Event,
targets: impl TriggerTargets + Send + Sync + 'static,
)
pub fn trigger_targets( &mut self, trigger: impl Event, targets: impl TriggerTargets + Send + Sync + 'static, )
Sends a Trigger
with the given targets
.
Methods from Deref<Target = World>§
Sourcepub fn get_reflect(
&self,
entity: Entity,
type_id: TypeId,
) -> Result<&dyn Reflect, GetComponentReflectError>
Available on crate feature bevy_reflect
only.
pub fn get_reflect( &self, entity: Entity, type_id: TypeId, ) -> Result<&dyn Reflect, GetComponentReflectError>
bevy_reflect
only.Retrieves a reference to the given entity
’s Component
of the given type_id
using
reflection.
Requires implementing Reflect
for the Component
(e.g., using #[derive(Reflect)
)
and app.register_type::<TheComponent>()
to have been called1.
If you want to call this with a ComponentId
, see World::components
and Components::get_id
to get
the corresponding TypeId
.
Also see the crate documentation for bevy_reflect
for more information on
Reflect
and bevy’s reflection capabilities.
§Errors
See GetComponentReflectError
for the possible errors and their descriptions.
§Example
use bevy_ecs::prelude::*;
use bevy_reflect::Reflect;
use std::any::TypeId;
// define a `Component` and derive `Reflect` for it
#[derive(Component, Reflect)]
struct MyComponent;
// create a `World` for this example
let mut world = World::new();
// Note: This is usually handled by `App::register_type()`, but this example cannot use `App`.
world.init_resource::<AppTypeRegistry>();
world.get_resource_mut::<AppTypeRegistry>().unwrap().write().register::<MyComponent>();
// spawn an entity with a `MyComponent`
let entity = world.spawn(MyComponent).id();
// retrieve a reflected reference to the entity's `MyComponent`
let comp_reflected: &dyn Reflect = world.get_reflect(entity, TypeId::of::<MyComponent>()).unwrap();
// make sure we got the expected type
assert!(comp_reflected.is::<MyComponent>());
§Note
Requires the bevy_reflect
feature (included in the default features).
More specifically: Requires
TypeData
forReflectFromPtr
to be registered for the giventype_id
, which is automatically handled when derivingReflect
and callingApp::register_type
. ↩
Sourcepub fn as_unsafe_world_cell_readonly(&self) -> UnsafeWorldCell<'_>
pub fn as_unsafe_world_cell_readonly(&self) -> UnsafeWorldCell<'_>
Creates a new UnsafeWorldCell
view with only read access to everything.
Sourcepub fn archetypes(&self) -> &Archetypes
pub fn archetypes(&self) -> &Archetypes
Retrieves this world’s Archetypes
collection.
Sourcepub fn components(&self) -> &Components
pub fn components(&self) -> &Components
Retrieves this world’s Components
collection.
Sourcepub fn components_queue(&self) -> ComponentsQueuedRegistrator<'_>
pub fn components_queue(&self) -> ComponentsQueuedRegistrator<'_>
Prepares a ComponentsQueuedRegistrator
for the world.
NOTE: ComponentsQueuedRegistrator
is easily misused.
See its docs for important notes on when and how it should be used.
Sourcepub fn removed_components(&self) -> &RemovedComponentEvents
pub fn removed_components(&self) -> &RemovedComponentEvents
Retrieves this world’s RemovedComponentEvents
collection
Sourcepub fn get_required_components<C: Component>(
&self,
) -> Option<&RequiredComponents>
pub fn get_required_components<C: Component>( &self, ) -> Option<&RequiredComponents>
Retrieves the required components for the given component type, if it exists.
Sourcepub fn get_required_components_by_id(
&self,
id: ComponentId,
) -> Option<&RequiredComponents>
pub fn get_required_components_by_id( &self, id: ComponentId, ) -> Option<&RequiredComponents>
Retrieves the required components for the component of the given ComponentId
, if it exists.
Sourcepub fn component_id<T: Component>(&self) -> Option<ComponentId>
pub fn component_id<T: Component>(&self) -> Option<ComponentId>
Returns the ComponentId
of the given Component
type T
.
The returned ComponentId
is specific to the World
instance
it was retrieved from and should not be used with another World
instance.
Returns None
if the Component
type has not yet been initialized within
the World
using World::register_component
.
use bevy_ecs::prelude::*;
let mut world = World::new();
#[derive(Component)]
struct ComponentA;
let component_a_id = world.register_component::<ComponentA>();
assert_eq!(component_a_id, world.component_id::<ComponentA>().unwrap())
§See also
Sourcepub fn resource_id<T: Resource>(&self) -> Option<ComponentId>
pub fn resource_id<T: Resource>(&self) -> Option<ComponentId>
Returns the ComponentId
of the given Resource
type T
.
The returned ComponentId
is specific to the World
instance it was retrieved from
and should not be used with another World
instance.
Returns None
if the Resource
type has not yet been initialized within the
World
using World::register_resource
, World::init_resource
or World::insert_resource
.
Sourcepub fn entity<F: WorldEntityFetch>(&self, entities: F) -> F::Ref<'_>
pub fn entity<F: WorldEntityFetch>(&self, entities: F) -> F::Ref<'_>
Returns EntityRef
s that expose read-only operations for the given
entities
. This will panic if any of the given entities do not exist. Use
World::get_entity
if you want to check for entity existence instead
of implicitly panicking.
This function supports fetching a single entity or multiple entities:
- Pass an
Entity
to receive a singleEntityRef
. - Pass a slice of
Entity
s to receive aVec<EntityRef>
. - Pass an array of
Entity
s to receive an equally-sized array ofEntityRef
s.
§Panics
If any of the given entities
do not exist in the world.
§Examples
§Single Entity
#[derive(Component)]
struct Position {
x: f32,
y: f32,
}
let mut world = World::new();
let entity = world.spawn(Position { x: 0.0, y: 0.0 }).id();
let position = world.entity(entity).get::<Position>().unwrap();
assert_eq!(position.x, 0.0);
§Array of Entity
s
#[derive(Component)]
struct Position {
x: f32,
y: f32,
}
let mut world = World::new();
let e1 = world.spawn(Position { x: 0.0, y: 0.0 }).id();
let e2 = world.spawn(Position { x: 1.0, y: 1.0 }).id();
let [e1_ref, e2_ref] = world.entity([e1, e2]);
let e1_position = e1_ref.get::<Position>().unwrap();
assert_eq!(e1_position.x, 0.0);
let e2_position = e2_ref.get::<Position>().unwrap();
assert_eq!(e2_position.x, 1.0);
§Slice of Entity
s
#[derive(Component)]
struct Position {
x: f32,
y: f32,
}
let mut world = World::new();
let e1 = world.spawn(Position { x: 0.0, y: 1.0 }).id();
let e2 = world.spawn(Position { x: 0.0, y: 1.0 }).id();
let e3 = world.spawn(Position { x: 0.0, y: 1.0 }).id();
let ids = vec![e1, e2, e3];
for eref in world.entity(&ids[..]) {
assert_eq!(eref.get::<Position>().unwrap().y, 1.0);
}
§EntityHashSet
#[derive(Component)]
struct Position {
x: f32,
y: f32,
}
let mut world = World::new();
let e1 = world.spawn(Position { x: 0.0, y: 1.0 }).id();
let e2 = world.spawn(Position { x: 0.0, y: 1.0 }).id();
let e3 = world.spawn(Position { x: 0.0, y: 1.0 }).id();
let ids = EntityHashSet::from_iter([e1, e2, e3]);
for (_id, eref) in world.entity(&ids) {
assert_eq!(eref.get::<Position>().unwrap().y, 1.0);
}
Sourcepub fn inspect_entity(
&self,
entity: Entity,
) -> Result<impl Iterator<Item = &ComponentInfo>, EntityDoesNotExistError>
pub fn inspect_entity( &self, entity: Entity, ) -> Result<impl Iterator<Item = &ComponentInfo>, EntityDoesNotExistError>
Returns the components of an Entity
through ComponentInfo
.
Sourcepub fn get_entity<F: WorldEntityFetch>(
&self,
entities: F,
) -> Result<F::Ref<'_>, EntityDoesNotExistError>
pub fn get_entity<F: WorldEntityFetch>( &self, entities: F, ) -> Result<F::Ref<'_>, EntityDoesNotExistError>
Returns EntityRef
s that expose read-only operations for the given
entities
, returning Err
if any of the given entities do not exist.
Instead of immediately unwrapping the value returned from this function,
prefer World::entity
.
This function supports fetching a single entity or multiple entities:
- Pass an
Entity
to receive a singleEntityRef
. - Pass a slice of
Entity
s to receive aVec<EntityRef>
. - Pass an array of
Entity
s to receive an equally-sized array ofEntityRef
s. - Pass a reference to a
EntityHashSet
to receive anEntityHashMap<EntityRef>
.
§Errors
If any of the given entities
do not exist in the world, the first
Entity
found to be missing will return an EntityDoesNotExistError
.
§Examples
For examples, see World::entity
.
Sourcepub fn iter_entities(&self) -> impl Iterator<Item = EntityRef<'_>> + '_
pub fn iter_entities(&self) -> impl Iterator<Item = EntityRef<'_>> + '_
Sourcepub fn get<T: Component>(&self, entity: Entity) -> Option<&T>
pub fn get<T: Component>(&self, entity: Entity) -> Option<&T>
Retrieves a reference to the given entity
’s Component
of the given type.
Returns None
if the entity
does not have a Component
of the given type.
use bevy_ecs::{component::Component, world::World};
#[derive(Component)]
struct Position {
x: f32,
y: f32,
}
let mut world = World::new();
let entity = world.spawn(Position { x: 0.0, y: 0.0 }).id();
let position = world.get::<Position>(entity).unwrap();
assert_eq!(position.x, 0.0);
Sourcepub fn try_query<D: QueryData>(&self) -> Option<QueryState<D, ()>>
pub fn try_query<D: QueryData>(&self) -> Option<QueryState<D, ()>>
Returns QueryState
for the given QueryData
, which is used to efficiently
run queries on the World
by storing and reusing the QueryState
.
use bevy_ecs::{component::Component, entity::Entity, world::World};
#[derive(Component, Debug, PartialEq)]
struct Position {
x: f32,
y: f32,
}
let mut world = World::new();
world.spawn_batch(vec![
Position { x: 0.0, y: 0.0 },
Position { x: 1.0, y: 1.0 },
]);
fn get_positions(world: &World) -> Vec<(Entity, &Position)> {
let mut query = world.try_query::<(Entity, &Position)>().unwrap();
query.iter(world).collect()
}
let positions = get_positions(&world);
assert_eq!(world.get::<Position>(positions[0].0).unwrap(), positions[0].1);
assert_eq!(world.get::<Position>(positions[1].0).unwrap(), positions[1].1);
Requires only an immutable world reference, but may fail if, for example, the components that make up this query have not been registered into the world.
use bevy_ecs::{component::Component, entity::Entity, world::World};
#[derive(Component)]
struct A;
let mut world = World::new();
let none_query = world.try_query::<&A>();
assert!(none_query.is_none());
world.register_component::<A>();
let some_query = world.try_query::<&A>();
assert!(some_query.is_some());
Sourcepub fn try_query_filtered<D: QueryData, F: QueryFilter>(
&self,
) -> Option<QueryState<D, F>>
pub fn try_query_filtered<D: QueryData, F: QueryFilter>( &self, ) -> Option<QueryState<D, F>>
Returns QueryState
for the given filtered QueryData
, which is used to efficiently
run queries on the World
by storing and reusing the QueryState
.
use bevy_ecs::{component::Component, entity::Entity, world::World, query::With};
#[derive(Component)]
struct A;
#[derive(Component)]
struct B;
let mut world = World::new();
let e1 = world.spawn(A).id();
let e2 = world.spawn((A, B)).id();
let mut query = world.try_query_filtered::<Entity, With<B>>().unwrap();
let matching_entities = query.iter(&world).collect::<Vec<Entity>>();
assert_eq!(matching_entities, vec![e2]);
Requires only an immutable world reference, but may fail if, for example, the components that make up this query have not been registered into the world.
Sourcepub fn removed<T: Component>(&self) -> impl Iterator<Item = Entity> + '_
pub fn removed<T: Component>(&self) -> impl Iterator<Item = Entity> + '_
Returns an iterator of entities that had components of type T
removed
since the last call to World::clear_trackers
.
Sourcepub fn removed_with_id(
&self,
component_id: ComponentId,
) -> impl Iterator<Item = Entity> + '_
pub fn removed_with_id( &self, component_id: ComponentId, ) -> impl Iterator<Item = Entity> + '_
Returns an iterator of entities that had components with the given component_id
removed
since the last call to World::clear_trackers
.
Sourcepub fn contains_resource<R: Resource>(&self) -> bool
pub fn contains_resource<R: Resource>(&self) -> bool
Returns true
if a resource of type R
exists. Otherwise returns false
.
Sourcepub fn contains_resource_by_id(&self, component_id: ComponentId) -> bool
pub fn contains_resource_by_id(&self, component_id: ComponentId) -> bool
Returns true
if a resource with provided component_id
exists. Otherwise returns false
.
Sourcepub fn contains_non_send<R: 'static>(&self) -> bool
pub fn contains_non_send<R: 'static>(&self) -> bool
Returns true
if a resource of type R
exists. Otherwise returns false
.
Sourcepub fn contains_non_send_by_id(&self, component_id: ComponentId) -> bool
pub fn contains_non_send_by_id(&self, component_id: ComponentId) -> bool
Returns true
if a resource with provided component_id
exists. Otherwise returns false
.
Sourcepub fn is_resource_added<R: Resource>(&self) -> bool
pub fn is_resource_added<R: Resource>(&self) -> bool
Returns true
if a resource of type R
exists and was added since the world’s
last_change_tick
. Otherwise, this returns false
.
This means that:
- When called from an exclusive system, this will check for additions since the system last ran.
- When called elsewhere, this will check for additions since the last time that
World::clear_trackers
was called.
Sourcepub fn is_resource_added_by_id(&self, component_id: ComponentId) -> bool
pub fn is_resource_added_by_id(&self, component_id: ComponentId) -> bool
Returns true
if a resource with id component_id
exists and was added since the world’s
last_change_tick
. Otherwise, this returns false
.
This means that:
- When called from an exclusive system, this will check for additions since the system last ran.
- When called elsewhere, this will check for additions since the last time that
World::clear_trackers
was called.
Sourcepub fn is_resource_changed<R: Resource>(&self) -> bool
pub fn is_resource_changed<R: Resource>(&self) -> bool
Returns true
if a resource of type R
exists and was modified since the world’s
last_change_tick
. Otherwise, this returns false
.
This means that:
- When called from an exclusive system, this will check for changes since the system last ran.
- When called elsewhere, this will check for changes since the last time that
World::clear_trackers
was called.
Sourcepub fn is_resource_changed_by_id(&self, component_id: ComponentId) -> bool
pub fn is_resource_changed_by_id(&self, component_id: ComponentId) -> bool
Returns true
if a resource with id component_id
exists and was modified since the world’s
last_change_tick
. Otherwise, this returns false
.
This means that:
- When called from an exclusive system, this will check for changes since the system last ran.
- When called elsewhere, this will check for changes since the last time that
World::clear_trackers
was called.
Sourcepub fn get_resource_change_ticks<R: Resource>(&self) -> Option<ComponentTicks>
pub fn get_resource_change_ticks<R: Resource>(&self) -> Option<ComponentTicks>
Retrieves the change ticks for the given resource.
Sourcepub fn get_resource_change_ticks_by_id(
&self,
component_id: ComponentId,
) -> Option<ComponentTicks>
pub fn get_resource_change_ticks_by_id( &self, component_id: ComponentId, ) -> Option<ComponentTicks>
Retrieves the change ticks for the given ComponentId
.
You should prefer to use the typed API World::get_resource_change_ticks
where possible.
Sourcepub fn resource<R: Resource>(&self) -> &R
pub fn resource<R: Resource>(&self) -> &R
Gets a reference to the resource of the given type
§Panics
Panics if the resource does not exist.
Use get_resource
instead if you want to handle this case.
If you want to instead insert a value if the resource does not exist,
use get_resource_or_insert_with
.
Sourcepub fn resource_ref<R: Resource>(&self) -> Ref<'_, R>
pub fn resource_ref<R: Resource>(&self) -> Ref<'_, R>
Gets a reference to the resource of the given type
§Panics
Panics if the resource does not exist.
Use get_resource_ref
instead if you want to handle this case.
If you want to instead insert a value if the resource does not exist,
use get_resource_or_insert_with
.
Sourcepub fn get_resource<R: Resource>(&self) -> Option<&R>
pub fn get_resource<R: Resource>(&self) -> Option<&R>
Gets a reference to the resource of the given type if it exists
Sourcepub fn get_resource_ref<R: Resource>(&self) -> Option<Ref<'_, R>>
pub fn get_resource_ref<R: Resource>(&self) -> Option<Ref<'_, R>>
Gets a reference including change detection to the resource of the given type if it exists.
Sourcepub fn non_send_resource<R: 'static>(&self) -> &R
pub fn non_send_resource<R: 'static>(&self) -> &R
Gets an immutable reference to the non-send resource of the given type, if it exists.
§Panics
Panics if the resource does not exist.
Use get_non_send_resource
instead if you want to handle this case.
This function will panic if it isn’t called from the same thread that the resource was inserted from.
Sourcepub fn get_non_send_resource<R: 'static>(&self) -> Option<&R>
pub fn get_non_send_resource<R: 'static>(&self) -> Option<&R>
Gets a reference to the non-send resource of the given type, if it exists.
Otherwise returns None
.
§Panics
This function will panic if it isn’t called from the same thread that the resource was inserted from.
Sourcepub fn read_change_tick(&self) -> Tick
pub fn read_change_tick(&self) -> Tick
Reads the current change tick of this world.
If you have exclusive (&mut
) access to the world, consider using change_tick()
,
which is more efficient since it does not require atomic synchronization.
Sourcepub fn last_change_tick(&self) -> Tick
pub fn last_change_tick(&self) -> Tick
When called from within an exclusive system (a System
that takes &mut World
as its first
parameter), this method returns the Tick
indicating the last time the exclusive system was run.
Otherwise, this returns the Tick
indicating the last time that World::clear_trackers
was called.
Sourcepub fn get_resource_by_id(&self, component_id: ComponentId) -> Option<Ptr<'_>>
pub fn get_resource_by_id(&self, component_id: ComponentId) -> Option<Ptr<'_>>
Gets a pointer to the resource with the id ComponentId
if it exists.
The returned pointer must not be used to modify the resource, and must not be
dereferenced after the immutable borrow of the World
ends.
You should prefer to use the typed API World::get_resource
where possible and only
use this in cases where the actual types are not known at compile time.
Sourcepub fn iter_resources(&self) -> impl Iterator<Item = (&ComponentInfo, Ptr<'_>)>
pub fn iter_resources(&self) -> impl Iterator<Item = (&ComponentInfo, Ptr<'_>)>
Iterates over all resources in the world.
The returned iterator provides lifetimed, but type-unsafe pointers. Actually reading the contents of each resource will require the use of unsafe code.
§Examples
§Printing the size of all resources
let mut total = 0;
for (info, _) in world.iter_resources() {
println!("Resource: {}", info.name());
println!("Size: {} bytes", info.layout().size());
total += info.layout().size();
}
println!("Total size: {} bytes", total);
§Dynamically running closures for resources matching specific TypeId
s
// In this example, `A` and `B` are resources. We deliberately do not use the
// `bevy_reflect` crate here to showcase the low-level [`Ptr`] usage. You should
// probably use something like `ReflectFromPtr` in a real-world scenario.
// Create the hash map that will store the closures for each resource type
let mut closures: HashMap<TypeId, Box<dyn Fn(&Ptr<'_>)>> = HashMap::default();
// Add closure for `A`
closures.insert(TypeId::of::<A>(), Box::new(|ptr| {
// SAFETY: We assert ptr is the same type of A with TypeId of A
let a = unsafe { &ptr.deref::<A>() };
// ... do something with `a` here
}));
// Add closure for `B`
closures.insert(TypeId::of::<B>(), Box::new(|ptr| {
// SAFETY: We assert ptr is the same type of B with TypeId of B
let b = unsafe { &ptr.deref::<B>() };
// ... do something with `b` here
}));
// Iterate all resources, in order to run the closures for each matching resource type
for (info, ptr) in world.iter_resources() {
let Some(type_id) = info.type_id() else {
// It's possible for resources to not have a `TypeId` (e.g. non-Rust resources
// dynamically inserted via a scripting language) in which case we can't match them.
continue;
};
let Some(closure) = closures.get(&type_id) else {
// No closure for this resource type, skip it.
continue;
};
// Run the closure for the resource
closure(&ptr);
}
Sourcepub fn get_non_send_by_id(&self, component_id: ComponentId) -> Option<Ptr<'_>>
pub fn get_non_send_by_id(&self, component_id: ComponentId) -> Option<Ptr<'_>>
Gets a !Send
resource to the resource with the id ComponentId
if it exists.
The returned pointer must not be used to modify the resource, and must not be
dereferenced after the immutable borrow of the World
ends.
You should prefer to use the typed API World::get_resource
where possible and only
use this in cases where the actual types are not known at compile time.
§Panics
This function will panic if it isn’t called from the same thread that the resource was inserted from.
Sourcepub fn get_by_id(
&self,
entity: Entity,
component_id: ComponentId,
) -> Option<Ptr<'_>>
pub fn get_by_id( &self, entity: Entity, component_id: ComponentId, ) -> Option<Ptr<'_>>
Retrieves an immutable untyped reference to the given entity
’s Component
of the given ComponentId
.
Returns None
if the entity
does not have a Component
of the given type.
You should prefer to use the typed API World::get_mut
where possible and only
use this in cases where the actual types are not known at compile time.
§Panics
This function will panic if it isn’t called from the same thread that the resource was inserted from.
Trait Implementations§
Source§impl<'w> Deref for DeferredWorld<'w>
impl<'w> Deref for DeferredWorld<'w>
Source§impl<'w> From<&'w mut World> for DeferredWorld<'w>
impl<'w> From<&'w mut World> for DeferredWorld<'w>
Source§fn from(world: &'w mut World) -> DeferredWorld<'w>
fn from(world: &'w mut World) -> DeferredWorld<'w>
Source§impl<'w> SystemParam for DeferredWorld<'w>
SAFETY: DeferredWorld
can read all components and resources but cannot be used to gain any other mutable references.
impl<'w> SystemParam for DeferredWorld<'w>
SAFETY: DeferredWorld
can read all components and resources but cannot be used to gain any other mutable references.
Source§type Item<'world, 'state> = DeferredWorld<'world>
type Item<'world, 'state> = DeferredWorld<'world>
Self
, instantiated with new lifetimes. Read moreSource§fn init_state(_world: &mut World, system_meta: &mut SystemMeta) -> Self::State
fn init_state(_world: &mut World, system_meta: &mut SystemMeta) -> Self::State
World
access used by this SystemParam
and creates a new instance of this param’s State
.Source§unsafe fn get_param<'world, 'state>(
_state: &'state mut Self::State,
_system_meta: &SystemMeta,
world: UnsafeWorldCell<'world>,
_change_tick: Tick,
) -> Self::Item<'world, 'state>
unsafe fn get_param<'world, 'state>( _state: &'state mut Self::State, _system_meta: &SystemMeta, world: UnsafeWorldCell<'world>, _change_tick: Tick, ) -> Self::Item<'world, 'state>
SystemParamFunction
. Read moreSource§unsafe fn new_archetype(
state: &mut Self::State,
archetype: &Archetype,
system_meta: &mut SystemMeta,
)
unsafe fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta, )
Archetype
, registers the components accessed by this SystemParam
(if applicable).a Read moreSource§fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)
fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)
SystemParam
’s state.
This is used to apply Commands
during ApplyDeferred
.Source§fn queue(
state: &mut Self::State,
system_meta: &SystemMeta,
world: DeferredWorld<'_>,
)
fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )
ApplyDeferred
.Source§unsafe fn validate_param(
state: &Self::State,
system_meta: &SystemMeta,
world: UnsafeWorldCell<'_>,
) -> Result<(), SystemParamValidationError>
unsafe fn validate_param( state: &Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'_>, ) -> Result<(), SystemParamValidationError>
Auto Trait Implementations§
impl<'w> Freeze for DeferredWorld<'w>
impl<'w> !RefUnwindSafe for DeferredWorld<'w>
impl<'w> Send for DeferredWorld<'w>
impl<'w> Sync for DeferredWorld<'w>
impl<'w> Unpin for DeferredWorld<'w>
impl<'w> !UnwindSafe for DeferredWorld<'w>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
Source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
, which can then be
downcast
into Box<dyn ConcreteType>
where ConcreteType
implements Trait
.Source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
, which can then be further
downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.Source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.Source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.