Struct Commands 

pub struct Commands<'w, 's> { /* private fields */ }

A Command queue to perform structural changes to the World.

Since each command requires exclusive access to the World, all queued commands are automatically applied in sequence when the ApplyDeferred system runs (see ApplyDeferred documentation for more details).

Each command can be used to modify the World in arbitrary ways:

• spawning or despawning entities
• inserting components on new or existing entities
• inserting resources
• etc.

For a version of Commands that works in parallel contexts (such as within Query::par_iter) see ParallelCommands

Usage

Add mut commands: Commands as a function argument to your system to get a copy of this struct that will be applied the next time a copy of ApplyDeferred runs. Commands are almost always used as a SystemParam.

fn my_system(mut commands: Commands) {
   // ...
}

Implementing

Each built-in command is implemented as a separate method, e.g. Commands::spawn. In addition to the pre-defined command methods, you can add commands with any arbitrary behavior using Commands::queue, which accepts any type implementing Command.

Since closures and other functions implement this trait automatically, this allows one-shot, anonymous custom commands.

// NOTE: type inference fails here, so annotations are required on the closure.
commands.queue(|w: &mut World| {
    // Mutate the world however you want...
});

Error handling

A Command can return a Result, which will be passed to an error handler if the Result is an error.

The default error handler panics. It can be configured via the DefaultErrorHandler resource.

Alternatively, you can customize the error handler for a specific command by calling Commands::queue_handled.

The error module provides some simple error handlers for convenience.

Implementations

impl<'w, 's> Commands<'w, 's>

pub fn new(queue: &'s mut CommandQueue, world: &'w World) -> Commands<'w, 's>

Returns a new Commands instance from a CommandQueue and a World.

pub fn new_from_entities( queue: &'s mut CommandQueue, allocator: &'w EntityAllocator, entities: &'w Entities, ) -> Commands<'w, 's>

Returns a new Commands instance from a CommandQueue and an Entities reference.

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

Returns a Commands with a smaller lifetime.

This is useful if you have &mut Commands but need Commands.

Example

fn my_system(mut commands: Commands) {
    // We do our initialization in a separate function,
    // which expects an owned `Commands`.
    do_initialization(commands.reborrow());

    // Since we only reborrowed the commands instead of moving them, we can still use them.
    commands.spawn_empty();
}

pub fn append(&mut self, other: &mut CommandQueue)

Take all commands from other and append them to self, leaving other empty.

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

Spawns a new empty Entity and returns its corresponding EntityCommands.

Example

#[derive(Component)]
struct Label(&'static str);
#[derive(Component)]
struct Strength(u32);
#[derive(Component)]
struct Agility(u32);

fn example_system(mut commands: Commands) {
    // Create a new empty entity.
    commands.spawn_empty();

    // Create another empty entity.
    commands.spawn_empty()
        // Add a new component bundle to the entity.
        .insert((Strength(1), Agility(2)))
        // Add a single component to the entity.
        .insert(Label("hello world"));
}

See also

• spawn to spawn an entity with components.
• spawn_batch to spawn many entities with the same combination of components.

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

where T: Bundle,

Spawns a new Entity with the given components and returns the entity’s corresponding EntityCommands.

To spawn many entities with the same combination of components, spawn_batch can be used for better performance.

Example

#[derive(Component)]
struct ComponentA(u32);
#[derive(Component)]
struct ComponentB(u32);

#[derive(Bundle)]
struct ExampleBundle {
    a: ComponentA,
    b: ComponentB,
}

fn example_system(mut commands: Commands) {
    // Create a new entity with a single component.
    commands.spawn(ComponentA(1));

    // Create a new entity with two components using a "tuple bundle".
    commands.spawn((ComponentA(2), ComponentB(1)));

    // Create a new entity with a component bundle.
    commands.spawn(ExampleBundle {
        a: ComponentA(3),
        b: ComponentB(2),
    });
}

See also

• spawn_empty to spawn an entity without any components.
• spawn_batch to spawn many entities with the same combination of components.

Examples found in repository

examples/ecs/system_param.rs (line 37)

fn spawn(mut commands: Commands) {
    commands.spawn(Player);
    commands.spawn(Player);
    commands.spawn(Player);
}

examples/audio/audio.rs (lines 14-16)

fn setup(asset_server: Res<AssetServer>, mut commands: Commands) {
    commands.spawn(AudioPlayer::new(
        asset_server.load("sounds/Windless Slopes.ogg"),
    ));
}

examples/window/transparent_window.rs (line 34)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2d);
    commands.spawn(Sprite::from_image(asset_server.load("branding/icon.png")));
}

examples/2d/move_sprite.rs (line 20)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2d);

    commands.spawn((
        Sprite::from_image(asset_server.load("branding/icon.png")),
        Transform::from_xyz(0., 0., 0.),
        Direction::Right,
    ));
}

examples/app/logs.rs (line 21)

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);
    commands.spawn((
        Text::new("Press P to panic"),
        Node {
            position_type: PositionType::Absolute,
            top: px(12),
            left: px(12),
            ..default()
        },
    ));
}

