Struct DeferredWorld

pub struct DeferredWorld<'w> { /* private fields */ }

A World reference that disallows structural ECS changes. This includes initializing resources, registering components or spawning entities.

Implementations

impl<'w> DeferredWorld<'w>

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

Reborrow self as a new instance of DeferredWorld

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

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

Examples found in repository

examples/ecs/component_hooks.rs (line 130)

fn setup(world: &mut World) {
    // In order to register component hooks the component must:
    // - not be currently in use by any entities in the world
    // - not already have a hook of that kind registered
    // This is to prevent overriding hooks defined in plugins and other crates as well as keeping things fast
    world
        .register_component_hooks::<MyComponent>()
        // There are 4 component lifecycle hooks: `on_add`, `on_insert`, `on_replace` and `on_remove`
        // A hook has 2 arguments:
        // - a `DeferredWorld`, this allows access to resource and component data as well as `Commands`
        // - a `HookContext`, this provides access to the following contextual information:
        //   - the entity that triggered the hook
        //   - the component id of the triggering component, this is mostly used for dynamic components
        //   - the location of the code that caused the hook to trigger
        //
        // `on_add` will trigger when a component is inserted onto an entity without it
        .on_add(
            |mut world,
             HookContext {
                 entity,
                 component_id,
                 caller,
                 ..
             }| {
                // You can access component data from within the hook
                let value = world.get::<MyComponent>(entity).unwrap().0;
                println!(
                    "{component_id:?} added to {entity} with value {value:?}{}",
                    caller
                        .map(|location| format!("due to {location}"))
                        .unwrap_or_default()
                );
                // Or access resources
                world
                    .resource_mut::<MyComponentIndex>()
                    .insert(value, entity);
                // Or send events
                world.send_event(MyEvent);
            },
        )
        // `on_insert` will trigger when a component is inserted onto an entity,
        // regardless of whether or not it already had it and after `on_add` if it ran
        .on_insert(|world, _| {
            println!("Current Index: {:?}", world.resource::<MyComponentIndex>());
        })
        // `on_replace` will trigger when a component is inserted onto an entity that already had it,
        // and runs before the value is replaced.
        // Also triggers when a component is removed from an entity, and runs before `on_remove`
        .on_replace(|mut world, context| {
            let value = world.get::<MyComponent>(context.entity).unwrap().0;
            world.resource_mut::<MyComponentIndex>().remove(&value);
        })
        // `on_remove` will trigger when a component is removed from an entity,
        // since it runs before the component is removed you can still access the component data
        .on_remove(
            |mut world,
             HookContext {
                 entity,
                 component_id,
                 caller,
                 ..
             }| {
                let value = world.get::<MyComponent>(entity).unwrap().0;
                println!(
                    "{component_id:?} removed from {entity} with value {value:?}{}",
                    caller
                        .map(|location| format!("due to {location}"))
                        .unwrap_or_default()
                );
                // You can also issue commands through `.commands()`
                world.commands().entity(entity).despawn();
            },
        );
}

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

where T: Component<Mutability = Mutable>,

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.

Examples found in repository

examples/ecs/error_handling.rs (line 139)

fn fallible_observer(
    trigger: Trigger<Pointer<Move>>,
    mut world: DeferredWorld,
    mut step: Local<f32>,
) -> Result {
    let mut transform = world
        .get_mut::<Transform>(trigger.target)
        .ok_or("No transform found.")?;

    *step = if transform.translation.x > 3. {
        -0.1
    } else if transform.translation.x < -3. || *step == 0. {
        0.1
    } else {
        *step
    };

    transform.translation.x += *step;

    Ok(())
}

pub fn get_entity_mut<F>( &mut self, entities: F, ) -> Result<<F as WorldEntityFetch>::DeferredMut<'_>, EntityMutableFetchError>

where F: WorldEntityFetch,

Returns EntityMuts 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 single EntityMut.
• Pass a slice of Entitys to receive a Vec<EntityMut>.
• Pass an array of Entitys to receive an equally-sized array of EntityMuts.
• Pass an &EntityHashSet to receive an EntityHashMap<EntityMut>.

As DeferredWorld does not allow structural changes, all returned references are EntityMuts, which do not allow structural changes (i.e. adding/removing components or despawning the entity).

Errors

• Returns EntityMutableFetchError::EntityDoesNotExist if any of the given entities 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.

pub fn entity_mut<F>( &mut self, entities: F, ) -> <F as WorldEntityFetch>::DeferredMut<'_>

where F: WorldEntityFetch,

Returns EntityMuts 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 single EntityMut.
• Pass a slice of Entitys to receive a Vec<EntityMut>.
• Pass an array of Entitys to receive an equally-sized array of EntityMuts.
• Pass an &EntityHashSet to receive an EntityHashMap<EntityMut>.

As DeferredWorld does not allow structural changes, all returned references are EntityMuts, 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 Entitys

#[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 Entitys

#[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);
}

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

pub fn query<'s, D, F>( &mut self, state: &'s mut QueryState<D, F>, ) -> Query<'_, 's, D, F>

where D: QueryData, F: QueryFilter,

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

pub fn resource_mut<R>(&mut self) -> Mut<'_, R>

where R: Resource,

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.

Examples found in repository

examples/ecs/component_hooks.rs (line 94)

