Struct EntityWorldMut

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

A mutable reference to a particular Entity, and the entire world.

This is essentially a performance-optimized (Entity, &mut World) tuple, which caches the EntityLocation to reduce duplicate lookups.

Since this type provides mutable access to the entire world, only one EntityWorldMut can exist at a time for a given world.

See also EntityMut, which allows disjoint mutable access to multiple entities at once. Unlike EntityMut, this type allows adding and removing components, and despawning the entity.

Implementations

impl<'w> EntityWorldMut<'w>

pub fn with_children( &mut self, func: impl FnOnce(&mut RelatedSpawner<'_, ChildOf>), ) -> &mut EntityWorldMut<'w>

Spawns children of this entity (with a ChildOf relationship) by taking a function that operates on a ChildSpawner. See also with_related.

pub fn add_children(&mut self, children: &[Entity]) -> &mut EntityWorldMut<'w>

Adds the given children to this entity See also add_related.

pub fn insert_children( &mut self, index: usize, children: &[Entity], ) -> &mut EntityWorldMut<'w>

Insert children at specific index. See also insert_related.

pub fn add_child(&mut self, child: Entity) -> &mut EntityWorldMut<'w>

Adds the given child to this entity See also add_related.

pub fn remove_children( &mut self, children: &[Entity], ) -> &mut EntityWorldMut<'w>

Removes the relationship between this entity and the given entities.

pub fn replace_children( &mut self, children: &[Entity], ) -> &mut EntityWorldMut<'w>

Replaces all the related children with a new set of children.

pub fn replace_children_with_difference( &mut self, entities_to_unrelate: &[Entity], entities_to_relate: &[Entity], newly_related_entities: &[Entity], ) -> &mut EntityWorldMut<'w>

Replaces all the related children with a new set of children.

Warning

Failing to maintain the functions invariants may lead to erratic engine behavior including random crashes. Refer to Self::replace_related_with_difference for a list of these invariants.

Panics

Panics when debug assertions are enabled if an invariant is is broken and the command is executed.

pub fn with_child(&mut self, bundle: impl Bundle) -> &mut EntityWorldMut<'w>

Spawns the passed bundle and adds it to this entity as a child.

For efficient spawning of multiple children, use with_children.

pub fn remove_parent(&mut self) -> &mut EntityWorldMut<'w>

👎Deprecated since 0.16.0: Use entity_mut.remove::<ChildOf>()

Removes the ChildOf component, if it exists.

pub fn set_parent(&mut self, parent: Entity) -> &mut EntityWorldMut<'w>

👎Deprecated since 0.16.0: Use entity_mut.insert(ChildOf(entity))

Inserts the ChildOf component with the given parent entity, if it exists.

impl<'w> EntityWorldMut<'w>

pub fn insert_reflect( &mut self, component: Box<dyn PartialReflect>, ) -> &mut EntityWorldMut<'w>

Adds the given boxed reflect component or bundle to the entity using the reflection data in AppTypeRegistry.

This will overwrite any previous component(s) of the same type.

Panics

• If the entity has been despawned while this EntityWorldMut is still alive.
• If AppTypeRegistry does not have the reflection data for the given Component or Bundle.
• If the component or bundle data is invalid. See PartialReflect::apply for further details.
• If AppTypeRegistry is not present in the World.

Note

Prefer to use the typed EntityWorldMut::insert if possible. Adding a reflected component is much slower.

pub fn insert_reflect_with_registry<T>( &mut self, component: Box<dyn PartialReflect>, ) -> &mut EntityWorldMut<'w>

where T: Resource + AsRef<TypeRegistry>,

Same as insert_reflect, but using the T resource as type registry instead of AppTypeRegistry.

This will overwrite any previous component(s) of the same type.

Panics

• If the entity has been despawned while this EntityWorldMut is still alive.
• If the given Resource does not have the reflection data for the given Component or Bundle.
• If the component or bundle data is invalid. See PartialReflect::apply for further details.
• If the given Resource is not present in the World.

pub fn remove_reflect( &mut self, component_type_path: Cow<'static, str>, ) -> &mut EntityWorldMut<'w>

Removes from the entity the component or bundle with the given type name registered in AppTypeRegistry.

If the type is a bundle, it will remove any components in that bundle regardless if the entity contains all the components.

Does nothing if the type is a component and the entity does not have a component of the same type, if the type is a bundle and the entity does not contain any of the components in the bundle, or if AppTypeRegistry does not contain the reflection data for the given component.

Panics

• If the entity has been despawned while this EntityWorldMut is still alive.
• If AppTypeRegistry is not present in the World.

Note

Prefer to use the typed EntityCommands::remove if possible. Removing a reflected component is much slower.

pub fn remove_reflect_with_registry<T>( &mut self, component_type_path: Cow<'static, str>, ) -> &mut EntityWorldMut<'w>

where T: Resource + AsRef<TypeRegistry>,

Same as remove_reflect, but using the T resource as type registry instead of AppTypeRegistry.

If the given type is a bundle, it will remove any components in that bundle regardless if the entity contains all the components.

Does nothing if the type is a component and the entity does not have a component of the same type, if the type is a bundle and the entity does not contain any of the components in the bundle, or if AppTypeRegistry does not contain the reflection data for the given component.

Panics

• If the entity has been despawned while this EntityWorldMut is still alive.
• If AppTypeRegistry is not present in the World.

impl<'w> EntityWorldMut<'w>

pub fn with_related<R>( &mut self, bundle: impl Bundle, ) -> &mut EntityWorldMut<'w>

where R: Relationship,

Spawns a entity related to this entity (with the R relationship) by taking a bundle

pub fn with_related_entities<R>( &mut self, func: impl FnOnce(&mut RelatedSpawner<'_, R>), ) -> &mut EntityWorldMut<'w>

where R: Relationship,

Spawns entities related to this entity (with the R relationship) by taking a function that operates on a RelatedSpawner.

pub fn add_related<R>(&mut self, related: &[Entity]) -> &mut EntityWorldMut<'w>

where R: Relationship,

Relates the given entities to this entity with the relation R.

See add_one_related if you want relate only one entity.

pub fn insert_related<R>( &mut self, index: usize, related: &[Entity], ) -> &mut EntityWorldMut<'w>

where R: Relationship, <<R as Relationship>::RelationshipTarget as RelationshipTarget>::Collection: OrderedRelationshipSourceCollection,

Relates the given entities to this entity with the relation R, starting at this particular index.

If the related has duplicates, a related entity will take the index of its last occurrence in related. If the indices go out of bounds, they will be clamped into bounds. This will not re-order existing related entities unless they are in related.

Example

use bevy_ecs::prelude::*;

let mut world = World::new();
let e0 = world.spawn_empty().id();
let e1 = world.spawn_empty().id();
let e2 = world.spawn_empty().id();
let e3 = world.spawn_empty().id();
let e4 = world.spawn_empty().id();

let mut main_entity = world.spawn_empty();
main_entity.add_related::<ChildOf>(&[e0, e1, e2, e2]);
main_entity.insert_related::<ChildOf>(1, &[e0, e3, e4, e4]);
let main_id = main_entity.id();

let relationship_source = main_entity.get::<Children>().unwrap().collection();
assert_eq!(relationship_source, &[e1, e0, e3, e2, e4]);

pub fn remove_related<R>( &mut self, related: &[Entity], ) -> &mut EntityWorldMut<'w>

where R: Relationship,

Removes the relation R between this entity and the given entities.

pub fn replace_related<R>( &mut self, related: &[Entity], ) -> &mut EntityWorldMut<'w>

where R: Relationship,

Replaces all the related entities with a new set of entities.

pub fn replace_related_with_difference<R>( &mut self, entities_to_unrelate: &[Entity], entities_to_relate: &[Entity], newly_related_entities: &[Entity], ) -> &mut EntityWorldMut<'w>

where R: Relationship,

Replaces all the related entities with a new set of entities.

This is a more efficient of Self::replace_related which doesn’t allocate. The passed in arguments must adhere to these invariants:

• entities_to_unrelate: A slice of entities to remove from the relationship source. Entities need not be related to this entity, but must not appear in entities_to_relate
• entities_to_relate: A slice of entities to relate to this entity. This must contain all entities that will remain related (i.e. not those in entities_to_unrelate) plus the newly related entities.
• newly_related_entities: A subset of entities_to_relate containing only entities not already related to this entity.
• Slices must not contain any duplicates

Warning

Violating these invariants may lead to panics, crashes or unpredictable engine behavior.

Panics

Panics when debug assertions are enabled and any invariants are broken.

pub fn add_one_related<R>(&mut self, entity: Entity) -> &mut EntityWorldMut<'w>

where R: Relationship,

Relates the given entity to this with the relation R.

See add_related if you want to relate more than one entity.

pub fn despawn_related<S>(&mut self) -> &mut EntityWorldMut<'w>

where S: RelationshipTarget,

Despawns entities that relate to this one via the given RelationshipTarget. This entity will not be despawned.

pub fn insert_recursive<S>( &mut self, bundle: impl Bundle + Clone, ) -> &mut EntityWorldMut<'w>

where S: RelationshipTarget,

Inserts a component or bundle of components into the entity and all related entities, traversing the relationship tracked in S in a breadth-first manner.

Warning

This method should only be called on relationships that form a tree-like structure. Any cycles will cause this method to loop infinitely.

pub fn remove_recursive<S, B>(&mut self) -> &mut EntityWorldMut<'w>

where S: RelationshipTarget, B: Bundle,

Removes a component or bundle of components of type B from the entity and all related entities, traversing the relationship tracked in S in a breadth-first manner.

Warning

This method should only be called on relationships that form a tree-like structure. Any cycles will cause this method to loop infinitely.

impl<'w> EntityWorldMut<'w>

pub fn into_readonly(self) -> EntityRef<'w>

Consumes self and returns read-only access to all of the entity’s components, with the world 'w lifetime.

pub fn as_readonly(&self) -> EntityRef<'_>

Gets read-only access to all of the entity’s components.

pub fn into_mutable(self) -> EntityMut<'w>

Consumes self and returns non-structural mutable access to all of the entity’s components, with the world 'w lifetime.

pub fn as_mutable(&mut self) -> EntityMut<'_>

Gets non-structural mutable access to all of the entity’s components.

pub fn id(&self) -> Entity

Returns the ID of the current entity.

Examples found in repository

examples/ecs/immutable_components.rs (line 109)

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

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

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

        if line.is_empty() {
            return;
        };

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

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

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

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

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

                let mut entity = world.spawn_empty();

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

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

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

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

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

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

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

pub fn location(&self) -> EntityLocation

Gets metadata indicating the location where the current entity is stored.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn archetype(&self) -> &Archetype

Returns the archetype that the current entity belongs to.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn contains<T>(&self) -> bool

where T: Component,

Returns true if the current entity has a component of type T. Otherwise, this returns false.

Notes

If you do not know the concrete type of a component, consider using Self::contains_id or Self::contains_type_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

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

Returns true if the current entity has a component identified by component_id. Otherwise, this returns false.

Notes

• If you know the concrete type of the component, you should prefer Self::contains.
• If you know the component’s TypeId but not its ComponentId, consider using Self::contains_type_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn contains_type_id(&self, type_id: TypeId) -> bool

Returns true if the current entity has a component with the type identified by type_id. Otherwise, this returns false.

Notes

• If you know the concrete type of the component, you should prefer Self::contains.
• If you have a ComponentId instead of a TypeId, consider using Self::contains_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn get<T>(&self) -> Option<&T>

where T: Component,

Gets access to the component of type T for the current entity. Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn components<Q>(&self) -> <Q as QueryData>::Item<'_>

where Q: ReadOnlyQueryData,

Returns read-only components for the current entity that match the query Q.

Panics

If the entity does not have the components required by the query Q or if the entity has been despawned while this EntityWorldMut is still alive.

pub fn get_components<Q>(&self) -> Option<<Q as QueryData>::Item<'_>>

where Q: ReadOnlyQueryData,

Returns read-only components for the current entity that match the query Q, or None if the entity does not have the components required by the query Q.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn into_borrow<T>(self) -> Option<&'w T>

where T: Component,

Consumes self and gets access to the component of type T with the world 'w lifetime for the current entity. Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn get_ref<T>(&self) -> Option<Ref<'_, T>>

where T: Component,

Gets access to the component of type T for the current entity, including change detection information as a Ref.

Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn into_ref<T>(self) -> Option<Ref<'w, T>>

where T: Component,

Consumes self and gets access to the component of type T with the world 'w lifetime for the current entity, including change detection information as a Ref.

Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

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

where T: Component<Mutability = Mutable>,

Gets mutable access to the component of type T for the current entity. Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Examples found in repository

examples/ecs/immutable_components.rs (line 36)

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

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

where T: Component,

Temporarily removes a Component T from this Entity and runs the provided closure on it, returning the result if T was available. This will trigger the OnRemove and OnReplace 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);

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

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

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

Temporarily removes a Component T from this Entity and runs the provided closure on it, returning the result if T was available. This will trigger the OnRemove and OnReplace 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.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub unsafe fn get_mut_assume_mutable<T>(&mut self) -> Option<Mut<'_, T>>

where T: Component,

Gets mutable access to the component of type T for the current entity. Returns None if the entity does not have a component of type T.

Safety

• T must be a mutable component

pub fn into_mut<T>(self) -> Option<Mut<'w, T>>

where T: Component<Mutability = Mutable>,

Consumes self and gets mutable access to the component of type T with the world 'w lifetime for the current entity. Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub unsafe fn into_mut_assume_mutable<T>(self) -> Option<Mut<'w, T>>

where T: Component,

Consumes self and gets mutable access to the component of type T with the world 'w lifetime for the current entity. Returns None if the entity does not have a component of type T.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Safety

• T must be a mutable component

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.

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.

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

where R: Resource,

Gets a reference 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

pub fn get_change_ticks<T>(&self) -> Option<ComponentTicks>

where T: Component,

Retrieves the change ticks for the given component. This can be useful for implementing change detection in custom runtimes.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn get_change_ticks_by_id( &self, component_id: ComponentId, ) -> Option<ComponentTicks>

Retrieves the change ticks for the given ComponentId. This can be useful for implementing change detection in custom runtimes.

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

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn get_by_id<F>( &self, component_ids: F, ) -> Result<<F as DynamicComponentFetch>::Ref<'_>, EntityComponentError>

where F: DynamicComponentFetch,

Returns untyped read-only reference(s) to component(s) for the current entity, based on the given ComponentIds.

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

Unlike EntityWorldMut::get, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

Returns EntityComponentError::MissingComponent if the entity does not have a component.

Examples

For examples on how to use this method, see EntityRef::get_by_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Examples found in repository

examples/ecs/immutable_components.rs (line 189)

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

            (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.
    }
}

pub fn into_borrow_by_id<F>( self, component_ids: F, ) -> Result<<F as DynamicComponentFetch>::Ref<'w>, EntityComponentError>

where F: DynamicComponentFetch,

Consumes self and returns untyped read-only reference(s) to component(s) with lifetime 'w for the current entity, based on the given ComponentIds.

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

Unlike EntityWorldMut::into_borrow, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

Returns EntityComponentError::MissingComponent if the entity does not have a component.

Examples

For examples on how to use this method, see EntityRef::get_by_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn get_mut_by_id<F>( &mut self, component_ids: F, ) -> Result<<F as DynamicComponentFetch>::Mut<'_>, EntityComponentError>

where F: DynamicComponentFetch,

Returns untyped mutable reference(s) to component(s) for the current entity, based on the given ComponentIds.

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

Unlike EntityWorldMut::get_mut, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

• Returns EntityComponentError::MissingComponent if the entity does not have a component.
• Returns EntityComponentError::AliasedMutability if a component is requested multiple times.

Examples

For examples on how to use this method, see EntityMut::get_mut_by_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Examples found in repository

examples/ecs/immutable_components.rs (line 192)

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

            (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.
    }
}

pub unsafe fn get_mut_assume_mutable_by_id<F>( &mut self, component_ids: F, ) -> Result<<F as DynamicComponentFetch>::Mut<'_>, EntityComponentError>

where F: DynamicComponentFetch,

Returns untyped mutable reference(s) to component(s) for the current entity, based on the given ComponentIds. Assumes the given ComponentIds refer to mutable components.

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

Unlike EntityWorldMut::get_mut_assume_mutable, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

• Returns EntityComponentError::MissingComponent if the entity does not have a component.
• Returns EntityComponentError::AliasedMutability if a component is requested multiple times.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Safety

It is the callers responsibility to ensure that

• the provided ComponentIds must refer to mutable components.

pub fn into_mut_by_id<F>( self, component_ids: F, ) -> Result<<F as DynamicComponentFetch>::Mut<'w>, EntityComponentError>

where F: DynamicComponentFetch,

Consumes self and returns untyped mutable reference(s) to component(s) with lifetime 'w for the current entity, based on the given ComponentIds.

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

Unlike EntityWorldMut::into_mut, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

• Returns EntityComponentError::MissingComponent if the entity does not have a component.
• Returns EntityComponentError::AliasedMutability if a component is requested multiple times.

Examples

For examples on how to use this method, see EntityMut::get_mut_by_id.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub unsafe fn into_mut_assume_mutable_by_id<F>( self, component_ids: F, ) -> Result<<F as DynamicComponentFetch>::Mut<'w>, EntityComponentError>

where F: DynamicComponentFetch,

Consumes self and returns untyped mutable reference(s) to component(s) with lifetime 'w for the current entity, based on the given ComponentIds. Assumes the given ComponentIds refer to mutable components.

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

Unlike EntityWorldMut::into_mut_assume_mutable, this returns untyped reference(s) to component(s), and it’s the job of the caller to ensure the correct type(s) are dereferenced (if necessary).

Errors

• Returns EntityComponentError::MissingComponent if the entity does not have a component.
• Returns EntityComponentError::AliasedMutability if a component is requested multiple times.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Safety

It is the callers responsibility to ensure that

• the provided ComponentIds must refer to mutable components.

pub fn insert<T>(&mut self, bundle: T) -> &mut EntityWorldMut<'w>

where T: Bundle,

Adds a Bundle of components to the entity.

This will overwrite any previous value(s) of the same component type.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Examples found in repository

examples/ecs/immutable_components.rs (line 46)

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_replace = on_replace_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!("OnInsert hook guarantees `Name` is available on entity")
    };
    let Some(mut index) = world.get_resource_mut::<NameIndex>() else {
        return;
    };

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

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

    index.name_to_entity.remove(&name);
}

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/async_tasks/async_compute.rs (lines 88-92)

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::thread_rng().gen_range(0.05..5.0));

                    // Pretend this is a time-intensive function. :)
                    async_std::task::sleep(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);

                            (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,
                            ))
                            // Task is complete, so remove task component from entity
                            .remove::<ComputeTransform>();
                    });

                    command_queue
                });

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

