Struct World 

pub struct World {

    id: WorldId,
    pub(crate) entities: Entities,
    pub(crate) entity_allocator: EntityAllocator,
    pub(crate) components: Components,
    pub(crate) component_ids: ComponentIds,
    pub(crate) resource_entities: ResourceEntities,
    pub(crate) archetypes: Archetypes,
    pub(crate) storages: Storages,
    pub(crate) bundles: Bundles,
    pub(crate) observers: Observers,
    pub(crate) removed_components: RemovedComponentMessages,
    pub(crate) change_tick: Atomic<u32>,
    pub(crate) last_change_tick: Tick,
    pub(crate) last_check_tick: Tick,
    pub(crate) last_trigger_id: u32,
    pub(crate) command_queue: RawCommandQueue,
}

Stores and exposes operations on entities, components, resources, and their associated metadata.

Each Entity has a set of unique components, based on their type. Entity components can be created, updated, removed, and queried using a given World.

For complex access patterns involving SystemParam, consider using SystemState.

To mutate different parts of the world simultaneously, use World::resource_scope or SystemState.

Resources

Worlds can also store Resources, which are unique instances of a given type that belong to a specific unique Entity. There are also non send resources, which can only be accessed on the main thread. These are stored outside of the ECS. See Resource for usage.

Fields

id: WorldId

entities: Entities

entity_allocator: EntityAllocator

components: Components

component_ids: ComponentIds

resource_entities: ResourceEntities

archetypes: Archetypes

storages: Storages

bundles: Bundles

observers: Observers

removed_components: RemovedComponentMessages

change_tick: Atomic<u32>

last_change_tick: Tick

last_check_tick: Tick

last_trigger_id: u32

command_queue: RawCommandQueue

Implementations

impl World

pub fn register_event_key<E>(&mut self) -> EventKey

where E: Event,

Generates the EventKey for this event type.

If this type has already been registered, this will return the existing EventKey.

This is used by various dynamically typed observer APIs, such as DeferredWorld::trigger_raw.

pub fn event_key<E>(&self) -> Option<EventKey>

where E: Event,

Fetches the EventKey for this event type, if it has already been generated.

This is used by various dynamically typed observer APIs, such as DeferredWorld::trigger_raw.

impl World

pub fn add_observer<M>( &mut self, observer: impl IntoObserver<M>, ) -> EntityWorldMut<'_>

Spawns a “global” Observer which will watch for the given event. Returns its Entity as a EntityWorldMut.

system can be any system whose first parameter is On.

Example

#[derive(Component)]
struct A;

world.add_observer(|_: On<Add, A>| {
    // ...
});
world.add_observer(|_: On<Remove, A>| {
    // ...
});

Calling observe on the returned EntityWorldMut will observe the observer itself, which you very likely do not want.

Panics

Panics if the given system is an exclusive system.

pub fn trigger<'a, E>(&mut self, event: E)

where E: Event, <E as Event>::Trigger<'a>: Default,

Triggers the given Event, which will run any Observers watching for it.

For a variant that borrows the event rather than consuming it, use World::trigger_ref instead.

pub fn trigger_with<'a, E>( &mut self, event: E, trigger: <E as Event>::Trigger<'a>, )

where E: Event,

Triggers the given Event using the given Trigger, which will run any Observers watching for it.

For a variant that borrows the event rather than consuming it, use World::trigger_ref instead.

pub fn trigger_ref<'a, E>(&mut self, event: &mut E)

where E: Event, <E as Event>::Trigger<'a>: Default,

Triggers the given mutable Event reference, which will run any Observers watching for it.

Compared to World::trigger, this method is most useful when it’s necessary to check or use the event after it has been modified by observers.

pub fn trigger_ref_with<'a, E>( &mut self, event: &mut E, trigger: &mut <E as Event>::Trigger<'a>, )

where E: Event,

Triggers the given mutable Event reference using the given mutable Trigger reference, which will run any Observers watching for it.

Compared to World::trigger, this method is most useful when it’s necessary to check or use the event after it has been modified by observers.

pub unsafe fn trigger_dynamic( &mut self, event_key: EventKey, event_data: PtrMut<'_>, trigger_data: PtrMut<'_>, )

Triggers global Observers for event_key with untyped event and trigger data.

Dynamic equivalent of World::trigger. Only fires global observers, not entity- or component-scoped ones.

Use World::trigger_dynamic_targets to also fire entity-scoped observers.

Safety

• event_data must point to a valid, aligned value whose layout matches what observers registered for this event_key expect.
• trigger_data must point to a valid, aligned value whose layout matches what observers registered for this event_key expect.

Examples found in repository

examples/ecs/dynamic.rs (lines 274-278)

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();
    let mut event_names = HashMap::<String, EventKey>::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}"),
                Some('e') => println!("{EVENT_PROMPT}"),
                Some('t') => println!("{EMIT_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,
                            None,
                        )
                    });
                    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_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);
                });
            }
            "e" => {
                rest.split(',').for_each(|event| {
                    let name = event.trim();
                    if name.is_empty() {
                        return;
                    }

                    // Register a ComponentId for this event, no Rust type needed.
                    // SAFETY: ZST with no drop
                    let event_component_id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            format!("event:{name}"),
                            StorageType::Table,
                            Layout::new::<()>(),
                            None,
                            false,
                            ComponentCloneBehavior::Ignore,
                            None,
                        )
                    });
                    // SAFETY: event_component_id was just registered for this event
                    let event_key = unsafe { EventKey::new(event_component_id) };
                    event_names.insert(name.to_string(), event_key);

                    // Build a dynamic observer that prints when the event fires.
                    let runner: ObserverRunner = |mut world, _observer, ctx, _event, _trigger| {
                        println!("  Observer fired!");
                        if let Some(mut counts) = world.get_resource_mut::<EventFireCount>() {
                            *counts.0.entry(ctx.event_key).or_insert(0) += 1;
                        }
                    };

                    // SAFETY: event_key was just registered, runner ignores pointers
                    let observer =
                        unsafe { Observer::with_dynamic_runner(runner).with_event_key(event_key) };
                    world.spawn(observer);

                    println!(
                        "Event '{name}' registered (key: {}) with a dynamic observer",
                        event_component_id.index()
                    );
                });

                // Ensure the counter resource exists.
                world.init_resource::<EventFireCount>();
            }
            "t" => {
                let name = rest.trim();
                let Some(&event_key) = event_names.get(name) else {
                    println!(
                        "Event '{name}' does not exist. Register it first with 'event {name}'"
                    );
                    continue;
                };

                let mut event_data = ();
                let mut trigger_data = ();
                // SAFETY: event_key was registered in this world, both pointers are valid ZSTs
                unsafe {
                    world.trigger_dynamic(
                        event_key,
                        PtrMut::from(&mut event_data),
                        PtrMut::from(&mut trigger_data),
                    );
                }

                let count = world
                    .get_resource::<EventFireCount>()
                    .map_or(0, |c| c.0.get(&event_key).copied().unwrap_or(0));
                println!("Event '{name}' triggered ({count} fires)");
            }
            _ => continue,
        }
    }
}

pub unsafe fn trigger_dynamic_targets( &mut self, event_key: EventKey, entity: Entity, event_data: PtrMut<'_>, trigger_data: PtrMut<'_>, )

Triggers Observers for event_key targeting entity, with untyped event and trigger data.

Fires global and entity-scoped observers. Dynamic equivalent of EntityWorldMut::trigger.

Safety

• event_data must point to a valid, aligned value whose layout matches what observers registered for this event_key expect.
• trigger_data must point to a valid, aligned value whose layout matches what observers registered for this event_key expect.

pub unsafe fn trigger_dynamic_targets_components( &mut self, event_key: EventKey, entity: Entity, components: &[ComponentId], event_data: PtrMut<'_>, trigger_data: PtrMut<'_>, )

Triggers Observers for event_key targeting entity and components, with untyped event and trigger data.

Fires global, entity-scoped, and component-scoped observers. Dynamic equivalent of EntityComponentsTrigger.

Safety

• event_data must point to a valid, aligned value whose layout matches what observers registered for this event_key expect.
• trigger_data must point to a valid, aligned value whose layout matches what observers registered for this event_key expect.

impl World

pub fn register_system<I, O, M>( &mut self, system: impl IntoSystem<I, O, M> + 'static, ) -> SystemId<I, O>

where I: SystemInput + 'static, O: 'static,

Registers a system and returns a SystemId so it can later be called by World::run_system.

It’s possible to register multiple copies of the same system by calling this function multiple times. If that’s not what you want, consider using World::register_system_cached instead.

This is different from adding systems to a Schedule, because the SystemId that is returned can be used anywhere in the World to run the associated system. This allows for running systems in a pushed-based fashion. Using a Schedule is still preferred for most cases due to its better performance and ability to run non-conflicting systems simultaneously.

Examples found in repository

examples/ecs/one_shot_systems.rs (line 51)

fn setup_with_world(world: &mut World) {
    // We can run it once manually
    world.run_system_once(system_b).unwrap();
    // Or with a Callback
    let system_id = world.register_system(system_b);
    world.spawn((Callback(system_id), B));
}

pub fn register_boxed_system<I, O>( &mut self, system: Box<dyn System<In = I, Out = O>>, ) -> SystemId<I, O>

where I: SystemInput + 'static, O: 'static,

Similar to Self::register_system, but allows passing in a BoxedSystem.

This is useful if the IntoSystem implementor has already been turned into a System trait object and put in a Box.

pub fn unregister_system<I, O>( &mut self, id: SystemId<I, O>, ) -> Result<RemovedSystem<I, O>, RegisteredSystemError<I, O>>

where I: SystemInput + 'static, O: 'static,

Removes a registered system and returns the system, if it exists. After removing a system, the SystemId becomes invalid and attempting to use it afterwards will result in errors. Re-adding the removed system will register it on a new SystemId.

If no system corresponds to the given SystemId, this method returns an error. Systems are also not allowed to remove themselves, this returns an error too.

pub fn run_system<O>( &mut self, id: SystemId<(), O>, ) -> Result<O, RegisteredSystemError<(), O>>

where O: 'static,

Run stored systems by their SystemId. Before running a system, it must first be registered. The method World::register_system stores a given system and returns a SystemId. This is different from RunSystemOnce::run_system_once, because it keeps local state between calls and change detection works correctly.

Also runs any queued-up commands.

In order to run a chained system with an input, use World::run_system_with instead.

Examples

Running a system

fn increment(mut counter: Local<u8>) {
   *counter += 1;
   println!("{}", *counter);
}

let mut world = World::default();
let counter_one = world.register_system(increment);
let counter_two = world.register_system(increment);
world.run_system(counter_one); // -> 1
world.run_system(counter_one); // -> 2
world.run_system(counter_two); // -> 1

Change detection

#[derive(Resource, Default)]
struct ChangeDetector;

let mut world = World::default();
world.init_resource::<ChangeDetector>();
let detector = world.register_system(|change_detector: ResMut<ChangeDetector>| {
    if change_detector.is_changed() {
        println!("Something happened!");
    } else {
        println!("Nothing happened.");
    }
});

// Resources are changed when they are first added
let _ = world.run_system(detector); // -> Something happened!
let _ = world.run_system(detector); // -> Nothing happened.
world.resource_mut::<ChangeDetector>().set_changed();
let _ = world.run_system(detector); // -> Something happened!

Getting system output

#[derive(Resource)]
struct PlayerScore(i32);

#[derive(Resource)]
struct OpponentScore(i32);

fn get_player_score(player_score: Res<PlayerScore>) -> i32 {
  player_score.0
}

fn get_opponent_score(opponent_score: Res<OpponentScore>) -> i32 {
  opponent_score.0
}

let mut world = World::default();
world.insert_resource(PlayerScore(3));
world.insert_resource(OpponentScore(2));

let scoring_systems = [
  ("player", world.register_system(get_player_score)),
  ("opponent", world.register_system(get_opponent_score)),
];

for (label, scoring_system) in scoring_systems {
  println!("{label} has score {}", world.run_system(scoring_system).expect("system succeeded"));
}

pub fn run_system_with<I, O>( &mut self, id: SystemId<I, O>, input: <I as SystemInput>::Inner<'_>, ) -> Result<O, RegisteredSystemError<I, O>>

where I: SystemInput + 'static, O: 'static,

Run a stored chained system by its SystemId, providing an input value. Before running a system, it must first be registered. The method World::register_system stores a given system and returns a SystemId.

To use the supplied input, the system should have a SystemInput as the first parameter. Also runs any queued-up commands.

Examples

fn increment(In(increment_by): In<u8>, mut counter: Local<u8>) -> u8 {
  *counter += increment_by;
  *counter
}

let mut world = World::default();
let counter_one = world.register_system(increment);
let counter_two = world.register_system(increment);
assert_eq!(world.run_system_with(counter_one, 1).unwrap(), 1);
assert_eq!(world.run_system_with(counter_one, 20).unwrap(), 21);
assert_eq!(world.run_system_with(counter_two, 30).unwrap(), 30);

See World::run_system for more examples.

pub fn register_system_cached<I, O, M, S>( &mut self, system: S, ) -> SystemId<I, O>

where I: SystemInput + 'static, O: 'static, S: IntoSystem<I, O, M> + 'static,

Registers a system or returns its cached SystemId.

If you want to run the system immediately and you don’t need its SystemId, see World::run_system_cached.

The first time this function is called for a particular system, it will register it and store its SystemId in a CachedSystemId resource for later. If you would rather manage the SystemId yourself, or register multiple copies of the same system, use World::register_system instead.

Limitations

This function only accepts ZST (zero-sized) systems to guarantee that any two systems of the same type must be equal. This means that closures that capture the environment, and function pointers, are not accepted.

If you want to access values from the environment within a system, consider passing them in as inputs via World::run_system_cached_with. If that’s not an option, consider World::register_system instead.

pub fn unregister_system_cached<I, O, M, S>( &mut self, _system: S, ) -> Result<RemovedSystem<I, O>, RegisteredSystemError<I, O>>

where I: SystemInput + 'static, O: 'static, S: IntoSystem<I, O, M> + 'static,

Removes a cached system and its CachedSystemId resource.

See World::register_system_cached for more information.

pub fn run_system_cached<O, M, S>( &mut self, system: S, ) -> Result<O, RegisteredSystemError<(), O>>

where O: 'static, S: IntoSystem<(), O, M> + 'static,

Runs a cached system, registering it if necessary.

See World::register_system_cached for more information.

pub fn run_system_cached_with<I, O, M, S>( &mut self, system: S, input: <I as SystemInput>::Inner<'_>, ) -> Result<O, RegisteredSystemError<I, O>>

where I: SystemInput + 'static, O: 'static, S: IntoSystem<I, O, M> + 'static,

Runs a cached system with an input, registering it if necessary.

To use the supplied input, the system should have a SystemInput as the first parameter. See World::register_system_cached for more information.

impl 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 get_reflect_mut( &mut self, entity: Entity, type_id: TypeId, ) -> Result<Mut<'_, dyn Reflect>, GetComponentReflectError>

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

This is the mutable version of World::get_reflect, see its docs for more information and an example.

Just calling this method does not trigger change detection.

Errors

See GetComponentReflectError for the possible errors and their descriptions.

Example

See the documentation for World::get_reflect.

Note

Requires the feature bevy_reflect (included in the default features).

pub fn insert_reflect_resource( &mut self, resource_id: ComponentId, reflected_resource: Box<dyn PartialReflect>, )

Inserts a reflected resource into the world. If the resource already exists, it is overwritten.

impl World

pub fn new() -> World

Creates a new empty World.

Panics

If usize::MAX Worlds have been created. This guarantee allows System Parameters to safely uniquely identify a World, since its WorldId is unique

Examples found in repository

examples/ecs/custom_executor.rs (line 46)

fn main() {
    let mut world = World::new();
    world.init_resource::<Counter>();

    let mut schedule = Schedule::default();
    schedule.set_executor(CustomExecutor);
    schedule.add_systems((increment, print_counter).chain());

    for _ in 0..5 {
        schedule.run(&mut world);
    }
}

crates/bevy_ecs/examples/resources.rs (line 16)

fn main() {
    // Create a world
    let mut world = World::new();

    // Add the counter resource
    world.insert_resource(Counter { value: 0 });

    // Create a schedule
    let mut schedule = Schedule::default();

    // Add systems to increase the counter and to print out the current value
    schedule.add_systems((increase_counter, print_counter).chain());

    for iteration in 1..=10 {
        println!("Simulating frame {iteration}/10");
        schedule.run(&mut world);
    }
}

crates/bevy_ecs/examples/change_detection.rs (line 21)

fn main() {
    // Create a new empty World to hold our Entities, Components and Resources
    let mut world = World::new();

    // Add the counter resource to remember how many entities where spawned
    world.insert_resource(EntityCounter { value: 0 });

    // Create a new Schedule, which stores systems and controls their relative ordering
    let mut schedule = Schedule::default();

    // Add systems to the Schedule to execute our app logic
    // We can label our systems to force a specific run-order between some of them
    schedule.add_systems((
        spawn_entities.in_set(SimulationSystems::Spawn),
        print_counter_when_changed.after(SimulationSystems::Spawn),
        age_all_entities.in_set(SimulationSystems::Age),
        remove_old_entities.after(SimulationSystems::Age),
        print_changed_entities.after(SimulationSystems::Age),
    ));

    // Simulate 10 frames in our world
    for iteration in 1..=10 {
        println!("Simulating frame {iteration}/10");
        schedule.run(&mut world);
    }
}

crates/bevy_ecs/examples/events.rs (line 10)

fn main() {
    // Create a new empty world.
    let mut world = World::new();
    // The message registry is stored as a resource, and allows us to quickly update all messages at once.
    // This call adds both the registry resource and the `Messages` resource into the world.
    MessageRegistry::register_message::<MyMessage>(&mut world);

    // Create a schedule to store our systems
    let mut schedule = Schedule::default();

    // Messages need to be updated every frame in order to clear our buffers.
    // This update should happen before we use the messages.
    // Here, we use system sets to control the ordering.
    #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
    pub struct EventFlusherSystems;

    schedule.add_systems(bevy_ecs::message::message_update_system.in_set(EventFlusherSystems));

    // Add systems sending and receiving messages after the messages are flushed.
    schedule.add_systems((
        sending_system.after(EventFlusherSystems),
        receiving_system.after(sending_system),
    ));

    // Simulate 10 frames of our world
    for iteration in 1..=10 {
        println!("Simulating frame {iteration}/10");
        schedule.run(&mut world);
    }
}

examples/scene/world_serialization.rs (line 175)

fn save_world_system(world: &mut World) {
    let asset_server = world.resource::<AssetServer>().clone();
    // The `TypeRegistry` resource contains information about all registered types (including components).
    // This is used to construct worlds, so we'll want to ensure that we use the registry from the
    // main world. To do this, we can simply clone the `AppTypeRegistry` resource.
    let type_registry = world.resource::<AppTypeRegistry>().clone();

    // Any ECS World can be serialized.
    // For demonstration purposes, we'll create a new one.
    let mut scene_world = World::new();

    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"),
        WorldAssetRoot(asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0")),
    ));
    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 a DynamicWorld from it.
    // For simplicity, we will create our scene using DynamicWorld directly, but if
    // you need more control, you can use DynamicWorldBuilder.
    let dynamic_world = DynamicWorld::from_world_with(&scene_world, &type_registry.read());

    // Dynamic Worlds can be serialized like this:
    let type_registry = world.resource::<AppTypeRegistry>();
    let type_registry = type_registry.read();
    let serialized_world = dynamic_world.serialize(&type_registry).unwrap();

    // Shows the serialized world in the console
    info!("{}", serialized_world);

    // Writing the world 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 world RON data to file
            File::create(format!("assets/{NEW_WORLD_FILE_PATH}"))
                .and_then(|mut file| file.write(serialized_world.as_bytes()))
                .expect("Error while writing world to file");
        })
        .detach();
}