fn setup(world: &mut World) {
    // In order to register component hooks the component must:
    // - not be currently in use by any entities in the world
    // - not already have a hook of that kind registered
    // This is to prevent overriding hooks defined in plugins and other crates as well as keeping things fast
    world
        .register_component_hooks::<MyComponent>()
        // There are 4 component lifecycle hooks: `on_add`, `on_insert`, `on_replace` and `on_remove`
        // A hook has 2 arguments:
        // - a `DeferredWorld`, this allows access to resource and component data as well as `Commands`
        // - a `HookContext`, this provides access to the following contextual information:
        //   - the entity that triggered the hook
        //   - the component id of the triggering component, this is mostly used for dynamic components
        //   - the location of the code that caused the hook to trigger
        //
        // `on_add` will trigger when a component is inserted onto an entity without it
        .on_add(
            |mut world,
             HookContext {
                 entity,
                 component_id,
                 caller,
                 ..
             }| {
                // You can access component data from within the hook
                let value = world.get::<MyComponent>(entity).unwrap().0;
                println!(
                    "{component_id:?} added to {entity} with value {value:?}{}",
                    caller
                        .map(|location| format!("due to {location}"))
                        .unwrap_or_default()
                );
                // Or access resources
                world
                    .resource_mut::<MyComponentIndex>()
                    .insert(value, entity);
                // Or send events
                world.send_event(MyEvent);
            },
        )
        // `on_insert` will trigger when a component is inserted onto an entity,
        // regardless of whether or not it already had it and after `on_add` if it ran
        .on_insert(|world, _| {
            println!("Current Index: {:?}", world.resource::<MyComponentIndex>());
        })
        // `on_replace` will trigger when a component is inserted onto an entity that already had it,
        // and runs before the value is replaced.
        // Also triggers when a component is removed from an entity, and runs before `on_remove`
        .on_replace(|mut world, context| {
            let value = world.get::<MyComponent>(context.entity).unwrap().0;
            world.resource_mut::<MyComponentIndex>().remove(&value);
        })
        // `on_remove` will trigger when a component is removed from an entity,
        // since it runs before the component is removed you can still access the component data
        .on_remove(
            |mut world,
             HookContext {
                 entity,
                 component_id,
                 caller,
                 ..
             }| {
                let value = world.get::<MyComponent>(entity).unwrap().0;
                println!(
                    "{component_id:?} removed from {entity} with value {value:?}{}",
                    caller
                        .map(|location| format!("due to {location}"))
                        .unwrap_or_default()
                );
                // You can also issue commands through `.commands()`
                world.commands().entity(entity).despawn();
            },
        );
}

pub fn get_resource_mut<R>(&mut self) -> Option<Mut<'_, R>>

where R: Resource,

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

Examples found in repository

examples/ecs/immutable_components.rs (line 82)

fn on_insert_name(mut world: DeferredWorld<'_>, HookContext { entity, .. }: HookContext) {
    let Some(&name) = world.entity(entity).get::<Name>() else {
        unreachable!("OnInsert hook guarantees `Name` is available on entity")
    };
    let Some(mut index) = world.get_resource_mut::<NameIndex>() else {
        return;
    };

    index.name_to_entity.insert(name, entity);
}

/// When a [`Name`] is removed or replaced, remove it from our [`NameIndex`].
///
/// Since all mutations to [`Name`] are captured by hooks, we know it is currently
/// inserted in the index.
fn on_replace_name(mut world: DeferredWorld<'_>, HookContext { entity, .. }: HookContext) {
    let Some(&name) = world.entity(entity).get::<Name>() else {
        unreachable!("OnReplace hook guarantees `Name` is available on entity")
    };
    let Some(mut index) = world.get_resource_mut::<NameIndex>() else {
        return;
    };

    index.name_to_entity.remove(&name);
}

pub fn non_send_resource_mut<R>(&mut self) -> Mut<'_, R>

where R: 'static,

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.

pub fn get_non_send_resource_mut<R>(&mut self) -> Option<Mut<'_, R>>

where R: 'static,

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.

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

where E: Event,

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

Examples found in repository

examples/ecs/component_hooks.rs (line 97)