examples/asset/web_asset.rs (line 18)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2d);
    let url = "https://raw.githubusercontent.com/bevyengine/bevy/refs/heads/main/assets/branding/bevy_bird_dark.png";
    // Simply use a url where you would normally use an asset folder relative path
    commands.spawn(Sprite::from_image(asset_server.load(url)));
}

Additional examples can be found in:

• examples/window/screenshot.rs
• examples/gltf/gltf_skinned_mesh.rs
• examples/2d/sprite_tile.rs
• examples/shader/shader_material_2d.rs
• examples/shader/shader_material_wesl.rs
• examples/shader/fallback_image.rs
• examples/dev_tools/fps_overlay.rs
• examples/shader/shader_material.rs
• examples/shader/shader_material_glsl.rs
• examples/asset/extra_source.rs
• examples/ui/window_fallthrough.rs
• examples/asset/hot_asset_reloading.rs
• examples/audio/audio_control.rs
• examples/shader_advanced/custom_vertex_attribute.rs
• examples/ui/font_atlas_debug.rs
• examples/gltf/load_gltf_extras.rs
• examples/asset/embedded_asset.rs
• examples/window/scale_factor_override.rs
• examples/2d/sprite_sheet.rs
• examples/3d/parenting.rs
• examples/remote/server.rs
• examples/3d/animated_material.rs
• examples/gltf/load_gltf.rs
• examples/gltf/update_gltf_scene.rs
• examples/shader/storage_buffer.rs
• examples/ui/virtual_keyboard.rs
• examples/3d/vertex_colors.rs
• examples/3d/spherical_area_lights.rs
• examples/2d/bloom_2d.rs
• examples/ui/ui_texture_slice.rs
• examples/ui/ui_texture_slice_flip_and_tile.rs
• examples/picking/dragdrop_picking.rs
• examples/ui/ui_texture_atlas_slice.rs
• examples/2d/mesh2d_alpha_mode.rs
• examples/asset/asset_settings.rs
• examples/2d/mesh2d_repeated_texture.rs
• examples/ui/tab_navigation.rs
• examples/ui/z_index.rs
• examples/ui/ui_drag_and_drop.rs
• examples/animation/animated_transform.rs

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

Returns the EntityCommands for the given Entity.

This method does not guarantee that commands queued by the returned EntityCommands will be successful, since the entity could be despawned before they are executed.

Example

#[derive(Resource)]
struct PlayerEntity {
    entity: Entity
}

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

fn example_system(mut commands: Commands, player: Res<PlayerEntity>) {
    // Get the entity and add a component.
    commands.entity(player.entity).insert(Label("hello world"));
}

See also

• get_entity for the fallible version.

Examples found in repository

examples/remote/server.rs (line 86)

fn remove(mut commands: Commands, cube_entity: Single<Entity, With<Cube>>) {
    commands.entity(*cube_entity).remove::<Cube>();
}

examples/window/screenshot.rs (line 38)

fn screenshot_saving(
    mut commands: Commands,
    screenshot_saving: Query<Entity, With<Capturing>>,
    window: Single<Entity, With<Window>>,
) {
    match screenshot_saving.iter().count() {
        0 => {
            commands.entity(*window).remove::<CursorIcon>();
        }
        x if x > 0 => {
            commands
                .entity(*window)
                .insert(CursorIcon::from(SystemCursorIcon::Progress));
        }
        _ => {}
    }
}

examples/ui/tab_navigation.rs (line 56)

fn focus_system(
    mut commands: Commands,
    focus: Res<InputFocus>,
    mut query: Query<Entity, With<Button>>,
) {
    if focus.is_changed() {
        for button in query.iter_mut() {
            if focus.0 == Some(button) {
                commands.entity(button).insert(Outline {
                    color: Color::WHITE,
                    width: px(2),
                    offset: px(2),
                });
            } else {
                commands.entity(button).remove::<Outline>();
            }
        }
    }
}

examples/picking/dragdrop_picking.rs (line 147)

fn on_drag_drop(
    mut event: On<Pointer<DragDrop>>,
    button: Single<Entity, With<DraggableButton>>,
    mut commands: Commands,
    ghost: Single<Entity, With<GhostPreview>>,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<ColorMaterial>>,
) {
    if event.dropped == *button {
        commands.entity(*ghost).despawn();
        let Some(position) = event.hit.position else {
            return;
        };
        commands.spawn((
            DroppedElement,
            Mesh2d(meshes.add(Circle::new(ELEMENT_SIZE))),
            MeshMaterial2d(materials.add(Color::srgb(1.0, 1.0, 0.6))),
            Transform::from_translation(position + 2. * Vec3::Z),
            Pickable::IGNORE,
        ));
        event.propagate(false);
    }
}

fn on_drag_leave(
    mut event: On<Pointer<DragLeave>>,
    button: Single<Entity, With<DraggableButton>>,
    mut commands: Commands,
    ghost: Single<Entity, With<GhostPreview>>,
) {
    if event.dragged == *button {
        commands.entity(*ghost).despawn();
        event.propagate(false);
    }
}