examples/ecs/relationships.rs (line 39)

fn main() {
    // Operating on a raw `World` and running systems one at a time
    // is great for writing tests and teaching abstract concepts!
    let mut world = World::new();

    // We're going to spawn a few entities and relate them to each other in a complex way.
    // To start, Bob will target Alice, Charlie will target Bob,
    // and Alice will target Charlie. This creates a loop in the relationship graph.
    //
    // Then, we'll spawn Devon, who will target Charlie,
    // creating a more complex graph with a branching structure.
    fn spawning_entities_with_relationships(mut commands: Commands) {
        // Calling .id() after spawning an entity will return the `Entity` identifier of the spawned entity,
        // even though the entity itself is not yet instantiated in the world.
        // This works because Commands will reserve the entity ID before actually spawning the entity,
        // through the use of atomic counters.
        let alice = commands.spawn(Name::new("Alice")).id();
        // Relations are just components, so we can add them into the bundle that we're spawning.
        let bob = commands.spawn((Name::new("Bob"), Targeting(alice))).id();

        // The `with_related` and `with_related_entities` helper methods on `EntityCommands` can be used to add relations in a more ergonomic way.
        let charlie = commands
            .spawn((Name::new("Charlie"), Targeting(bob)))
            // The `with_related` method will spawn a bundle with `Targeting` relationship
            .with_related::<Targeting>(Name::new("James"))
            // The `with_related_entities` method will automatically add the `Targeting` component to any entities spawned within the closure,
            // targeting the entity that we're calling `with_related` on.
            .with_related_entities::<Targeting>(|related_spawner_commands| {
                // We could spawn multiple entities here, and they would all target `charlie`.
                related_spawner_commands.spawn(Name::new("Devon"));
            })
            .id();

        // Simply inserting the `Targeting` component will automatically create and update the `TargetedBy` component on the target entity.
        // We can do this at any point; not just when the entity is spawned.
        commands.entity(alice).insert(Targeting(charlie));
    }

    world
        .run_system_once(spawning_entities_with_relationships)
        .unwrap();

    fn debug_relationships(
        // Not all of our entities are targeted by something, so we use `Option` in our query to handle this case.
        relations_query: Query<(&Name, &Targeting, Option<&TargetedBy>)>,
        name_query: Query<&Name>,
    ) {
        let mut relationships = String::new();

        for (name, targeting, maybe_targeted_by) in relations_query.iter() {
            let targeting_name = name_query.get(targeting.0).unwrap();
            let targeted_by_string = if let Some(targeted_by) = maybe_targeted_by {
                let mut vec_of_names = Vec::<&Name>::new();

                for entity in targeted_by.iter() {
                    let name = name_query.get(entity).unwrap();
                    vec_of_names.push(name);
                }

                // Convert this to a nice string for printing.
                let vec_of_str: Vec<&str> = vec_of_names.iter().map(|name| name.as_str()).collect();
                vec_of_str.join(", ")
            } else {
                "nobody".to_string()
            };

            relationships.push_str(&format!(
                "{name} is targeting {targeting_name}, and is targeted by {targeted_by_string}\n",
            ));
        }

        println!("{relationships}");
    }

    world.run_system_once(debug_relationships).unwrap();

    // Demonstrates how to correctly mutate relationships.
    // Relationship components are immutable! We can't query for the `Targeting` component mutably and modify it directly,
    // but we can insert a new `Targeting` component to replace the old one.
    // This allows the hooks on the `Targeting` component to update the `TargetedBy` component correctly.
    // The `TargetedBy` component will be updated automatically!
    fn mutate_relationships(name_query: Query<(Entity, &Name)>, mut commands: Commands) {
        // Let's find Devon by doing a linear scan of the entity names.
        let devon = name_query
            .iter()
            .find(|(_entity, name)| name.as_str() == "Devon")
            .unwrap()
            .0;

        let alice = name_query
            .iter()
            .find(|(_entity, name)| name.as_str() == "Alice")
            .unwrap()
            .0;

        println!("Making Devon target Alice.\n");
        commands.entity(devon).insert(Targeting(alice));
    }

    world.run_system_once(mutate_relationships).unwrap();
    world.run_system_once(debug_relationships).unwrap();

    // Systems can return errors,
    // which can be used to signal that something went wrong during the system's execution.
    #[derive(Debug)]
    #[expect(
        dead_code,
        reason = "Rust considers types that are only used by their debug trait as dead code."
    )]
    struct TargetingCycle {
        initial_entity: Entity,
        visited: EntityHashSet,
    }

    /// Bevy's relationships come with all sorts of useful methods for traversal.
    /// Here, we're going to look for cycles using a depth-first search.
    fn check_for_cycles(
        // We want to check every entity for cycles
        query_to_check: Query<Entity, With<Targeting>>,
        // Fetch the names for easier debugging.
        name_query: Query<&Name>,
        // The targeting_query allows us to traverse the relationship graph.
        targeting_query: Query<&Targeting>,
    ) -> Result<(), TargetingCycle> {
        for initial_entity in query_to_check.iter() {
            let mut visited = EntityHashSet::new();
            let mut targeting_name = name_query.get(initial_entity).unwrap().clone();
            println!("Checking for cycles starting at {targeting_name}",);

            // There's all sorts of methods like this; check the `Query` docs for more!
            // This would also be easy to do by just manually checking the `Targeting` component,
            // and calling `query.get(targeted_entity)` on the entity that it targets in a loop.
            for targeting in targeting_query.iter_ancestors(initial_entity) {
                let target_name = name_query.get(targeting).unwrap();
                println!("{targeting_name} is targeting {target_name}",);
                targeting_name = target_name.clone();

                if !visited.insert(targeting) {
                    return Err(TargetingCycle {
                        initial_entity,
                        visited,
                    });
                }
            }
        }

        // If we've checked all the entities and haven't found a cycle, we're good!
        Ok(())
    }

    // Calling `world.run_system_once` on systems which return Results gives us two layers of errors:
    // the first checks if running the system failed, and the second checks if the system itself returned an error.
    // We're unwrapping the first, but checking the output of the system itself.
    let cycle_result = world.run_system_once(check_for_cycles).unwrap();
    println!("{cycle_result:?} \n");
    // We deliberately introduced a cycle during spawning!
    assert!(cycle_result.is_err());

    // Now, let's demonstrate removing relationships and break the cycle.
    fn untarget(mut commands: Commands, name_query: Query<(Entity, &Name)>) {
        // Let's find Charlie by doing a linear scan of the entity names.
        let charlie = name_query
            .iter()
            .find(|(_entity, name)| name.as_str() == "Charlie")
            .unwrap()
            .0;

        // We can remove the `Targeting` component to remove the relationship
        // and break the cycle we saw earlier.
        println!("Removing Charlie's targeting relationship.\n");
        commands.entity(charlie).remove::<Targeting>();
    }

    world.run_system_once(untarget).unwrap();
    world.run_system_once(debug_relationships).unwrap();
    // Cycle free!
    let cycle_result = world.run_system_once(check_for_cycles).unwrap();
    println!("{cycle_result:?} \n");
    assert!(cycle_result.is_ok());
}

Additional examples can be found in:

• examples/ecs/dynamic.rs

pub fn id(&self) -> WorldId

Retrieves this World’s unique ID

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

Creates a new UnsafeWorldCell view with complete read+write access.

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.

Examples found in repository

examples/ecs/callbacks.rs (line 37)

fn setup_callbacks(mut commands: Commands) {
    let trivial_callback = Callback {
        system_id: commands.register_system(|| {
            println!("This is the trivial callback system");
        }),
    };

    let ordinary_system_callback = Callback {
        system_id: commands.register_system(|query: Query<&Callback>| {
            let n_callbacks = query.iter().len();
            println!("This is the ordinary callback system. There are currently {n_callbacks} callbacks in the world.");
        }),
    };

    let exclusive_callback = Callback {
        system_id: commands.register_system(|world: &mut World| {
            let n_entities = world.entities().len();
            println!("This is the exclusive callback system. There are currently {n_entities} entities in the world.");
        }),
    };

    commands.spawn(trivial_callback);
    commands.spawn(ordinary_system_callback);
    commands.spawn(exclusive_callback);
}

pub fn entity_allocator(&self) -> &EntityAllocator

Retrieves this world’s EntityAllocator collection.

pub fn entity_allocator_mut(&mut self) -> &mut EntityAllocator

Retrieves this world’s EntityAllocator collection mutably.

pub unsafe fn entities_mut(&mut self) -> &mut Entities

Retrieves this world’s Entities collection mutably.

Safety

Mutable reference must not be used to put the Entities data in an invalid state for this World

pub fn entity_count(&self) -> u32

Retrieves the number of Entities in the world.

This is helpful as a diagnostic, but it can also be used effectively in tests.

pub fn archetypes(&self) -> &Archetypes

Retrieves this world’s Archetypes collection.

pub fn components(&self) -> &Components

Retrieves this world’s Components collection.

Examples found in repository

examples/ecs/dynamic.rs (line 124)

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();
    let mut event_names = HashMap::<String, EventKey>::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}"),
                Some('e') => println!("{EVENT_PROMPT}"),
                Some('t') => println!("{EMIT_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,
                            None,
                        )
                    });
                    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_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);
                });
            }
            "e" => {
                rest.split(',').for_each(|event| {
                    let name = event.trim();
                    if name.is_empty() {
                        return;
                    }

                    // Register a ComponentId for this event, no Rust type needed.
                    // SAFETY: ZST with no drop
                    let event_component_id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            format!("event:{name}"),
                            StorageType::Table,
                            Layout::new::<()>(),
                            None,
                            false,
                            ComponentCloneBehavior::Ignore,
                            None,
                        )
                    });
                    // SAFETY: event_component_id was just registered for this event
                    let event_key = unsafe { EventKey::new(event_component_id) };
                    event_names.insert(name.to_string(), event_key);

                    // Build a dynamic observer that prints when the event fires.
                    let runner: ObserverRunner = |mut world, _observer, ctx, _event, _trigger| {
                        println!("  Observer fired!");
                        if let Some(mut counts) = world.get_resource_mut::<EventFireCount>() {
                            *counts.0.entry(ctx.event_key).or_insert(0) += 1;
                        }
                    };

                    // SAFETY: event_key was just registered, runner ignores pointers
                    let observer =
                        unsafe { Observer::with_dynamic_runner(runner).with_event_key(event_key) };
                    world.spawn(observer);

                    println!(
                        "Event '{name}' registered (key: {}) with a dynamic observer",
                        event_component_id.index()
                    );
                });

                // Ensure the counter resource exists.
                world.init_resource::<EventFireCount>();
            }
            "t" => {
                let name = rest.trim();
                let Some(&event_key) = event_names.get(name) else {
                    println!(
                        "Event '{name}' does not exist. Register it first with 'event {name}'"
                    );
                    continue;
                };

                let mut event_data = ();
                let mut trigger_data = ();
                // SAFETY: event_key was registered in this world, both pointers are valid ZSTs
                unsafe {
                    world.trigger_dynamic(
                        event_key,
                        PtrMut::from(&mut event_data),
                        PtrMut::from(&mut trigger_data),
                    );
                }

                let count = world
                    .get_resource::<EventFireCount>()
                    .map_or(0, |c| c.0.get(&event_key).copied().unwrap_or(0));
                println!("Event '{name}' triggered ({count} fires)");
            }
            _ => continue,
        }
    }
}

pub fn resource_entities(&self) -> &ResourceEntities

Retrieves this world’s ResourceEntities.

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 components_registrator(&mut self) -> ComponentsRegistrator<'_>

Prepares a ComponentsRegistrator for the world.

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

Retrieves this world’s RemovedComponentMessages collection