fn setup(world: &mut World) {
    // In order to register component hooks the component must:
    // - not be currently in use by any entities in the world
    // - not already have a hook of that kind registered
    // This is to prevent overriding hooks defined in plugins and other crates as well as keeping things fast
    world
        .register_component_hooks::<MyComponent>()
        // There are 4 component lifecycle hooks: `on_add`, `on_insert`, `on_replace` and `on_remove`
        // A hook has 2 arguments:
        // - a `DeferredWorld`, this allows access to resource and component data as well as `Commands`
        // - a `HookContext`, this provides access to the following contextual information:
        //   - the entity that triggered the hook
        //   - the component id of the triggering component, this is mostly used for dynamic components
        //   - the location of the code that caused the hook to trigger
        //
        // `on_add` will trigger when a component is inserted onto an entity without it
        .on_add(
            |mut world,
             HookContext {
                 entity,
                 component_id,
                 caller,
                 ..
             }| {
                // You can access component data from within the hook
                let value = world.get::<MyComponent>(entity).unwrap().0;
                println!(
                    "{component_id:?} added to {entity} with value {value:?}{}",
                    caller
                        .map(|location| format!("due to {location}"))
                        .unwrap_or_default()
                );
                // Or access resources
                world
                    .resource_mut::<MyComponentIndex>()
                    .insert(value, entity);
                // Or send events
                world.send_event(MyEvent);
            },
        )
        // `on_insert` will trigger when a component is inserted onto an entity,
        // regardless of whether or not it already had it and after `on_add` if it ran
        .on_insert(|world, _| {
            println!("Current Index: {:?}", world.resource::<MyComponentIndex>());
        })
        // `on_replace` will trigger when a component is inserted onto an entity that already had it,
        // and runs before the value is replaced.
        // Also triggers when a component is removed from an entity, and runs before `on_remove`
        .on_replace(|mut world, context| {
            let value = world.get::<MyComponent>(context.entity).unwrap().0;
            world.resource_mut::<MyComponentIndex>().remove(&value);
        })
        // `on_remove` will trigger when a component is removed from an entity,
        // since it runs before the component is removed you can still access the component data
        .on_remove(
            |mut world,
             HookContext {
                 entity,
                 component_id,
                 caller,
                 ..
             }| {
                let value = world.get::<MyComponent>(entity).unwrap().0;
                println!(
                    "{component_id:?} removed from {entity} with value {value:?}{}",
                    caller
                        .map(|location| format!("due to {location}"))
                        .unwrap_or_default()
                );
                // You can also issue commands through `.commands()`
                world.commands().entity(entity).despawn();
            },
        );
}

pub fn send_event_default<E>(&mut self) -> Option<EventId<E>>

where E: Event + Default,

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.

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

where E: Event,

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.

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.

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.

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.

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

Sends a “global” Trigger without any targets.

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>