examples/2d/bloom_2d.rs (line 115)

fn update_bloom_settings(
    camera: Single<(Entity, &Tonemapping, Option<&mut Bloom>), With<Camera>>,
    mut text: Single<&mut Text>,
    mut commands: Commands,
    keycode: Res<ButtonInput<KeyCode>>,
    time: Res<Time>,
) {
    let (camera_entity, tonemapping, bloom) = camera.into_inner();

    match bloom {
        Some(mut bloom) => {
            text.0 = "Bloom (Toggle: Space)\n".to_string();
            text.push_str(&format!("(Q/A) Intensity: {:.2}\n", bloom.intensity));
            text.push_str(&format!(
                "(W/S) Low-frequency boost: {:.2}\n",
                bloom.low_frequency_boost
            ));
            text.push_str(&format!(
                "(E/D) Low-frequency boost curvature: {:.2}\n",
                bloom.low_frequency_boost_curvature
            ));
            text.push_str(&format!(
                "(R/F) High-pass frequency: {:.2}\n",
                bloom.high_pass_frequency
            ));
            text.push_str(&format!(
                "(T/G) Mode: {}\n",
                match bloom.composite_mode {
                    BloomCompositeMode::EnergyConserving => "Energy-conserving",
                    BloomCompositeMode::Additive => "Additive",
                }
            ));
            text.push_str(&format!(
                "(Y/H) Threshold: {:.2}\n",
                bloom.prefilter.threshold
            ));
            text.push_str(&format!(
                "(U/J) Threshold softness: {:.2}\n",
                bloom.prefilter.threshold_softness
            ));
            text.push_str(&format!("(I/K) Horizontal Scale: {:.2}\n", bloom.scale.x));

            if keycode.just_pressed(KeyCode::Space) {
                commands.entity(camera_entity).remove::<Bloom>();
            }

            let dt = time.delta_secs();

            if keycode.pressed(KeyCode::KeyA) {
                bloom.intensity -= dt / 10.0;
            }
            if keycode.pressed(KeyCode::KeyQ) {
                bloom.intensity += dt / 10.0;
            }
            bloom.intensity = bloom.intensity.clamp(0.0, 1.0);

            if keycode.pressed(KeyCode::KeyS) {
                bloom.low_frequency_boost -= dt / 10.0;
            }
            if keycode.pressed(KeyCode::KeyW) {
                bloom.low_frequency_boost += dt / 10.0;
            }
            bloom.low_frequency_boost = bloom.low_frequency_boost.clamp(0.0, 1.0);

            if keycode.pressed(KeyCode::KeyD) {
                bloom.low_frequency_boost_curvature -= dt / 10.0;
            }
            if keycode.pressed(KeyCode::KeyE) {
                bloom.low_frequency_boost_curvature += dt / 10.0;
            }
            bloom.low_frequency_boost_curvature =
                bloom.low_frequency_boost_curvature.clamp(0.0, 1.0);

            if keycode.pressed(KeyCode::KeyF) {
                bloom.high_pass_frequency -= dt / 10.0;
            }
            if keycode.pressed(KeyCode::KeyR) {
                bloom.high_pass_frequency += dt / 10.0;
            }
            bloom.high_pass_frequency = bloom.high_pass_frequency.clamp(0.0, 1.0);

            if keycode.pressed(KeyCode::KeyG) {
                bloom.composite_mode = BloomCompositeMode::Additive;
            }
            if keycode.pressed(KeyCode::KeyT) {
                bloom.composite_mode = BloomCompositeMode::EnergyConserving;
            }

            if keycode.pressed(KeyCode::KeyH) {
                bloom.prefilter.threshold -= dt;
            }
            if keycode.pressed(KeyCode::KeyY) {
                bloom.prefilter.threshold += dt;
            }
            bloom.prefilter.threshold = bloom.prefilter.threshold.max(0.0);

            if keycode.pressed(KeyCode::KeyJ) {
                bloom.prefilter.threshold_softness -= dt / 10.0;
            }
            if keycode.pressed(KeyCode::KeyU) {
                bloom.prefilter.threshold_softness += dt / 10.0;
            }
            bloom.prefilter.threshold_softness = bloom.prefilter.threshold_softness.clamp(0.0, 1.0);

            if keycode.pressed(KeyCode::KeyK) {
                bloom.scale.x -= dt * 2.0;
            }
            if keycode.pressed(KeyCode::KeyI) {
                bloom.scale.x += dt * 2.0;
            }
            bloom.scale.x = bloom.scale.x.clamp(0.0, 16.0);
        }

        None => {
            text.0 = "Bloom: Off (Toggle: Space)\n".to_string();

            if keycode.just_pressed(KeyCode::Space) {
                commands.entity(camera_entity).insert(Bloom::default());
            }
        }
    }

    text.push_str(&format!("(O) Tonemapping: {tonemapping:?}\n"));
    if keycode.just_pressed(KeyCode::KeyO) {
        commands
            .entity(camera_entity)
            .insert(next_tonemap(tonemapping));
    }
}