pub fn observers(&self) -> &Observers

Retrieves this world’s Observers list

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

Creates a new Commands instance that writes to the world’s command queue Use World::flush to apply all queued commands

pub fn register_component<T>(&mut self) -> ComponentId

where T: Component,

Registers a new Component type and returns the ComponentId created for it.

Usage Notes

In most cases, you don’t need to call this method directly since component registration happens automatically during system initialization.

pub fn register_disabling_component<C>(&mut self)

where C: Component,

Registers a component type as “disabling”, using default query filters to exclude entities with the component from queries.

pub fn register_component_hooks<T>(&mut self) -> &mut ComponentHooks

where T: Component,

Returns a mutable reference to the ComponentHooks for a Component type.

Will panic if T exists in any archetypes.

Examples found in repository

examples/ecs/component_hooks.rs (line 67)

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_discard` 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 messages
                world.write_message(MyMessage);
            },
        )
        // `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_discard` 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_discard(|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 register_component_hooks_by_id( &mut self, id: ComponentId, ) -> Option<&mut ComponentHooks>

Returns a mutable reference to the ComponentHooks for a Component with the given id if it exists.

Will panic if id exists in any archetypes.

pub fn register_required_components<T, R>(&mut self)

where T: Component, R: Component + Default,

Registers the given component R as a required component for T.

When T is added to an entity, R and its own required components will also be added if R was not already provided. The Default constructor will be used for the creation of R. If a custom constructor is desired, use World::register_required_components_with instead.

For the non-panicking version, see World::try_register_required_components.

Note that requirements must currently be registered before T is inserted into the world for the first time. This limitation may be fixed in the future.

Panics

Panics if R is already a directly required component for T, or if T has ever been added on an entity before the registration.

Indirect requirements through other components are allowed. In those cases, any existing requirements will only be overwritten if the new requirement is more specific.

Example

#[derive(Component)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct B(usize);

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct C(u32);

// Register B as required by A and C as required by B.
world.register_required_components::<A, B>();
world.register_required_components::<B, C>();

// This will implicitly also insert B and C with their Default constructors.
let id = world.spawn(A).id();
assert_eq!(&B(0), world.entity(id).get::<B>().unwrap());
assert_eq!(&C(0), world.entity(id).get::<C>().unwrap());

pub fn register_required_components_with<T, R>( &mut self, constructor: fn() -> R, )

where T: Component, R: Component,

Registers the given component R as a required component for T.

When T is added to an entity, R and its own required components will also be added if R was not already provided. The given constructor will be used for the creation of R. If a Default constructor is desired, use World::register_required_components instead.

For the non-panicking version, see World::try_register_required_components_with.

Note that requirements must currently be registered before T is inserted into the world for the first time. This limitation may be fixed in the future.

Panics

Panics if R is already a directly required component for T, or if T has ever been added on an entity before the registration.

Indirect requirements through other components are allowed. In those cases, any existing requirements will only be overwritten if the new requirement is more specific.

Example

#[derive(Component)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct B(usize);

#[derive(Component, PartialEq, Eq, Debug)]
struct C(u32);

// Register B and C as required by A and C as required by B.
// A requiring C directly will overwrite the indirect requirement through B.
world.register_required_components::<A, B>();
world.register_required_components_with::<B, C>(|| C(1));
world.register_required_components_with::<A, C>(|| C(2));

// This will implicitly also insert B with its Default constructor and C
// with the custom constructor defined by A.
let id = world.spawn(A).id();
assert_eq!(&B(0), world.entity(id).get::<B>().unwrap());
assert_eq!(&C(2), world.entity(id).get::<C>().unwrap());

pub fn try_register_required_components<T, R>( &mut self, ) -> Result<(), RequiredComponentsError>

where T: Component, R: Component + Default,

Tries to register the given component R as a required component for T.

When T is added to an entity, R and its own required components will also be added if R was not already provided. The Default constructor will be used for the creation of R. If a custom constructor is desired, use World::register_required_components_with instead.

For the panicking version, see World::register_required_components.

Note that requirements must currently be registered before T is inserted into the world for the first time. This limitation may be fixed in the future.

Errors

Returns a RequiredComponentsError if R is already a directly required component for T, or if T has ever been added on an entity before the registration.

Indirect requirements through other components are allowed. In those cases, any existing requirements will only be overwritten if the new requirement is more specific.

Example

#[derive(Component)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct B(usize);

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct C(u32);

// Register B as required by A and C as required by B.
world.register_required_components::<A, B>();
world.register_required_components::<B, C>();

// Duplicate registration! This will fail.
assert!(world.try_register_required_components::<A, B>().is_err());

// This will implicitly also insert B and C with their Default constructors.
let id = world.spawn(A).id();
assert_eq!(&B(0), world.entity(id).get::<B>().unwrap());
assert_eq!(&C(0), world.entity(id).get::<C>().unwrap());

pub fn try_register_required_components_with<T, R>( &mut self, constructor: fn() -> R, ) -> Result<(), RequiredComponentsError>

where T: Component, R: Component,

Tries to register the given component R as a required component for T.

When T is added to an entity, R and its own required components will also be added if R was not already provided. The given constructor will be used for the creation of R. If a Default constructor is desired, use World::register_required_components instead.

For the panicking version, see World::register_required_components_with.

Note that requirements must currently be registered before T is inserted into the world for the first time. This limitation may be fixed in the future.

Errors

Returns a RequiredComponentsError if R is already a directly required component for T, or if T has ever been added on an entity before the registration.

Indirect requirements through other components are allowed. In those cases, any existing requirements will only be overwritten if the new requirement is more specific.

Example

#[derive(Component)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct B(usize);

#[derive(Component, PartialEq, Eq, Debug)]
struct C(u32);

// Register B and C as required by A and C as required by B.
// A requiring C directly will overwrite the indirect requirement through B.
world.register_required_components::<A, B>();
world.register_required_components_with::<B, C>(|| C(1));
world.register_required_components_with::<A, C>(|| C(2));

// Duplicate registration! Even if the constructors were different, this would fail.
assert!(world.try_register_required_components_with::<B, C>(|| C(1)).is_err());

// This will implicitly also insert B with its Default constructor and C
// with the custom constructor defined by A.
let id = world.spawn(A).id();
assert_eq!(&B(0), world.entity(id).get::<B>().unwrap());
assert_eq!(&C(2), world.entity(id).get::<C>().unwrap());

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 register_component_with_descriptor( &mut self, descriptor: ComponentDescriptor, ) -> ComponentId

Registers a new Component type and returns the ComponentId created for it.

This method differs from World::register_component in that it uses a ComponentDescriptor to register the new component type instead of statically available type information. This enables the dynamic registration of new component definitions at runtime for advanced use cases.

While the option to register a component from a descriptor is useful in type-erased contexts, the standard World::register_component function should always be used instead when type information is available at compile time.

Examples found in repository

examples/ecs/immutable_components.rs (line 164)

fn demo_3(world: &mut World) {
    // This is a list of dynamic components we will create.
    // The first item is the name of the component, and the second is the size
    // in bytes.
    let my_dynamic_components = [("Foo", 1), ("Bar", 2), ("Baz", 4)];

    // This pipeline takes our component descriptions, registers them, and gets
    // their ComponentId's.
    let my_registered_components = my_dynamic_components
        .into_iter()
        .map(|(name, size)| {
            // SAFETY:
            // - No drop command is required
            // - The component will store [u8; size], which is Send + Sync
            let descriptor = unsafe {
                ComponentDescriptor::new_with_layout(
                    name.to_string(),
                    StorageType::Table,
                    Layout::array::<u8>(size).unwrap(),
                    None,
                    false,
                    ComponentCloneBehavior::Default,
                    None,
                )
            };

            (name, size, descriptor)
        })
        .map(|(name, size, descriptor)| {
            let component_id = world.register_component_with_descriptor(descriptor);

            (name, size, component_id)
        })
        .collect::<Vec<(&str, usize, ComponentId)>>();

    // Now that our components are registered, let's add them to an entity
    let mut entity = world.spawn_empty();

    for (_name, size, component_id) in &my_registered_components {
        // We're just storing some zeroes for the sake of demonstration.
        let data = core::iter::repeat_n(0, *size).collect::<Vec<u8>>();

        OwningPtr::make(data, |ptr| {
            // SAFETY:
            // - ComponentId has been taken from the same world
            // - Array is created to the layout specified in the world
            unsafe {
                entity.insert_by_id(*component_id, ptr);
            }
        });
    }

    for (_name, _size, component_id) in &my_registered_components {
        // With immutable components, we can read the values...
        assert!(entity.get_by_id(*component_id).is_ok());

        // ...but we cannot gain a mutable reference.
        assert!(entity.get_mut_by_id(*component_id).is_err());

        // Instead, you must either remove or replace the value.
    }
}

examples/stress_tests/many_components.rs (lines 86-101)

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,
                        None,
                    )
                },
            )
        })
        .collect();

    // fill the schedule with systems
    let mut schedule = Schedule::new(Update);
    for _ in 1..=num_systems {
        let num_access_components = rng.random_range(1..10);
        let access_components: Vec<ComponentId> = component_ids
            .sample(&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.random_range(1..10);
        let components: Vec<ComponentId> = component_ids
            .sample(&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.random_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());
        }
    }

    // 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(HashSet::from_iter([
            DiagnosticPath::new("fps"),
        ])));
    app.run();
}

examples/ecs/dynamic.rs (lines 113-123)

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();
    let mut event_names = HashMap::<String, EventKey>::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}"),
                Some('e') => println!("{EVENT_PROMPT}"),
                Some('t') => println!("{EMIT_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,
                            None,
                        )
                    });
                    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_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);
                });
            }
            "e" => {
                rest.split(',').for_each(|event| {
                    let name = event.trim();
                    if name.is_empty() {
                        return;
                    }

                    // Register a ComponentId for this event, no Rust type needed.
                    // SAFETY: ZST with no drop
                    let event_component_id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            format!("event:{name}"),
                            StorageType::Table,
                            Layout::new::<()>(),
                            None,
                            false,
                            ComponentCloneBehavior::Ignore,
                            None,
                        )
                    });
                    // SAFETY: event_component_id was just registered for this event
                    let event_key = unsafe { EventKey::new(event_component_id) };
                    event_names.insert(name.to_string(), event_key);

                    // Build a dynamic observer that prints when the event fires.
                    let runner: ObserverRunner = |mut world, _observer, ctx, _event, _trigger| {
                        println!("  Observer fired!");
                        if let Some(mut counts) = world.get_resource_mut::<EventFireCount>() {
                            *counts.0.entry(ctx.event_key).or_insert(0) += 1;
                        }
                    };

                    // SAFETY: event_key was just registered, runner ignores pointers
                    let observer =
                        unsafe { Observer::with_dynamic_runner(runner).with_event_key(event_key) };
                    world.spawn(observer);

                    println!(
                        "Event '{name}' registered (key: {}) with a dynamic observer",
                        event_component_id.index()
                    );
                });

                // Ensure the counter resource exists.
                world.init_resource::<EventFireCount>();
            }
            "t" => {
                let name = rest.trim();
                let Some(&event_key) = event_names.get(name) else {
                    println!(
                        "Event '{name}' does not exist. Register it first with 'event {name}'"
                    );
                    continue;
                };

                let mut event_data = ();
                let mut trigger_data = ();
                // SAFETY: event_key was registered in this world, both pointers are valid ZSTs
                unsafe {
                    world.trigger_dynamic(
                        event_key,
                        PtrMut::from(&mut event_data),
                        PtrMut::from(&mut trigger_data),
                    );
                }

                let count = world
                    .get_resource::<EventFireCount>()
                    .map_or(0, |c| c.0.get(&event_key).copied().unwrap_or(0));
                println!("Event '{name}' triggered ({count} fires)");
            }
            _ => continue,
        }
    }
}

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

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

pub fn register_resource<R>(&mut self) -> ComponentId

where R: Resource,

Registers a new Resource type and returns the ComponentId created for it.

The Resource doesn’t have a value in the World, it’s only registered. If you want to insert the Resource in the World, use World::init_resource or World::insert_resource instead.

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

where T: Resource,

👎Deprecated since 0.19.0:

use component_id

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

fn on_insert_name(mut world: DeferredWorld<'_>, HookContext { entity, .. }: HookContext) {
    let Some(&name) = world.entity(entity).get::<Name>() else {
        unreachable!("Insert 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_discard_name(mut world: DeferredWorld<'_>, HookContext { entity, .. }: HookContext) {
    let Some(&name) = world.entity(entity).get::<Name>() else {
        unreachable!("Discard 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 entity_mut<F>(&mut self, entities: F) -> <F as WorldEntityFetch>::Mut<'_>

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 World::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 EntityWorldMut.
  • This reference type allows for structural changes to the entity, such as adding or removing components, or despawning the entity.
• Pass a slice of Entitys to receive a Vec<EntityMut>.
• Pass an array of Entitys to receive an equally-sized array of EntityMuts.
• Pass a reference to a EntityHashSet to receive an EntityHashMap<EntityMut>.

In order to perform structural changes on the returned entity reference, such as adding or removing components, or despawning the entity, only a single Entity can be passed to this function. Allowing multiple entities at the same time with structural access would lead to undefined behavior, so EntityMut is returned when requesting multiple entities.

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 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);
entity_mut.despawn();

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

Examples found in repository

examples/ecs/immutable_components.rs (line 118)

fn demo_2(world: &mut World) {
    // Setup our name index
    world.init_resource::<NameIndex>();

    // Spawn some entities!
    let alyssa = world.spawn(Name("Alyssa")).id();
    let javier = world.spawn(Name("Javier")).id();

    // Check our index
    let index = world.resource::<NameIndex>();

    assert_eq!(index.get_entity("Alyssa"), Some(alyssa));
    assert_eq!(index.get_entity("Javier"), Some(javier));

    // Changing the name of an entity is also fully capture by our index
    world.entity_mut(javier).insert(Name("Steven"));

    // Javier changed their name to Steven
    let steven = javier;

    // Check our index
    let index = world.resource::<NameIndex>();

    assert_eq!(index.get_entity("Javier"), None);
    assert_eq!(index.get_entity("Steven"), Some(steven));
}

examples/gltf/gltf_extension_animation_graph.rs (line 278)

    fn on_scene_completed(
        &mut self,
        load_context: &mut LoadContext<'_>,
        _scene: &gltf::Scene,
        _world_root_id: Entity,
        world: &mut World,
    ) {
        // Create an AnimationGraph from the desired clip
        let (graph, index) = AnimationGraph::from_clip(self.clip.clone().unwrap());
        // Store the animation graph as an asset with an arbitrary label
        // We only have one graph, so this label will be unique
        let graph_handle =
            load_context.add_labeled_asset("MyAnimationGraphLabel".to_string(), graph);

        // Create a component that stores a reference to our animation
        let animation_to_play = AnimationToPlay {
            graph_handle,
            index,
        };

        // Insert the `AnimationToPlay` component on the first animation root
        let mut entity = world.entity_mut(*self.animation_root_entities.iter().next().unwrap());
        entity.insert(animation_to_play);
    }

examples/async_tasks/async_compute.rs (line 100)

fn spawn_tasks(mut commands: Commands) {
    let thread_pool = AsyncComputeTaskPool::get();
    for x in 0..NUM_CUBES {
        for y in 0..NUM_CUBES {
            for z in 0..NUM_CUBES {
                // Spawn new task on the AsyncComputeTaskPool; the task will be
                // executed in the background, and the Task future returned by
                // spawn() can be used to poll for the result
                let entity = commands.spawn_empty().id();
                let task = thread_pool.spawn(async move {
                    let duration = Duration::from_secs_f32(rand::rng().random_range(0.05..5.0));

                    // Pretend this is a time-intensive function. :)
                    Delay::new(duration).await;

                    // Such hard work, all done!
                    let transform = Transform::from_xyz(x as f32, y as f32, z as f32);
                    let mut command_queue = CommandQueue::default();

                    // we use a raw command queue to pass a FnOnce(&mut World) back to be
                    // applied in a deferred manner.
                    command_queue.push(move |world: &mut World| {
                        let (box_mesh_handle, box_material_handle) = {
                            let mut system_state = SystemState::<(
                                Res<BoxMeshHandle>,
                                Res<BoxMaterialHandle>,
                            )>::new(world);
                            let (box_mesh_handle, box_material_handle) =
                                system_state.get_mut(world).unwrap();

                            (box_mesh_handle.clone(), box_material_handle.clone())
                        };

                        world
                            .entity_mut(entity)
                            // Add our new `Mesh3d` and `MeshMaterial3d` to our tagged entity
                            .insert((
                                Mesh3d(box_mesh_handle),
                                MeshMaterial3d(box_material_handle),
                                transform,
                            ));
                    });

                    command_queue
                });

                // Add our new task as a component
                commands.entity(entity).insert(ComputeTransform(task));
            }
        }
    }
}

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

Returns the components of an Entity through ComponentInfo.

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

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

Examples

For examples, see World::entity.

pub fn get_entity_mut<F>( &mut self, entities: F, ) -> Result<<F as WorldEntityFetch>::Mut<'_>, 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 EntityWorldMut.
  • This reference type allows for structural changes to the entity, such as adding or removing components, or despawning the entity.
• Pass a slice of Entitys to receive a Vec<EntityMut>.
• Pass an array of Entitys to receive an equally-sized array of EntityMuts.
• Pass a reference to a EntityHashSet to receive an EntityHashMap<EntityMut>.

In order to perform structural changes on the returned entity reference, such as adding or removing components, or despawning the entity, only a single Entity can be passed to this function. Allowing multiple entities at the same time with structural access would lead to undefined behavior, so EntityMut is returned when requesting multiple entities.

Errors

• Returns EntityMutableFetchError::NotSpawned 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 World::entity_mut.

Examples found in repository

examples/no_std/library/src/lib.rs (line 129)

fn unwrap<B: Bundle>(event: On<Unwrap>, world: &mut World) {
    if let Ok(mut target) = world.get_entity_mut(event.event_target())
        && let Some(DelayedComponent(bundle)) = target.take::<DelayedComponent<B>>()
    {
        target.insert(bundle);
    }

    world.despawn(event.observer());
}

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 immutable access to the World. If you have mutable access to the World, use query()::<EntityRef>().iter(&world) instead.

Note that this does iterate through all entities, including resource entities.

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 DeferredWorld::entities_and_commands for the deferred version.

Example

#[derive(Component)]
struct Targets(Vec<Entity>);
#[derive(Component)]
struct TargetedBy(Entity);

let mut world: World = // ...
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 spawn_at<B>( &mut self, entity: Entity, bundle: B, ) -> Result<EntityWorldMut<'_>, SpawnError>

where B: Bundle,

Spawns the bundle on the valid but not spawned entity. If the entity can not be spawned for any reason, returns an error.

If it succeeds, this declares the entity to have this bundle.

In general, you should prefer spawn. Spawn internally calls this method, but it takes care of finding a suitable Entity for you. This is made available for advanced use, which you can see at EntityAllocator::alloc.

Risk

It is possible to spawn an entity that has not been allocated yet; however, doing so is currently a bad idea as the allocator may hand out this entity index in the future, assuming it to be not spawned. This would cause a panic.

Manual spawning is a powerful tool, but must be used carefully.

Example

Currently, this is primarily used to spawn entities that come from EntityAllocator::alloc. See that for an example.

pub fn spawn_empty_at( &mut self, entity: Entity, ) -> Result<EntityWorldMut<'_>, SpawnError>

A faster version of spawn_at for the empty bundle.

Examples found in repository

examples/ecs/error_handling.rs (line 164)

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")
        // The default error severity is Severity::Panic.
        // We can add a Severity level to any Result locally to downgrade it appropriately.
        .with_severity(Severity::Warning)?;

    world
        // This entity doesn't exist!
        .spawn_empty_at(Entity::from_raw_u32(12345678).unwrap())
        .map_severity(|e| match e {
            // Not that concerning, we just need to make sure to find a different entity
            SpawnError::AlreadySpawned => Severity::Debug,
            // Oh no
            SpawnError::Invalid(_) => Severity::Error,
        })?;

    Ok(())
}

pub fn spawn<B>(&mut self, bundle: B) -> EntityWorldMut<'_>

where B: Bundle,

Spawns a new Entity with a given Bundle of components and returns a corresponding EntityWorldMut, which can be used to add components to the entity or retrieve its id. In case large batches of entities need to be spawned, consider using World::spawn_batch instead.

use bevy_ecs::{bundle::Bundle, component::Component, world::World};

#[derive(Component)]
struct Position {
  x: f32,
  y: f32,
}

#[derive(Component)]
struct Velocity {
    x: f32,
    y: f32,
};

#[derive(Component)]
struct Name(&'static str);

#[derive(Bundle)]
struct PhysicsBundle {
    position: Position,
    velocity: Velocity,
}

let mut world = World::new();

// `spawn` can accept a single component:
world.spawn(Position { x: 0.0, y: 0.0 });

// It can also accept a tuple of components:
world.spawn((
    Position { x: 0.0, y: 0.0 },
    Velocity { x: 1.0, y: 1.0 },
));

// Or it can accept a pre-defined Bundle of components:
world.spawn(PhysicsBundle {
    position: Position { x: 2.0, y: 2.0 },
    velocity: Velocity { x: 0.0, y: 4.0 },
});

let entity = world
    // Tuples can also mix Bundles and Components
    .spawn((
        PhysicsBundle {
            position: Position { x: 2.0, y: 2.0 },
            velocity: Velocity { x: 0.0, y: 4.0 },
        },
        Name("Elaina Proctor"),
    ))
    // Calling id() will return the unique identifier for the spawned entity
    .id();
let position = world.entity(entity).get::<Position>().unwrap();
assert_eq!(position.x, 2.0);

Examples found in repository

examples/app/externally_driven_headless_renderer.rs (line 100)

    fn spawn_camera(&mut self, target: RenderTarget) -> Entity {
        self.0
            .main
            .world_mut()
            .spawn((Camera3d::default(), target, Transform::IDENTITY))
            .id()
    }

    // Run one world update and wait for rendering to finish.
    fn update(&mut self) {
        self.0.update();
        // Wait for frame to finish rendering by wait polling the device
        self.0
            .main
            .world()
            .resource::<RenderDevice>()
            .wgpu_device()
            .poll(PollType::Wait {
                submission_index: None,
                timeout: None,
            })
            .unwrap();
    }

    // Schedules a screenshot to be captured on the next update.
    fn screenshot(&mut self, target: RenderTarget, i: u32) {
        self.0
            .main
            .world_mut()
            .spawn(Screenshot::image(target.as_image().unwrap().clone()))
            .observe(save_to_disk(format!("test_images/screenshot{i}.png")));
    }

examples/ecs/one_shot_systems.rs (line 52)

fn setup_with_world(world: &mut World) {
    // We can run it once manually
    world.run_system_once(system_b).unwrap();
    // Or with a Callback
    let system_id = world.register_system(system_b);
    world.spawn((Callback(system_id), B));
}

examples/ecs/ecs_guide.rs (lines 255-261)

fn exclusive_player_system(world: &mut World) {
    // this does the same thing as "new_player_system"
    let total_players = world.resource_mut::<GameState>().total_players;
    let should_add_player = {
        let game_rules = world.resource::<GameRules>();
        let add_new_player = random::<bool>();
        add_new_player && total_players < game_rules.max_players
    };
    // Randomly add a new player
    if should_add_player {
        println!("Player {} has joined the game!", total_players + 1);
        world.spawn((
            Player {
                name: format!("Player {}", total_players + 1),
            },
            Score { value: 0 },
            PlayerStreak::None,
        ));

        let mut game_state = world.resource_mut::<GameState>();
        game_state.total_players += 1;
    }
}

examples/ecs/immutable_components.rs (line 32)

fn demo_1(world: &mut World) {
    // Immutable components can be inserted just like mutable components.
    let mut entity = world.spawn((MyMutableComponent(false), MyImmutableComponent(false)));

    // But where mutable components can be mutated...
    let mut my_mutable_component = entity.get_mut::<MyMutableComponent>().unwrap();
    my_mutable_component.0 = true;

    // ...immutable ones cannot. The below fails to compile as `MyImmutableComponent`
    // is declared as immutable.
    // let mut my_immutable_component = entity.get_mut::<MyImmutableComponent>().unwrap();

    // Instead, you could take or replace the immutable component to update its value.
    let mut my_immutable_component = entity.take::<MyImmutableComponent>().unwrap();
    my_immutable_component.0 = true;
    entity.insert(my_immutable_component);
}

/// This is an example of a component like [`Name`](bevy::prelude::Name), but immutable.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Component, Reflect)]
#[reflect(Hash, Component)]
#[component(
    immutable,
    // Since this component is immutable, we can fully capture all mutations through
    // these component hooks. This allows for keeping other parts of the ECS synced
    // to a component's value at all times.
    on_insert = on_insert_name,
    on_discard = on_discard_name,
)]
pub struct Name(pub &'static str);

/// This index allows for O(1) lookups of an [`Entity`] by its [`Name`].
#[derive(Resource, Default)]
struct NameIndex {
    name_to_entity: HashMap<Name, Entity>,
}

impl NameIndex {
    fn get_entity(&self, name: &'static str) -> Option<Entity> {
        self.name_to_entity.get(&Name(name)).copied()
    }
}

/// When a [`Name`] is inserted, we will add it to our [`NameIndex`].
///
/// Since all mutations to [`Name`] are captured by hooks, we know it is not currently
/// inserted in the index, and its value will not change without triggering a hook.
fn on_insert_name(mut world: DeferredWorld<'_>, HookContext { entity, .. }: HookContext) {
    let Some(&name) = world.entity(entity).get::<Name>() else {
        unreachable!("Insert 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_discard_name(mut world: DeferredWorld<'_>, HookContext { entity, .. }: HookContext) {
    let Some(&name) = world.entity(entity).get::<Name>() else {
        unreachable!("Discard hook guarantees `Name` is available on entity")
    };
    let Some(mut index) = world.get_resource_mut::<NameIndex>() else {
        return;
    };

    index.name_to_entity.remove(&name);
}

fn demo_2(world: &mut World) {
    // Setup our name index
    world.init_resource::<NameIndex>();

    // Spawn some entities!
    let alyssa = world.spawn(Name("Alyssa")).id();
    let javier = world.spawn(Name("Javier")).id();

    // Check our index
    let index = world.resource::<NameIndex>();

    assert_eq!(index.get_entity("Alyssa"), Some(alyssa));
    assert_eq!(index.get_entity("Javier"), Some(javier));

    // Changing the name of an entity is also fully capture by our index
    world.entity_mut(javier).insert(Name("Steven"));

    // Javier changed their name to Steven
    let steven = javier;

    // Check our index
    let index = world.resource::<NameIndex>();

    assert_eq!(index.get_entity("Javier"), None);
    assert_eq!(index.get_entity("Steven"), Some(steven));
}

examples/scene/world_serialization.rs (lines 179-185)

fn save_world_system(world: &mut World) {
    let asset_server = world.resource::<AssetServer>().clone();
    // The `TypeRegistry` resource contains information about all registered types (including components).
    // This is used to construct worlds, so we'll want to ensure that we use the registry from the
    // main world. To do this, we can simply clone the `AppTypeRegistry` resource.
    let type_registry = world.resource::<AppTypeRegistry>().clone();

    // Any ECS World can be serialized.
    // For demonstration purposes, we'll create a new one.
    let mut scene_world = World::new();

    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"),
        WorldAssetRoot(asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0")),
    ));
    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 a DynamicWorld from it.
    // For simplicity, we will create our scene using DynamicWorld directly, but if
    // you need more control, you can use DynamicWorldBuilder.
    let dynamic_world = DynamicWorld::from_world_with(&scene_world, &type_registry.read());

    // Dynamic Worlds can be serialized like this:
    let type_registry = world.resource::<AppTypeRegistry>();
    let type_registry = type_registry.read();
    let serialized_world = dynamic_world.serialize(&type_registry).unwrap();

    // Shows the serialized world in the console
    info!("{}", serialized_world);

    // Writing the world 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 world RON data to file
            File::create(format!("assets/{NEW_WORLD_FILE_PATH}"))
                .and_then(|mut file| file.write(serialized_world.as_bytes()))
                .expect("Error while writing world to file");
        })
        .detach();
}

examples/ecs/dynamic.rs (line 250)

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();
    let mut event_names = HashMap::<String, EventKey>::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}"),
                Some('e') => println!("{EVENT_PROMPT}"),
                Some('t') => println!("{EMIT_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,
                            None,
                        )
                    });
                    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_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);
                });
            }
            "e" => {
                rest.split(',').for_each(|event| {
                    let name = event.trim();
                    if name.is_empty() {
                        return;
                    }

                    // Register a ComponentId for this event, no Rust type needed.
                    // SAFETY: ZST with no drop
                    let event_component_id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            format!("event:{name}"),
                            StorageType::Table,
                            Layout::new::<()>(),
                            None,
                            false,
                            ComponentCloneBehavior::Ignore,
                            None,
                        )
                    });
                    // SAFETY: event_component_id was just registered for this event
                    let event_key = unsafe { EventKey::new(event_component_id) };
                    event_names.insert(name.to_string(), event_key);

                    // Build a dynamic observer that prints when the event fires.
                    let runner: ObserverRunner = |mut world, _observer, ctx, _event, _trigger| {
                        println!("  Observer fired!");
                        if let Some(mut counts) = world.get_resource_mut::<EventFireCount>() {
                            *counts.0.entry(ctx.event_key).or_insert(0) += 1;
                        }
                    };

                    // SAFETY: event_key was just registered, runner ignores pointers
                    let observer =
                        unsafe { Observer::with_dynamic_runner(runner).with_event_key(event_key) };
                    world.spawn(observer);

                    println!(
                        "Event '{name}' registered (key: {}) with a dynamic observer",
                        event_component_id.index()
                    );
                });

                // Ensure the counter resource exists.
                world.init_resource::<EventFireCount>();
            }
            "t" => {
                let name = rest.trim();
                let Some(&event_key) = event_names.get(name) else {
                    println!(
                        "Event '{name}' does not exist. Register it first with 'event {name}'"
                    );
                    continue;
                };

                let mut event_data = ();
                let mut trigger_data = ();
                // SAFETY: event_key was registered in this world, both pointers are valid ZSTs
                unsafe {
                    world.trigger_dynamic(
                        event_key,
                        PtrMut::from(&mut event_data),
                        PtrMut::from(&mut trigger_data),
                    );
                }

                let count = world
                    .get_resource::<EventFireCount>()
                    .map_or(0, |c| c.0.get(&event_key).copied().unwrap_or(0));
                println!("Event '{name}' triggered ({count} fires)");
            }
            _ => continue,
        }
    }
}

pub fn spawn_empty(&mut self) -> EntityWorldMut<'_>

Spawns a new Entity and returns a corresponding EntityWorldMut, which can be used to add components to the entity or retrieve its id.

use bevy_ecs::{component::Component, world::World};

#[derive(Component)]
struct Position {
  x: f32,
  y: f32,
}
#[derive(Component)]
struct Label(&'static str);
#[derive(Component)]
struct Num(u32);

let mut world = World::new();
let entity = world.spawn_empty()
    .insert(Position { x: 0.0, y: 0.0 }) // add a single component
    .insert((Num(1), Label("hello"))) // add a bundle of components
    .id();

let position = world.entity(entity).get::<Position>().unwrap();
assert_eq!(position.x, 0.0);

Examples found in repository

examples/ecs/immutable_components.rs (line 171)

fn demo_3(world: &mut World) {
    // This is a list of dynamic components we will create.
    // The first item is the name of the component, and the second is the size
    // in bytes.
    let my_dynamic_components = [("Foo", 1), ("Bar", 2), ("Baz", 4)];

    // This pipeline takes our component descriptions, registers them, and gets
    // their ComponentId's.
    let my_registered_components = my_dynamic_components
        .into_iter()
        .map(|(name, size)| {
            // SAFETY:
            // - No drop command is required
            // - The component will store [u8; size], which is Send + Sync
            let descriptor = unsafe {
                ComponentDescriptor::new_with_layout(
                    name.to_string(),
                    StorageType::Table,
                    Layout::array::<u8>(size).unwrap(),
                    None,
                    false,
                    ComponentCloneBehavior::Default,
                    None,
                )
            };

            (name, size, descriptor)
        })
        .map(|(name, size, descriptor)| {
            let component_id = world.register_component_with_descriptor(descriptor);

            (name, size, component_id)
        })
        .collect::<Vec<(&str, usize, ComponentId)>>();

    // Now that our components are registered, let's add them to an entity
    let mut entity = world.spawn_empty();

    for (_name, size, component_id) in &my_registered_components {
        // We're just storing some zeroes for the sake of demonstration.
        let data = core::iter::repeat_n(0, *size).collect::<Vec<u8>>();

        OwningPtr::make(data, |ptr| {
            // SAFETY:
            // - ComponentId has been taken from the same world
            // - Array is created to the layout specified in the world
            unsafe {
                entity.insert_by_id(*component_id, ptr);
            }
        });
    }

    for (_name, _size, component_id) in &my_registered_components {
        // With immutable components, we can read the values...
        assert!(entity.get_by_id(*component_id).is_ok());

        // ...but we cannot gain a mutable reference.
        assert!(entity.get_mut_by_id(*component_id).is_err());

        // Instead, you must either remove or replace the value.
    }
}

examples/stress_tests/many_components.rs (line 135)

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,
                        None,
                    )
                },
            )
        })
        .collect();

    // fill the schedule with systems
    let mut schedule = Schedule::new(Update);
    for _ in 1..=num_systems {
        let num_access_components = rng.random_range(1..10);
        let access_components: Vec<ComponentId> = component_ids
            .sample(&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.random_range(1..10);
        let components: Vec<ComponentId> = component_ids
            .sample(&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.random_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());
        }
    }

    // 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(HashSet::from_iter([
            DiagnosticPath::new("fps"),
        ])));
    app.run();
}

examples/ecs/dynamic.rs (line 161)

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();
    let mut event_names = HashMap::<String, EventKey>::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}"),
                Some('e') => println!("{EVENT_PROMPT}"),
                Some('t') => println!("{EMIT_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,
                            None,
                        )
                    });
                    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_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);
                });
            }
            "e" => {
                rest.split(',').for_each(|event| {
                    let name = event.trim();
                    if name.is_empty() {
                        return;
                    }

                    // Register a ComponentId for this event, no Rust type needed.
                    // SAFETY: ZST with no drop
                    let event_component_id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            format!("event:{name}"),
                            StorageType::Table,
                            Layout::new::<()>(),
                            None,
                            false,
                            ComponentCloneBehavior::Ignore,
                            None,
                        )
                    });
                    // SAFETY: event_component_id was just registered for this event
                    let event_key = unsafe { EventKey::new(event_component_id) };
                    event_names.insert(name.to_string(), event_key);

                    // Build a dynamic observer that prints when the event fires.
                    let runner: ObserverRunner = |mut world, _observer, ctx, _event, _trigger| {
                        println!("  Observer fired!");
                        if let Some(mut counts) = world.get_resource_mut::<EventFireCount>() {
                            *counts.0.entry(ctx.event_key).or_insert(0) += 1;
                        }
                    };

                    // SAFETY: event_key was just registered, runner ignores pointers
                    let observer =
                        unsafe { Observer::with_dynamic_runner(runner).with_event_key(event_key) };
                    world.spawn(observer);

                    println!(
                        "Event '{name}' registered (key: {}) with a dynamic observer",
                        event_component_id.index()
                    );
                });

                // Ensure the counter resource exists.
                world.init_resource::<EventFireCount>();
            }
            "t" => {
                let name = rest.trim();
                let Some(&event_key) = event_names.get(name) else {
                    println!(
                        "Event '{name}' does not exist. Register it first with 'event {name}'"
                    );
                    continue;
                };

                let mut event_data = ();
                let mut trigger_data = ();
                // SAFETY: event_key was registered in this world, both pointers are valid ZSTs
                unsafe {
                    world.trigger_dynamic(
                        event_key,
                        PtrMut::from(&mut event_data),
                        PtrMut::from(&mut trigger_data),
                    );
                }

                let count = world
                    .get_resource::<EventFireCount>()
                    .map_or(0, |c| c.0.get(&event_key).copied().unwrap_or(0));
                println!("Event '{name}' triggered ({count} fires)");
            }
            _ => continue,
        }
    }
}

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

where I: IntoIterator, <I as IntoIterator>::Item: Bundle, <<I as IntoIterator>::Item as DynamicBundle>::Effect: NoBundleEffect,

Spawns a batch of entities with the same component Bundle type. Takes a given Bundle iterator and returns a corresponding Entity iterator. This is more efficient than spawning entities and adding components to them individually using World::spawn, but it is limited to spawning entities with the same Bundle type, whereas spawning individually is more flexible.

use bevy_ecs::{component::Component, entity::Entity, world::World};

#[derive(Component)]
struct Str(&'static str);
#[derive(Component)]
struct Num(u32);

let mut world = World::new();
let entities = world.spawn_batch(vec![
  (Str("a"), Num(0)), // the first entity
  (Str("b"), Num(1)), // the second entity
]).collect::<Vec<Entity>>();

assert_eq!(entities.len(), 2);

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

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_discard` 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 messages
                world.write_message(MyMessage);
            },
        )
        // `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_discard` 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_discard(|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.

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 mut position = world.get_mut::<Position>(entity).unwrap();
position.x = 1.0;