examples/games/game_menu.rs (line 602)

    fn display_settings_menu_setup(mut commands: Commands, display_quality: Res<DisplayQuality>) {
        fn button_node() -> Node {
            Node {
                width: Val::Px(200.0),
                height: Val::Px(65.0),
                margin: UiRect::all(Val::Px(20.0)),
                justify_content: JustifyContent::Center,
                align_items: AlignItems::Center,
                ..default()
            }
        }
        fn button_text_style() -> impl Bundle {
            (
                TextFont {
                    font_size: 33.0,
                    ..default()
                },
                TextColor(TEXT_COLOR),
            )
        }

        let display_quality = *display_quality;
        commands.spawn((
            Node {
                width: Val::Percent(100.0),
                height: Val::Percent(100.0),
                align_items: AlignItems::Center,
                justify_content: JustifyContent::Center,
                ..default()
            },
            OnDisplaySettingsMenuScreen,
            children![(
                Node {
                    flex_direction: FlexDirection::Column,
                    align_items: AlignItems::Center,
                    ..default()
                },
                BackgroundColor(CRIMSON.into()),
                children![
                    // Create a new `Node`, this time not setting its `flex_direction`. It will
                    // use the default value, `FlexDirection::Row`, from left to right.
                    (
                        Node {
                            align_items: AlignItems::Center,
                            ..default()
                        },
                        BackgroundColor(CRIMSON.into()),
                        Children::spawn((
                            // Display a label for the current setting
                            Spawn((Text::new("Display Quality"), button_text_style())),
                            SpawnWith(move |parent: &mut ChildSpawner| {
                                for quality_setting in [
                                    DisplayQuality::Low,
                                    DisplayQuality::Medium,
                                    DisplayQuality::High,
                                ] {
                                    let mut entity = parent.spawn((
                                        Button,
                                        Node {
                                            width: Val::Px(150.0),
                                            height: Val::Px(65.0),
                                            ..button_node()
                                        },
                                        BackgroundColor(NORMAL_BUTTON),
                                        quality_setting,
                                        children![(
                                            Text::new(format!("{quality_setting:?}")),
                                            button_text_style(),
                                        )],
                                    ));
                                    if display_quality == quality_setting {
                                        entity.insert(SelectedOption);
                                    }
                                }
                            })
                        ))
                    ),
                    // Display the back button to return to the settings screen
                    (
                        Button,
                        button_node(),
                        BackgroundColor(NORMAL_BUTTON),
                        MenuButtonAction::BackToSettings,
                        children![(Text::new("Back"), button_text_style())]
                    )
                ]
            )],
        ));
    }

    fn sound_settings_menu_setup(mut commands: Commands, volume: Res<Volume>) {
        let button_node = Node {
            width: Val::Px(200.0),
            height: Val::Px(65.0),
            margin: UiRect::all(Val::Px(20.0)),
            justify_content: JustifyContent::Center,
            align_items: AlignItems::Center,
            ..default()
        };
        let button_text_style = (
            TextFont {
                font_size: 33.0,
                ..default()
            },
            TextColor(TEXT_COLOR),
        );

        let volume = *volume;
        let button_node_clone = button_node.clone();
        commands.spawn((
            Node {
                width: Val::Percent(100.0),
                height: Val::Percent(100.0),
                align_items: AlignItems::Center,
                justify_content: JustifyContent::Center,
                ..default()
            },
            OnSoundSettingsMenuScreen,
            children![(
                Node {
                    flex_direction: FlexDirection::Column,
                    align_items: AlignItems::Center,
                    ..default()
                },
                BackgroundColor(CRIMSON.into()),
                children![
                    (
                        Node {
                            align_items: AlignItems::Center,
                            ..default()
                        },
                        BackgroundColor(CRIMSON.into()),
                        Children::spawn((
                            Spawn((Text::new("Volume"), button_text_style.clone())),
                            SpawnWith(move |parent: &mut ChildSpawner| {
                                for volume_setting in [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] {
                                    let mut entity = parent.spawn((
                                        Button,
                                        Node {
                                            width: Val::Px(30.0),
                                            height: Val::Px(65.0),
                                            ..button_node_clone.clone()
                                        },
                                        BackgroundColor(NORMAL_BUTTON),
                                        Volume(volume_setting),
                                    ));
                                    if volume == Volume(volume_setting) {
                                        entity.insert(SelectedOption);
                                    }
                                }
                            })
                        ))
                    ),
                    (
                        Button,
                        button_node,
                        BackgroundColor(NORMAL_BUTTON),
                        MenuButtonAction::BackToSettings,
                        children![(Text::new("Back"), button_text_style)]
                    )
                ]
            )],
        ));
    }