examples/animation/animated_transform.rs (line 154)

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
    mut animations: ResMut<Assets<AnimationClip>>,
    mut graphs: ResMut<Assets<AnimationGraph>>,
) {
    // Camera
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(-2.0, 2.5, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));

    // Light
    commands.spawn((
        PointLight {
            intensity: 500_000.0,
            ..default()
        },
        Transform::from_xyz(0.0, 2.5, 0.0),
    ));

    // Let's use the `Name` component to target entities. We can use anything we
    // like, but names are convenient.
    let planet = Name::new("planet");
    let orbit_controller = Name::new("orbit_controller");
    let satellite = Name::new("satellite");

    // Creating the animation
    let mut animation = AnimationClip::default();
    // A curve can modify a single part of a transform: here, the translation.
    let planet_animation_target_id = AnimationTargetId::from_name(&planet);
    animation.add_curve_to_target(
        planet_animation_target_id,
        AnimatableCurve::new(
            animated_field!(Transform::translation),
            UnevenSampleAutoCurve::new([0.0, 1.0, 2.0, 3.0, 4.0].into_iter().zip([
                Vec3::new(1.0, 0.0, 1.0),
                Vec3::new(-1.0, 0.0, 1.0),
                Vec3::new(-1.0, 0.0, -1.0),
                Vec3::new(1.0, 0.0, -1.0),
                // in case seamless looping is wanted, the last keyframe should
                // be the same as the first one
                Vec3::new(1.0, 0.0, 1.0),
            ]))
            .expect("should be able to build translation curve because we pass in valid samples"),
        ),
    );
    // Or it can modify the rotation of the transform.
    // To find the entity to modify, the hierarchy will be traversed looking for
    // an entity with the right name at each level.
    let orbit_controller_animation_target_id =
        AnimationTargetId::from_names([planet.clone(), orbit_controller.clone()].iter());
    animation.add_curve_to_target(
        orbit_controller_animation_target_id,
        AnimatableCurve::new(
            animated_field!(Transform::rotation),
            UnevenSampleAutoCurve::new([0.0, 1.0, 2.0, 3.0, 4.0].into_iter().zip([
                Quat::IDENTITY,
                Quat::from_axis_angle(Vec3::Y, PI / 2.),
                Quat::from_axis_angle(Vec3::Y, PI / 2. * 2.),
                Quat::from_axis_angle(Vec3::Y, PI / 2. * 3.),
                Quat::IDENTITY,
            ]))
            .expect("Failed to build rotation curve"),
        ),
    );
    // If a curve in an animation is shorter than the other, it will not repeat
    // until all other curves are finished. In that case, another animation should
    // be created for each part that would have a different duration / period.
    let satellite_animation_target_id = AnimationTargetId::from_names(
        [planet.clone(), orbit_controller.clone(), satellite.clone()].iter(),
    );
    animation.add_curve_to_target(
        satellite_animation_target_id,
        AnimatableCurve::new(
            animated_field!(Transform::scale),
            UnevenSampleAutoCurve::new(
                [0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0]
                    .into_iter()
                    .zip([
                        Vec3::splat(0.8),
                        Vec3::splat(1.2),
                        Vec3::splat(0.8),
                        Vec3::splat(1.2),
                        Vec3::splat(0.8),
                        Vec3::splat(1.2),
                        Vec3::splat(0.8),
                        Vec3::splat(1.2),
                        Vec3::splat(0.8),
                    ]),
            )
            .expect("Failed to build scale curve"),
        ),
    );
    // There can be more than one curve targeting the same entity path.
    animation.add_curve_to_target(
        AnimationTargetId::from_names(
            [planet.clone(), orbit_controller.clone(), satellite.clone()].iter(),
        ),
        AnimatableCurve::new(
            animated_field!(Transform::rotation),
            UnevenSampleAutoCurve::new([0.0, 1.0, 2.0, 3.0, 4.0].into_iter().zip([
                Quat::IDENTITY,
                Quat::from_axis_angle(Vec3::Y, PI / 2.),
                Quat::from_axis_angle(Vec3::Y, PI / 2. * 2.),
                Quat::from_axis_angle(Vec3::Y, PI / 2. * 3.),
                Quat::IDENTITY,
            ]))
            .expect("should be able to build translation curve because we pass in valid samples"),
        ),
    );

    // Create the animation graph
    let (graph, animation_index) = AnimationGraph::from_clip(animations.add(animation));

    // Create the animation player, and set it to repeat
    let mut player = AnimationPlayer::default();
    player.play(animation_index).repeat();

    // Create the scene that will be animated
    // First entity is the planet
    let planet_entity = commands
        .spawn((
            Mesh3d(meshes.add(Sphere::default())),
            MeshMaterial3d(materials.add(Color::srgb(0.8, 0.7, 0.6))),
            // Add the animation graph and player
            planet,
            AnimationGraphHandle(graphs.add(graph)),
            player,
        ))
        .id();
    commands.entity(planet_entity).insert((
        planet_animation_target_id,
        AnimatedBy(planet_entity),
        children![(
            Transform::default(),
            Visibility::default(),
            orbit_controller,
            orbit_controller_animation_target_id,
            AnimatedBy(planet_entity),
            children![(
                Mesh3d(meshes.add(Cuboid::new(0.5, 0.5, 0.5))),
                MeshMaterial3d(materials.add(Color::srgb(0.3, 0.9, 0.3))),
                Transform::from_xyz(1.5, 0.0, 0.0),
                satellite_animation_target_id,
                AnimatedBy(planet_entity),
                satellite,
            )],
        )],
    ));
}