pub fn get_reflect( &self, entity: Entity, type_id: TypeId, ) -> Result<&(dyn Reflect + 'static), GetComponentReflectError>

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 called¹.

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

---

1. More specifically: Requires TypeData for ReflectFromPtr to be registered for the given type_id, which is automatically handled when deriving Reflect and calling App::register_type. ↩

pub fn id(&self) -> WorldId

Retrieves this World’s unique ID

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

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

pub fn entities(&self) -> &Entities

Retrieves this world’s Entities collection.

pub fn archetypes(&self) -> &Archetypes

Retrieves this world’s Archetypes collection.

Examples found in repository

examples/stress_tests/many_components.rs (line 162)

fn stress_test(num_entities: u32, num_components: u32, num_systems: u32) {
    let mut rng = ChaCha8Rng::seed_from_u64(42);
    let mut app = App::default();
    let world = app.world_mut();

    // register a bunch of components
    let component_ids: Vec<ComponentId> = (1..=num_components)
        .map(|i| {
            world.register_component_with_descriptor(
                // SAFETY:
                // * We don't implement a drop function
                // * u8 is Sync and Send
                unsafe {
                    ComponentDescriptor::new_with_layout(
                        format!("Component{}", i).to_string(),
                        StorageType::Table,
                        Layout::new::<u8>(),
                        None,
                        true, // is mutable
                        ComponentCloneBehavior::Default,
                    )
                },
            )
        })
        .collect();

    // fill the schedule with systems
    let mut schedule = Schedule::new(Update);
    for _ in 1..=num_systems {
        let num_access_components = rng.gen_range(1..10);
        let access_components: Vec<ComponentId> = component_ids
            .choose_multiple(&mut rng, num_access_components)
            .copied()
            .collect();
        let system = (QueryParamBuilder::new(|builder| {
            for &access_component in &access_components {
                if rand::random::<bool>() {
                    builder.mut_id(access_component);
                } else {
                    builder.ref_id(access_component);
                }
            }
        }),)
            .build_state(world)
            .build_any_system(base_system);
        schedule.add_systems((move || access_components.clone()).pipe(system));
    }

    // spawn a bunch of entities
    for _ in 1..=num_entities {
        let num_components = rng.gen_range(1..10);
        let components: Vec<ComponentId> = component_ids
            .choose_multiple(&mut rng, num_components)
            .copied()
            .collect();

        let mut entity = world.spawn_empty();
        // We use `ManuallyDrop` here as we need to avoid dropping the u8's when `values` is dropped
        // since ownership of the values is passed to the world in `insert_by_ids`.
        // But we do want to deallocate the memory when values is dropped.
        let mut values: Vec<ManuallyDrop<u8>> = components
            .iter()
            .map(|_id| ManuallyDrop::new(rng.gen_range(0..255)))
            .collect();
        let ptrs: Vec<OwningPtr> = values
            .iter_mut()
            .map(|value| {
                // SAFETY:
                // * We don't read/write `values` binding after this and values are `ManuallyDrop`,
                // so we have the right to drop/move the values
                unsafe { PtrMut::from(value).promote() }
            })
            .collect();
        // SAFETY:
        // * component_id's are from the same world
        // * `values` was initialized above, so references are valid
        unsafe {
            entity.insert_by_ids(&components, ptrs.into_iter());
        }
    }

    println!(
        "Number of Archetype-Components: {}",
        world.archetypes().archetype_components_len()
    );

    // overwrite Update schedule in the app
    app.add_schedule(schedule);
    app.add_plugins(MinimalPlugins)
        .add_plugins(DiagnosticsPlugin)
        .add_plugins(LogPlugin::default())
        .add_plugins(FrameTimeDiagnosticsPlugin::default())
        .add_plugins(LogDiagnosticsPlugin::filtered(vec![DiagnosticPath::new(
            "fps",
        )]));
    app.run();
}

pub fn components(&self) -> &Components

Retrieves this world’s Components collection.

Examples found in repository

examples/ecs/dynamic.rs (line 102)

fn main() {
    let mut world = World::new();
    let mut lines = std::io::stdin().lines();
    let mut component_names = HashMap::<String, ComponentId>::new();
    let mut component_info = HashMap::<ComponentId, ComponentInfo>::new();

    println!("{PROMPT}");
    loop {
        print!("\n> ");
        let _ = std::io::stdout().flush();
        let Some(Ok(line)) = lines.next() else {
            return;
        };

        if line.is_empty() {
            return;
        };

        let Some((first, rest)) = line.trim().split_once(|c: char| c.is_whitespace()) else {
            match &line.chars().next() {
                Some('c') => println!("{COMPONENT_PROMPT}"),
                Some('s') => println!("{ENTITY_PROMPT}"),
                Some('q') => println!("{QUERY_PROMPT}"),
                _ => println!("{PROMPT}"),
            }
            continue;
        };

        match &first[0..1] {
            "c" => {
                rest.split(',').for_each(|component| {
                    let mut component = component.split_whitespace();
                    let Some(name) = component.next() else {
                        return;
                    };
                    let size = match component.next().map(str::parse) {
                        Some(Ok(size)) => size,
                        _ => 0,
                    };
                    // Register our new component to the world with a layout specified by it's size
                    // SAFETY: [u64] is Send + Sync
                    let id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            name.to_string(),
                            StorageType::Table,
                            Layout::array::<u64>(size).unwrap(),
                            None,
                            true,
                            ComponentCloneBehavior::Default,
                        )
                    });
                    let Some(info) = world.components().get_info(id) else {
                        return;
                    };
                    component_names.insert(name.to_string(), id);
                    component_info.insert(id, info.clone());
                    println!("Component {} created with id: {}", name, id.index());
                });
            }
            "s" => {
                let mut to_insert_ids = Vec::new();
                let mut to_insert_data = Vec::new();
                rest.split(',').for_each(|component| {
                    let mut component = component.split_whitespace();
                    let Some(name) = component.next() else {
                        return;
                    };

                    // Get the id for the component with the given name
                    let Some(&id) = component_names.get(name) else {
                        println!("Component {name} does not exist");
                        return;
                    };

                    // Calculate the length for the array based on the layout created for this component id
                    let info = world.components().get_info(id).unwrap();
                    let len = info.layout().size() / size_of::<u64>();
                    let mut values: Vec<u64> = component
                        .take(len)
                        .filter_map(|value| value.parse::<u64>().ok())
                        .collect();
                    values.resize(len, 0);

                    // Collect the id and array to be inserted onto our entity
                    to_insert_ids.push(id);
                    to_insert_data.push(values);
                });

                let mut entity = world.spawn_empty();

                // Construct an `OwningPtr` for each component in `to_insert_data`
                let to_insert_ptr = to_owning_ptrs(&mut to_insert_data);

                // SAFETY:
                // - Component ids have been taken from the same world
                // - Each array is created to the layout specified in the world
                unsafe {
                    entity.insert_by_ids(&to_insert_ids, to_insert_ptr.into_iter());
                }

                println!("Entity spawned with id: {}", entity.id());
            }
            "q" => {
                let mut builder = QueryBuilder::<FilteredEntityMut>::new(&mut world);
                parse_query(rest, &mut builder, &component_names);
                let mut query = builder.build();
                query.iter_mut(&mut world).for_each(|filtered_entity| {
                    let terms = filtered_entity
                        .access()
                        .try_iter_component_access()
                        .unwrap()
                        .map(|component_access| {
                            let id = *component_access.index();
                            let ptr = filtered_entity.get_by_id(id).unwrap();
                            let info = component_info.get(&id).unwrap();
                            let len = info.layout().size() / size_of::<u64>();

                            // SAFETY:
                            // - All components are created with layout [u64]
                            // - len is calculated from the component descriptor
                            let data = unsafe {
                                std::slice::from_raw_parts_mut(
                                    ptr.assert_unique().as_ptr().cast::<u64>(),
                                    len,
                                )
                            };

                            // If we have write access, increment each value once
                            if matches!(component_access, ComponentAccessKind::Exclusive(_)) {
                                data.iter_mut().for_each(|data| {
                                    *data += 1;
                                });
                            }

                            format!("{}: {:?}", info.name(), data[0..len].to_vec())
                        })
                        .collect::<Vec<_>>()
                        .join(", ");

                    println!("{}: {}", filtered_entity.id(), terms);
                });
            }
            _ => continue,
        }
    }
}

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.

pub fn storages(&self) -> &Storages

Retrieves this world’s Storages collection.

pub fn bundles(&self) -> &Bundles

Retrieves this world’s Bundles collection.

pub fn removed_components(&self) -> &RemovedComponentEvents

Retrieves this world’s RemovedComponentEvents collection

pub fn get_required_components<C>(&self) -> Option<&RequiredComponents>

where C: Component,

Retrieves the required components for the given component type, if it exists.

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.

pub fn component_id<T>(&self) -> Option<ComponentId>

where T: Component,

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

• Components::component_id()
• Components::get_id()