pub fn insert_with_relationship_hook_mode<T>( &mut self, bundle: T, relationship_hook_mode: RelationshipHookMode, ) -> &mut EntityWorldMut<'w>

where T: Bundle,

Adds a Bundle of components to the entity. Relationship components in the bundle will follow the configuration in relationship_hook_mode.

This will overwrite any previous value(s) of the same component type.

Warning

This can easily break the integrity of relationships. This is intended to be used for cloning and spawning code internals, not most user-facing scenarios.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn insert_if_new<T>(&mut self, bundle: T) -> &mut EntityWorldMut<'w>

where T: Bundle,

Adds a Bundle of components to the entity without overwriting.

This will leave any previous value(s) of the same component type unchanged.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub unsafe fn insert_by_id( &mut self, component_id: ComponentId, component: OwningPtr<'_>, ) -> &mut EntityWorldMut<'w>

Inserts a dynamic Component into the entity.

This will overwrite any previous value(s) of the same component type.

You should prefer to use the typed API EntityWorldMut::insert where possible.

Safety

• ComponentId must be from the same world as EntityWorldMut
• OwningPtr must be a valid reference to the type represented by ComponentId

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Examples found in repository

examples/ecs/immutable_components.rs (line 182)

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

            (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.
    }
}

pub unsafe fn insert_by_ids<'a, I>( &mut self, component_ids: &[ComponentId], iter_components: I, ) -> &mut EntityWorldMut<'w>