pub fn get_entity( &mut self, entity: Entity, ) -> Result<EntityCommands<'_>, InvalidEntityError>

Returns the EntityCommands for the requested Entity if it is valid. This method does not guarantee that commands queued by the returned EntityCommands will be successful, since the entity could be despawned before they are executed. This also does not error when the entity has not been spawned. For that behavior, see get_spawned_entity, which should be preferred for accessing entities you expect to already be spawned, like those found from a query. For details on entity spawning vs validity, see entity module docs.

Errors

Returns InvalidEntityError if the requested entity does not exist.

Example

#[derive(Resource)]
struct PlayerEntity {
    entity: Entity
}

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

fn example_system(mut commands: Commands, player: Res<PlayerEntity>) -> Result {
    // Get the entity if it still exists and store the `EntityCommands`.
    // If it doesn't exist, the `?` operator will propagate the returned error
    // to the system, and the system will pass it to an error handler.
    let mut entity_commands = commands.get_entity(player.entity)?;

    // Add a component to the entity.
    entity_commands.insert(Label("hello world"));

    // Return from the system successfully.
    Ok(())
}

See also

• entity for the infallible version.

pub fn get_spawned_entity( &mut self, entity: Entity, ) -> Result<EntityCommands<'_>, EntityNotSpawnedError>

Returns the EntityCommands for the requested Entity if it spawned in the world now. Note that for entities that have not been spawned yet, like ones from spawn, this will error. If that is not desired, try get_entity. This should be used over get_entity when you expect the entity to already be spawned in the world. If the entity is valid but not yet spawned, this will error that information, where get_entity would succeed, leading to potentially surprising results. For details on entity spawning vs validity, see entity module docs.

This method does not guarantee that commands queued by the returned EntityCommands will be successful, since the entity could be despawned before they are executed.

Errors

Returns EntityNotSpawnedError if the requested entity does not exist.

Example

#[derive(Resource)]
struct PlayerEntity {
    entity: Entity
}

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

fn example_system(mut commands: Commands, player: Res<PlayerEntity>) -> Result {
    // Get the entity if it still exists and store the `EntityCommands`.
    // If it doesn't exist, the `?` operator will propagate the returned error
    // to the system, and the system will pass it to an error handler.
    let mut entity_commands = commands.get_spawned_entity(player.entity)?;

    // Add a component to the entity.
    entity_commands.insert(Label("hello world"));

    // Return from the system successfully.
    Ok(())
}

See also

• entity for the infallible version.

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

where I: IntoIterator + Send + Sync + 'static, <I as IntoIterator>::Item: Bundle, <<I as IntoIterator>::Item as DynamicBundle>::Effect: NoBundleEffect,

Spawns multiple entities with the same combination of components, based on a batch of Bundles.

A batch can be any type that implements IntoIterator and contains bundles, such as a Vec<Bundle> or an array [Bundle; N].

This method is equivalent to iterating the batch and calling spawn for each bundle, but is faster by pre-allocating memory and having exclusive World access.

Example

use bevy_ecs::prelude::*;

#[derive(Component)]
struct Score(u32);

fn example_system(mut commands: Commands) {
    commands.spawn_batch([
        (Name::new("Alice"), Score(0)),
        (Name::new("Bob"), Score(0)),
    ]);
}

See also

• spawn to spawn an entity with components.
• spawn_empty to spawn an entity without components.

pub fn queue<C, T>(&mut self, command: C)

where C: Command<T> + HandleError<T>,

Pushes a generic Command to the command queue.

If the Command returns a Result, it will be handled using the default error handler.

To use a custom error handler, see Commands::queue_handled.

The command can be:

• A custom struct that implements Command.
• A closure or function that matches one of the following signatures:
  • (&mut World)
• A built-in command from the command module.

Example

#[derive(Resource, Default)]
struct Counter(u64);

struct AddToCounter(String);

impl Command<Result> for AddToCounter {
    fn apply(self, world: &mut World) -> Result {
        let mut counter = world.get_resource_or_insert_with(Counter::default);
        let amount: u64 = self.0.parse()?;
        counter.0 += amount;
        Ok(())
    }
}

fn add_three_to_counter_system(mut commands: Commands) {
    commands.queue(AddToCounter("3".to_string()));
}

fn add_twenty_five_to_counter_system(mut commands: Commands) {
    commands.queue(|world: &mut World| {
        let mut counter = world.get_resource_or_insert_with(Counter::default);
        counter.0 += 25;
    });
}

pub fn queue_handled<C, T>( &mut self, command: C, error_handler: fn(BevyError, ErrorContext), )

where C: Command<T> + HandleError<T>,