pub fn resource_id<T>(&self) -> Option<ComponentId>

where T: Resource,

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.

pub fn entity<F>(&self, entities: F) -> <F as WorldEntityFetch>::Ref<'_>

where F: WorldEntityFetch,

Returns EntityRefs 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 single EntityRef.
• Pass a slice of Entitys to receive a Vec<EntityRef>.
• Pass an array of Entitys to receive an equally-sized array of EntityRefs.

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 Entitys

#[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 Entitys

#[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);
}

Examples found in repository

examples/ecs/immutable_components.rs (line 79)

fn on_insert_name(mut world: DeferredWorld<'_>, HookContext { entity, .. }: HookContext) {
    let Some(&name) = world.entity(entity).get::<Name>() else {
        unreachable!("OnInsert hook guarantees `Name` is available on entity")
    };
    let Some(mut index) = world.get_resource_mut::<NameIndex>() else {
        return;
    };

    index.name_to_entity.insert(name, entity);
}

/// When a [`Name`] is removed or replaced, remove it from our [`NameIndex`].
///
/// Since all mutations to [`Name`] are captured by hooks, we know it is currently
/// inserted in the index.
fn on_replace_name(mut world: DeferredWorld<'_>, HookContext { entity, .. }: HookContext) {
    let Some(&name) = world.entity(entity).get::<Name>() else {
        unreachable!("OnReplace hook guarantees `Name` is available on entity")
    };
    let Some(mut index) = world.get_resource_mut::<NameIndex>() else {
        return;
    };

    index.name_to_entity.remove(&name);
}

pub fn inspect_entity( &self, entity: Entity, ) -> Result<impl Iterator<Item = &ComponentInfo>, EntityDoesNotExistError>

Returns the components of an Entity through ComponentInfo.

pub fn get_entity<F>( &self, entities: F, ) -> Result<<F as WorldEntityFetch>::Ref<'_>, EntityDoesNotExistError>

where F: WorldEntityFetch,

Returns EntityRefs 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 single EntityRef.
• Pass a slice of Entitys to receive a Vec<EntityRef>.
• Pass an array of Entitys to receive an equally-sized array of EntityRefs.
• Pass a reference to a EntityHashSet to receive an EntityHashMap<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.

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.

pub fn get<T>(&self, entity: Entity) -> Option<&T>

where T: Component,

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

Examples found in repository

examples/ecs/component_hooks.rs (line 85)

fn setup(world: &mut World) {
    // In order to register component hooks the component must:
    // - not be currently in use by any entities in the world
    // - not already have a hook of that kind registered
    // This is to prevent overriding hooks defined in plugins and other crates as well as keeping things fast
    world
        .register_component_hooks::<MyComponent>()
        // There are 4 component lifecycle hooks: `on_add`, `on_insert`, `on_replace` and `on_remove`
        // A hook has 2 arguments:
        // - a `DeferredWorld`, this allows access to resource and component data as well as `Commands`
        // - a `HookContext`, this provides access to the following contextual information:
        //   - the entity that triggered the hook
        //   - the component id of the triggering component, this is mostly used for dynamic components
        //   - the location of the code that caused the hook to trigger
        //
        // `on_add` will trigger when a component is inserted onto an entity without it
        .on_add(
            |mut world,
             HookContext {
                 entity,
                 component_id,
                 caller,
                 ..
             }| {
                // You can access component data from within the hook
                let value = world.get::<MyComponent>(entity).unwrap().0;
                println!(
                    "{component_id:?} added to {entity} with value {value:?}{}",
                    caller
                        .map(|location| format!("due to {location}"))
                        .unwrap_or_default()
                );
                // Or access resources
                world
                    .resource_mut::<MyComponentIndex>()
                    .insert(value, entity);
                // Or send events
                world.send_event(MyEvent);
            },
        )
        // `on_insert` will trigger when a component is inserted onto an entity,
        // regardless of whether or not it already had it and after `on_add` if it ran
        .on_insert(|world, _| {
            println!("Current Index: {:?}", world.resource::<MyComponentIndex>());
        })
        // `on_replace` will trigger when a component is inserted onto an entity that already had it,
        // and runs before the value is replaced.
        // Also triggers when a component is removed from an entity, and runs before `on_remove`
        .on_replace(|mut world, context| {
            let value = world.get::<MyComponent>(context.entity).unwrap().0;
            world.resource_mut::<MyComponentIndex>().remove(&value);
        })
        // `on_remove` will trigger when a component is removed from an entity,
        // since it runs before the component is removed you can still access the component data
        .on_remove(
            |mut world,
             HookContext {
                 entity,
                 component_id,
                 caller,
                 ..
             }| {
                let value = world.get::<MyComponent>(entity).unwrap().0;
                println!(
                    "{component_id:?} removed from {entity} with value {value:?}{}",
                    caller
                        .map(|location| format!("due to {location}"))
                        .unwrap_or_default()
                );
                // You can also issue commands through `.commands()`
                world.commands().entity(entity).despawn();
            },
        );
}

pub fn try_query<D>(&self) -> Option<QueryState<D>>

where D: QueryData,

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

pub fn try_query_filtered<D, F>(&self) -> Option<QueryState<D, F>>

where D: QueryData, F: QueryFilter,

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.

pub fn removed<T>(&self) -> impl Iterator<Item = Entity>