where I: Iterator<Item = OwningPtr<'a>>,

Inserts a dynamic Bundle into the entity.

This will overwrite any previous value(s) of the same component type.

You should prefer to use the typed API EntityWorldMut::insert where possible. If your Bundle only has one component, use the cached API EntityWorldMut::insert_by_id.

If possible, pass a sorted slice of ComponentId to maximize caching potential.

Safety

• Each ComponentId must be from the same world as EntityWorldMut
• Each OwningPtr must be a valid reference to the type represented by ComponentId

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Examples found in repository

examples/stress_tests/many_components.rs (line 156)

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

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

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

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

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

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

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

examples/ecs/dynamic.rs (line 148)

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

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

        if line.is_empty() {
            return;
        };

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

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

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

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

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

                let mut entity = world.spawn_empty();

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

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

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

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

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

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

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

pub fn take<T>(&mut self) -> Option<T>

where T: Bundle + BundleFromComponents,

Removes all components in the Bundle from the entity and returns their previous values.

Note: If the entity does not have every component in the bundle, this method will not remove any of them.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Examples found in repository

examples/ecs/immutable_components.rs (line 44)

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

pub fn remove<T>(&mut self) -> &mut EntityWorldMut<'w>

where T: Bundle,

Removes any components in the Bundle from the entity.