Pushes a generic Command to the command queue.

If the Command returns a Result, the given error_handler will be used to handle error cases.

To implicitly use the default error handler, see Commands::queue.

The command can be:

• A custom struct that implements Command.
• A closure or function that matches one of the following signatures:
  • (&mut World)
  • (&mut World) -> Result
• A built-in command from the command module.

Example

use bevy_ecs::error::warn;

#[derive(Resource, Default)]
struct Counter(u64);

struct AddToCounter(String);

impl Command<Result> for AddToCounter {
    fn apply(self, world: &mut World) -> Result {
        let mut counter = world.get_resource_or_insert_with(Counter::default);
        let amount: u64 = self.0.parse()?;
        counter.0 += amount;
        Ok(())
    }
}

fn add_three_to_counter_system(mut commands: Commands) {
    commands.queue_handled(AddToCounter("3".to_string()), warn);
}

fn add_twenty_five_to_counter_system(mut commands: Commands) {
    commands.queue(|world: &mut World| {
        let mut counter = world.get_resource_or_insert_with(Counter::default);
        counter.0 += 25;
    });
}

pub fn queue_silenced<C, T>(&mut self, command: C)

where C: Command<T> + HandleError<T>,

Pushes a generic Command to the queue like Commands::queue_handled, but instead silently ignores any errors.

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

where I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static, B: Bundle, <B as DynamicBundle>::Effect: NoBundleEffect,

Adds a series of Bundles to each Entity they are paired with, based on a batch of (Entity, Bundle) pairs.

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

This will overwrite any pre-existing components shared by the Bundle type. Use Commands::insert_batch_if_new to keep the pre-existing components instead.

This method is equivalent to iterating the batch and calling insert for each pair, but is faster by caching data that is shared between entities.

Fallible

This command will fail if any of the given entities do not exist.

It will internally return a TryInsertBatchError, which will be handled by the default error handler.

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

where I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static, B: Bundle, <B as DynamicBundle>::Effect: NoBundleEffect,

Adds a series of Bundles to each Entity they are paired with, based on a batch of (Entity, Bundle) pairs.

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

This will keep any pre-existing components shared by the Bundle type and discard the new values. Use Commands::insert_batch to overwrite the pre-existing components instead.

This method is equivalent to iterating the batch and calling insert_if_new for each pair, but is faster by caching data that is shared between entities.

Fallible

This command will fail if any of the given entities do not exist.

It will internally return a TryInsertBatchError, which will be handled by the default error handler.

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

where I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static, B: Bundle, <B as DynamicBundle>::Effect: NoBundleEffect,

Adds a series of Bundles to each Entity they are paired with, based on a batch of (Entity, Bundle) pairs.

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

This will overwrite any pre-existing components shared by the Bundle type. Use Commands::try_insert_batch_if_new to keep the pre-existing components instead.

This method is equivalent to iterating the batch and calling insert for each pair, but is faster by caching data that is shared between entities.

Fallible

This command will fail if any of the given entities do not exist.

It will internally return a TryInsertBatchError, which will be handled by logging the error at the warn level.

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

where I: IntoIterator<Item = (Entity, B)> + Send + Sync + 'static, B: Bundle, <B as DynamicBundle>::Effect: NoBundleEffect,

Adds a series of Bundles to each Entity they are paired with, based on a batch of (Entity, Bundle) pairs.

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

This will keep any pre-existing components shared by the Bundle type and discard the new values. Use Commands::try_insert_batch to overwrite the pre-existing components instead.

This method is equivalent to iterating the batch and calling insert_if_new for each pair, but is faster by caching data that is shared between entities.

Fallible

This command will fail if any of the given entities do not exist.

It will internally return a TryInsertBatchError, which will be handled by logging the error at the warn level.

pub fn init_resource<R>(&mut self)

where R: Resource + FromWorld,

Inserts a Resource into the World with an inferred value.

The inferred value is determined by the FromWorld trait of the resource. Note that any resource with the Default trait automatically implements FromWorld, and those default values will be used.

If the resource already exists when the command is applied, nothing happens.

Example

#[derive(Resource, Default)]
struct Scoreboard {
    current_score: u32,
    high_score: u32,
}

fn initialize_scoreboard(mut commands: Commands) {
    commands.init_resource::<Scoreboard>();
}

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

where R: Resource,

Inserts a Resource into the World with a specific value.

This will overwrite any previous value of the same resource type.

Example

#[derive(Resource)]
struct Scoreboard {
    current_score: u32,
    high_score: u32,
}

fn system(mut commands: Commands) {
    commands.insert_resource(Scoreboard {
        current_score: 0,
        high_score: 0,
    });
}

Examples found in repository

examples/2d/sprite_tile.rs (lines 24-29)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2d);

    commands.insert_resource(AnimationState {
        min: 128.0,
        max: 512.0,
        current: 128.0,
        speed: 50.0,
    });
    commands.spawn(Sprite {
        image: asset_server.load("branding/icon.png"),
        image_mode: SpriteImageMode::Tiled {
            tile_x: true,
            tile_y: true,
            stretch_value: 0.5, // The image will tile every 128px
        },
        ..default()
    });
}