where T: Component,

Returns an iterator of entities that had components of type T removed since the last call to World::clear_trackers.

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.

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

where R: Resource,

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

pub fn contains_resource_by_id(&self, component_id: ComponentId) -> bool

Returns true if a resource with provided component_id exists. Otherwise returns false.

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

where R: 'static,

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

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.

pub fn is_resource_added<R>(&self) -> bool

where R: Resource,

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.

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.

pub fn is_resource_changed<R>(&self) -> bool

where R: Resource,

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.

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.

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

where R: Resource,

Retrieves the change ticks for the given resource.

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.

pub fn resource<R>(&self) -> &R

where R: Resource,

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.

Examples found in repository

examples/3d/specular_tint.rs (line 33)

    fn from_world(world: &mut World) -> Self {
        let asset_server = world.resource::<AssetServer>();
        Self {
            noise_texture: asset_server.load("textures/AlphaNoise.png"),
        }
    }

examples/shader/custom_render_phase.rs (line 172)

    fn from_world(world: &mut World) -> Self {
        Self {
            mesh_pipeline: MeshPipeline::from_world(world),
            shader_handle: world.resource::<AssetServer>().load(SHADER_ASSET_PATH),
        }
    }

examples/scene/scene.rs (line 91)

    fn from_world(world: &mut World) -> Self {
        let time = world.resource::<Time>();
        ComponentB {
            _time_since_startup: time.elapsed(),
            value: "Default Value".to_string(),
        }
    }
}

/// A simple resource that also derives `Reflect`, allowing it to be stored in scenes.
///
/// Just like a component, you can skip serializing fields or implement `FromWorld` if needed.
#[derive(Resource, Reflect, Default)]
#[reflect(Resource)]
struct ResourceA {
    /// This resource tracks a `score` value.
    pub score: u32,
}

/// # Scene File Paths
///
/// `SCENE_FILE_PATH` points to the original scene file that we'll be loading.
/// `NEW_SCENE_FILE_PATH` points to the new scene file that we'll be creating
/// (and demonstrating how to serialize to disk).
///
/// The initial scene file will be loaded below and not change when the scene is saved.
const SCENE_FILE_PATH: &str = "scenes/load_scene_example.scn.ron";

/// The new, updated scene data will be saved here so that you can see the changes.
const NEW_SCENE_FILE_PATH: &str = "scenes/load_scene_example-new.scn.ron";

/// Loads a scene from an asset file and spawns it in the current world.
///
/// Spawning a `DynamicSceneRoot` creates a new parent entity, which then spawns new
/// instances of the scene's entities as its children. If you modify the
/// `SCENE_FILE_PATH` scene file, or if you enable file watching, you can see
/// changes reflected immediately.
fn load_scene_system(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(DynamicSceneRoot(asset_server.load(SCENE_FILE_PATH)));
}

/// Logs changes made to `ComponentA` entities, and also checks whether `ResourceA`
/// has been recently added.
///
/// Any time a `ComponentA` is modified, that change will appear here. This system
/// demonstrates how you might detect and handle scene updates at runtime.
fn log_system(
    query: Query<(Entity, &ComponentA), Changed<ComponentA>>,
    res: Option<Res<ResourceA>>,
) {
    for (entity, component_a) in &query {
        info!("  Entity({})", entity.index());
        info!(
            "    ComponentA: {{ x: {} y: {} }}\n",
            component_a.x, component_a.y
        );
    }
    if let Some(res) = res {
        if res.is_added() {
            info!("  New ResourceA: {{ score: {} }}\n", res.score);
        }
    }
}

/// Demonstrates how to create a new scene from scratch, populate it with data,
/// and then serialize it to a file. The new file is written to `NEW_SCENE_FILE_PATH`.
///
/// This system creates a fresh world, duplicates the type registry so that our
/// custom component types are recognized, spawns some sample entities and resources,
/// and then serializes the resulting dynamic scene.
fn save_scene_system(world: &mut World) {
    // Scenes can be created from any ECS World.
    // You can either create a new one for the scene or use the current World.
    // For demonstration purposes, we'll create a new one.
    let mut scene_world = World::new();

    // The `TypeRegistry` resource contains information about all registered types (including components).
    // This is used to construct scenes, so we'll want to ensure that our previous type registrations
    // exist in this new scene world as well.
    // To do this, we can simply clone the `AppTypeRegistry` resource.
    let type_registry = world.resource::<AppTypeRegistry>().clone();
    scene_world.insert_resource(type_registry);

    let mut component_b = ComponentB::from_world(world);
    component_b.value = "hello".to_string();
    scene_world.spawn((
        component_b,
        ComponentA { x: 1.0, y: 2.0 },
        Transform::IDENTITY,
        Name::new("joe"),
    ));
    scene_world.spawn(ComponentA { x: 3.0, y: 4.0 });
    scene_world.insert_resource(ResourceA { score: 1 });

    // With our sample world ready to go, we can now create our scene using DynamicScene or DynamicSceneBuilder.
    // For simplicity, we will create our scene using DynamicScene:
    let scene = DynamicScene::from_world(&scene_world);

    // Scenes can be serialized like this:
    let type_registry = world.resource::<AppTypeRegistry>();
    let type_registry = type_registry.read();
    let serialized_scene = scene.serialize(&type_registry).unwrap();

    // Showing the scene in the console
    info!("{}", serialized_scene);

    // Writing the scene to a new file. Using a task to avoid calling the filesystem APIs in a system
    // as they are blocking.
    //
    // This can't work in Wasm as there is no filesystem access.
    #[cfg(not(target_arch = "wasm32"))]
    IoTaskPool::get()
        .spawn(async move {
            // Write the scene RON data to file
            File::create(format!("assets/{NEW_SCENE_FILE_PATH}"))
                .and_then(|mut file| file.write(serialized_scene.as_bytes()))
                .expect("Error while writing scene to file");
        })
        .detach();
}