See EntityCommands::remove for more details.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

Examples found in repository

examples/async_tasks/async_compute.rs (line 94)

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::thread_rng().gen_range(0.05..5.0));

                    // Pretend this is a time-intensive function. :)
                    async_std::task::sleep(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);

                            (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,
                            ))
                            // Task is complete, so remove task component from entity
                            .remove::<ComputeTransform>();
                    });

                    command_queue
                });

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

pub fn remove_with_requires<T>(&mut self) -> &mut EntityWorldMut<'w>

where T: Bundle,

Removes all components in the Bundle and remove all required components for each component in the bundle

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn retain<T>(&mut self) -> &mut EntityWorldMut<'w>

where T: Bundle,

Removes any components except those in the Bundle (and its Required Components) from the entity.

See EntityCommands::retain for more details.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn remove_by_id( &mut self, component_id: ComponentId, ) -> &mut EntityWorldMut<'w>

Removes a dynamic Component from the entity if it exists.

You should prefer to use the typed API EntityWorldMut::remove where possible.

Panics

Panics if the provided ComponentId does not exist in the World or if the entity has been despawned while this EntityWorldMut is still alive.

pub fn remove_by_ids( &mut self, component_ids: &[ComponentId], ) -> &mut EntityWorldMut<'w>

Removes a dynamic bundle from the entity if it exists.