pub fn modify_component<T, R>( &mut self, entity: Entity, f: impl FnOnce(&mut T) -> R, ) -> Result<Option<R>, EntityMutableFetchError>

where T: Component,

Temporarily removes a Component T from the provided Entity and runs the provided closure on it, returning the result if T was available. This will trigger the Remove and Discard component hooks without causing an archetype move.

This is most useful with immutable components, where removal and reinsertion is the only way to modify a value.

If you do not need to ensure the above hooks are triggered, and your component is mutable, prefer using get_mut.

Examples

#[derive(Component, PartialEq, Eq, Debug)]
#[component(immutable)]
struct Foo(bool);

world.modify_component(entity, |foo: &mut Foo| {
    foo.0 = true;
});

pub fn modify_component_by_id<R>( &mut self, entity: Entity, component_id: ComponentId, f: impl for<'a> FnOnce(MutUntyped<'a>) -> R, ) -> Result<Option<R>, EntityMutableFetchError>

Temporarily removes a Component identified by the provided ComponentId from the provided Entity and runs the provided closure on it, returning the result if the component was available. This will trigger the Remove and Discard component hooks without causing an archetype move.

This is most useful with immutable components, where removal and reinsertion is the only way to modify a value.

If you do not need to ensure the above hooks are triggered, and your component is mutable, prefer using get_mut_by_id.

