Struct bevy_ecs::Commands

pub struct Commands { /* fields omitted */ }

A list of commands that will be run to populate a World and Resources.

Implementations

impl Commands

pub fn spawn(
    &mut self,
    bundle: impl DynamicBundle + Send + Sync + 'static
) -> &mut Self

Creates a new entity with the components contained in bundle.

Note that bundle is a DynamicBundle, which is a collection of components. DynamicBundle is automatically implemented for tuples of components. You can also create your own bundle types by deriving Bundle. If you would like to spawn an entity with a single component, consider wrapping the component in a tuple (which DynamicBundle is implemented for).

See Self::set_current_entity, Self::insert.

Example

use bevy_ecs::prelude::*;

struct Component1;
struct Component2;

#[derive(Bundle)]
struct ExampleBundle {
    a: Component1,
    b: Component2,
}

fn example_system(mut commands: Commands) {
    // Create a new entity with a component bundle.
    commands.spawn(ExampleBundle {
        a: Component1,
        b: Component2,
    });

    // Create a new entity with a single component.
    commands.spawn((Component1,));
    // Create a new entity with two components.
    commands.spawn((Component1, Component2));
}

pub fn spawn_batch<I>(&mut self, bundles_iter: I) -> &mut Self where
    I: IntoIterator + Send + Sync + 'static,
    I::Item: Bundle, 

Equivalent to iterating bundles_iter and calling Self::spawn on each bundle, but slightly more performant.

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

Despawns only the specified entity, not including its children.

pub fn insert(
    &mut self,
    entity: Entity,
    bundle: impl DynamicBundle + Send + Sync + 'static
) -> &mut Self

Inserts a bundle of components into entity.

See World::insert.

pub fn insert_one(
    &mut self,
    entity: Entity,
    component: impl Component
) -> &mut Self

Inserts a single component into entity.

See World::insert_one.

pub fn insert_resource<T: Resource>(&mut self, resource: T) -> &mut Self

pub fn insert_local_resource<T: Resource>(
    &mut self,
    system_id: SystemId,
    resource: T
) -> &mut Self

Insert a resource that is local to a specific system.

See crate::System::id.

pub fn remove_one<T>(&mut self, entity: Entity) -> &mut Self where
    T: Component, 

See World::remove_one.

pub fn remove<T>(&mut self, entity: Entity) -> &mut Self where
    T: Bundle + Send + Sync + 'static, 

See World::remove.

pub fn with_bundle(
    &mut self,
    bundle: impl DynamicBundle + Send + Sync + 'static
) -> &mut Self

Adds a bundle of components to the current entity.

See Self::with, Self::current_entity.

pub fn with(&mut self, component: impl Component) -> &mut Self

Adds a single component to the current entity.

See Self::with_bundle, Self::current_entity.

Warning

It's possible to call this with a bundle, but this is likely not intended and Self::with_bundle should be used instead. If with is called with a bundle, the bundle itself will be added as a component instead of the bundles' inner components each being added.

Example

with can be chained with Self::spawn.

use bevy_ecs::prelude::*;

struct Component1;
struct Component2;

fn example_system(mut commands: Commands) {
    // Create a new entity with a `Component1` and `Component2`.
    commands.spawn((Component1,)).with(Component2);

    // Psst! These are also equivalent to the line above!
    commands.spawn((Component1, Component2));
    commands.spawn(()).with(Component1).with(Component2);
    #[derive(Bundle)]
    struct ExampleBundle {
        a: Component1,
        b: Component2,
    }
    commands.spawn(()).with_bundle(ExampleBundle {
        a: Component1,
        b: Component2,
    });
}

pub fn add_command<C: Command + 'static>(&mut self, command: C) -> &mut Self

Adds a command directly to the command list. Prefer this to Self::add_command_boxed if the type of command is statically known.

pub fn add_command_boxed(&mut self, command: Box<dyn Command>) -> &mut Self

See Self::add_command.

pub fn apply(&mut self, world: &mut World, resources: &mut Resources)

Runs all the stored commands on world and resources. The command buffer is emptied as a part of this call.

pub fn current_entity(&self) -> Option<Entity>

Returns the current entity, set by Self::spawn or with Self::set_current_entity.

pub fn set_current_entity(&mut self, entity: Entity)

pub fn clear_current_entity(&mut self)

pub fn for_current_entity(&mut self, f: impl FnOnce(Entity)) -> &mut Self

pub fn set_entity_reserver(&mut self, entity_reserver: EntityReserver)

Trait Implementations

impl Default for Commands

pub fn default() -> Commands

Returns the "default value" for a type.

impl<'a> SystemParam for &'a mut Commands

type Fetch = FetchCommands