examples/shader/custom_shader_instancing.rs (line 207)

    fn from_world(world: &mut World) -> Self {
        let mesh_pipeline = world.resource::<MeshPipeline>();

        CustomPipeline {
            shader: world.load_asset(SHADER_ASSET_PATH),
            mesh_pipeline: mesh_pipeline.clone(),
        }
    }

examples/shader/specialized_mesh_pipeline.rs (line 174)

    fn from_world(world: &mut World) -> Self {
        // Load the shader
        let shader_handle: Handle<Shader> = world.resource::<AssetServer>().load(SHADER_ASSET_PATH);
        Self {
            mesh_pipeline: MeshPipeline::from_world(world),
            shader_handle,
        }
    }

tests/ecs/ambiguity_detection.rs (line 73)

fn count_ambiguities(sub_app: &SubApp) -> AmbiguitiesCount {
    let schedules = sub_app.world().resource::<Schedules>();
    let mut ambiguities = <HashMap<_, _>>::default();
    for (_, schedule) in schedules.iter() {
        let ambiguities_in_schedule = schedule.graph().conflicting_systems().len();
        ambiguities.insert(schedule.label(), ambiguities_in_schedule);
    }
    AmbiguitiesCount(ambiguities)
}

Additional examples can be found in:

• examples/shader/custom_phase_item.rs
• examples/shader/texture_binding_array.rs
• examples/ecs/immutable_components.rs
• examples/ecs/ecs_guide.rs
• examples/3d/occlusion_culling.rs
• examples/shader/gpu_readback.rs
• examples/shader/compute_shader_game_of_life.rs
• examples/ecs/component_hooks.rs
• examples/shader/custom_post_processing.rs

pub fn resource_ref<R>(&self) -> Ref<'_, R>

where R: Resource,

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.

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

where R: Resource,

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

Examples found in repository

examples/ecs/error_handling.rs (line 162)

fn failing_system(world: &mut World) -> Result {
    world
        // `get_resource` returns an `Option<T>`, so we use `ok_or` to convert it to a `Result` on
        // which we can call `?` to propagate the error.
        .get_resource::<UninitializedResource>()
        // We can provide a `str` here because `BevyError` implements `From<&str>`.
        .ok_or("Resource not initialized")?;

    Ok(())
}

fn failing_commands(mut commands: Commands) {
    commands
        // This entity doesn't exist!
        .entity(Entity::from_raw(12345678))
        // Normally, this failed command would panic,
        // but since we've set the global error handler to `warn`
        // it will log a warning instead.
        .insert(Transform::default());

    // The error handlers for commands can be set individually as well,
    // by using the queue_handled method.
    commands.queue_handled(
        |world: &mut World| -> Result {
            world
                .get_resource::<UninitializedResource>()
                .ok_or("Resource not initialized when accessed in a command")?;

            Ok(())
        },
        |error, context| {
            error!("{error}, {context}");
        },
    );
}

examples/shader/custom_render_phase.rs (line 595)

    fn run<'w>(
        &self,
        graph: &mut RenderGraphContext,
        render_context: &mut RenderContext<'w>,
        (camera, view, target): QueryItem<'w, Self::ViewQuery>,
        world: &'w World,
    ) -> Result<(), NodeRunError> {
        // First, we need to get our phases resource
        let Some(stencil_phases) = world.get_resource::<ViewSortedRenderPhases<Stencil3d>>() else {
            return Ok(());
        };

        // Get the view entity from the graph
        let view_entity = graph.view_entity();

        // Get the phase for the current view running our node
        let Some(stencil_phase) = stencil_phases.get(&view.retained_view_entity) else {
            return Ok(());
        };

        // Render pass setup
        let mut render_pass = render_context.begin_tracked_render_pass(RenderPassDescriptor {
            label: Some("stencil pass"),
            // For the purpose of the example, we will write directly to the view target. A real
            // stencil pass would write to a custom texture and that texture would be used in later
            // passes to render custom effects using it.
            color_attachments: &[Some(target.get_color_attachment())],
            // We don't bind any depth buffer for this pass
            depth_stencil_attachment: None,
            timestamp_writes: None,
            occlusion_query_set: None,
        });

        if let Some(viewport) = camera.viewport.as_ref() {
            render_pass.set_camera_viewport(viewport);
        }

        // Render the phase
        // This will execute each draw functions of each phase items queued in this phase
        if let Err(err) = stencil_phase.render(&mut render_pass, world, view_entity) {
            error!("Error encountered while rendering the stencil phase {err:?}");
        }

        Ok(())
    }