You should prefer the typed modify_component whenever possible.

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

Despawns the given Entity, if it exists. This will also remove all of the entity’s Components.

Returns true if the entity is successfully despawned and false if the entity does not exist. This counts despawning a not constructed entity as a success, and frees it to the allocator. See entity module docs for more about construction.

Note

This will also despawn the entities in any RelationshipTarget that is configured to despawn descendants. For example, this will recursively despawn Children.

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();
assert!(world.despawn(entity));
assert!(world.get_entity(entity).is_err());
assert!(world.get::<Position>(entity).is_none());

Examples found in repository

examples/no_std/library/src/lib.rs (line 135)

fn unwrap<B: Bundle>(event: On<Unwrap>, world: &mut World) {
    if let Ok(mut target) = world.get_entity_mut(event.event_target())
        && let Some(DelayedComponent(bundle)) = target.take::<DelayedComponent<B>>()
    {
        target.insert(bundle);
    }

    world.despawn(event.observer());
}

pub fn try_despawn(&mut self, entity: Entity) -> Result<(), EntityDespawnError>

Despawns the given entity, if it exists. This will also remove all of the entity’s Components.

Returns an EntityDespawnError if the entity is not spawned to be despawned.

Note

This will also despawn the entities in any RelationshipTarget that is configured to despawn descendants. For example, this will recursively despawn Children.

pub fn despawn_no_free(&mut self, entity: Entity) -> Option<Entity>

Performs try_despawn_no_free, warning on errors. See that method for more information.

pub fn try_despawn_no_free( &mut self, entity: Entity, ) -> Result<Entity, EntityDespawnError>

Despawns the given entity, if it exists. This will also remove all of the entity’s Components.

The only difference between this and despawning an entity is that this does not release the entity to be reused. It is up to the caller to either re-spawn or free the entity; otherwise, the EntityIndex will not be able to be reused. In general, despawn should be used instead, which automatically allows the row to be reused.

Returns the new Entity if of the despawned EntityIndex, which should eventually either be re-spawned or freed to the allocator. Returns an EntityDespawnError if the entity is not spawned.

Note

This will also despawn the entities in any RelationshipTarget that is configured to despawn descendants. For example, this will recursively despawn Children.

Example

There is no simple example in which this would be practical, but one use for this is a custom entity allocator. Despawning internally calls this and frees the entity id to Bevy’s default entity allocator. The same principal can be used to create custom allocators with additional properties. For example, this could be used to make an allocator that yields groups of consecutive EntityIndexs, etc. See EntityAllocator::alloc for more on this.

pub fn clear_trackers(&mut self)

Clears the internal component tracker state.

The world maintains some internal state about changed and removed components. This state is used by RemovedComponents to provide access to the entities that had a specific type of component removed since last tick.

The state is also used for change detection when accessing components and resources outside of a system, for example via World::get_mut() or World::get_resource_mut().

By clearing this internal state, the world “forgets” about those changes, allowing a new round of detection to be recorded.

When using bevy_ecs as part of the full Bevy engine, this method is called automatically by bevy_app::App::update and bevy_app::SubApp::update, so you don’t need to call it manually. When using bevy_ecs as a separate standalone crate however, you do need to call this manually.

// a whole new world
let mut world = World::new();

// you changed it
let entity = world.spawn(Transform::default()).id();

// change is detected
let transform = world.get_mut::<Transform>(entity).unwrap();
assert!(transform.is_changed());

// update the last change tick
world.clear_trackers();

// change is no longer detected
let transform = world.get_mut::<Transform>(entity).unwrap();
assert!(!transform.is_changed());

pub fn query<D>(&mut self) -> 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,
}

#[derive(Component)]
struct Velocity {
  x: f32,
  y: f32,
}

let mut world = World::new();
let entities = world.spawn_batch(vec![
    (Position { x: 0.0, y: 0.0}, Velocity { x: 1.0, y: 0.0 }),
    (Position { x: 0.0, y: 0.0}, Velocity { x: 0.0, y: 1.0 }),
]).collect::<Vec<Entity>>();

let mut query = world.query::<(&mut Position, &Velocity)>();
for (mut position, velocity) in query.iter_mut(&mut world) {
   position.x += velocity.x;
   position.y += velocity.y;
}

assert_eq!(world.get::<Position>(entities[0]).unwrap(), &Position { x: 1.0, y: 0.0 });
assert_eq!(world.get::<Position>(entities[1]).unwrap(), &Position { x: 0.0, y: 1.0 });

To iterate over entities in a deterministic order, sort the results of the query using the desired component as a key. Note that this requires fetching the whole result set from the query and allocation of a Vec to store it.

use bevy_ecs::{component::Component, entity::Entity, world::World};