examples/remote/server.rs (lines 47-50)

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    // circular base
    commands.spawn((
        Mesh3d(meshes.add(Circle::new(4.0))),
        MeshMaterial3d(materials.add(Color::WHITE)),
        Transform::from_rotation(Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2)),
    ));

    // cube
    commands.spawn((
        Mesh3d(meshes.add(Cuboid::new(1.0, 1.0, 1.0))),
        MeshMaterial3d(materials.add(Color::srgb_u8(124, 144, 255))),
        Transform::from_xyz(0.0, 0.5, 0.0),
        Cube(1.0),
    ));

    // test resource
    commands.insert_resource(TestResource {
        foo: Vec2::new(1.0, -1.0),
        bar: false,
    });

    // light
    commands.spawn((
        PointLight {
            shadows_enabled: true,
            ..default()
        },
        Transform::from_xyz(4.0, 8.0, 4.0),
    ));

    // camera
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(-2.5, 4.5, 9.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));
}

examples/ui/font_atlas_debug.rs (line 109)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>, mut state: ResMut<State>) {
    let font_handle = asset_server.load("fonts/FiraSans-Bold.ttf");
    state.handle = font_handle.clone();
    commands.spawn(Camera2d);
    commands
        .spawn((
            Node {
                position_type: PositionType::Absolute,
                bottom: Val::ZERO,
                ..default()
            },
            BackgroundColor(Color::NONE),
        ))
        .with_children(|parent| {
            parent.spawn((
                Text::new("a"),
                TextFont {
                    font: font_handle,
                    font_size: 50.0,
                    ..default()
                },
                TextColor(YELLOW.into()),
            ));
        });
    // We're seeding the PRNG here to make this example deterministic for testing purposes.
    // This isn't strictly required in practical use unless you need your app to be deterministic.
    commands.insert_resource(SeededRng(ChaCha8Rng::seed_from_u64(19878367467713)));
}

examples/shader/storage_buffer.rs (line 44)

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut buffers: ResMut<Assets<ShaderStorageBuffer>>,
    mut materials: ResMut<Assets<CustomMaterial>>,
) {
    // Example data for the storage buffer
    let color_data: Vec<[f32; 4]> = vec![
        [1.0, 0.0, 0.0, 1.0],
        [0.0, 1.0, 0.0, 1.0],
        [0.0, 0.0, 1.0, 1.0],
        [1.0, 1.0, 0.0, 1.0],
        [0.0, 1.0, 1.0, 1.0],
    ];

    let colors = buffers.add(ShaderStorageBuffer::from(color_data));

    let mesh_handle = meshes.add(Cuboid::from_size(Vec3::splat(0.3)));
    // Create the custom material with the storage buffer
    let material_handle = materials.add(CustomMaterial {
        colors: colors.clone(),
    });

    commands.insert_resource(CustomMaterialHandle(material_handle.clone()));

    // Spawn cubes with the custom material
    let mut current_color_id: u32 = 0;
    for i in -6..=6 {
        for j in -3..=3 {
            commands.spawn((
                Mesh3d(mesh_handle.clone()),
                MeshMaterial3d(material_handle.clone()),
                MeshTag(current_color_id % 5),
                Transform::from_xyz(i as f32, j as f32, 0.0),
            ));
            current_color_id += 1;
        }
    }

    // Camera
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(0.0, 0.0, 10.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));
}

pub fn remove_resource<R>(&mut self)

where R: Resource,

Removes a Resource from the World.

Example

#[derive(Resource)]
struct Scoreboard {
    current_score: u32,
    high_score: u32,
}

fn system(mut commands: Commands) {
    commands.remove_resource::<Scoreboard>();
}

pub fn run_system(&mut self, id: SystemId)

Runs the system corresponding to the given SystemId. Before running a system, it must first be registered via Commands::register_system or World::register_system.

The system is run in an exclusive and single-threaded way. Running slow systems can become a bottleneck.

There is no way to get the output of a system when run as a command, because the execution of the system happens later. To get the output of a system, use World::run_system or World::run_system_with instead of running the system as a command.

Fallible

This command will fail if the given SystemId does not correspond to a System.

It will internally return a RegisteredSystemError, which will be handled by logging the error at the warn level.