You should prefer to use the typed API EntityWorldMut::remove where possible.

Panics

Panics if any of the provided ComponentIds do not exist in the World or if the entity has been despawned while this EntityWorldMut is still alive.

pub fn clear(&mut self) -> &mut EntityWorldMut<'w>

Removes all components associated with the entity.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn despawn(self)

Despawns the current entity.

See World::despawn for more details.

Note

This will also despawn any Children entities, and any other RelationshipTarget that is configured to despawn descendants. This results in “recursive despawn” behavior.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn despawn_recursive(self)

👎Deprecated since 0.16.0: Use entity.despawn(), which now automatically despawns recursively.

Despawns the provided entity and its descendants.

pub fn flush(self) -> Entity

Ensures any commands triggered by the actions of Self are applied, equivalent to World::flush

pub fn world(&self) -> &World

Gets read-only access to the world that the current entity belongs to.

pub unsafe fn world_mut(&mut self) -> &mut World

Returns this entity’s world.

See EntityWorldMut::world_scope or EntityWorldMut::into_world_mut for a safe alternative.

Safety

Caller must not modify the world in a way that changes the current entity’s location If the caller does do something that could change the location, self.update_location() must be called before using any other methods on this EntityWorldMut.

pub fn into_world_mut(self) -> &'w mut World