examples/app/headless_renderer.rs (line 346)

    fn run(
        &self,
        _graph: &mut RenderGraphContext,
        render_context: &mut RenderContext,
        world: &World,
    ) -> Result<(), NodeRunError> {
        let image_copiers = world.get_resource::<ImageCopiers>().unwrap();
        let gpu_images = world
            .get_resource::<RenderAssets<bevy::render::texture::GpuImage>>()
            .unwrap();

        for image_copier in image_copiers.iter() {
            if !image_copier.enabled() {
                continue;
            }

            let src_image = gpu_images.get(&image_copier.src_image).unwrap();

            let mut encoder = render_context
                .render_device()
                .create_command_encoder(&CommandEncoderDescriptor::default());

            let block_dimensions = src_image.texture_format.block_dimensions();
            let block_size = src_image.texture_format.block_copy_size(None).unwrap();

            // Calculating correct size of image row because
            // copy_texture_to_buffer can copy image only by rows aligned wgpu::COPY_BYTES_PER_ROW_ALIGNMENT
            // That's why image in buffer can be little bit wider
            // This should be taken into account at copy from buffer stage
            let padded_bytes_per_row = RenderDevice::align_copy_bytes_per_row(
                (src_image.size.width as usize / block_dimensions.0 as usize) * block_size as usize,
            );

            encoder.copy_texture_to_buffer(
                src_image.texture.as_image_copy(),
                TexelCopyBufferInfo {
                    buffer: &image_copier.buffer,
                    layout: TexelCopyBufferLayout {
                        offset: 0,
                        bytes_per_row: Some(
                            std::num::NonZero::<u32>::new(padded_bytes_per_row as u32)
                                .unwrap()
                                .into(),
                        ),
                        rows_per_image: None,
                    },
                },
                src_image.size,
            );

            let render_queue = world.get_resource::<RenderQueue>().unwrap();
            render_queue.submit(std::iter::once(encoder.finish()));
        }

        Ok(())
    }

examples/3d/occlusion_culling.rs (line 429)

    fn run<'w>(
        &self,
        _: &mut RenderGraphContext,
        render_context: &mut RenderContext<'w>,
        world: &'w World,
    ) -> Result<(), NodeRunError> {
        // Extract the buffers that hold the GPU indirect draw parameters from
        // the world resources. We're going to read those buffers to determine
        // how many meshes were actually drawn.
        let (Some(indirect_parameters_buffers), Some(indirect_parameters_mapping_buffers)) = (
            world.get_resource::<IndirectParametersBuffers>(),
            world.get_resource::<IndirectParametersStagingBuffers>(),
        ) else {
            return Ok(());
        };

        // Get the indirect parameters buffers corresponding to the opaque 3D
        // phase, since all our meshes are in that phase.
        let Some(phase_indirect_parameters_buffers) =
            indirect_parameters_buffers.get(&TypeId::of::<Opaque3d>())
        else {
            return Ok(());
        };

        // Grab both the buffers we're copying from and the staging buffers
        // we're copying to. Remember that we can't map the indirect parameters
        // buffers directly, so we have to copy their contents to a staging
        // buffer.
        let (
            Some(indexed_data_buffer),
            Some(indexed_batch_sets_buffer),
            Some(indirect_parameters_staging_data_buffer),
            Some(indirect_parameters_staging_batch_sets_buffer),
        ) = (
            phase_indirect_parameters_buffers.indexed.data_buffer(),
            phase_indirect_parameters_buffers
                .indexed
                .batch_sets_buffer(),
            indirect_parameters_mapping_buffers.data.as_ref(),
            indirect_parameters_mapping_buffers.batch_sets.as_ref(),
        )
        else {
            return Ok(());
        };

        // Copy from the indirect parameters buffers to the staging buffers.
        render_context.command_encoder().copy_buffer_to_buffer(
            indexed_data_buffer,
            0,
            indirect_parameters_staging_data_buffer,
            0,
            indexed_data_buffer.size(),
        );
        render_context.command_encoder().copy_buffer_to_buffer(
            indexed_batch_sets_buffer,
            0,
            indirect_parameters_staging_batch_sets_buffer,
            0,
            indexed_batch_sets_buffer.size(),
        );

        Ok(())
    }

pub fn get_resource_ref<R>(&self) -> Option<Ref<'_, R>>

where R: Resource,

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

pub fn non_send_resource<R>(&self) -> &R

where R: 'static,

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.

pub fn get_non_send_resource<R>(&self) -> Option<&R>

where R: 'static,

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.

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.

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.

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.

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::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);
}

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.

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

impl<'w> Deref for DeferredWorld<'w>

type Target = World

The resulting type after dereferencing.

fn deref(&self) -> &<DeferredWorld<'w> as Deref>::Target

Dereferences the value.

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

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

Converts to this type from the input type.

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.

fn init_state( _world: &mut World, system_meta: &mut SystemMeta, ) -> <DeferredWorld<'w> as SystemParam>::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

unsafe fn get_param<'world, 'state>( _state: &'state mut <DeferredWorld<'w> as SystemParam>::State, _system_meta: &SystemMeta, world: UnsafeWorldCell<'world>, _change_tick: Tick, ) -> <DeferredWorld<'w> as SystemParam>::Item<'world, 'state>

Creates a parameter to be passed into a SystemParamFunction.

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

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

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

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

unsafe fn validate_param( state: &Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'_>, ) -> Result<(), SystemParamValidationError>

Validates that the param can be acquired by the get_param.