pub fn run_system_with<I>( &mut self, id: SystemId<I>, input: <I as SystemInput>::Inner<'static>, )

where I: SystemInput + 'static, <I as SystemInput>::Inner<'static>: Send,

Runs the system corresponding to the given SystemId with input. Before running a system, it must first be registered via Commands::register_system or World::register_system.

The system is run in an exclusive and single-threaded way. Running slow systems can become a bottleneck.

There is no way to get the output of a system when run as a command, because the execution of the system happens later. To get the output of a system, use World::run_system or World::run_system_with instead of running the system as a command.

Fallible

This command will fail if the given SystemId does not correspond to a System.

It will internally return a RegisteredSystemError, which will be handled by logging the error at the warn level.

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

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

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

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.

Using a Schedule is still preferred for most cases due to its better performance and ability to run non-conflicting systems simultaneously.

Note

If the same system is registered more than once, each registration will be considered a different system, and they will each be given their own SystemId.

If you want to avoid registering the same system multiple times, consider using Commands::run_system_cached or storing the SystemId in a Local.

Example

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

fn register_system(
    mut commands: Commands,
    mut local_system: Local<Option<SystemId>>,
) {
    if let Some(system) = *local_system {
        commands.run_system(system);
    } else {
        *local_system = Some(commands.register_system(increment_counter));
    }
}

fn increment_counter(mut value: ResMut<Counter>) {
    value.0 += 1;
}

pub fn unregister_system<I, O>(&mut self, system_id: SystemId<I, O>)

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

Removes a system previously registered with Commands::register_system or World::register_system.

After removing a system, the SystemId becomes invalid and attempting to use it afterwards will result in an error. Re-adding the removed system will register it with a new SystemId.

Fallible

This command will fail if the given SystemId does not correspond to a System.

It will internally return a RegisteredSystemError, which will be handled by logging the error at the warn level.

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

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

Removes a system previously registered with one of the following:

• Commands::run_system_cached
• World::run_system_cached
• World::register_system_cached

Fallible

This command will fail if the given system is not currently cached in a CachedSystemId resource.

It will internally return a RegisteredSystemError, which will be handled by logging the error at the warn level.

pub fn run_system_cached<M, S>(&mut self, system: S)

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

Runs a cached system, registering it if necessary.

Unlike Commands::run_system, this method does not require manual registration.

The first time this method is called for a particular system, it will register the system 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 Commands::register_system instead.

Limitations

This method 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 Commands::run_system_cached_with.

If that’s not an option, consider Commands::register_system instead.

pub fn run_system_cached_with<I, M, S>( &mut self, system: S, input: <I as SystemInput>::Inner<'static>, )

where I: SystemInput + Send + 'static, <I as SystemInput>::Inner<'static>: Send, M: 'static, S: IntoSystem<I, (), M> + Send + 'static,

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

Unlike Commands::run_system_with, this method does not require manual registration.

The first time this method is called for a particular system, it will register the system 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 Commands::register_system instead.

Limitations

This method 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.

If that’s not an option, consider Commands::register_system instead.

pub fn trigger<'a>(&mut self, event: impl Event : Default>)

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

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

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

where E: Event, <E as Event>::Trigger<'static>: Send + Sync,

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

pub fn add_observer<E, B, M>( &mut self, observer: impl IntoObserverSystem<E, B, M>, ) -> EntityCommands<'_>

where E: Event, B: Bundle,

Spawns an Observer and returns the EntityCommands associated with the entity that stores the observer.

observer can be any system whose first parameter is On.

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

Panics

Panics if the given system is an exclusive system.

pub fn write_message<M>(&mut self, message: M) -> &mut Commands<'w, 's>

where M: Message,

Writes an arbitrary Message.

This is a convenience method for writing messages without requiring a MessageWriter.

Performance

Since this is a command, exclusive world access is used, which means that it will not profit from system-level parallelism on supported platforms.

If these messages are performance-critical or very frequently sent, consider using a MessageWriter instead.

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

Runs the schedule corresponding to the given ScheduleLabel.

Calls World::try_run_schedule.

Fallible

This command will fail if the given ScheduleLabel does not correspond to a Schedule.

It will internally return a TryRunScheduleError, which will be handled by logging the error at the warn level.

Example

#[derive(ScheduleLabel, Hash, Debug, PartialEq, Eq, Clone, Copy)]
struct FooSchedule;

commands.run_schedule(FooSchedule);

Trait Implementations

impl CommandsStatesExt for Commands<'_, '_>

fn set_state<S>(&mut self, state: S)

where S: FreelyMutableState,

Sets the next state the app should move to.

fn set_state_if_neq<S>(&mut self, state: S)

where S: FreelyMutableState,

Sets the next state the app should move to, skipping any state transitions if the next state is the same as the current state.

impl SystemParam for Commands<'_, '_>

type State = FetchState

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

type Item<'w, 's> = Commands<'w, 's>

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) -> <Commands<'_, '_> as SystemParam>::State

Creates a new instance of this param’s State.

fn init_access( state: &<Commands<'_, '_> as SystemParam>::State, system_meta: &mut SystemMeta, component_access_set: &mut FilteredAccessSet, world: &mut World, )

Registers any World access used by this SystemParam

fn apply( state: &mut <Commands<'_, '_> as SystemParam>::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 <Commands<'_, '_> as SystemParam>::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

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

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

Validates that the param can be acquired by the get_param.

unsafe fn get_param<'w, 's>( state: &'s mut <Commands<'_, '_> as SystemParam>::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> <Commands<'_, '_> as SystemParam>::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

impl<'w, 's> ReadOnlySystemParam for Commands<'w, 's>

where Deferred<'s, CommandQueue>: ReadOnlySystemParam, &'w Entities: ReadOnlySystemParam,

impl Send for Commands<'_, '_>

impl Sync for Commands<'_, '_>