Returns this entity’s World, consuming itself.

pub fn world_scope<U>(&mut self, f: impl FnOnce(&mut World) -> U) -> U

Gives mutable access to this entity’s World in a temporary scope. This is a safe alternative to using EntityWorldMut::world_mut.

Examples

#[derive(Resource, Default, Clone, Copy)]
struct R(u32);

// This closure gives us temporary access to the world.
let new_r = entity.world_scope(|world: &mut World| {
    // Mutate the world while we have access to it.
    let mut r = world.resource_mut::<R>();
    r.0 += 1;

    // Return a value from the world before giving it back to the `EntityWorldMut`.
    *r
});

pub fn update_location(&mut self)

Updates the internal entity location to match the current location in the internal World.

This is only required when using the unsafe function EntityWorldMut::world_mut, which enables the location to change.

pub fn is_despawned(&self) -> bool

Returns if the entity has been despawned.

Normally it shouldn’t be needed to explicitly check if the entity has been despawned between commands as this shouldn’t happen. However, for some special cases where it is known that a hook or an observer might despawn the entity while a EntityWorldMut reference is still held, this method can be used to check if the entity is still alive to avoid panicking when calling further methods.

pub fn entry<'a, T>(&'a mut self) -> Entry<'w, 'a, T>

where T: Component,

Gets an Entry into the world for this entity and component for in-place manipulation.

The type parameter specifies which component to get.

Examples

#[derive(Component, Default, Clone, Copy, Debug, PartialEq)]
struct Comp(u32);

let mut entity = world.spawn_empty();
entity.entry().or_insert_with(|| Comp(4));
assert_eq!(world.query::<&Comp>().single(&world).unwrap().0, 4);

entity.entry::<Comp>().and_modify(|mut c| c.0 += 1);
assert_eq!(world.query::<&Comp>().single(&world).unwrap().0, 5);

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn trigger(&mut self, event: impl Event) -> &mut EntityWorldMut<'w>

Triggers the given event for this entity, which will run any observers watching for it.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn observe<E, B, M>( &mut self, observer: impl IntoObserverSystem<E, B, M>, ) -> &mut EntityWorldMut<'w>

where E: Event, B: Bundle,

Creates an Observer listening for events of type E targeting this entity. In order to trigger the callback the entity must also match the query when the event is fired.

Panics

If the entity has been despawned while this EntityWorldMut is still alive.