#[derive(Component, PartialEq, Eq, PartialOrd, Ord, Debug)]
struct Order(i32);
#[derive(Component, PartialEq, Debug)]
struct Label(&'static str);

let mut world = World::new();
let a = world.spawn((Order(2), Label("second"))).id();
let b = world.spawn((Order(3), Label("third"))).id();
let c = world.spawn((Order(1), Label("first"))).id();
let mut entities = world.query::<(Entity, &Order, &Label)>()
    .iter(&world)
    .collect::<Vec<_>>();
// Sort the query results by their `Order` component before comparing
// to expected results. Query iteration order should not be relied on.
entities.sort_by_key(|e| e.1);
assert_eq!(entities, vec![
    (c, &Order(1), &Label("first")),
    (a, &Order(2), &Label("second")),
    (b, &Order(3), &Label("third")),
]);

Examples found in repository

examples/window/persisting_window_settings.rs (line 57)

fn init_window_pos(app: &mut App) {
    let world = app.world_mut();
    let Some(window_settings) = world.get_resource::<WindowSettings>() else {
        return;
    };
    let window_settings = window_settings.clone();

    let Ok(mut window) = world.query::<&mut Window>().single_mut(world) else {
        warn!("window not found");
        return;
    };

    if let Some(position) = window_settings.position {
        window.position = WindowPosition::new(position);
    }

    if let Some(size) = window_settings.size {
        window.resolution = WindowResolution::new(size.x, size.y);
    }

    window.mode = if window_settings.fullscreen {
        WindowMode::BorderlessFullscreen(MonitorSelection::Current)
    } else {
        WindowMode::Windowed
    };
}

examples/tools/scene_viewer/scene_viewer_plugin.rs (line 139)

fn scene_load_check(
    asset_server: Res<AssetServer>,
    mut scenes: ResMut<Assets<WorldAsset>>,
    gltf_assets: Res<Assets<Gltf>>,
    mut scene_handle: ResMut<SceneHandle>,
    mut scene_spawner: ResMut<WorldInstanceSpawner>,
) {
    match scene_handle.instance_id {
        None => {
            if asset_server
                .load_state(&scene_handle.gltf_handle)
                .is_loaded()
            {
                let gltf = gltf_assets.get(&scene_handle.gltf_handle).unwrap();
                if gltf.scenes.len() > 1 {
                    info!(
                        "Displaying scene {} out of {}",
                        scene_handle.scene_index,
                        gltf.scenes.len()
                    );
                    info!("You can select the scene by adding '#Scene' followed by a number to the end of the file path (e.g '#Scene1' to load the second scene).");
                }

                let gltf_scene_handle =
                    gltf.scenes
                        .get(scene_handle.scene_index)
                        .unwrap_or_else(|| {
                            panic!(
                                "glTF file doesn't contain scene {}!",
                                scene_handle.scene_index
                            )
                        });
                let mut scene = scenes.get_mut(gltf_scene_handle).unwrap();

                let mut query = scene
                    .world
                    .query::<(Option<&DirectionalLight>, Option<&PointLight>)>();
                scene_handle.has_light =
                    query
                        .iter(&scene.world)
                        .any(|(maybe_directional_light, maybe_point_light)| {
                            maybe_directional_light.is_some() || maybe_point_light.is_some()
                        });

                scene_handle.instance_id = Some(scene_spawner.spawn(gltf_scene_handle.clone()));

                info!("Spawning scene...");
            }
        }
        Some(instance_id) if !scene_handle.is_loaded => {
            if scene_spawner.instance_is_ready(instance_id) {
                info!("...done!");
                scene_handle.is_loaded = true;
            }
        }
        Some(_) => {}
    }
}

pub fn query_filtered<D, F>(&mut self) -> 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.query_filtered::<Entity, With<B>>();
let matching_entities = query.iter(&world).collect::<Vec<Entity>>();

assert_eq!(matching_entities, vec![e2]);

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 register_non_send_with_descriptor( &mut self, descriptor: ComponentDescriptor, ) -> ComponentId

Registers a new non-send resource type and returns the ComponentId created for it.

This enables the dynamic registration of new non-send resources definitions at runtime for advanced use cases.

Note

Registering a non-send resource does not insert it into World. For insertion, you could use World::insert_non_send_by_id.

pub fn init_resource<R>(&mut self) -> ComponentId

where R: Resource + FromWorld,

Initializes a new resource and returns the ComponentId created for it.

If the resource already exists, nothing happens.

The value given by the FromWorld::from_world method will be used. Note that any resource with the Default trait automatically implements FromWorld, and those default values will be here instead.

Examples found in repository

examples/ecs/custom_executor.rs (line 47)

fn main() {
    let mut world = World::new();
    world.init_resource::<Counter>();

    let mut schedule = Schedule::default();
    schedule.set_executor(CustomExecutor);
    schedule.add_systems((increment, print_counter).chain());

    for _ in 0..5 {
        schedule.run(&mut world);
    }
}

examples/ecs/immutable_components.rs (line 105)

fn demo_2(world: &mut World) {
    // Setup our name index
    world.init_resource::<NameIndex>();

    // Spawn some entities!
    let alyssa = world.spawn(Name("Alyssa")).id();
    let javier = world.spawn(Name("Javier")).id();

    // Check our index
    let index = world.resource::<NameIndex>();

    assert_eq!(index.get_entity("Alyssa"), Some(alyssa));
    assert_eq!(index.get_entity("Javier"), Some(javier));

    // Changing the name of an entity is also fully capture by our index
    world.entity_mut(javier).insert(Name("Steven"));

    // Javier changed their name to Steven
    let steven = javier;

    // Check our index
    let index = world.resource::<NameIndex>();

    assert_eq!(index.get_entity("Javier"), None);
    assert_eq!(index.get_entity("Steven"), Some(steven));
}

examples/ecs/dynamic.rs (line 259)

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();
    let mut event_names = HashMap::<String, EventKey>::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}"),
                Some('e') => println!("{EVENT_PROMPT}"),
                Some('t') => println!("{EMIT_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,
                            None,
                        )
                    });
                    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_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);
                });
            }
            "e" => {
                rest.split(',').for_each(|event| {
                    let name = event.trim();
                    if name.is_empty() {
                        return;
                    }

                    // Register a ComponentId for this event, no Rust type needed.
                    // SAFETY: ZST with no drop
                    let event_component_id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            format!("event:{name}"),
                            StorageType::Table,
                            Layout::new::<()>(),
                            None,
                            false,
                            ComponentCloneBehavior::Ignore,
                            None,
                        )
                    });
                    // SAFETY: event_component_id was just registered for this event
                    let event_key = unsafe { EventKey::new(event_component_id) };
                    event_names.insert(name.to_string(), event_key);

                    // Build a dynamic observer that prints when the event fires.
                    let runner: ObserverRunner = |mut world, _observer, ctx, _event, _trigger| {
                        println!("  Observer fired!");
                        if let Some(mut counts) = world.get_resource_mut::<EventFireCount>() {
                            *counts.0.entry(ctx.event_key).or_insert(0) += 1;
                        }
                    };

                    // SAFETY: event_key was just registered, runner ignores pointers
                    let observer =
                        unsafe { Observer::with_dynamic_runner(runner).with_event_key(event_key) };
                    world.spawn(observer);

                    println!(
                        "Event '{name}' registered (key: {}) with a dynamic observer",
                        event_component_id.index()
                    );
                });

                // Ensure the counter resource exists.
                world.init_resource::<EventFireCount>();
            }
            "t" => {
                let name = rest.trim();
                let Some(&event_key) = event_names.get(name) else {
                    println!(
                        "Event '{name}' does not exist. Register it first with 'event {name}'"
                    );
                    continue;
                };

                let mut event_data = ();
                let mut trigger_data = ();
                // SAFETY: event_key was registered in this world, both pointers are valid ZSTs
                unsafe {
                    world.trigger_dynamic(
                        event_key,
                        PtrMut::from(&mut event_data),
                        PtrMut::from(&mut trigger_data),
                    );
                }

                let count = world
                    .get_resource::<EventFireCount>()
                    .map_or(0, |c| c.0.get(&event_key).copied().unwrap_or(0));
                println!("Event '{name}' triggered ({count} fires)");
            }
            _ => continue,
        }
    }
}

pub fn insert_resource<R>(&mut self, value: R)

where R: Resource,

Inserts a new resource with the given value.

Resources are “unique” data of a given type. If you insert a resource of a type that already exists, you will overwrite any existing data.

Examples found in repository

crates/bevy_ecs/examples/resources.rs (line 19)

fn main() {
    // Create a world
    let mut world = World::new();

    // Add the counter resource
    world.insert_resource(Counter { value: 0 });

    // Create a schedule
    let mut schedule = Schedule::default();

    // Add systems to increase the counter and to print out the current value
    schedule.add_systems((increase_counter, print_counter).chain());

    for iteration in 1..=10 {
        println!("Simulating frame {iteration}/10");
        schedule.run(&mut world);
    }
}

crates/bevy_ecs/examples/change_detection.rs (line 24)

fn main() {
    // Create a new empty World to hold our Entities, Components and Resources
    let mut world = World::new();

    // Add the counter resource to remember how many entities where spawned
    world.insert_resource(EntityCounter { value: 0 });

    // Create a new Schedule, which stores systems and controls their relative ordering
    let mut schedule = Schedule::default();

    // Add systems to the Schedule to execute our app logic
    // We can label our systems to force a specific run-order between some of them
    schedule.add_systems((
        spawn_entities.in_set(SimulationSystems::Spawn),
        print_counter_when_changed.after(SimulationSystems::Spawn),
        age_all_entities.in_set(SimulationSystems::Age),
        remove_old_entities.after(SimulationSystems::Age),
        print_changed_entities.after(SimulationSystems::Age),
    ));

    // Simulate 10 frames in our world
    for iteration in 1..=10 {
        println!("Simulating frame {iteration}/10");
        schedule.run(&mut world);
    }
}

examples/scene/world_serialization.rs (line 187)

fn save_world_system(world: &mut World) {
    let asset_server = world.resource::<AssetServer>().clone();
    // The `TypeRegistry` resource contains information about all registered types (including components).
    // This is used to construct worlds, so we'll want to ensure that we use the registry from the
    // main world. To do this, we can simply clone the `AppTypeRegistry` resource.
    let type_registry = world.resource::<AppTypeRegistry>().clone();

    // Any ECS World can be serialized.
    // For demonstration purposes, we'll create a new one.
    let mut scene_world = World::new();

    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"),
        WorldAssetRoot(asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0")),
    ));
    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 a DynamicWorld from it.
    // For simplicity, we will create our scene using DynamicWorld directly, but if
    // you need more control, you can use DynamicWorldBuilder.
    let dynamic_world = DynamicWorld::from_world_with(&scene_world, &type_registry.read());

    // Dynamic Worlds can be serialized like this:
    let type_registry = world.resource::<AppTypeRegistry>();
    let type_registry = type_registry.read();
    let serialized_world = dynamic_world.serialize(&type_registry).unwrap();

    // Shows the serialized world in the console
    info!("{}", serialized_world);

    // Writing the world 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 world RON data to file
            File::create(format!("assets/{NEW_WORLD_FILE_PATH}"))
                .and_then(|mut file| file.write(serialized_world.as_bytes()))
                .expect("Error while writing world to file");
        })
        .detach();
}

pub fn init_non_send_resource<R>(&mut self) -> ComponentId

where R: 'static + FromWorld,

👎Deprecated since 0.19.0:

use World::init_non_send

Initializes a new non-send resource and returns the ComponentId created for it.

pub fn init_non_send<R>(&mut self) -> ComponentId

where R: 'static + FromWorld,

Initializes new non-send data and returns the ComponentId created for it.

If the data already exists, nothing happens.

The value given by the FromWorld::from_world method will be used. Note that any non-send data with the Default trait automatically implements FromWorld, and those default values will be here instead.

Panics

Panics if called from a thread other than the main thread.

pub fn insert_non_send_resource<R>(&mut self, value: R)

where R: 'static,

👎Deprecated since 0.19.0:

use World::insert_non_send

Inserts a new non-send resource with the given value.

pub fn insert_non_send<R>(&mut self, value: R)

where R: 'static,

Inserts new non-send data with the given value.

NonSend data cannot be sent across threads, and do not need the Send + Sync bounds. Systems with NonSend resources are always scheduled on the main thread.

Panics

If a value is already present, this function will panic if called from a different thread than where the original value was inserted from.

pub fn remove_resource<R>(&mut self) -> Option<R>

where R: Resource,

Removes the resource of a given type and returns it, if it exists. Otherwise returns None.

pub fn remove_non_send_resource<R>(&mut self) -> Option<R>

where R: 'static,

👎Deprecated since 0.19.0:

use World::remove_non_send

Removes a !Send resource from the world and returns it, if present.

pub fn remove_non_send<R>(&mut self) -> Option<R>

where R: 'static,

Removes !Send data from the world and returns it, if present.

NonSend resources cannot be sent across threads, and do not need the Send + Sync bounds. Systems with NonSend data are always scheduled on the main thread.

Returns None if a value was not previously present.

Panics

If a value is present, this function will panic if called from a different thread than where the value was inserted from.

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 !Send data of type R exists. Otherwise returns false.

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

Returns true if !Send data with 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/audio/play_sound_effect.rs (line 14)

    fn from_world(world: &mut World) -> Self {
        let asset_server = world.resource::<AssetServer>();
        SoundEffect {
            handle: asset_server.load("sounds/breakout_collision.ogg"),
        }
    }

examples/scene/world_serialization.rs (line 89)

    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 world files.
///
/// 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,
}

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

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

/// Loads a world from an asset file and spawns it in the current world.
///
/// Spawning a `DynamicWorldRoot` creates a new parent entity, which then spawns new
/// instances of the world's entities as its children. If you modify the
/// `WORLD_FILE_PATH` file, or if you enable file watching, you can see
/// changes reflected immediately.
fn load_world_system(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(DynamicWorldRoot(asset_server.load(WORLD_FILE_PATH)));
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(1.0, 1.0, 1.0).looking_at(Vec3::new(0.0, 0.25, 0.0), Vec3::Y),
    ));
    commands.spawn((
        DirectionalLight::default(),
        Transform::default().looking_to(Vec3::new(0.0, -1.0, -1.0), Vec3::Y),
    ));
}

/// 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 world 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
        && res.is_added()
    {
        info!("  New ResourceA: {{ score: {} }}\n", res.score);
    }
}

/// Demonstrates how to create a new world from scratch, populate it with data,
/// and then serialize it to a file. The new file is written to `NEW_WORLD_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 world.
fn save_world_system(world: &mut World) {
    let asset_server = world.resource::<AssetServer>().clone();
    // The `TypeRegistry` resource contains information about all registered types (including components).
    // This is used to construct worlds, so we'll want to ensure that we use the registry from the
    // main world. To do this, we can simply clone the `AppTypeRegistry` resource.
    let type_registry = world.resource::<AppTypeRegistry>().clone();

    // Any ECS World can be serialized.
    // For demonstration purposes, we'll create a new one.
    let mut scene_world = World::new();

    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"),
        WorldAssetRoot(asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0")),
    ));
    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 a DynamicWorld from it.
    // For simplicity, we will create our scene using DynamicWorld directly, but if
    // you need more control, you can use DynamicWorldBuilder.
    let dynamic_world = DynamicWorld::from_world_with(&scene_world, &type_registry.read());

    // Dynamic Worlds can be serialized like this:
    let type_registry = world.resource::<AppTypeRegistry>();
    let type_registry = type_registry.read();
    let serialized_world = dynamic_world.serialize(&type_registry).unwrap();

    // Shows the serialized world in the console
    info!("{}", serialized_world);

    // Writing the world 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 world RON data to file
            File::create(format!("assets/{NEW_WORLD_FILE_PATH}"))
                .and_then(|mut file| file.write(serialized_world.as_bytes()))
                .expect("Error while writing world to file");
        })
        .detach();
}

examples/app/externally_driven_headless_renderer.rs (line 111)

    fn update(&mut self) {
        self.0.update();
        // Wait for frame to finish rendering by wait polling the device
        self.0
            .main
            .world()
            .resource::<RenderDevice>()
            .wgpu_device()
            .poll(PollType::Wait {
                submission_index: None,
                timeout: None,
            })
            .unwrap();
    }

tests/ecs/ambiguity_detection.rs (line 80)

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

examples/2d/dynamic_mip_generation.rs (line 295)

    fn from_world(world: &mut World) -> Self {
        let mut meshes = world.resource_mut::<Assets<Mesh>>();
        let rectangle = meshes.add(Rectangle::default());

        let asset_server = world.resource::<AssetServer>();
        let font = asset_server.load("fonts/FiraSans-Bold.ttf");
        let text_font = TextFont {
            font: font.into(),
            font_size: FONT_SIZE,
            ..default()
        };

        AppAssets {
            rectangle,
            text_font,
        }
    }

Additional examples can be found in:

• examples/ecs/immutable_components.rs
• examples/ecs/ecs_guide.rs
• examples/3d/clustered_decal_maps.rs
• examples/shader_advanced/custom_phase_item.rs
• examples/ecs/component_hooks.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 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.

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/shader/shader_material_wesl.rs (line 44)

    fn build(&self, app: &mut App) {
        let handle = app
            .world_mut()
            .resource_mut::<AssetServer>()
            .load::<Shader>("shaders/util.wesl");
        app.insert_resource(UtilityShader(handle));
    }

tests/ecs/ambiguity_detection.rs (line 67)

fn configure_ambiguity_detection(sub_app: &mut SubApp) {
    let mut schedules = sub_app.world_mut().resource_mut::<Schedules>();
    for (_, schedule) in schedules.iter_mut() {
        schedule.set_build_settings(ScheduleBuildSettings {
            // NOTE: you can change this to `LogLevel::Ignore` to easily see the current number of ambiguities.
            ambiguity_detection: LogLevel::Warn,
            use_shortnames: false,
            ..default()
        });
    }
}

examples/2d/dynamic_mip_generation.rs (line 292)

    fn from_world(world: &mut World) -> Self {
        let mut meshes = world.resource_mut::<Assets<Mesh>>();
        let rectangle = meshes.add(Rectangle::default());

        let asset_server = world.resource::<AssetServer>();
        let font = asset_server.load("fonts/FiraSans-Bold.ttf");
        let text_font = TextFont {
            font: font.into(),
            font_size: FONT_SIZE,
            ..default()
        };

        AppAssets {
            rectangle,
            text_font,
        }
    }

examples/shader_advanced/compute_mesh.rs (line 68)

    fn finish(&self, app: &mut App) {
        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
            return;
        };
        render_app
            .world_mut()
            .resource_mut::<MeshAllocatorSettings>()
            // This allows using the mesh allocator slabs as
            // storage buffers directly in the compute shader.
            // Which means that we can write from our compute
            // shader directly to the allocated mesh slabs.
            .extra_buffer_usages = BufferUsages::STORAGE;
    }

examples/app/custom_loop.rs (line 19)

fn my_runner(mut app: App) -> AppExit {
    // Finalize plugin building, including running any necessary clean-up.
    // This is normally completed by the default runner.
    app.finish();
    app.cleanup();

    println!("Type stuff into the console");
    for line in io::stdin().lines() {
        {
            let mut input = app.world_mut().resource_mut::<Input>();
            input.0 = line.unwrap();
        }
        app.update();

        if let Some(exit) = app.should_exit() {
            return exit;
        }
    }

    AppExit::Success
}

