Struct bevy_ecs::world::DeferredWorld

source ·
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>

source

pub fn reborrow(&mut self) -> DeferredWorld<'_>

Reborrow self as a new instance of DeferredWorld

source

pub fn commands(&mut self) -> Commands<'_, '_>

Creates a Commands instance that pushes to the world’s command queue

source

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

Retrieves a mutable 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.

source

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

Retrieves an EntityMut that exposes read and write operations for the given entity. Returns None if the entity does not exist. Instead of unwrapping the value returned from this function, prefer Self::entity_mut.

source

pub fn entity_mut(&mut self, entity: Entity) -> EntityMut<'_>

Retrieves an EntityMut that exposes read and write operations for the given entity. This will panic if the entity does not exist. Use Self::get_entity_mut if you want to check for entity existence instead of implicitly panic-ing.

source

pub fn query<'s, D: QueryData, F: QueryFilter>( &'w mut self, state: &'s mut QueryState<D, F> ) -> Query<'w, '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

source

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.

source

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

source

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.

source

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.

source

pub fn send_event<E: Event>(&mut self, event: E) -> Option<EventId<E>>

Sends an Event. This method returns the ID of the sent event, or None if the event could not be sent.

source

pub fn send_event_default<E: Event + Default>(&mut self) -> Option<EventId<E>>

Sends the default value of the Event of type E. This method returns the ID of the sent event, or None if the event could not be sent.

source

pub fn send_event_batch<E: Event>( &mut self, events: impl IntoIterator<Item = E> ) -> Option<SendBatchIds<E>>

Sends a batch of Events from an iterator. This method returns the IDs of the sent events, or None if the event could not be sent.

source

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.

source

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.

source

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.

source

pub fn trigger<T: Event>(&mut self, trigger: impl Event)

Sends a “global” [Trigger] without any targets.

source

pub fn trigger_targets( &mut self, trigger: impl Event, targets: impl TriggerTargets )

Sends a [Trigger] with the given targets.

Methods from Deref<Target = World>§

source

pub fn id(&self) -> WorldId

Retrieves this World’s unique ID

source

pub fn as_unsafe_world_cell_readonly(&self) -> UnsafeWorldCell<'_>

Creates a new UnsafeWorldCell view with only read access to everything.

source

pub fn entities(&self) -> &Entities

Retrieves this world’s Entities collection.

source

pub fn archetypes(&self) -> &Archetypes

Retrieves this world’s Archetypes collection.

source

pub fn components(&self) -> &Components

Retrieves this world’s Components collection.

source

pub fn storages(&self) -> &Storages

Retrieves this world’s Storages collection.

source

pub fn bundles(&self) -> &Bundles

Retrieves this world’s Bundles collection.

source

pub fn removed_components(&self) -> &RemovedComponentEvents

Retrieves this world’s RemovedComponentEvents collection

source

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::init_component.

use bevy_ecs::prelude::*;

let mut world = World::new();

#[derive(Component)]
struct ComponentA;

let component_a_id = world.init_component::<ComponentA>();

assert_eq!(component_a_id, world.component_id::<ComponentA>().unwrap())
§See also
source

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

Retrieves an EntityRef that exposes read-only operations for the given entity. This will panic if the entity does not exist. Use World::get_entity if you want to check for entity existence instead of implicitly panic-ing.

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.entity(entity).get::<Position>().unwrap();
assert_eq!(position.x, 0.0);
source

pub fn inspect_entity(&self, entity: Entity) -> Vec<&ComponentInfo>

Returns the components of an Entity through ComponentInfo.

source

pub fn get_entity(&self, entity: Entity) -> Option<EntityRef<'_>>

Retrieves an EntityRef that exposes read-only operations for the given entity. Returns None if the entity does not exist. Instead of unwrapping the value returned from this function, prefer World::entity.

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 entity_ref = world.get_entity(entity).unwrap();
let position = entity_ref.get::<Position>().unwrap();
assert_eq!(position.x, 0.0);
source

pub fn get_many_entities<const N: usize>( &self, entities: [Entity; N] ) -> Result<[EntityRef<'_>; N], Entity>

Gets an EntityRef for multiple entities at once.

§Errors

If any entity does not exist in the world.

§Examples
// Getting multiple entities.
let [entity1, entity2] = world.get_many_entities([id1, id2]).unwrap();

// Trying to get a despawned entity will fail.
world.despawn(id2);
assert!(world.get_many_entities([id1, id2]).is_err());
source

pub fn get_many_entities_dynamic<'w>( &'w self, entities: &[Entity] ) -> Result<Vec<EntityRef<'w>>, Entity>

Gets an EntityRef for multiple entities at once, whose number is determined at runtime.

§Errors

If any entity does not exist in the world.

§Examples
// Getting multiple entities.
let entities = world.get_many_entities_dynamic(&[id1, id2]).unwrap();
let entity1 = entities.get(0).unwrap();
let entity2 = entities.get(1).unwrap();

// Trying to get a despawned entity will fail.
world.despawn(id2);
assert!(world.get_many_entities_dynamic(&[id1, id2]).is_err());
source

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

Returns an Entity iterator of current entities.

This is useful in contexts where you only have read-only access to the World.

source

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

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.

source

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.

source

pub fn contains_resource<R: Resource>(&self) -> bool

Returns true if a resource of type R exists. Otherwise returns false.

source

pub fn contains_non_send<R: 'static>(&self) -> bool

Returns true if a resource of type R exists. Otherwise returns false.

source

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.
source

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.
source

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.
source

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.
source

pub fn get_resource_change_ticks<R: Resource>(&self) -> Option<ComponentTicks>

Retrieves the change ticks for the given resource.

source

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.

source

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.

source

pub fn resource_ref<R: Resource>(&self) -> Res<'_, 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.

source

pub fn get_resource<R: Resource>(&self) -> Option<&R>

Gets a reference to the resource of the given type if it exists

source

pub fn get_resource_ref<R: Resource>(&self) -> Option<Res<'_, R>>

Gets a reference including change detection to the resource of the given type if it exists.

source

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.

source

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.

source

pub fn increment_change_tick(&self) -> Tick

Increments the world’s current change tick and returns the old value.

source

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.

source

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.

source

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.

source

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 TypeIds
// 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::new();

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

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.

source

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>

§

type Target = World

The resulting type after dereferencing.
source§

fn deref(&self) -> &Self::Target

Dereferences the value.
source§

impl<'w> From<&'w mut World> for DeferredWorld<'w>

source§

fn from(world: &'w mut World) -> DeferredWorld<'w>

Converts to this type from the input type.
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.

§

type State = ()

Used to store data which persists across invocations of a system.
§

type Item<'world, 'state> = DeferredWorld<'world>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes. Read more
source§

fn init_state(_world: &mut World, system_meta: &mut SystemMeta) -> Self::State

Registers any 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>

Creates a parameter to be passed into a SystemParamFunction. Read more
source§

unsafe fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta )

For the specified Archetype, registers the components accessed by this SystemParam (if applicable).a Read more
source§

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during apply_deferred.
source§

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_> )

Queues any deferred mutations to be applied at the next apply_deferred.

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> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> Downcast for T
where T: Any,

source§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
source§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
source§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &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)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
source§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> ConditionalSend for T
where T: Send,