pub fn clone_with( &mut self, target: Entity, config: impl FnOnce(&mut EntityClonerBuilder<'_>) + Send + Sync + 'static, ) -> &mut EntityWorldMut<'w>

Clones parts of an entity (components, observers, etc.) onto another entity, configured through EntityClonerBuilder.

By default, the other entity will receive all the components of the original that implement Clone or Reflect.

Configure through EntityClonerBuilder as follows:

world.entity_mut(entity).clone_with(target, |builder| {
    builder.deny::<ComponentB>();
});

See EntityClonerBuilder for more options.

Panics

• If this entity has been despawned while this EntityWorldMut is still alive.
• If the target entity does not exist.

pub fn clone_and_spawn(&mut self) -> Entity

Spawns a clone of this entity and returns the Entity of the clone.

The clone will receive all the components of the original that implement Clone or Reflect.

To configure cloning behavior (such as only cloning certain components), use EntityWorldMut::clone_and_spawn_with.

Panics

If this entity has been despawned while this EntityWorldMut is still alive.

pub fn clone_and_spawn_with( &mut self, config: impl FnOnce(&mut EntityClonerBuilder<'_>) + Send + Sync + 'static, ) -> Entity

Spawns a clone of this entity and allows configuring cloning behavior using EntityClonerBuilder, returning the Entity of the clone.

By default, the clone will receive all the components of the original that implement Clone or Reflect.

Configure through EntityClonerBuilder as follows:

let entity_clone = world.entity_mut(entity).clone_and_spawn_with(|builder| {
    builder.deny::<ComponentB>();
});

See EntityClonerBuilder for more options.

Panics

If this entity has been despawned while this EntityWorldMut is still alive.

pub fn clone_components<B>(&mut self, target: Entity) -> &mut EntityWorldMut<'w>

where B: Bundle,

Clones the specified components of this entity and inserts them into another entity.

Components can only be cloned if they implement Clone or Reflect.

Panics

• If this entity has been despawned while this EntityWorldMut is still alive.
• If the target entity does not exist.

pub fn move_components<B>(&mut self, target: Entity) -> &mut EntityWorldMut<'w>

where B: Bundle,

Clones the specified components of this entity and inserts them into another entity, then removes the components from this entity.

Components can only be cloned if they implement Clone or Reflect.

Panics

• If this entity has been despawned while this EntityWorldMut is still alive.
• If the target entity does not exist.

pub fn spawned_by(&self) -> MaybeLocation

Returns the source code location from which this entity has last been spawned.

Trait Implementations

impl BuildChildrenTransformExt for EntityWorldMut<'_>

fn set_parent_in_place(&mut self, parent: Entity) -> &mut EntityWorldMut<'_>

Change this entity’s parent while preserving this entity’s GlobalTransform by updating its Transform.

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

Make this entity parentless while preserving this entity’s GlobalTransform by updating its Transform to be equal to its current GlobalTransform.

impl<'a> From<&'a EntityWorldMut<'_>> for EntityRef<'a>

fn from(entity: &'a EntityWorldMut<'_>) -> EntityRef<'a>

Converts to this type from the input type.

impl<'a> From<&'a EntityWorldMut<'_>> for FilteredEntityRef<'a>

fn from(entity: &'a EntityWorldMut<'_>) -> FilteredEntityRef<'a>

Converts to this type from the input type.

impl<'a> From<&'a mut EntityWorldMut<'_>> for EntityMut<'a>

fn from(entity: &'a mut EntityWorldMut<'_>) -> EntityMut<'a>

Converts to this type from the input type.

impl<'a> From<&'a mut EntityWorldMut<'_>> for FilteredEntityMut<'a>

fn from(entity: &'a mut EntityWorldMut<'_>) -> FilteredEntityMut<'a>

Converts to this type from the input type.

impl<'a> From<EntityWorldMut<'a>> for FilteredEntityMut<'a>

fn from(entity: EntityWorldMut<'a>) -> FilteredEntityMut<'a>

Converts to this type from the input type.

impl<'a> From<EntityWorldMut<'a>> for FilteredEntityRef<'a>

fn from(entity: EntityWorldMut<'a>) -> FilteredEntityRef<'a>

Converts to this type from the input type.

impl<'w> From<EntityWorldMut<'w>> for EntityMut<'w>

fn from(entity: EntityWorldMut<'w>) -> EntityMut<'w>

Converts to this type from the input type.

impl<'w> From<EntityWorldMut<'w>> for EntityRef<'w>

fn from(entity: EntityWorldMut<'w>) -> EntityRef<'w>

Converts to this type from the input type.