examples/gltf/gltf_extension_animation_graph.rs (line 142)

    fn build(&self, app: &mut App) {
        #[cfg(target_family = "wasm")]
        bevy::tasks::block_on(async {
            app.world_mut()
                .resource_mut::<GltfExtensionHandlers>()
                .0
                .write()
                .await
                .push(Box::new(GltfExtensionHandlerAnimation::default()))
        });
        #[cfg(not(target_family = "wasm"))]
        app.world_mut()
            .resource_mut::<GltfExtensionHandlers>()
            .0
            .write_blocking()
            .push(Box::new(GltfExtensionHandlerAnimation::default()));
    }

Additional examples can be found in:

• examples/gltf/gltf_extension_mesh_2d.rs
• examples/app/externally_driven_headless_renderer.rs
• examples/ecs/ecs_guide.rs
• examples/shader_advanced/render_depth_to_texture.rs
• examples/showcase/stepping.rs
• examples/2d/mesh2d_manual.rs
• examples/time/time.rs
• examples/ecs/custom_schedule.rs
• examples/ecs/system_stepping.rs

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/window/persisting_window_settings.rs (line 52)

fn init_window_pos(app: &mut App) {
    let world = app.world_mut();
    let Some(window_settings) = world.get_resource::<WindowSettings>() else {
        return;
    };
    let window_settings = window_settings.clone();

    let Ok(mut window) = world.query::<&mut Window>().single_mut(world) else {
        warn!("window not found");
        return;
    };

    if let Some(position) = window_settings.position {
        window.position = WindowPosition::new(position);
    }

    if let Some(size) = window_settings.size {
        window.resolution = WindowResolution::new(size.x, size.y);
    }

    window.mode = if window_settings.fullscreen {
        WindowMode::BorderlessFullscreen(MonitorSelection::Current)
    } else {
        WindowMode::Windowed
    };
}

examples/ecs/error_handling.rs (line 155)

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")
        // The default error severity is Severity::Panic.
        // We can add a Severity level to any Result locally to downgrade it appropriately.
        .with_severity(Severity::Warning)?;

    world
        // This entity doesn't exist!
        .spawn_empty_at(Entity::from_raw_u32(12345678).unwrap())
        .map_severity(|e| match e {
            // Not that concerning, we just need to make sure to find a different entity
            SpawnError::AlreadySpawned => Severity::Debug,
            // Oh no
            SpawnError::Invalid(_) => Severity::Error,
        })?;

    Ok(())
}

fn failing_commands(mut commands: Commands) {
    commands
        // This entity doesn't exist!
        .entity(Entity::from_raw_u32(12345678).unwrap())
        // 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/ecs/dynamic.rs (line 282)

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();
    let mut event_names = HashMap::<String, EventKey>::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}"),
                Some('e') => println!("{EVENT_PROMPT}"),
                Some('t') => println!("{EMIT_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,
                            None,
                        )
                    });
                    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_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);
                });
            }
            "e" => {
                rest.split(',').for_each(|event| {
                    let name = event.trim();
                    if name.is_empty() {
                        return;
                    }

                    // Register a ComponentId for this event, no Rust type needed.
                    // SAFETY: ZST with no drop
                    let event_component_id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            format!("event:{name}"),
                            StorageType::Table,
                            Layout::new::<()>(),
                            None,
                            false,
                            ComponentCloneBehavior::Ignore,
                            None,
                        )
                    });
                    // SAFETY: event_component_id was just registered for this event
                    let event_key = unsafe { EventKey::new(event_component_id) };
                    event_names.insert(name.to_string(), event_key);

                    // Build a dynamic observer that prints when the event fires.
                    let runner: ObserverRunner = |mut world, _observer, ctx, _event, _trigger| {
                        println!("  Observer fired!");
                        if let Some(mut counts) = world.get_resource_mut::<EventFireCount>() {
                            *counts.0.entry(ctx.event_key).or_insert(0) += 1;
                        }
                    };

                    // SAFETY: event_key was just registered, runner ignores pointers
                    let observer =
                        unsafe { Observer::with_dynamic_runner(runner).with_event_key(event_key) };
                    world.spawn(observer);

                    println!(
                        "Event '{name}' registered (key: {}) with a dynamic observer",
                        event_component_id.index()
                    );
                });

                // Ensure the counter resource exists.
                world.init_resource::<EventFireCount>();
            }
            "t" => {
                let name = rest.trim();
                let Some(&event_key) = event_names.get(name) else {
                    println!(
                        "Event '{name}' does not exist. Register it first with 'event {name}'"
                    );
                    continue;
                };

                let mut event_data = ();
                let mut trigger_data = ();
                // SAFETY: event_key was registered in this world, both pointers are valid ZSTs
                unsafe {
                    world.trigger_dynamic(
                        event_key,
                        PtrMut::from(&mut event_data),
                        PtrMut::from(&mut trigger_data),
                    );
                }

                let count = world
                    .get_resource::<EventFireCount>()
                    .map_or(0, |c| c.0.get(&event_key).copied().unwrap_or(0));
                println!("Event '{name}' triggered ({count} fires)");
            }
            _ => continue,
        }
    }
}

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 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/showcase/loading_screen.rs (line 301)

    fn update_pipelines_ready(mut main_world: ResMut<MainWorld>, pipelines: Res<PipelineCache>) {
        if let Some(mut pipelines_ready) = main_world.get_resource_mut::<PipelinesReady>() {
            pipelines_ready.0 = pipelines.waiting_pipelines().count() == 0;
        }
    }

pub fn get_resource_or_insert_with<R>( &mut self, func: impl FnOnce() -> R, ) -> Mut<'_, R>

where R: Resource,

Gets a mutable reference to the resource of type T if it exists, otherwise inserts the resource using the result of calling func.

Example

#[derive(Resource)]
struct MyResource(i32);

let my_res = world.get_resource_or_insert_with(|| MyResource(10));
assert_eq!(my_res.0, 10);

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

where R: Resource + FromWorld,

Gets a mutable reference to the resource of type T if it exists, otherwise initializes the resource by calling its FromWorld implementation.

Example

#[derive(Resource)]
struct Foo(i32);

impl Default for Foo {
    fn default() -> Self {
        Self(15)
    }
}

#[derive(Resource)]
struct MyResource(i32);

impl FromWorld for MyResource {
    fn from_world(world: &mut World) -> Self {
        let foo = world.get_resource_or_init::<Foo>();
        Self(foo.0 * 2)
    }
}

let my_res = world.get_resource_or_init::<MyResource>();
assert_eq!(my_res.0, 30);

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

where R: 'static,

👎Deprecated since 0.19.0:

use World::non_send

Gets an immutable reference to a non-send resource of the given type, if it exists.

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

where R: 'static,

Gets an immutable reference to the non-send data of the given type, if it exists.

Panics

Panics if the data does not exist. Use get_non_send 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 non_send_resource_mut<R>(&mut self) -> Mut<'_, R>

where R: 'static,

👎Deprecated since 0.19.0:

use World::non_send_mut

Gets a mutable reference to a non-send resource of the given type, if it exists.

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

where R: 'static,

Gets a mutable reference to the non-send data of the given type, if it exists.

Panics

Panics if the data does not exist. Use get_non_send_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<R>(&self) -> Option<&R>

where R: 'static,

👎Deprecated since 0.19.0:

use World::get_non_send

Gets a reference to a non-send resource of the given type, if it exists. Otherwise returns None.

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

where R: 'static,

Gets a reference to the non-send data 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 get_non_send_resource_mut<R>(&mut self) -> Option<Mut<'_, R>>

where R: 'static,

👎Deprecated since 0.19.0:

use World::get_non_send_mut

Gets a mutable reference to a non-send resource of the given type, if it exists. Otherwise returns None.

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

where R: 'static,

Gets a mutable reference to the non-send data 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 insert_batch<I, B>(&mut self, batch: I)

where I: IntoIterator, <I as IntoIterator>::IntoIter: Iterator<Item = (Entity, B)>, B: Bundle, <B as DynamicBundle>::Effect: NoBundleEffect,

For a given batch of (Entity, Bundle) pairs, adds the Bundle of components to each Entity. This is faster than doing equivalent operations one-by-one.

A batch can be any type that implements IntoIterator containing (Entity, Bundle) tuples, such as a Vec<(Entity, Bundle)> or an array [(Entity, Bundle); N].

This will overwrite any previous values of components shared by the Bundle. See World::insert_batch_if_new to keep the old values instead.

Panics

This function will panic if any of the associated entities do not exist.

For the fallible version, see World::try_insert_batch.

pub fn insert_batch_if_new<I, B>(&mut self, batch: I)

where I: IntoIterator, <I as IntoIterator>::IntoIter: Iterator<Item = (Entity, B)>, B: Bundle, <B as DynamicBundle>::Effect: NoBundleEffect,

For a given batch of (Entity, Bundle) pairs, adds the Bundle of components to each Entity without overwriting. This is faster than doing equivalent operations one-by-one.

A batch can be any type that implements IntoIterator containing (Entity, Bundle) tuples, such as a Vec<(Entity, Bundle)> or an array [(Entity, Bundle); N].

This is the same as World::insert_batch, but in case of duplicate components it will leave the old values instead of replacing them with new ones.

Panics

This function will panic if any of the associated entities do not exist.

For the fallible version, see World::try_insert_batch_if_new.

pub fn try_insert_batch<I, B>( &mut self, batch: I, ) -> Result<(), TryInsertBatchError>

where I: IntoIterator, <I as IntoIterator>::IntoIter: Iterator<Item = (Entity, B)>, B: Bundle, <B as DynamicBundle>::Effect: NoBundleEffect,

For a given batch of (Entity, Bundle) pairs, adds the Bundle of components to each Entity. This is faster than doing equivalent operations one-by-one.

A batch can be any type that implements IntoIterator containing (Entity, Bundle) tuples, such as a Vec<(Entity, Bundle)> or an array [(Entity, Bundle); N].

This will overwrite any previous values of components shared by the Bundle. See World::try_insert_batch_if_new to keep the old values instead.

Returns a TryInsertBatchError if any of the provided entities do not exist.

For the panicking version, see World::insert_batch.

pub fn try_insert_batch_if_new<I, B>( &mut self, batch: I, ) -> Result<(), TryInsertBatchError>

where I: IntoIterator, <I as IntoIterator>::IntoIter: Iterator<Item = (Entity, B)>, B: Bundle, <B as DynamicBundle>::Effect: NoBundleEffect,

For a given batch of (Entity, Bundle) pairs, adds the Bundle of components to each Entity without overwriting. This is faster than doing equivalent operations one-by-one.

A batch can be any type that implements IntoIterator containing (Entity, Bundle) tuples, such as a Vec<(Entity, Bundle)> or an array [(Entity, Bundle); N].

This is the same as World::try_insert_batch, but in case of duplicate components it will leave the old values instead of replacing them with new ones.

Returns a TryInsertBatchError if any of the provided entities do not exist.

For the panicking version, see World::insert_batch_if_new.

pub fn resource_scope<R, U>( &mut self, f: impl FnOnce(&mut World, Mut<'_, R>) -> U, ) -> U

where R: Resource,

Temporarily removes the requested resource from this World, runs custom user code, then re-adds the resource before returning.

This enables safe simultaneous mutable access to both a resource and the rest of the World. For more complex access patterns, consider using SystemState.

Panics

Panics if the resource does not exist. Use try_resource_scope instead if you want to handle this case.

Example

use bevy_ecs::prelude::*;
#[derive(Resource)]
struct A(u32);
#[derive(Component)]
struct B(u32);
let mut world = World::new();
world.insert_resource(A(1));
let entity = world.spawn(B(1)).id();

world.resource_scope(|world, mut a: Mut<A>| {
    let b = world.get_mut::<B>(entity).unwrap();
    a.0 += b.0;
});
assert_eq!(world.get_resource::<A>().unwrap().0, 2);

Note

If the world’s resource metadata is cleared within the scope, such as by calling World::clear_resources or World::clear_all, the resource will not be re-inserted at the end of the scope.

pub fn try_resource_scope<R, U>( &mut self, f: impl FnOnce(&mut World, Mut<'_, R>) -> U, ) -> Option<U>

where R: Resource,

Temporarily removes the requested resource from this World if it exists, runs custom user code, then re-adds the resource before returning. Returns None if the resource does not exist in this World.

This enables safe simultaneous mutable access to both a resource and the rest of the World. For more complex access patterns, consider using SystemState.

See also resource_scope.

Note

If the world’s resource metadata is cleared within the scope, such as by calling World::clear_resources or World::clear_all, the resource will not be re-inserted at the end of the scope.

pub fn write_message<M>(&mut self, message: M) -> Option<MessageId<M>>

where M: Message,

Writes a Message. This method returns the MessageId of the written message, or None if the message could not be written.

Examples found in repository

examples/app/persisting_preferences.rs (line 136)

    fn apply(self, world: &mut World) {
        world.write_message(AppExit::Success);
    }

examples/window/persisting_window_settings.rs (line 144)

    fn apply(self, world: &mut World) {
        world.write_message(AppExit::Success);
    }

examples/app/render_recovery.rs (line 133)

fn input(
    input: Res<ButtonInput<Key>>,
    mut error: ResMut<RenderError>,
    mut handler: ResMut<RenderErrorHandler>,
) {
    *error = RenderError::None;
    if input.just_pressed(Key::Character("o".into())) {
        *error = RenderError::OutOfMemory;
    }
    if input.just_pressed(Key::Character("v".into())) {
        *error = RenderError::Validation;
    }
    if input.just_pressed(Key::Character("d".into())) {
        *error = RenderError::DeviceLost;
    }
    if input.just_pressed(Key::Character("l".into())) {
        *error = RenderError::Loop;
    }

    if input.just_pressed(Key::Character("1".into())) {
        *handler = RenderErrorHandler(|_, _, _| RenderErrorPolicy::Ignore);
    }
    if input.just_pressed(Key::Character("2".into())) {
        *handler = RenderErrorHandler(|error, _, _| panic!("Rendering error {error:?}"));
    }
    if input.just_pressed(Key::Character("3".into())) {
        *handler = RenderErrorHandler(|_, main_world, _| {
            main_world.write_message(AppExit::error());
            RenderErrorPolicy::StopRendering
        });
    }
    if input.just_pressed(Key::Character("4".into())) {
        *handler = RenderErrorHandler(|_, _, _| RenderErrorPolicy::StopRendering);
    }
    if input.just_pressed(Key::Character("5".into())) {
        *handler = RenderErrorHandler(|_, _, _| RenderErrorPolicy::Recover(default()));
    }
}

pub fn write_message_default<M>(&mut self) -> Option<MessageId<M>>

where M: Message + Default,

Writes the default value of the Message of type M. This method returns the MessageId of the written message, or None if the event could not be written.

pub fn write_message_batch<M>( &mut self, messages: impl IntoIterator<Item = M>, ) -> Option<WriteBatchIds<M>>

where M: Message,

Writes a batch of Messages from an iterator. This method returns the IDs of the written messages, or None if the events could not be written.

pub unsafe fn insert_resource_by_id( &mut self, component_id: ComponentId, value: OwningPtr<'_>, caller: MaybeLocation, )

Inserts a new resource with the given value. Will replace the value if it already existed.

You should prefer to use the typed API World::insert_resource where possible and only use this in cases where the actual types are not known at compile time.

Safety

The value referenced by value must be valid for the given ComponentId of this world.

pub unsafe fn insert_non_send_by_id( &mut self, component_id: ComponentId, value: OwningPtr<'_>, caller: MaybeLocation, )

Inserts new !Send data with the given value. Will replace the value if it already existed.

You should prefer to use the typed API World::insert_non_send where possible and only use this in cases where the actual types are not known at compile time.

Panics

If a value is already present, this function will panic if not called from the same thread that the original value was inserted from.

Safety

The value referenced by value must be valid for the given ComponentId of this world.

pub fn flush(&mut self)

Flushes queued entities and commands.

Queued entities will be spawned, and then commands will be applied.

pub fn increment_change_tick(&mut self) -> Tick

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

If you need to call this method, but do not have &mut access to the world, consider using as_unsafe_world_cell_readonly to obtain an UnsafeWorldCell and calling increment_change_tick on that. Note that this can be done in safe code, despite the name of the type.

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 change_tick(&mut self) -> Tick

Reads the current change tick of this world.

This does the same thing as read_change_tick(), only this method 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 last_change_tick_scope<T>( &mut self, last_change_tick: Tick, f: impl FnOnce(&mut World) -> T, ) -> T

Sets World::last_change_tick() to the specified value during a scope. When the scope terminates, it will return to its old value.

This is useful if you need a region of code to be able to react to earlier changes made in the same system.

Examples

// This function runs an update loop repeatedly, allowing each iteration of the loop
// to react to changes made in the previous loop iteration.
fn update_loop(
    world: &mut World,
    mut update_fn: impl FnMut(&mut World) -> std::ops::ControlFlow<()>,
) {
    let mut last_change_tick = world.last_change_tick();

    // Repeatedly run the update function until it requests a break.
    loop {
        let control_flow = world.last_change_tick_scope(last_change_tick, |world| {
            // Increment the change tick so we can detect changes from the previous update.
            last_change_tick = world.change_tick();
            world.increment_change_tick();

            // Update once.
            update_fn(world)
        });

        // End the loop when the closure returns `ControlFlow::Break`.
        if control_flow.is_break() {
            break;
        }
    }
}

pub fn check_change_ticks(&mut self) -> Option<CheckChangeTicks>

Iterates all component change ticks and clamps any older than MAX_CHANGE_AGE. This also triggers CheckChangeTicks observers and returns the same event here.

Calling this method prevents Ticks overflowing and thus prevents false positives when comparing them.

Note: Does nothing and returns None if the World counter has not been incremented at least CHECK_TICK_THRESHOLD times since the previous pass.

pub fn clear_all(&mut self)

Clears all entities, resources, and non-send data. This invalidates all Entity and resource fetches such as Res, ResMut

pub fn clear_entities(&mut self)

Despawns all entities in this World.

Note: This includes all resources, as they are stored as components. Any resource fetch to this World will fail unless they are re-initialized, including engine-internal resources that are only initialized on app/world construction.

This can easily cause systems expecting certain resources to immediately start panicking. Use with caution.

pub fn clear_resources(&mut self)

Clears all resources in this World.

Note: Any resource fetch to this World will fail unless they are re-initialized, including engine-internal resources that are only initialized on app/world construction.

This can easily cause systems expecting certain resources to immediately start panicking. Use with caution.

pub fn clear_non_send(&mut self)

Clears all non-send data in this World.

pub fn register_bundle<B>(&mut self) -> &BundleInfo

where B: Bundle,

Registers all of the components in the given Bundle and returns both the component ids and the bundle id.

This is largely equivalent to calling register_component on each component in the bundle.

pub fn register_dynamic_bundle( &mut self, component_ids: &[ComponentId], ) -> &BundleInfo

Registers the given ComponentIds as a dynamic bundle and returns both the required component ids and the bundle id.

Note that the components need to be registered first, this function only creates a bundle combining them. Components can be registered with World::register_component/_with_descriptor.

You should prefer to use the typed API World::register_bundle where possible and only use this in cases where not all of the actual types are known at compile time.

Panics

This function will panic if any of the provided component ids do not belong to a component known to this World.

pub fn fallback_error_handler(&self) -> fn(BevyError, ErrorContext)

Convenience method for accessing the world’s fallback error handler, which can be overwritten with FallbackErrorHandler.

impl World

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 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 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 iter_resources_mut( &mut self, ) -> impl Iterator<Item = (&ComponentInfo, MutUntyped<'_>)>

Mutably iterates over all resources in the world.

The returned iterator provides lifetimed, but type-unsafe pointers. Actually reading from or writing to the contents of each resource will require the use of unsafe code.

Example

// In this example, `A` and `B` are resources. We deliberately do not use the
// `bevy_reflect` crate here to showcase the low-level `MutUntyped` usage. You should
// probably use something like `ReflectFromPtr` in a real-world scenario.

// Create the hash map that will store the mutator closures for each resource type
let mut mutators: HashMap<TypeId, Box<dyn Fn(&mut MutUntyped<'_>)>> = HashMap::default();

// Add mutator closure for `A`
mutators.insert(TypeId::of::<A>(), Box::new(|mut_untyped| {
    // Note: `MutUntyped::as_mut()` automatically marks the resource as changed
    // for ECS change detection, and gives us a `PtrMut` we can use to mutate the resource.
    // SAFETY: We assert ptr is the same type of A with TypeId of A
    let a = unsafe { &mut mut_untyped.as_mut().deref_mut::<A>() };
    // ... mutate `a` here
}));

// Add mutator closure for `B`
mutators.insert(TypeId::of::<B>(), Box::new(|mut_untyped| {
    // SAFETY: We assert ptr is the same type of B with TypeId of B
    let b = unsafe { &mut mut_untyped.as_mut().deref_mut::<B>() };
    // ... mutate `b` here
}));

// Iterate all resources, in order to run the mutator closures for each matching resource type
for (info, mut mut_untyped) in world.iter_resources_mut() {
    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(mutator) = mutators.get(&type_id) else {
       // No mutator closure for this resource type, skip it.
       continue;
    };

    // Run the mutator closure for the resource
    mutator(&mut mut_untyped);
}

pub fn get_non_send_by_id(&self, component_id: ComponentId) -> Option<Ptr<'_>>

Gets a pointer to !Send data 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_non_send 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 data was inserted from.

pub fn get_non_send_mut_by_id( &mut self, component_id: ComponentId, ) -> Option<MutUntyped<'_>>

Gets mutable access to !Send data with the id ComponentId if it exists. The returned pointer may be used to modify the data, as long as the mutable borrow of the World is still valid.

You should prefer to use the typed API World::get_non_send_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 data was inserted from.

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

Removes the resource of a given type, if it exists. Returns true if the resource is successfully removed and false if the entity does not exist.

You should prefer to use the typed API World::remove_resource where possible and only use this in cases where the actual types are not known at compile time.

pub fn remove_non_send_by_id(&mut self, component_id: ComponentId) -> Option<()>

Removes the non-send data of a given type, if it exists. Otherwise returns None.

You should prefer to use the typed API World::remove_non_send 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 data 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.

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.

impl World

pub fn add_schedule(&mut self, schedule: Schedule)

Adds the specified Schedule to the world. If a schedule already exists with the same label, it will be replaced.

The schedule can later be run by calling .run_schedule(label) or by directly accessing the Schedules resource.

The Schedules resource will be initialized if it does not already exist.

An alternative to this is to call Schedules::add_systems() with some ScheduleLabel and let the schedule for that label be created if it does not already exist.

pub fn try_schedule_scope<R>( &mut self, label: impl ScheduleLabel, f: impl FnOnce(&mut World, &mut Schedule) -> R, ) -> Result<R, TryRunScheduleError>

Temporarily removes the schedule associated with label from the world, runs user code, and finally re-adds the schedule. This returns a TryRunScheduleError if there is no schedule associated with label.

The Schedule is fetched from the Schedules resource of the world by its label, and system state is cached.

For simple cases where you just need to call the schedule once, consider using World::try_run_schedule instead. For other use cases, see the example on World::schedule_scope.

pub fn schedule_scope<R>( &mut self, label: impl ScheduleLabel, f: impl FnOnce(&mut World, &mut Schedule) -> R, ) -> R

Temporarily removes the schedule associated with label from the world, runs user code, and finally re-adds the schedule.

The Schedule is fetched from the Schedules resource of the world by its label, and system state is cached.

Examples

// Run the schedule five times.
world.schedule_scope(MySchedule, |world, schedule| {
    for _ in 0..5 {
        schedule.run(world);
    }
});

For simple cases where you just need to call the schedule once, consider using World::run_schedule instead.

Panics

If the requested schedule does not exist.

pub fn try_run_schedule( &mut self, label: impl ScheduleLabel, ) -> Result<(), TryRunScheduleError>

Attempts to run the Schedule associated with the label a single time, and returns a TryRunScheduleError if the schedule does not exist.

The Schedule is fetched from the Schedules resource of the world by its label, and system state is cached.

For simple testing use cases, call Schedule::run(&mut world) instead.

Examples found in repository

examples/state/custom_transitions.rs (line 113)

    fn run_reenter<S: States>(transition: In<Option<StateTransitionEvent<S>>>, world: &mut World) {
        // We return early if no transition event happened.
        let Some(transition) = transition.0 else {
            return;
        };

        // If we wanted to ignore identity transitions,
        // we'd compare `exited` and `entered` here,
        // and return if they were the same.

        // We check if we actually entered a state.
        // A [`None`] would indicate that the state was removed from the world.
        // This only happens in the case of [`SubStates`] and [`ComputedStates`].
        let Some(entered) = transition.entered else {
            return;
        };

        // If all conditions are valid, we run our custom schedule.
        let _ = world.try_run_schedule(OnReenter(entered));

        // If you want to overwrite the default `OnEnter` behavior to act like re-enter,
        // you can do so by running the `OnEnter` schedule here. Note that you don't want
        // to run `OnEnter` when the default behavior does so.
        // ```
        // if transition.entered != transition.exited {
        //     return;
        // }
        // let _ = world.try_run_schedule(OnReenter(entered));
        // ```
    }

    /// Custom schedule that will behave like [`OnExit`], but run on identity transitions.
    #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
    pub struct OnReexit<S: States>(pub S);

    fn run_reexit<S: States>(transition: In<Option<StateTransitionEvent<S>>>, world: &mut World) {
        let Some(transition) = transition.0 else {
            return;
        };
        let Some(exited) = transition.exited else {
            return;
        };

        let _ = world.try_run_schedule(OnReexit(exited));
    }

pub fn run_schedule(&mut self, label: impl ScheduleLabel)

Runs the Schedule associated with the label a single time.

The Schedule is fetched from the Schedules resource of the world by its label, and system state is cached.

For simple testing use cases, call Schedule::run(&mut world) instead. This avoids the need to create a unique ScheduleLabel.

Panics

If the requested schedule does not exist.

pub fn allow_ambiguous_component<T>(&mut self)

where T: Component,

Ignore system order ambiguities caused by conflicts on Components of type T.

pub fn allow_ambiguous_resource<T>(&mut self)

where T: Resource,

Ignore system order ambiguities caused by conflicts on Resources of type T.

Trait Implementations

impl Debug for World

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

Formats the value using the given formatter.

impl Default for World

fn default() -> World

Returns the “default value” for a type.

impl DirectAssetAccessExt for World

fn add_asset<'a, A>(&mut self, asset: impl Into<A>) -> Handle<A>

where A: Asset,

Insert an asset similarly to Assets::add.

Panics

If self doesn’t have an AssetServer resource initialized yet.

fn load_asset<'a, A>(&self, path: impl Into<AssetPath<'a>>) -> Handle<A>

where A: Asset,

Load an asset similarly to AssetServer::load.

Panics

If self doesn’t have an AssetServer resource initialized yet.

fn load_builder(&self) -> LoadBuilder<'_>

Creates a new LoadBuilder similar to AssetServer::load_builder.

Panics

If self doesn’t have an AssetServer resource initialized yet.

fn load_asset_with_settings<'a, A, S>( &self, path: impl Into<AssetPath<'a>>, settings: impl Fn(&mut S) + Send + Sync + 'static, ) -> Handle<A>

where A: Asset, S: Settings,

👎Deprecated:

Use world.load_builder().with_settings(settings).load(path)

Load an asset with settings, similarly to AssetServer::load_with_settings.

Panics

If self doesn’t have an AssetServer resource initialized yet.

impl Drop for World

fn drop(&mut self)

Executes the destructor for this type.

impl<'w> From<&'w World> for FilteredResources<'w, 'static>

fn from(value: &'w World) -> FilteredResources<'w, 'static>

Converts to this type from the input type.

impl<'w> From<&'w World> for UnsafeWorldCell<'w>

fn from(value: &'w World) -> UnsafeWorldCell<'w>

Converts to this type from the input type.

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> From<&'w mut World> for FilteredResources<'w, 'static>

fn from(value: &'w mut World) -> FilteredResources<'w, 'static>

Converts to this type from the input type.

impl<'w> From<&'w mut World> for FilteredResourcesMut<'w, 'static>

fn from(value: &'w mut World) -> FilteredResourcesMut<'w, 'static>

Converts to this type from the input type.

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

fn from(value: &'w mut World) -> UnsafeWorldCell<'w>

Converts to this type from the input type.

impl GetAssetServer for World

fn get_asset_server(&self) -> &AssetServer

impl IsFocused for World

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

Returns true if the given entity has input focus.

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

Returns true if the given entity or any of its descendants has input focus.

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

Returns true if the given entity has input focus and the focus indicator should be visible.

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

Returns true if the given entity, or any descendant, has input focus and the focus indicator should be visible.

impl RunSystemOnce for &mut World

fn run_system_once_with<T, In, Out, Marker>( self, system: T, input: <<<T as IntoSystem<In, Out, Marker>>::System as System>::In as SystemInput>::Inner<'_>, ) -> Result<Out, RunSystemError>

where T: IntoSystem<In, Out, Marker>, In: SystemInput,

Tries to run a system with given input and apply deferred parameters.

fn run_system_once<T, Out, Marker>( self, system: T, ) -> Result<Out, RunSystemError>

where T: IntoSystem<(), Out, Marker>,

Tries to run a system and apply its deferred parameters.

impl SystemParam for &World

type State = ()

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

type Item<'w, 's> = &'w 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) -> <&World as SystemParam>::State

Creates a new instance of this param’s State.

fn init_access( _state: &<&World as SystemParam>::State, _system_meta: &mut SystemMeta, component_access_set: &mut FilteredAccessSet, _world: &mut World, )

Registers any World access used by this SystemParam.

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

Creates a parameter to be passed into a SystemParamFunction.

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.

impl WorldSceneExt for World

fn spawn_scene<S>( &mut self, scene: S, ) -> Result<EntityWorldMut<'_>, SpawnSceneError>

where S: Scene,

Spawns the given Scene immediately. This will resolve the Scene (using Scene::resolve). If that fails (for example, if there are dependencies that have not been loaded yet), it will return a SpawnSceneError. If resolving the Scene is successful, the scene will be spawned.

fn queue_spawn_scene<S>(&mut self, scene: S) -> EntityWorldMut<'_>

where S: Scene,

Queues the scene to be spawned. This will evaluate the scene’s dependencies (via Scene::register_dependencies) and queue it to be resolved and spawned after all of the dependencies have been loaded. If a SpawnSceneError occurs, it will be logged as an error.

fn spawn_scene_list<L>( &mut self, scenes: L, ) -> Result<Vec<Entity>, SpawnSceneError>

where L: SceneList,

Spawns the given SceneList immediately. This will resolve the scene list (using SceneList::resolve_list). If that fails (for example, if there are dependencies that have not been loaded yet), it will return a SpawnSceneError. If resolving the SceneList is successful, the scene list will be spawned.

fn queue_spawn_scene_list<L>(&mut self, scenes: L)

where L: SceneList,

Queues the scene_list to be spawned. This will evaluate the scene_list’s dependencies (via Scene::register_dependencies) and queue it to be resolved and spawned after all of the dependencies have been loaded. If a SpawnSceneError occurs, it will be logged as an error.

impl<'w> ReadOnlySystemParam for &'w World

impl Send for World

impl Sync for World