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

Examples found in repository

examples/async_tasks/async_compute.rs (line 117)

fn handle_tasks(
    mut commands: Commands,
    mut transform_tasks: Query<(Entity, &mut ComputeTransform)>,
) {
    for (entity, mut task) in &mut transform_tasks {
        if let Some(mut commands_queue) = block_on(future::poll_once(&mut task.0)) {
            // append the returned command queue to have it execute later
            commands.append(&mut commands_queue);
            // Task is complete, so remove task component from entity
            commands.entity(entity).remove::<ComputeTransform>();
        }
    }
}

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.

Examples found in repository

examples/async_tasks/async_compute.rs (line 61)

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

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

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

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

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

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

                    command_queue
                });

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

examples/stress_tests/transform_hierarchy.rs (line 405)

fn spawn_tree(
    parent_map: &[usize],
    commands: &mut Commands,
    update_filter: &UpdateFilter,
    root_transform: Transform,
) -> InsertResult {
    // total count (# of nodes + root)
    let count = parent_map.len() + 1;

    #[derive(Default, Clone, Copy)]
    struct NodeInfo {
        child_count: u32,
        depth: u32,
    }

    // node index -> entity lookup list
    let mut ents: Vec<Entity> = Vec::with_capacity(count);
    let mut node_info: Vec<NodeInfo> = vec![default(); count];
    for (i, &parent_idx) in parent_map.iter().enumerate() {
        // assert spawn order (parent must be processed before child)
        assert!(parent_idx <= i, "invalid spawn order");
        node_info[parent_idx].child_count += 1;
    }

    // insert root
    ents.push(commands.spawn(root_transform).id());

    let mut result = InsertResult::default();
    let mut rng = rand::rng();
    // used to count through the number of children (used only for visual layout)
    let mut child_idx: Vec<u16> = vec![0; count];

    // insert children
    for (current_idx, &parent_idx) in parent_map.iter().enumerate() {
        let current_idx = current_idx + 1;

        // separation factor to visually separate children (0..1)
        let sep = child_idx[parent_idx] as f32 / node_info[parent_idx].child_count as f32;
        child_idx[parent_idx] += 1;

        // calculate and set depth
        // this works because it's guaranteed that we have already iterated over the parent
        let depth = node_info[parent_idx].depth + 1;
        let info = &mut node_info[current_idx];
        info.depth = depth;

        // update max depth of tree
        result.maximum_depth = result.maximum_depth.max(depth.try_into().unwrap());

        // insert child
        let child_entity = {
            let mut cmd = commands.spawn_empty();

            // check whether or not to update this node
            let update = (rng.random::<f32>() <= update_filter.probability)
                && (depth >= update_filter.min_depth && depth <= update_filter.max_depth);

            if update {
                cmd.insert(UpdateValue(sep));
                result.active_nodes += 1;
            }

            let transform = {
                let mut translation = Vec3::ZERO;
                // use the same placement fn as the `update` system
                // this way the entities won't be all at (0, 0, 0) when they don't have an `Update` component
                set_translation(&mut translation, sep);
                Transform::from_translation(translation)
            };

            // only insert the components necessary for the transform propagation
            cmd.insert(transform);

            cmd.id()
        };

        commands.entity(ents[parent_idx]).add_child(child_entity);

        ents.push(child_entity);
    }

    result.inserted_nodes = ents.len();
    result
}

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/games/game_menu.rs (line 44)

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

mod splash {
    use bevy::prelude::*;

    use super::GameState;

    // This plugin will display a splash screen with Bevy logo for 1 second before switching to the menu
    pub fn splash_plugin(app: &mut App) {
        // As this plugin is managing the splash screen, it will focus on the state `GameState::Splash`
        app
            // When entering the state, spawn everything needed for this screen
            .add_systems(OnEnter(GameState::Splash), splash_setup)
            // While in this state, run the `countdown` system
            .add_systems(Update, countdown.run_if(in_state(GameState::Splash)));
    }

    // Tag component used to tag entities added on the splash screen
    #[derive(Component)]
    struct OnSplashScreen;

    // Newtype to use a `Timer` for this screen as a resource
    #[derive(Resource, Deref, DerefMut)]
    struct SplashTimer(Timer);

    fn splash_setup(mut commands: Commands, asset_server: Res<AssetServer>) {
        let icon = asset_server.load("branding/icon.png");
        // Display the logo
        commands.spawn((
            // This entity will be despawned when exiting the state
            DespawnOnExit(GameState::Splash),
            Node {
                align_items: AlignItems::Center,
                justify_content: JustifyContent::Center,
                width: percent(100),
                height: percent(100),
                ..default()
            },
            OnSplashScreen,
            children![(
                ImageNode::new(icon),
                Node {
                    // This will set the logo to be 200px wide, and auto adjust its height
                    width: px(200),
                    ..default()
                },
            )],
        ));
        // Insert the timer as a resource
        commands.insert_resource(SplashTimer(Timer::from_seconds(1.0, TimerMode::Once)));
    }

    // Tick the timer, and change state when finished
    fn countdown(
        mut game_state: ResMut<NextState<GameState>>,
        time: Res<Time>,
        mut timer: ResMut<SplashTimer>,
    ) {
        if timer.tick(time.delta()).is_finished() {
            game_state.set(GameState::Menu);
        }
    }
}

mod game {
    use bevy::{
        color::palettes::basic::{BLUE, LIME},
        prelude::*,
    };

    use super::{DisplayQuality, GameState, Volume, TEXT_COLOR};

    // This plugin will contain the game. In this case, it's just be a screen that will
    // display the current settings for 5 seconds before returning to the menu
    pub fn game_plugin(app: &mut App) {
        app.add_systems(OnEnter(GameState::Game), game_setup)
            .add_systems(Update, game.run_if(in_state(GameState::Game)));
    }

    // Tag component used to tag entities added on the game screen
    #[derive(Component)]
    struct OnGameScreen;

    #[derive(Resource, Deref, DerefMut)]
    struct GameTimer(Timer);

    fn game_setup(
        mut commands: Commands,
        display_quality: Res<DisplayQuality>,
        volume: Res<Volume>,
    ) {
        commands.spawn((
            DespawnOnExit(GameState::Game),
            Node {
                width: percent(100),
                height: percent(100),
                // center children
                align_items: AlignItems::Center,
                justify_content: JustifyContent::Center,
                ..default()
            },
            OnGameScreen,
            children![(
                Node {
                    // This will display its children in a column, from top to bottom
                    flex_direction: FlexDirection::Column,
                    // `align_items` will align children on the cross axis. Here the main axis is
                    // vertical (column), so the cross axis is horizontal. This will center the
                    // children
                    align_items: AlignItems::Center,
                    ..default()
                },
                BackgroundColor(Color::BLACK),
                children![
                    (
                        Text::new("Will be back to the menu shortly..."),
                        TextFont {
                            font_size: 67.0,
                            ..default()
                        },
                        TextColor(TEXT_COLOR),
                        Node {
                            margin: UiRect::all(px(50)),
                            ..default()
                        },
                    ),
                    (
                        Text::default(),
                        Node {
                            margin: UiRect::all(px(50)),
                            ..default()
                        },
                        children![
                            (
                                TextSpan(format!("quality: {:?}", *display_quality)),
                                TextFont {
                                    font_size: 50.0,
                                    ..default()
                                },
                                TextColor(BLUE.into()),
                            ),
                            (
                                TextSpan::new(" - "),
                                TextFont {
                                    font_size: 50.0,
                                    ..default()
                                },
                                TextColor(TEXT_COLOR),
                            ),
                            (
                                TextSpan(format!("volume: {:?}", *volume)),
                                TextFont {
                                    font_size: 50.0,
                                    ..default()
                                },
                                TextColor(LIME.into()),
                            ),
                        ]
                    ),
                ]
            )],
        ));
        // Spawn a 5 seconds timer to trigger going back to the menu
        commands.insert_resource(GameTimer(Timer::from_seconds(5.0, TimerMode::Once)));
    }

    // Tick the timer, and change state when finished
    fn game(
        time: Res<Time>,
        mut game_state: ResMut<NextState<GameState>>,
        mut timer: ResMut<GameTimer>,
    ) {
        if timer.tick(time.delta()).is_finished() {
            game_state.set(GameState::Menu);
        }
    }
}

mod menu {
    use bevy::{
        app::AppExit,
        color::palettes::css::CRIMSON,
        ecs::spawn::{SpawnIter, SpawnWith},
        prelude::*,
    };

    use super::{DisplayQuality, GameState, Volume, TEXT_COLOR};

    // This plugin manages the menu, with 5 different screens:
    // - a main menu with "New Game", "Settings", "Quit"
    // - a settings menu with two submenus and a back button
    // - two settings screen with a setting that can be set and a back button
    pub fn menu_plugin(app: &mut App) {
        app
            // At start, the menu is not enabled. This will be changed in `menu_setup` when
            // entering the `GameState::Menu` state.
            // Current screen in the menu is handled by an independent state from `GameState`
            .init_state::<MenuState>()
            .add_systems(OnEnter(GameState::Menu), menu_setup)
            // Systems to handle the main menu screen
            .add_systems(OnEnter(MenuState::Main), main_menu_setup)
            // Systems to handle the settings menu screen
            .add_systems(OnEnter(MenuState::Settings), settings_menu_setup)
            // Systems to handle the display settings screen
            .add_systems(
                OnEnter(MenuState::SettingsDisplay),
                display_settings_menu_setup,
            )
            .add_systems(
                Update,
                (setting_button::<DisplayQuality>.run_if(in_state(MenuState::SettingsDisplay)),),
            )
            // Systems to handle the sound settings screen
            .add_systems(OnEnter(MenuState::SettingsSound), sound_settings_menu_setup)
            .add_systems(
                Update,
                setting_button::<Volume>.run_if(in_state(MenuState::SettingsSound)),
            )
            // Common systems to all screens that handles buttons behavior
            .add_systems(
                Update,
                (menu_action, button_system).run_if(in_state(GameState::Menu)),
            );
    }

    // State used for the current menu screen
    #[derive(Clone, Copy, Default, Eq, PartialEq, Debug, Hash, States)]
    enum MenuState {
        Main,
        Settings,
        SettingsDisplay,
        SettingsSound,
        #[default]
        Disabled,
    }

    // Tag component used to tag entities added on the main menu screen
    #[derive(Component)]
    struct OnMainMenuScreen;

    // Tag component used to tag entities added on the settings menu screen
    #[derive(Component)]
    struct OnSettingsMenuScreen;

    // Tag component used to tag entities added on the display settings menu screen
    #[derive(Component)]
    struct OnDisplaySettingsMenuScreen;

    // Tag component used to tag entities added on the sound settings menu screen
    #[derive(Component)]
    struct OnSoundSettingsMenuScreen;

    const NORMAL_BUTTON: Color = Color::srgb(0.15, 0.15, 0.15);
    const HOVERED_BUTTON: Color = Color::srgb(0.25, 0.25, 0.25);
    const HOVERED_PRESSED_BUTTON: Color = Color::srgb(0.25, 0.65, 0.25);
    const PRESSED_BUTTON: Color = Color::srgb(0.35, 0.75, 0.35);

    // Tag component used to mark which setting is currently selected
    #[derive(Component)]
    struct SelectedOption;

    // All actions that can be triggered from a button click
    #[derive(Component)]
    enum MenuButtonAction {
        Play,
        Settings,
        SettingsDisplay,
        SettingsSound,
        BackToMainMenu,
        BackToSettings,
        Quit,
    }

    // This system handles changing all buttons color based on mouse interaction
    fn button_system(
        mut interaction_query: Query<
            (&Interaction, &mut BackgroundColor, Option<&SelectedOption>),
            (Changed<Interaction>, With<Button>),
        >,
    ) {
        for (interaction, mut background_color, selected) in &mut interaction_query {
            *background_color = match (*interaction, selected) {
                (Interaction::Pressed, _) | (Interaction::None, Some(_)) => PRESSED_BUTTON.into(),
                (Interaction::Hovered, Some(_)) => HOVERED_PRESSED_BUTTON.into(),
                (Interaction::Hovered, None) => HOVERED_BUTTON.into(),
                (Interaction::None, None) => NORMAL_BUTTON.into(),
            }
        }
    }

    // This system updates the settings when a new value for a setting is selected, and marks
    // the button as the one currently selected
    fn setting_button<T: Resource + Component + PartialEq + Copy>(
        interaction_query: Query<(&Interaction, &T, Entity), (Changed<Interaction>, With<Button>)>,
        selected_query: Single<(Entity, &mut BackgroundColor), With<SelectedOption>>,
        mut commands: Commands,
        mut setting: ResMut<T>,
    ) {
        let (previous_button, mut previous_button_color) = selected_query.into_inner();
        for (interaction, button_setting, entity) in &interaction_query {
            if *interaction == Interaction::Pressed && *setting != *button_setting {
                *previous_button_color = NORMAL_BUTTON.into();
                commands.entity(previous_button).remove::<SelectedOption>();
                commands.entity(entity).insert(SelectedOption);
                *setting = *button_setting;
            }
        }
    }

    fn menu_setup(mut menu_state: ResMut<NextState<MenuState>>) {
        menu_state.set(MenuState::Main);
    }

    fn main_menu_setup(mut commands: Commands, asset_server: Res<AssetServer>) {
        // Common style for all buttons on the screen
        let button_node = Node {
            width: px(300),
            height: px(65),
            margin: UiRect::all(px(20)),
            justify_content: JustifyContent::Center,
            align_items: AlignItems::Center,
            ..default()
        };
        let button_icon_node = Node {
            width: px(30),
            // This takes the icons out of the flexbox flow, to be positioned exactly
            position_type: PositionType::Absolute,
            // The icon will be close to the left border of the button
            left: px(10),
            ..default()
        };
        let button_text_font = TextFont {
            font_size: 33.0,
            ..default()
        };

        let right_icon = asset_server.load("textures/Game Icons/right.png");
        let wrench_icon = asset_server.load("textures/Game Icons/wrench.png");
        let exit_icon = asset_server.load("textures/Game Icons/exitRight.png");

        commands.spawn((
            DespawnOnExit(MenuState::Main),
            Node {
                width: percent(100),
                height: percent(100),
                align_items: AlignItems::Center,
                justify_content: JustifyContent::Center,
                ..default()
            },
            OnMainMenuScreen,
            children![(
                Node {
                    flex_direction: FlexDirection::Column,
                    align_items: AlignItems::Center,
                    ..default()
                },
                BackgroundColor(CRIMSON.into()),
                children![
                    // Display the game name
                    (
                        Text::new("Bevy Game Menu UI"),
                        TextFont {
                            font_size: 67.0,
                            ..default()
                        },
                        TextColor(TEXT_COLOR),
                        Node {
                            margin: UiRect::all(px(50)),
                            ..default()
                        },
                    ),
                    // Display three buttons for each action available from the main menu:
                    // - new game
                    // - settings
                    // - quit
                    (
                        Button,
                        button_node.clone(),
                        BackgroundColor(NORMAL_BUTTON),
                        MenuButtonAction::Play,
                        children![
                            (ImageNode::new(right_icon), button_icon_node.clone()),
                            (
                                Text::new("New Game"),
                                button_text_font.clone(),
                                TextColor(TEXT_COLOR),
                            ),
                        ]
                    ),
                    (
                        Button,
                        button_node.clone(),
                        BackgroundColor(NORMAL_BUTTON),
                        MenuButtonAction::Settings,
                        children![
                            (ImageNode::new(wrench_icon), button_icon_node.clone()),
                            (
                                Text::new("Settings"),
                                button_text_font.clone(),
                                TextColor(TEXT_COLOR),
                            ),
                        ]
                    ),
                    (
                        Button,
                        button_node,
                        BackgroundColor(NORMAL_BUTTON),
                        MenuButtonAction::Quit,
                        children![
                            (ImageNode::new(exit_icon), button_icon_node),
                            (Text::new("Quit"), button_text_font, TextColor(TEXT_COLOR),),
                        ]
                    ),
                ]
            )],
        ));
    }

    fn settings_menu_setup(mut commands: Commands) {
        let button_node = Node {
            width: px(200),
            height: px(65),
            margin: UiRect::all(px(20)),
            justify_content: JustifyContent::Center,
            align_items: AlignItems::Center,
            ..default()
        };

        let button_text_style = (
            TextFont {
                font_size: 33.0,
                ..default()
            },
            TextColor(TEXT_COLOR),
        );

        commands.spawn((
            DespawnOnExit(MenuState::Settings),
            Node {
                width: percent(100),
                height: percent(100),
                align_items: AlignItems::Center,
                justify_content: JustifyContent::Center,
                ..default()
            },
            OnSettingsMenuScreen,
            children![(
                Node {
                    flex_direction: FlexDirection::Column,
                    align_items: AlignItems::Center,
                    ..default()
                },
                BackgroundColor(CRIMSON.into()),
                Children::spawn(SpawnIter(
                    [
                        (MenuButtonAction::SettingsDisplay, "Display"),
                        (MenuButtonAction::SettingsSound, "Sound"),
                        (MenuButtonAction::BackToMainMenu, "Back"),
                    ]
                    .into_iter()
                    .map(move |(action, text)| {
                        (
                            Button,
                            button_node.clone(),
                            BackgroundColor(NORMAL_BUTTON),
                            action,
                            children![(Text::new(text), button_text_style.clone())],
                        )
                    })
                ))
            )],
        ));
    }

    fn display_settings_menu_setup(mut commands: Commands, display_quality: Res<DisplayQuality>) {
        fn button_node() -> Node {
            Node {
                width: px(200),
                height: px(65),
                margin: UiRect::all(px(20)),
                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((
            DespawnOnExit(MenuState::SettingsDisplay),
            Node {
                width: percent(100),
                height: percent(100),
                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: px(150),
                                            height: px(65),
                                            ..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: px(200),
            height: px(65),
            margin: UiRect::all(px(20)),
            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((
            DespawnOnExit(MenuState::SettingsSound),
            Node {
                width: percent(100),
                height: percent(100),
                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: px(30),
                                            height: px(65),
                                            ..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)]
                    )
                ]
            )],
        ));
    }

examples/state/custom_transitions.rs (line 222)

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

fn setup_game(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Sprite::from_image(asset_server.load("branding/icon.png")));
    info!("Setup game");
}

fn teardown_game(mut commands: Commands, player: Single<Entity, With<Sprite>>) {
    commands.entity(*player).despawn();
    info!("Teardown game");
}

#[derive(Resource)]
struct MenuData {
    pub button_entity: Entity,
}

const NORMAL_BUTTON: Color = Color::srgb(0.15, 0.15, 0.15);
const HOVERED_BUTTON: Color = Color::srgb(0.25, 0.25, 0.25);
const PRESSED_BUTTON: Color = Color::srgb(0.35, 0.75, 0.35);

fn setup_menu(mut commands: Commands) {
    let button_entity = commands
        .spawn((
            Node {
                // center button
                width: percent(100),
                height: percent(100),
                justify_content: JustifyContent::Center,
                align_items: AlignItems::Center,
                ..default()
            },
            children![(
                Button,
                Node {
                    width: px(150),
                    height: px(65),
                    // horizontally center child text
                    justify_content: JustifyContent::Center,
                    // vertically center child text
                    align_items: AlignItems::Center,
                    ..default()
                },
                BackgroundColor(NORMAL_BUTTON),
                children![(
                    Text::new("Play"),
                    TextFont {
                        font_size: 33.0,
                        ..default()
                    },
                    TextColor(Color::srgb(0.9, 0.9, 0.9)),
                )]
            )],
        ))
        .id();
    commands.insert_resource(MenuData { button_entity });
}

examples/state/states.rs (line 49)

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

fn setup_menu(mut commands: Commands) {
    let button_entity = commands
        .spawn((
            Node {
                // center button
                width: percent(100),
                height: percent(100),
                justify_content: JustifyContent::Center,
                align_items: AlignItems::Center,
                ..default()
            },
            children![(
                Button,
                Node {
                    width: px(150),
                    height: px(65),
                    // horizontally center child text
                    justify_content: JustifyContent::Center,
                    // vertically center child text
                    align_items: AlignItems::Center,
                    ..default()
                },
                BackgroundColor(NORMAL_BUTTON),
                children![(
                    Text::new("Play"),
                    TextFont {
                        font_size: 33.0,
                        ..default()
                    },
                    TextColor(Color::srgb(0.9, 0.9, 0.9)),
                )],
            )],
        ))
        .id();
    commands.insert_resource(MenuData { button_entity });
}

fn menu(
    mut next_state: ResMut<NextState<AppState>>,
    mut interaction_query: Query<
        (&Interaction, &mut BackgroundColor),
        (Changed<Interaction>, With<Button>),
    >,
) {
    for (interaction, mut color) in &mut interaction_query {
        match *interaction {
            Interaction::Pressed => {
                *color = PRESSED_BUTTON.into();
                next_state.set(AppState::InGame);
            }
            Interaction::Hovered => {
                *color = HOVERED_BUTTON.into();
            }
            Interaction::None => {
                *color = NORMAL_BUTTON.into();
            }
        }
    }
}

fn cleanup_menu(mut commands: Commands, menu_data: Res<MenuData>) {
    commands.entity(menu_data.button_entity).despawn();
}

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

examples/window/clear_color.rs (line 17)

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

examples/window/custom_user_event.rs (line 50)

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

examples/2d/sprite_scale.rs (line 14)

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

fn setup_sprites(mut commands: Commands, asset_server: Res<AssetServer>) {
    let square = asset_server.load("textures/slice_square_2.png");
    let banner = asset_server.load("branding/banner.png");

    let rects = [
        Rect {
            size: Vec2::new(100., 225.),
            text: "Stretched".to_string(),
            transform: Transform::from_translation(Vec3::new(-570., 230., 0.)),
            texture: square.clone(),
            image_mode: SpriteImageMode::Auto,
        },
        Rect {
            size: Vec2::new(100., 225.),
            text: "Fill Center".to_string(),
            transform: Transform::from_translation(Vec3::new(-450., 230., 0.)),
            texture: square.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillCenter),
        },
        Rect {
            size: Vec2::new(100., 225.),
            text: "Fill Start".to_string(),
            transform: Transform::from_translation(Vec3::new(-330., 230., 0.)),
            texture: square.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillStart),
        },
        Rect {
            size: Vec2::new(100., 225.),
            text: "Fill End".to_string(),
            transform: Transform::from_translation(Vec3::new(-210., 230., 0.)),
            texture: square.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillEnd),
        },
        Rect {
            size: Vec2::new(300., 100.),
            text: "Fill Start Horizontal".to_string(),
            transform: Transform::from_translation(Vec3::new(10., 290., 0.)),
            texture: square.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillStart),
        },
        Rect {
            size: Vec2::new(300., 100.),
            text: "Fill End Horizontal".to_string(),
            transform: Transform::from_translation(Vec3::new(10., 155., 0.)),
            texture: square.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillEnd),
        },
        Rect {
            size: Vec2::new(200., 200.),
            text: "Fill Center".to_string(),
            transform: Transform::from_translation(Vec3::new(280., 230., 0.)),
            texture: banner.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillCenter),
        },
        Rect {
            size: Vec2::new(200., 100.),
            text: "Fill Center".to_string(),
            transform: Transform::from_translation(Vec3::new(500., 230., 0.)),
            texture: square.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillCenter),
        },
        Rect {
            size: Vec2::new(100., 100.),
            text: "Stretched".to_string(),
            transform: Transform::from_translation(Vec3::new(-570., -40., 0.)),
            texture: banner.clone(),
            image_mode: SpriteImageMode::Auto,
        },
        Rect {
            size: Vec2::new(200., 200.),
            text: "Fit Center".to_string(),
            transform: Transform::from_translation(Vec3::new(-400., -40., 0.)),
            texture: banner.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FitCenter),
        },
        Rect {
            size: Vec2::new(200., 200.),
            text: "Fit Start".to_string(),
            transform: Transform::from_translation(Vec3::new(-180., -40., 0.)),
            texture: banner.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FitStart),
        },
        Rect {
            size: Vec2::new(200., 200.),
            text: "Fit End".to_string(),
            transform: Transform::from_translation(Vec3::new(40., -40., 0.)),
            texture: banner.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FitEnd),
        },
        Rect {
            size: Vec2::new(100., 200.),
            text: "Fit Center".to_string(),
            transform: Transform::from_translation(Vec3::new(210., -40., 0.)),
            texture: banner.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FitCenter),
        },
    ];

    for rect in rects {
        commands.spawn((
            Sprite {
                image: rect.texture,
                custom_size: Some(rect.size),
                image_mode: rect.image_mode,
                ..default()
            },
            rect.transform,
            children![(
                Text2d::new(rect.text),
                TextLayout::new_with_justify(Justify::Center),
                TextFont::from_font_size(15.),
                Transform::from_xyz(0., -0.5 * rect.size.y - 10., 0.),
                bevy::sprite::Anchor::TOP_CENTER,
            )],
        ));
    }
}

fn setup_texture_atlas(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut texture_atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
) {
    let gabe = asset_server.load("textures/rpg/chars/gabe/gabe-idle-run.png");
    let animation_indices_gabe = AnimationIndices { first: 0, last: 6 };
    let gabe_atlas = TextureAtlas {
        layout: texture_atlas_layouts.add(TextureAtlasLayout::from_grid(
            UVec2::splat(24),
            7,
            1,
            None,
            None,
        )),
        index: animation_indices_gabe.first,
    };

    let sprite_sheets = [
        SpriteSheet {
            size: Vec2::new(120., 50.),
            text: "Stretched".to_string(),
            transform: Transform::from_translation(Vec3::new(-570., -200., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Auto,
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
        SpriteSheet {
            size: Vec2::new(120., 50.),
            text: "Fill Center".to_string(),
            transform: Transform::from_translation(Vec3::new(-570., -300., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillCenter),
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
        SpriteSheet {
            size: Vec2::new(120., 50.),
            text: "Fill Start".to_string(),
            transform: Transform::from_translation(Vec3::new(-430., -200., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillStart),
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
        SpriteSheet {
            size: Vec2::new(120., 50.),
            text: "Fill End".to_string(),
            transform: Transform::from_translation(Vec3::new(-430., -300., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillEnd),
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
        SpriteSheet {
            size: Vec2::new(50., 120.),
            text: "Fill Center".to_string(),
            transform: Transform::from_translation(Vec3::new(-300., -250., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillCenter),
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
        SpriteSheet {
            size: Vec2::new(50., 120.),
            text: "Fill Start".to_string(),
            transform: Transform::from_translation(Vec3::new(-190., -250., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillStart),
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
        SpriteSheet {
            size: Vec2::new(50., 120.),
            text: "Fill End".to_string(),
            transform: Transform::from_translation(Vec3::new(-90., -250., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FillEnd),
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
        SpriteSheet {
            size: Vec2::new(120., 50.),
            text: "Fit Center".to_string(),
            transform: Transform::from_translation(Vec3::new(20., -200., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FitCenter),
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
        SpriteSheet {
            size: Vec2::new(120., 50.),
            text: "Fit Start".to_string(),
            transform: Transform::from_translation(Vec3::new(20., -300., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FitStart),
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
        SpriteSheet {
            size: Vec2::new(120., 50.),
            text: "Fit End".to_string(),
            transform: Transform::from_translation(Vec3::new(160., -200., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Scale(ScalingMode::FitEnd),
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
    ];

    for sprite_sheet in sprite_sheets {
        commands.spawn((
            Sprite {
                image_mode: sprite_sheet.image_mode,
                custom_size: Some(sprite_sheet.size),
                ..Sprite::from_atlas_image(sprite_sheet.texture.clone(), sprite_sheet.atlas.clone())
            },
            sprite_sheet.indices,
            sprite_sheet.timer,
            sprite_sheet.transform,
            children![(
                Text2d::new(sprite_sheet.text),
                TextLayout::new_with_justify(Justify::Center),
                TextFont::from_font_size(15.),
                Transform::from_xyz(0., -0.5 * sprite_sheet.size.y - 10., 0.),
                bevy::sprite::Anchor::TOP_CENTER,
            )],
        ));
    }
}

Additional examples can be found in:

• examples/window/window_resizing.rs
• examples/state/computed_states.rs
• examples/state/sub_states.rs
• examples/app/without_winit.rs
• examples/window/custom_cursor_image.rs
• examples/ecs/custom_query_param.rs
• examples/ui/feathers.rs
• examples/ecs/system_param.rs
• examples/3d/irradiance_volumes.rs
• examples/ui/button.rs
• examples/ui/standard_widgets.rs
• examples/ui/standard_widgets_observers.rs
• examples/ecs/one_shot_systems.rs
• examples/scene/scene.rs
• examples/ui/viewport_debug.rs
• examples/audio/audio.rs
• examples/asset/custom_asset_reader.rs
• examples/window/transparent_window.rs
• examples/3d/mixed_lighting.rs
• examples/time/timers.rs
• examples/2d/sprite.rs
• examples/3d/reflection_probes.rs
• examples/asset/asset_decompression.rs
• examples/ecs/removal_detection.rs
• examples/2d/move_sprite.rs
• examples/app/logs.rs
• examples/audio/decodable.rs
• examples/testbed/ui.rs
• examples/app/log_layers_ecs.rs
• examples/ecs/change_detection.rs
• examples/usage/context_menu.rs
• examples/3d/fog.rs
• examples/asset/multi_asset_sync.rs
• examples/2d/mesh2d.rs
• examples/asset/web_asset.rs
• examples/ecs/component_hooks.rs
• examples/2d/sprite_flipping.rs
• examples/window/screenshot.rs
• examples/movement/physics_in_fixed_timestep.rs
• examples/camera/2d_screen_shake.rs
• examples/math/render_primitives.rs
• examples/ecs/generic_system.rs
• examples/stress_tests/many_gizmos.rs
• examples/animation/gltf_skinned_mesh.rs
• examples/ecs/state_scoped.rs
• examples/games/alien_cake_addict.rs
• examples/shader/animate_shader.rs
• examples/async_tasks/async_compute.rs
• examples/3d/query_gltf_primitives.rs
• examples/audio/pitch.rs
• examples/ecs/observer_propagation.rs
• examples/2d/sprite_tile.rs
• examples/3d/lightmaps.rs
• examples/shader/shader_material_2d.rs
• examples/shader/shader_material_wesl.rs
• examples/shader_advanced/render_depth_to_texture.rs
• examples/shader/array_texture.rs
• examples/ecs/fallible_params.rs
• examples/3d/ssr.rs
• examples/2d/custom_gltf_vertex_attribute.rs
• examples/ecs/ecs_guide.rs
• examples/camera/2d_top_down_camera.rs
• examples/2d/pixel_grid_snap.rs
• examples/shader/fallback_image.rs
• examples/shader_advanced/custom_phase_item.rs
• examples/ecs/hotpatching_systems.rs
• examples/3d/motion_blur.rs
• examples/gizmos/2d_gizmos.rs
• examples/3d/3d_viewport_to_world.rs
• examples/dev_tools/fps_overlay.rs
• examples/3d/clustered_decals.rs
• examples/shader/shader_material.rs
• examples/shader/shader_material_glsl.rs
• examples/asset/extra_source.rs
• examples/shader_advanced/texture_binding_array.rs
• examples/ui/window_fallthrough.rs
• examples/ui/scrollbars.rs
• examples/asset/hot_asset_reloading.rs
• examples/ecs/parallel_query.rs
• examples/3d/manual_material.rs
• examples/3d/light_textures.rs
• examples/audio/audio_control.rs
• examples/async_tasks/external_source_external_thread.rs
• examples/games/loading_screen.rs
• examples/2d/transparency_2d.rs
• examples/transforms/3d_rotation.rs
• examples/3d/rotate_environment_map.rs
• examples/transforms/scale.rs
• examples/ecs/entity_disabling.rs
• examples/shader_advanced/custom_vertex_attribute.rs
• examples/animation/morph_targets.rs
• examples/3d/post_processing.rs
• tests/window/minimizing.rs
• tests/window/resizing.rs
• examples/3d/atmospheric_fog.rs
• examples/transforms/translation.rs
• examples/3d/load_gltf_extras.rs
• examples/shader/shader_defs.rs
• examples/ui/font_atlas_debug.rs
• examples/3d/clearcoat.rs
• examples/shader/compute_shader_game_of_life.rs
• examples/3d/3d_scene.rs
• examples/asset/embedded_asset.rs
• examples/window/scale_factor_override.rs
• examples/3d/color_grading.rs
• examples/2d/sprite_sheet.rs
• examples/window/window_drag_move.rs
• examples/3d/tonemapping.rs
• examples/shader_advanced/custom_post_processing.rs
• examples/3d/parenting.rs
• examples/animation/animation_graph.rs
• examples/shader/shader_material_screenspace_texture.rs
• examples/3d/pcss.rs
• examples/3d/depth_of_field.rs
• examples/camera/camera_orbit.rs
• examples/3d/edit_material_on_gltf.rs
• examples/shader/shader_material_bindless.rs
• examples/3d/anisotropy.rs
• examples/remote/server.rs
• examples/animation/animation_masks.rs
• examples/2d/tilemap_chunk.rs
• examples/3d/animated_material.rs
• examples/camera/custom_projection.rs
• examples/3d/load_gltf.rs
• examples/input/text_input.rs
• examples/3d/two_passes.rs
• examples/animation/animated_mesh_events.rs
• examples/3d/lines.rs
• examples/stress_tests/many_materials.rs
• examples/animation/animated_mesh.rs
• examples/diagnostics/log_diagnostics.rs
• examples/stress_tests/many_glyphs.rs
• examples/shader/extended_material_bindless.rs
• examples/3d/skybox.rs
• examples/3d/order_independent_transparency.rs
• examples/stress_tests/text_pipeline.rs
• examples/3d/update_gltf_scene.rs
• examples/shader_advanced/custom_render_phase.rs
• examples/3d/atmosphere.rs
• examples/3d/fog_volumes.rs
• examples/ui/text_background_colors.rs
• examples/shader/storage_buffer.rs
• examples/window/low_power.rs
• examples/2d/mesh2d_vertex_color_texture.rs
• examples/ecs/hierarchy.rs
• examples/ui/virtual_keyboard.rs
• examples/3d/generate_custom_mesh.rs
• examples/2d/wireframe_2d.rs
• examples/3d/mesh_ray_cast.rs
• examples/stress_tests/many_sprites.rs
• examples/audio/soundtrack.rs
• examples/animation/color_animation.rs
• examples/audio/spatial_audio_2d.rs
• examples/picking/simple_picking.rs
• examples/movement/smooth_follow.rs
• examples/ui/relative_cursor_position.rs
• examples/ui/ui_material.rs
• examples/shader/extended_material.rs
• examples/animation/animation_events.rs
• examples/3d/vertex_colors.rs
• examples/shader_advanced/custom_shader_instancing.rs
• tests/window/desktop_request_redraw.rs
• examples/3d/orthographic.rs
• examples/games/contributors.rs
• examples/picking/debug_picking.rs
• examples/testbed/2d.rs
• examples/ui/ui_scaling.rs
• examples/shader_advanced/specialized_mesh_pipeline.rs
• examples/3d/spherical_area_lights.rs
• examples/ecs/observers.rs
• examples/math/bounding_2d.rs
• examples/ui/ui_texture_atlas.rs
• examples/2d/2d_viewport_to_world.rs
• examples/usage/cooldown.rs
• examples/transforms/transform.rs
• examples/window/multiple_windows.rs
• examples/stress_tests/many_animated_sprites.rs
• examples/2d/bloom_2d.rs
• examples/camera/first_person_view_model.rs
• examples/stress_tests/many_text2d.rs
• examples/gizmos/axes.rs
• examples/ecs/relationships.rs
• examples/math/custom_primitives.rs
• examples/3d/occlusion_culling.rs
• examples/3d/ssao.rs
• examples/ui/ghost_nodes.rs
• examples/ui/overflow_debug.rs
• examples/animation/animated_ui.rs
• examples/stress_tests/many_buttons.rs
• examples/asset/alter_sprite.rs
• examples/app/headless_renderer.rs
• examples/stress_tests/many_gradients.rs
• examples/animation/eased_motion.rs
• examples/3d/wireframe.rs
• examples/2d/2d_shapes.rs
• examples/stress_tests/transform_hierarchy.rs
• examples/audio/spatial_audio_3d.rs
• examples/shader/automatic_instancing.rs
• examples/ecs/error_handling.rs
• examples/camera/projection_zoom.rs
• examples/2d/rotation.rs
• examples/ui/ui_texture_slice.rs
• examples/3d/specular_tint.rs
• examples/camera/2d_on_ui.rs
• examples/ui/viewport_node.rs
• examples/3d/visibility_range.rs
• examples/2d/sprite_animation.rs
• examples/math/cubic_splines.rs
• examples/3d/volumetric_fog.rs
• examples/animation/animated_mesh_control.rs
• examples/2d/cpu_draw.rs
• examples/testbed/3d.rs
• tests/3d/test_invalid_skinned_mesh.rs
• examples/stress_tests/many_cameras_lights.rs
• examples/3d/texture.rs
• examples/time/virtual_time.rs
• examples/ui/ui_texture_slice_flip_and_tile.rs
• examples/3d/shadow_caster_receiver.rs
• examples/window/monitor_info.rs
• examples/ui/size_constraints.rs
• examples/3d/anti_aliasing.rs
• examples/3d/bloom_3d.rs
• examples/stress_tests/many_lights.rs
• examples/gizmos/3d_gizmos.rs
• examples/ui/transparency_ui.rs
• examples/transforms/align.rs
• examples/math/random_sampling.rs
• examples/ui/ui_texture_atlas_slice.rs
• examples/picking/sprite_picking.rs
• examples/games/stepping.rs
• examples/3d/scrolling_fog.rs
• examples/3d/decal.rs
• examples/2d/mesh2d_alpha_mode.rs
• examples/2d/mesh2d_arcs.rs
• examples/3d/render_to_texture.rs
• examples/asset/repeated_texture.rs
• examples/ecs/iter_combinations.rs
• examples/ui/text_wrap_debug.rs
• examples/2d/mesh2d_manual.rs
• examples/ui/stacked_gradients.rs
• examples/2d/sprite_slice.rs
• examples/asset/alter_mesh.rs
• examples/3d/transparency_3d.rs
• examples/ui/text.rs
• examples/asset/asset_settings.rs
• examples/shader/gpu_readback.rs
• examples/3d/meshlet.rs
• examples/2d/mesh2d_repeated_texture.rs
• examples/gizmos/light_gizmos.rs
• examples/3d/spotlight.rs
• examples/3d/pbr.rs
• examples/ui/ui_target_camera.rs
• examples/3d/3d_shapes.rs
• examples/3d/auto_exposure.rs
• examples/animation/easing_functions.rs
• examples/asset/asset_loading.rs
• examples/ui/overflow.rs
• examples/ui/overflow_clip_margin.rs
• examples/ui/flex_layout.rs
• examples/shader/shader_prepass.rs
• examples/window/multi_window_text.rs
• examples/stress_tests/bevymark.rs
• examples/3d/solari.rs
• examples/ui/display_and_visibility.rs
• examples/3d/shadow_biases.rs
• examples/ui/drag_to_scroll.rs
• examples/ui/tab_navigation.rs
• examples/3d/split_screen.rs
• examples/ui/scroll.rs
• examples/games/breakout.rs
• examples/picking/mesh_picking.rs
• examples/ui/z_index.rs
• examples/ui/render_ui_to_texture.rs
• examples/stress_tests/many_foxes.rs
• examples/games/desk_toy.rs
• examples/math/sampling_primitives.rs
• examples/3d/parallax_mapping.rs
• examples/2d/texture_atlas.rs
• examples/ui/directional_navigation.rs
• examples/ui/ui_drag_and_drop.rs
• examples/3d/deferred_rendering.rs
• examples/ui/box_shadow.rs
• examples/2d/text2d.rs
• examples/animation/custom_skinned_mesh.rs
• examples/3d/blend_modes.rs
• examples/stress_tests/many_cubes.rs
• examples/animation/animated_transform.rs
• examples/3d/lighting.rs
• examples/3d/camera_sub_view.rs
• examples/ui/text_debug.rs
• examples/ui/borders.rs
• examples/ui/grid.rs
• examples/3d/transmission.rs
• examples/ui/ui_transform.rs
• examples/ui/gradients.rs
• examples/testbed/full_ui.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/state/custom_transitions.rs (line 166)

fn cleanup_menu(mut commands: Commands, menu_data: Res<MenuData>) {
    commands.entity(menu_data.button_entity).despawn();
}

const SPEED: f32 = 100.0;
fn movement(
    time: Res<Time>,
    input: Res<ButtonInput<KeyCode>>,
    mut query: Query<&mut Transform, With<Sprite>>,
) {
    for mut transform in &mut query {
        let mut direction = Vec3::ZERO;
        if input.pressed(KeyCode::ArrowLeft) {
            direction.x -= 1.0;
        }
        if input.pressed(KeyCode::ArrowRight) {
            direction.x += 1.0;
        }
        if input.pressed(KeyCode::ArrowUp) {
            direction.y += 1.0;
        }
        if input.pressed(KeyCode::ArrowDown) {
            direction.y -= 1.0;
        }

        if direction != Vec3::ZERO {
            transform.translation += direction.normalize() * SPEED * time.delta_secs();
        }
    }
}

fn change_color(time: Res<Time>, mut query: Query<&mut Sprite>) {
    for mut sprite in &mut query {
        let new_color = LinearRgba {
            blue: ops::sin(time.elapsed_secs() * 0.5) + 2.0,
            ..LinearRgba::from(sprite.color)
        };

        sprite.color = new_color.into();
    }
}

// We can restart the game by pressing "R".
// This will trigger an [`AppState::InGame`] -> [`AppState::InGame`]
// transition, which will run our custom schedules.
fn trigger_game_restart(
    input: Res<ButtonInput<KeyCode>>,
    mut next_state: ResMut<NextState<AppState>>,
) {
    if input.just_pressed(KeyCode::KeyR) {
        // Although we are already in this state setting it again will generate an identity transition.
        // While default schedules ignore those kinds of transitions, our custom schedules will react to them.
        next_state.set(AppState::InGame);
    }
}

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

fn setup_game(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Sprite::from_image(asset_server.load("branding/icon.png")));
    info!("Setup game");
}

fn teardown_game(mut commands: Commands, player: Single<Entity, With<Sprite>>) {
    commands.entity(*player).despawn();
    info!("Teardown game");
}

examples/state/states.rs (line 113)

fn cleanup_menu(mut commands: Commands, menu_data: Res<MenuData>) {
    commands.entity(menu_data.button_entity).despawn();
}

examples/state/sub_states.rs (line 87)

fn cleanup_menu(mut commands: Commands, menu_data: Res<MenuData>) {
    commands.entity(menu_data.button_entity).despawn();
}

examples/remote/server.rs (line 86)

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

examples/state/computed_states.rs (line 401)

    pub fn cleanup_menu(mut commands: Commands, menu_data: Res<MenuData>) {
        commands.entity(menu_data.root_entity).despawn();
    }

examples/stress_tests/many_buttons.rs (line 322)

fn despawn_ui(mut commands: Commands, root_node: Single<Entity, (With<Node>, Without<ChildOf>)>) {
    commands.entity(*root_node).despawn();
}

Additional examples can be found in:

• examples/ecs/generic_system.rs
• examples/usage/context_menu.rs
• examples/3d/light_textures.rs
• examples/games/loading_screen.rs
• examples/ecs/removal_detection.rs
• examples/ui/standard_widgets_observers.rs
• examples/async_tasks/external_source_external_thread.rs
• examples/3d/volumetric_fog.rs
• examples/asset/multi_asset_sync.rs
• examples/input/text_input.rs
• examples/ecs/one_shot_systems.rs
• examples/window/screenshot.rs
• examples/3d/reflection_probes.rs
• examples/3d/depth_of_field.rs
• examples/ui/tab_navigation.rs
• examples/ecs/observer_propagation.rs
• examples/ecs/entity_disabling.rs
• examples/shader_advanced/custom_shader_instancing.rs
• examples/3d/pbr.rs
• examples/asset/asset_decompression.rs
• examples/animation/morph_targets.rs
• examples/window/window_settings.rs
• examples/app/log_layers_ecs.rs
• examples/ecs/error_handling.rs
• examples/testbed/3d.rs
• examples/animation/animated_mesh_control.rs
• examples/games/game_menu.rs
• examples/ui/standard_widgets.rs
• examples/3d/anisotropy.rs
• examples/3d/clearcoat.rs
• examples/3d/clustered_decals.rs
• examples/usage/cooldown.rs
• examples/3d/order_independent_transparency.rs
• examples/3d/tonemapping.rs
• examples/3d/irradiance_volumes.rs
• examples/3d/shadow_caster_receiver.rs
• examples/ecs/fallible_params.rs
• examples/games/stepping.rs
• examples/3d/pcss.rs
• examples/3d/visibility_range.rs
• examples/window/custom_cursor_image.rs
• examples/ecs/hierarchy.rs
• examples/audio/soundtrack.rs
• examples/3d/lightmaps.rs
• tests/window/desktop_request_redraw.rs
• examples/animation/animated_mesh.rs
• examples/math/bounding_2d.rs
• examples/ecs/relationships.rs
• examples/3d/occlusion_culling.rs
• examples/animation/eased_motion.rs
• examples/games/alien_cake_addict.rs
• examples/3d/edit_material_on_gltf.rs
• examples/games/breakout.rs
• examples/3d/ssr.rs
• examples/animation/animated_mesh_events.rs
• examples/async_tasks/async_compute.rs
• examples/animation/animation_graph.rs
• examples/window/monitor_info.rs
• examples/3d/blend_modes.rs
• examples/3d/solari.rs
• examples/math/random_sampling.rs
• examples/stress_tests/transform_hierarchy.rs
• examples/ui/text_wrap_debug.rs
• examples/animation/animation_masks.rs
• examples/testbed/ui.rs
• examples/3d/deferred_rendering.rs
• examples/math/sampling_primitives.rs
• examples/3d/mixed_lighting.rs
• examples/diagnostics/log_diagnostics.rs
• examples/ecs/component_hooks.rs
• examples/3d/ssao.rs
• examples/ui/scroll.rs
• tests/3d/test_invalid_skinned_mesh.rs
• examples/stress_tests/many_foxes.rs
• examples/3d/bloom_3d.rs
• examples/ui/directional_navigation.rs
• examples/2d/bloom_2d.rs
• examples/animation/custom_skinned_mesh.rs
• examples/3d/anti_aliasing.rs
• examples/animation/animated_transform.rs
• examples/3d/transmission.rs
• examples/ui/text_debug.rs
• examples/ui/feathers.rs

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

Returns the EntityCommands for the requested Entity if it exists.

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

Examples found in repository

examples/ecs/observers.rs (line 142)

fn explode_mine(explode: On<Explode>, query: Query<&Mine>, mut commands: Commands) {
    // Explode is an EntityEvent. `explode.entity` is the entity that Explode was triggered for.
    let Ok(mut entity) = commands.get_entity(explode.entity) else {
        return;
    };
    info!("Boom! {} exploded.", explode.entity);
    entity.despawn();
    let mine = query.get(explode.entity).unwrap();
    // Trigger another explosion cascade.
    commands.trigger(ExplodeMines {
        pos: mine.pos,
        radius: mine.size,
    });
}

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.

Examples found in repository

examples/ecs/ecs_guide.rs (lines 193-208)

fn startup_system(mut commands: Commands, mut game_state: ResMut<GameState>) {
    // Create our game rules resource
    commands.insert_resource(GameRules {
        max_rounds: 10,
        winning_score: 4,
        max_players: 4,
    });

    // Add some players to our world. Players start with a score of 0 ... we want our game to be
    // fair!
    commands.spawn_batch(vec![
        (
            Player {
                name: "Alice".to_string(),
            },
            Score { value: 0 },
            PlayerStreak::None,
        ),
        (
            Player {
                name: "Bob".to_string(),
            },
            Score { value: 0 },
            PlayerStreak::None,
        ),
    ]);

    // set the total players to "2"
    game_state.total_players = 2;
}

examples/stress_tests/many_sprites.rs (line 99)

fn setup(mut commands: Commands, assets: Res<AssetServer>, color_tint: Res<ColorTint>) {
    warn!(include_str!("warning_string.txt"));

    let mut rng = rand::rng();

    let tile_size = Vec2::splat(64.0);
    let map_size = Vec2::splat(320.0);

    let half_x = (map_size.x / 2.0) as i32;
    let half_y = (map_size.y / 2.0) as i32;

    let sprite_handle = assets.load("branding/icon.png");

    // Spawns the camera

    commands.spawn(Camera2d);

    // Builds and spawns the sprites
    let mut sprites = vec![];
    for y in -half_y..half_y {
        for x in -half_x..half_x {
            let position = Vec2::new(x as f32, y as f32);
            let translation = (position * tile_size).extend(rng.random::<f32>());
            let rotation = Quat::from_rotation_z(rng.random::<f32>());
            let scale = Vec3::splat(rng.random::<f32>() * 2.0);

            sprites.push((
                Sprite {
                    image: sprite_handle.clone(),
                    custom_size: Some(tile_size),
                    color: if color_tint.0 {
                        COLORS[rng.random_range(0..3)]
                    } else {
                        Color::WHITE
                    },
                    ..default()
                },
                Transform {
                    translation,
                    rotation,
                    scale,
                },
            ));
        }
    }
    commands.spawn_batch(sprites);
}

examples/stress_tests/many_text2d.rs (line 152)

fn setup(mut commands: Commands, font: Res<FontHandle>, args: Res<Args>) {
    warn!(include_str!("warning_string.txt"));

    let mut rng = ChaCha8Rng::seed_from_u64(42);

    let tile_size = Vec2::splat(64.0);
    let map_size = Vec2::splat(640.0);

    let half_x = (map_size.x / 4.0) as i32;
    let half_y = (map_size.y / 4.0) as i32;

    // Spawns the camera

    commands.spawn(Camera2d);

    // Builds and spawns the `Text2d`s, distributing them in a way that ensures a
    // good distribution of on-screen and off-screen entities.
    let mut text2ds = vec![];
    for y in -half_y..half_y {
        for x in -half_x..half_x {
            let position = Vec2::new(x as f32, y as f32);
            let translation = (position * tile_size).extend(rng.random::<f32>());
            let rotation = Quat::from_rotation_z(rng.random::<f32>());
            let scale = Vec3::splat(rng.random::<f32>() * 2.0);
            let color = Hsla::hsl(rng.random_range(0.0..360.0), 0.8, 0.8);

            text2ds.push((
                Text2d(random_text(&mut rng, &args)),
                random_text_font(&mut rng, &args, font.0.clone()),
                TextColor(color.into()),
                TextLayout::new_with_justify(if args.center {
                    Justify::Center
                } else {
                    Justify::Left
                }),
                Transform {
                    translation,
                    rotation,
                    scale,
                },
            ));
        }
    }

    if args.no_frustum_culling {
        let bundles = text2ds.into_iter().map(|bundle| (bundle, NoFrustumCulling));
        commands.spawn_batch(bundles);
    } else {
        commands.spawn_batch(text2ds);
    }
}

examples/stress_tests/many_lights.rs (lines 71-86)

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    warn!(include_str!("warning_string.txt"));

    const LIGHT_RADIUS: f32 = 0.3;
    const LIGHT_INTENSITY: f32 = 1000.0;
    const RADIUS: f32 = 50.0;
    const N_LIGHTS: usize = 100_000;

    commands.spawn((
        Mesh3d(meshes.add(Sphere::new(RADIUS).mesh().ico(9).unwrap())),
        MeshMaterial3d(materials.add(Color::WHITE)),
        Transform::from_scale(Vec3::NEG_ONE),
    ));

    let mesh = meshes.add(Cuboid::default());
    let material = materials.add(StandardMaterial {
        base_color: DEEP_PINK.into(),
        ..default()
    });

    // NOTE: This pattern is good for testing performance of culling as it provides roughly
    // the same number of visible meshes regardless of the viewing angle.
    // NOTE: f64 is used to avoid precision issues that produce visual artifacts in the distribution
    let golden_ratio = 0.5f64 * (1.0f64 + 5.0f64.sqrt());

    // Spawn N_LIGHTS many lights
    commands.spawn_batch((0..N_LIGHTS).map(move |i| {
        let mut rng = rng();

        let spherical_polar_theta_phi = fibonacci_spiral_on_sphere(golden_ratio, i, N_LIGHTS);
        let unit_sphere_p = spherical_polar_to_cartesian(spherical_polar_theta_phi);

        (
            PointLight {
                range: LIGHT_RADIUS,
                intensity: LIGHT_INTENSITY,
                color: Color::hsl(rng.random_range(0.0..360.0), 1.0, 0.5),
                ..default()
            },
            Transform::from_translation((RADIUS as f64 * unit_sphere_p).as_vec3()),
        )
    }));

    // camera
    match std::env::args().nth(1).as_deref() {
        Some("orthographic") => commands.spawn((
            Camera3d::default(),
            Projection::from(OrthographicProjection {
                scaling_mode: ScalingMode::FixedHorizontal {
                    viewport_width: 20.0,
                },
                ..OrthographicProjection::default_3d()
            }),
        )),
        _ => commands.spawn(Camera3d::default()),
    };

    // add one cube, the only one with strong handles
    // also serves as a reference point during rotation
    commands.spawn((
        Mesh3d(mesh),
        MeshMaterial3d(material),
        Transform {
            translation: Vec3::new(0.0, RADIUS, 0.0),
            scale: Vec3::splat(5.0),
            ..default()
        },
    ));
}

examples/3d/spotlight.rs (lines 58-72)

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    // ground plane
    commands.spawn((
        Mesh3d(meshes.add(Plane3d::default().mesh().size(100.0, 100.0))),
        MeshMaterial3d(materials.add(Color::WHITE)),
        Movable,
    ));

    // cubes

    // 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.
    let mut rng = ChaCha8Rng::seed_from_u64(19878367467713);
    let cube_mesh = meshes.add(Cuboid::new(0.5, 0.5, 0.5));
    let blue = materials.add(Color::srgb_u8(124, 144, 255));

    commands.spawn_batch(
        std::iter::repeat_with(move || {
            let x = rng.random_range(-5.0..5.0);
            let y = rng.random_range(0.0..3.0);
            let z = rng.random_range(-5.0..5.0);

            (
                Mesh3d(cube_mesh.clone()),
                MeshMaterial3d(blue.clone()),
                Transform::from_xyz(x, y, z),
                Movable,
            )
        })
        .take(40),
    );

    let sphere_mesh = meshes.add(Sphere::new(0.05).mesh().uv(32, 18));
    let sphere_mesh_direction = meshes.add(Sphere::new(0.1).mesh().uv(32, 18));
    let red_emissive = materials.add(StandardMaterial {
        base_color: RED.into(),
        emissive: LinearRgba::new(1.0, 0.0, 0.0, 0.0),
        ..default()
    });
    let maroon_emissive = materials.add(StandardMaterial {
        base_color: MAROON.into(),
        emissive: LinearRgba::new(0.369, 0.0, 0.0, 0.0),
        ..default()
    });

    for x in 0..4 {
        for z in 0..4 {
            let x = x as f32 - 2.0;
            let z = z as f32 - 2.0;
            // red spot_light
            commands.spawn((
                SpotLight {
                    intensity: 40_000.0, // lumens
                    color: Color::WHITE,
                    shadows_enabled: true,
                    inner_angle: PI / 4.0 * 0.85,
                    outer_angle: PI / 4.0,
                    ..default()
                },
                Transform::from_xyz(1.0 + x, 2.0, z)
                    .looking_at(Vec3::new(1.0 + x, 0.0, z), Vec3::X),
                children![
                    (
                        Mesh3d(sphere_mesh.clone()),
                        MeshMaterial3d(red_emissive.clone()),
                    ),
                    (
                        Mesh3d(sphere_mesh_direction.clone()),
                        MeshMaterial3d(maroon_emissive.clone()),
                        Transform::from_translation(Vec3::Z * -0.1),
                        NotShadowCaster,
                    )
                ],
            ));
        }
    }

    // camera
    commands.spawn((
        Camera3d::default(),
        Hdr,
        Transform::from_xyz(-4.0, 5.0, 10.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));

    commands.spawn((
        Text::new(INSTRUCTIONS),
        Node {
            position_type: PositionType::Absolute,
            top: px(12),
            left: px(12),
            ..default()
        },
    ));
}

examples/stress_tests/bevymark.rs (line 446)

fn spawn_birds(
    commands: &mut Commands,
    args: &Args,
    primary_window_resolution: &WindowResolution,
    counter: &mut BevyCounter,
    spawn_count: usize,
    bird_resources: &mut BirdResources,
    waves_to_simulate: Option<usize>,
    wave: usize,
) {
    let bird_x = (primary_window_resolution.width() / -2.) + HALF_BIRD_SIZE;
    let bird_y = (primary_window_resolution.height() / 2.) - HALF_BIRD_SIZE;

    let half_extents = 0.5 * primary_window_resolution.size();

    let color = counter.color;
    let current_count = counter.count;

    match args.mode {
        Mode::Sprite => {
            let batch = (0..spawn_count)
                .map(|count| {
                    let bird_z = if args.ordered_z {
                        (current_count + count) as f32 * 0.00001
                    } else {
                        bird_resources.transform_rng.random::<f32>()
                    };

                    let (transform, velocity) = bird_velocity_transform(
                        half_extents,
                        Vec3::new(bird_x, bird_y, bird_z),
                        &mut bird_resources.velocity_rng,
                        waves_to_simulate,
                        FIXED_DELTA_TIME,
                    );

                    let color = if args.vary_per_instance {
                        Color::linear_rgb(
                            bird_resources.color_rng.random(),
                            bird_resources.color_rng.random(),
                            bird_resources.color_rng.random(),
                        )
                    } else {
                        color
                    };
                    (
                        Sprite {
                            image: bird_resources
                                .textures
                                .choose(&mut bird_resources.material_rng)
                                .unwrap()
                                .clone(),
                            color,
                            ..default()
                        },
                        transform,
                        Bird { velocity },
                    )
                })
                .collect::<Vec<_>>();
            commands.spawn_batch(batch);
        }
        Mode::Mesh2d => {
            let batch = (0..spawn_count)
                .map(|count| {
                    let bird_z = if args.ordered_z {
                        (current_count + count) as f32 * 0.00001
                    } else {
                        bird_resources.transform_rng.random::<f32>()
                    };

                    let (transform, velocity) = bird_velocity_transform(
                        half_extents,
                        Vec3::new(bird_x, bird_y, bird_z),
                        &mut bird_resources.velocity_rng,
                        waves_to_simulate,
                        FIXED_DELTA_TIME,
                    );

                    let material =
                        if args.vary_per_instance || args.material_texture_count > args.waves {
                            bird_resources
                                .materials
                                .choose(&mut bird_resources.material_rng)
                                .unwrap()
                                .clone()
                        } else {
                            bird_resources.materials[wave % bird_resources.materials.len()].clone()
                        };
                    (
                        Mesh2d(bird_resources.quad.clone()),
                        MeshMaterial2d(material),
                        transform,
                        Bird { velocity },
                    )
                })
                .collect::<Vec<_>>();
            commands.spawn_batch(batch);
        }
    }

    counter.count += spawn_count;
    counter.color = Color::linear_rgb(
        bird_resources.color_rng.random(),
        bird_resources.color_rng.random(),
        bird_resources.color_rng.random(),
    );
}

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

Examples found in repository

examples/ecs/error_handling.rs (lines 172-183)

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

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

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

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.

Examples found in repository

examples/2d/mesh2d_manual.rs (line 373)

pub fn extract_colored_mesh2d(
    mut commands: Commands,
    mut previous_len: Local<usize>,
    // When extracting, you must use `Extract` to mark the `SystemParam`s
    // which should be taken from the main world.
    query: Extract<
        Query<
            (
                Entity,
                RenderEntity,
                &ViewVisibility,
                &GlobalTransform,
                &Mesh2d,
            ),
            With<ColoredMesh2d>,
        >,
    >,
    mut render_mesh_instances: ResMut<RenderColoredMesh2dInstances>,
) {
    let mut values = Vec::with_capacity(*previous_len);
    for (entity, render_entity, view_visibility, transform, handle) in &query {
        if !view_visibility.get() {
            continue;
        }

        let transforms = Mesh2dTransforms {
            world_from_local: (&transform.affine()).into(),
            flags: MeshFlags::empty().bits(),
        };

        values.push((render_entity, ColoredMesh2d));
        render_mesh_instances.insert(
            entity.into(),
            RenderMesh2dInstance {
                mesh_asset_id: handle.0.id(),
                transforms,
                material_bind_group_id: Material2dBindGroupId::default(),
                automatic_batching: false,
                tag: 0,
            },
        );
    }
    *previous_len = values.len();
    commands.try_insert_batch(values);
}

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

Examples found in repository

examples/shader_advanced/custom_phase_item.rs (line 210)

fn prepare_custom_phase_item_buffers(mut commands: Commands) {
    commands.init_resource::<CustomPhaseItemBuffers>();
}

examples/diagnostics/log_diagnostics.rs (line 89)

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

    commands.init_resource::<LogDiagnosticsFilters>();
    commands.init_resource::<LogDiagnosticsStatus>();

    commands.spawn((
        LogDiagnosticsCommands,
        Node {
            top: px(5),
            left: px(5),
            flex_direction: FlexDirection::Column,
            ..default()
        },
    ));
}

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/audio/pitch.rs (line 22)

fn setup(mut commands: Commands) {
    commands.insert_resource(PitchFrequency(220.0));
}

examples/app/headless_renderer.rs (lines 324-326)

fn image_copy_extract(mut commands: Commands, image_copiers: Extract<Query<&ImageCopier>>) {
    commands.insert_resource(ImageCopiers(
        image_copiers.iter().cloned().collect::<Vec<ImageCopier>>(),
    ));
}

examples/2d/texture_atlas.rs (line 34)

fn load_textures(mut commands: Commands, asset_server: Res<AssetServer>) {
    // Load multiple, individual sprites from a folder
    commands.insert_resource(RpgSpriteFolder(asset_server.load_folder("textures/rpg")));
}

examples/shader_advanced/custom_shader_instancing.rs (lines 208-211)

fn init_custom_pipeline(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mesh_pipeline: Res<MeshPipeline>,
) {
    commands.insert_resource(CustomPipeline {
        shader: asset_server.load(SHADER_ASSET_PATH),
        mesh_pipeline: mesh_pipeline.clone(),
    });
}

examples/shader_advanced/custom_render_phase.rs (lines 169-172)

fn init_stencil_pipeline(
    mut commands: Commands,
    mesh_pipeline: Res<MeshPipeline>,
    asset_server: Res<AssetServer>,
) {
    commands.insert_resource(StencilPipeline {
        mesh_pipeline: mesh_pipeline.clone(),
        shader_handle: asset_server.load(SHADER_ASSET_PATH),
    });
}

examples/ecs/change_detection.rs (line 32)

fn setup(mut commands: Commands) {
    // Note the first change detection log correctly points to this line because the component is
    // added. Although commands are deferred, they are able to track the original calling location.
    commands.spawn(MyComponent(0.0));
    commands.insert_resource(MyResource(0.0));
}

Additional examples can be found in:

• examples/shader_advanced/specialized_mesh_pipeline.rs
• examples/2d/mesh2d_manual.rs
• examples/async_tasks/async_compute.rs
• examples/asset/processing/asset_processing.rs
• examples/2d/sprite_tile.rs
• examples/shader/array_texture.rs
• examples/window/window_settings.rs
• examples/audio/soundtrack.rs
• examples/games/desk_toy.rs
• examples/async_tasks/external_source_external_thread.rs
• examples/games/loading_screen.rs
• examples/ecs/ecs_guide.rs
• examples/shader/compute_shader_game_of_life.rs
• examples/3d/manual_material.rs
• examples/games/game_menu.rs
• examples/remote/server.rs
• examples/ui/font_atlas_debug.rs
• examples/2d/tilemap_chunk.rs
• examples/asset/multi_asset_sync.rs
• examples/state/custom_transitions.rs
• examples/testbed/3d.rs
• examples/state/states.rs
• examples/3d/skybox.rs
• examples/state/sub_states.rs
• examples/shader/storage_buffer.rs
• examples/movement/smooth_follow.rs
• examples/games/contributors.rs
• examples/gizmos/axes.rs
• examples/3d/motion_blur.rs
• examples/animation/animated_mesh_events.rs
• examples/math/cubic_splines.rs
• examples/animation/animation_graph.rs
• examples/animation/animated_mesh_control.rs
• examples/2d/cpu_draw.rs
• examples/shader_advanced/custom_post_processing.rs
• examples/transforms/align.rs
• examples/math/random_sampling.rs
• examples/3d/solari.rs
• examples/state/computed_states.rs
• examples/animation/animation_masks.rs
• examples/games/alien_cake_addict.rs
• examples/shader/gpu_readback.rs
• examples/3d/auto_exposure.rs
• examples/stress_tests/bevymark.rs
• examples/ui/drag_to_scroll.rs
• examples/games/breakout.rs
• examples/stress_tests/many_foxes.rs
• examples/math/sampling_primitives.rs
• examples/3d/lighting.rs

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

Examples found in repository

examples/games/desk_toy.rs (line 267)

fn end_drag(mut commands: Commands) {
    commands.remove_resource::<DragOperation>();
}

examples/asset/multi_asset_sync.rs (line 275)

fn despawn_loading_state_entities(mut commands: Commands, loading: Query<Entity, With<Loading>>) {
    // Despawn entities in the loading phase.
    for entity in loading.iter() {
        commands.entity(entity).despawn();
    }

    // Despawn resources used in the loading phase.
    commands.remove_resource::<AssetBarrier>();
    commands.remove_resource::<AsyncLoadingState>();
}

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.

Examples found in repository

examples/ecs/one_shot_systems.rs (line 77)

fn evaluate_callbacks(query: Query<(Entity, &Callback), With<Triggered>>, mut commands: Commands) {
    for (entity, callback) in query.iter() {
        commands.run_system(callback.0);
        commands.entity(entity).remove::<Triggered>();
    }
}

examples/games/loading_screen.rs (line 106)

fn level_selection(
    mut commands: Commands,
    keyboard: Res<ButtonInput<KeyCode>>,
    level_data: Res<LevelData>,
    loading_state: Res<LoadingState>,
) {
    // Only trigger a load if the current level is fully loaded.
    if let LoadingState::LevelReady = loading_state.as_ref() {
        if keyboard.just_pressed(KeyCode::Digit1) {
            commands.run_system(level_data.unload_level_id);
            commands.run_system(level_data.level_1_id);
        } else if keyboard.just_pressed(KeyCode::Digit2) {
            commands.run_system(level_data.unload_level_id);
            commands.run_system(level_data.level_2_id);
        }
    }
}

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

Examples found in repository

examples/ecs/one_shot_systems.rs (line 43)

fn setup_with_commands(mut commands: Commands) {
    let system_id = commands.register_system(system_a);
    commands.spawn((Callback(system_id), A));
}

examples/games/loading_screen.rs (line 73)

fn setup(mut commands: Commands) {
    let level_data = LevelData {
        unload_level_id: commands.register_system(unload_current_level),
        level_1_id: commands.register_system(load_level_1),
        level_2_id: commands.register_system(load_level_2),
    };
    commands.insert_resource(level_data);

    // Spawns the UI that will show the user prompts.
    let text_style = TextFont {
        font_size: 42.0,
        ..default()
    };
    commands
        .spawn((
            Node {
                justify_self: JustifySelf::Center,
                align_self: AlignSelf::FlexEnd,
                ..default()
            },
            BackgroundColor(Color::NONE),
        ))
        .with_child((Text::new("Press 1 or 2 to load a new scene."), text_style));
}

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.

Examples found in repository

examples/usage/context_menu.rs (line 66)

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);

    commands.spawn(background_and_button()).observe(
        // any click bubbling up here should lead to closing any open menu
        |_: On<Pointer<Press>>, mut commands: Commands| {
            commands.trigger(CloseContextMenus);
        },
    );
}

fn on_trigger_close_menus(
    _event: On<CloseContextMenus>,
    mut commands: Commands,
    menus: Query<Entity, With<ContextMenu>>,
) {
    for e in menus.iter() {
        commands.entity(e).despawn();
    }
}

fn on_trigger_menu(event: On<OpenContextMenu>, mut commands: Commands) {
    commands.trigger(CloseContextMenus);

    let pos = event.pos;

    debug!("open context menu at: {pos}");

    commands
        .spawn((
            Name::new("context menu"),
            ContextMenu,
            Node {
                position_type: PositionType::Absolute,
                left: px(pos.x),
                top: px(pos.y),
                flex_direction: FlexDirection::Column,
                ..default()
            },
            BorderColor::all(Color::BLACK),
            BorderRadius::all(px(4)),
            BackgroundColor(Color::linear_rgb(0.1, 0.1, 0.1)),
            children![
                context_item("fuchsia", basic::FUCHSIA),
                context_item("gray", basic::GRAY),
                context_item("maroon", basic::MAROON),
                context_item("purple", basic::PURPLE),
                context_item("teal", basic::TEAL),
            ],
        ))
        .observe(
            |event: On<Pointer<Press>>,
             menu_items: Query<&ContextMenuItem>,
             mut clear_col: ResMut<ClearColor>,
             mut commands: Commands| {
                let target = event.original_event_target();

                if let Ok(item) = menu_items.get(target) {
                    clear_col.0 = item.0.into();
                    commands.trigger(CloseContextMenus);
                }
            },
        );
}

fn context_item(text: &str, col: Srgba) -> impl Bundle {
    (
        Name::new(format!("item-{text}")),
        ContextMenuItem(col),
        Button,
        Node {
            padding: UiRect::all(px(5)),
            ..default()
        },
        children![(
            Pickable::IGNORE,
            Text::new(text),
            TextFont {
                font_size: 24.0,
                ..default()
            },
            TextColor(Color::WHITE),
        )],
    )
}

fn background_and_button() -> impl Bundle {
    (
        Name::new("background"),
        Node {
            width: percent(100),
            height: percent(100),
            align_items: AlignItems::Center,
            justify_content: JustifyContent::Center,
            ..default()
        },
        ZIndex(-10),
        Children::spawn(SpawnWith(|parent: &mut RelatedSpawner<ChildOf>| {
            parent
                .spawn((
                    Name::new("button"),
                    Button,
                    Node {
                        width: px(250),
                        height: px(65),
                        border: UiRect::all(px(5)),
                        justify_content: JustifyContent::Center,
                        align_items: AlignItems::Center,
                        ..default()
                    },
                    BorderColor::all(Color::BLACK),
                    BorderRadius::MAX,
                    BackgroundColor(Color::BLACK),
                    children![(
                        Pickable::IGNORE,
                        Text::new("Context Menu"),
                        TextFont {
                            font_size: 28.0,
                            ..default()
                        },
                        TextColor(Color::WHITE),
                        TextShadow::default(),
                    )],
                ))
                .observe(|mut event: On<Pointer<Press>>, mut commands: Commands| {
                    // by default this event would bubble up further leading to the `CloseContextMenus`
                    // event being triggered and undoing the opening of one here right away.
                    event.propagate(false);

                    debug!("click: {}", event.pointer_location.position);

                    commands.trigger(OpenContextMenu {
                        pos: event.pointer_location.position,
                    });
                });
        })),
    )
}

examples/ecs/observer_propagation.rs (line 74)

fn attack_armor(entities: Query<Entity, With<Armor>>, mut commands: Commands) {
    let mut rng = rng();
    if let Some(entity) = entities.iter().choose(&mut rng) {
        let damage = rng.random_range(1..20);
        commands.trigger(Attack { damage, entity });
        info!("⚔️  Attack for {} damage", damage);
    }
}

examples/ui/scroll.rs (line 44)

fn send_scroll_events(
    mut mouse_wheel_reader: MessageReader<MouseWheel>,
    hover_map: Res<HoverMap>,
    keyboard_input: Res<ButtonInput<KeyCode>>,
    mut commands: Commands,
) {
    for mouse_wheel in mouse_wheel_reader.read() {
        let mut delta = -Vec2::new(mouse_wheel.x, mouse_wheel.y);

        if mouse_wheel.unit == MouseScrollUnit::Line {
            delta *= LINE_HEIGHT;
        }

        if keyboard_input.any_pressed([KeyCode::ControlLeft, KeyCode::ControlRight]) {
            std::mem::swap(&mut delta.x, &mut delta.y);
        }

        for pointer_map in hover_map.values() {
            for entity in pointer_map.keys().copied() {
                commands.trigger(Scroll { entity, delta });
            }
        }
    }
}

examples/ui/directional_navigation.rs (lines 383-406)

fn interact_with_focused_button(
    action_state: Res<ActionState>,
    input_focus: Res<InputFocus>,
    mut commands: Commands,
) {
    if action_state
        .pressed_actions
        .contains(&DirectionalNavigationAction::Select)
        && let Some(focused_entity) = input_focus.0
    {
        commands.trigger(Pointer::<Click> {
            entity: focused_entity,
            // We're pretending that we're a mouse
            pointer_id: PointerId::Mouse,
            // This field isn't used, so we're just setting it to a placeholder value
            pointer_location: Location {
                target: NormalizedRenderTarget::None {
                    width: 0,
                    height: 0,
                },
                position: Vec2::ZERO,
            },
            event: Click {
                button: PointerButton::Primary,
                // This field isn't used, so we're just setting it to a placeholder value
                hit: HitData {
                    camera: Entity::PLACEHOLDER,
                    depth: 0.0,
                    position: None,
                    normal: None,
                },
                duration: Duration::from_secs_f32(0.1),
            },
        });
    }
}

examples/ecs/observers.rs (line 30)

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .init_resource::<SpatialIndex>()
        .add_systems(Startup, setup)
        .add_systems(Update, (draw_shapes, handle_click))
        // Observers are systems that run when an event is "triggered". This observer runs whenever
        // `ExplodeMines` is triggered.
        .add_observer(
            |explode_mines: On<ExplodeMines>,
             mines: Query<&Mine>,
             index: Res<SpatialIndex>,
             mut commands: Commands| {
                // Access resources
                for entity in index.get_nearby(explode_mines.pos) {
                    // Run queries
                    let mine = mines.get(entity).unwrap();
                    if mine.pos.distance(explode_mines.pos) < mine.size + explode_mines.radius {
                        // And queue commands, including triggering additional events
                        // Here we trigger the `Explode` event for entity `e`
                        commands.trigger(Explode { entity });
                    }
                }
            },
        )
        // This observer runs whenever the `Mine` component is added to an entity, and places it in a simple spatial index.
        .add_observer(on_add_mine)
        // This observer runs whenever the `Mine` component is removed from an entity (including despawning it)
        // and removes it from the spatial index.
        .add_observer(on_remove_mine)
        .run();
}

#[derive(Component)]
struct Mine {
    pos: Vec2,
    size: f32,
}

impl Mine {
    fn random(rand: &mut ChaCha8Rng) -> Self {
        Mine {
            pos: Vec2::new(
                (rand.random::<f32>() - 0.5) * 1200.0,
                (rand.random::<f32>() - 0.5) * 600.0,
            ),
            size: 4.0 + rand.random::<f32>() * 16.0,
        }
    }
}

/// This is a normal [`Event`]. Any observer that watches for it will run when it is triggered.
#[derive(Event)]
struct ExplodeMines {
    pos: Vec2,
    radius: f32,
}

/// An [`EntityEvent`] is a specialized type of [`Event`] that can target a specific entity. In addition to
/// running normal "top level" observers when it is triggered (which target _any_ entity that Explodes), it will
/// also run any observers that target the _specific_ entity for that event.
#[derive(EntityEvent)]
struct Explode {
    entity: Entity,
}

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);
    commands.spawn((
        Text::new(
            "Click on a \"Mine\" to trigger it.\n\
            When it explodes it will trigger all overlapping mines.",
        ),
        Node {
            position_type: PositionType::Absolute,
            top: px(12),
            left: px(12),
            ..default()
        },
    ));

    let mut rng = ChaCha8Rng::seed_from_u64(19878367467713);

    commands
        .spawn(Mine::random(&mut rng))
        // Observers can watch for events targeting a specific entity.
        // This will create a new observer that runs whenever the Explode event
        // is triggered for this spawned entity.
        .observe(explode_mine);

    // We want to spawn a bunch of mines. We could just call the code above for each of them.
    // That would create a new observer instance for every Mine entity. Having duplicate observers
    // generally isn't worth worrying about as the overhead is low. But if you want to be maximally efficient,
    // you can reuse observers across entities.
    //
    // First, observers are actually just entities with the Observer component! The `observe()` functions
    // you've seen so far in this example are just shorthand for manually spawning an observer.
    let mut observer = Observer::new(explode_mine);

    // As we spawn entities, we can make this observer watch each of them:
    for _ in 0..1000 {
        let entity = commands.spawn(Mine::random(&mut rng)).id();
        observer.watch_entity(entity);
    }

    // By spawning the Observer component, it becomes active!
    commands.spawn(observer);
}

fn on_add_mine(add: On<Add, Mine>, query: Query<&Mine>, mut index: ResMut<SpatialIndex>) {
    let mine = query.get(add.entity).unwrap();
    let tile = (
        (mine.pos.x / CELL_SIZE).floor() as i32,
        (mine.pos.y / CELL_SIZE).floor() as i32,
    );
    index.map.entry(tile).or_default().insert(add.entity);
}

// Remove despawned mines from our index
fn on_remove_mine(remove: On<Remove, Mine>, query: Query<&Mine>, mut index: ResMut<SpatialIndex>) {
    let mine = query.get(remove.entity).unwrap();
    let tile = (
        (mine.pos.x / CELL_SIZE).floor() as i32,
        (mine.pos.y / CELL_SIZE).floor() as i32,
    );
    index.map.entry(tile).and_modify(|set| {
        set.remove(&remove.entity);
    });
}

fn explode_mine(explode: On<Explode>, query: Query<&Mine>, mut commands: Commands) {
    // Explode is an EntityEvent. `explode.entity` is the entity that Explode was triggered for.
    let Ok(mut entity) = commands.get_entity(explode.entity) else {
        return;
    };
    info!("Boom! {} exploded.", explode.entity);
    entity.despawn();
    let mine = query.get(explode.entity).unwrap();
    // Trigger another explosion cascade.
    commands.trigger(ExplodeMines {
        pos: mine.pos,
        radius: mine.size,
    });
}

// Draw a circle for each mine using `Gizmos`
fn draw_shapes(mut gizmos: Gizmos, mines: Query<&Mine>) {
    for mine in &mines {
        gizmos.circle_2d(
            mine.pos,
            mine.size,
            Color::hsl((mine.size - 4.0) / 16.0 * 360.0, 1.0, 0.8),
        );
    }
}

// Trigger `ExplodeMines` at the position of a given click
fn handle_click(
    mouse_button_input: Res<ButtonInput<MouseButton>>,
    camera: Single<(&Camera, &GlobalTransform)>,
    windows: Query<&Window>,
    mut commands: Commands,
) {
    let Ok(windows) = windows.single() else {
        return;
    };

    let (camera, camera_transform) = *camera;
    if let Some(pos) = windows
        .cursor_position()
        .and_then(|cursor| camera.viewport_to_world(camera_transform, cursor).ok())
        .map(|ray| ray.origin.truncate())
        && mouse_button_input.just_pressed(MouseButton::Left)
    {
        commands.trigger(ExplodeMines { pos, radius: 1.0 });
    }
}

examples/games/breakout.rs (line 354)

fn check_for_collisions(
    mut commands: Commands,
    mut score: ResMut<Score>,
    ball_query: Single<(&mut Velocity, &Transform), With<Ball>>,
    collider_query: Query<(Entity, &Transform, Option<&Brick>), With<Collider>>,
) {
    let (mut ball_velocity, ball_transform) = ball_query.into_inner();

    for (collider_entity, collider_transform, maybe_brick) in &collider_query {
        let collision = ball_collision(
            BoundingCircle::new(ball_transform.translation.truncate(), BALL_DIAMETER / 2.),
            Aabb2d::new(
                collider_transform.translation.truncate(),
                collider_transform.scale.truncate() / 2.,
            ),
        );

        if let Some(collision) = collision {
            // Trigger observers of the "BallCollided" event
            commands.trigger(BallCollided);

            // Bricks should be despawned and increment the scoreboard on collision
            if maybe_brick.is_some() {
                commands.entity(collider_entity).despawn();
                **score += 1;
            }

            // Reflect the ball's velocity when it collides
            let mut reflect_x = false;
            let mut reflect_y = false;

            // Reflect only if the velocity is in the opposite direction of the collision
            // This prevents the ball from getting stuck inside the bar
            match collision {
                Collision::Left => reflect_x = ball_velocity.x > 0.0,
                Collision::Right => reflect_x = ball_velocity.x < 0.0,
                Collision::Top => reflect_y = ball_velocity.y < 0.0,
                Collision::Bottom => reflect_y = ball_velocity.y > 0.0,
            }

            // Reflect velocity on the x-axis if we hit something on the x-axis
            if reflect_x {
                ball_velocity.x = -ball_velocity.x;
            }

            // Reflect velocity on the y-axis if we hit something on the y-axis
            if reflect_y {
                ball_velocity.y = -ball_velocity.y;
            }
        }
    }
}

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

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

👎Deprecated since 0.17.0: Use Commands::trigger instead.

A deprecated alias for trigger to ease migration.

Instead of specifying the trigger target separately, information about the target of the event is embedded in the data held by the event type itself.

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.

Examples found in repository

tests/window/desktop_request_redraw.rs (line 105)

fn redraw(mut commands: Commands, query: Query<Entity, With<AnimationActive>>) {
    if query.iter().next().is_some() {
        commands.write_message(RequestRedraw);
    }
}

examples/3d/clustered_decals.rs (line 166)

fn setup(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    app_status: Res<AppStatus>,
    render_device: Res<RenderDevice>,
    render_adapter: Res<RenderAdapter>,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<ExtendedMaterial<StandardMaterial, CustomDecalExtension>>>,
) {
    // Error out if clustered decals aren't supported on the current platform.
    if !decal::clustered::clustered_decals_are_usable(&render_device, &render_adapter) {
        error!("Clustered decals aren't usable on this platform.");
        commands.write_message(AppExit::error());
    }

    spawn_cube(&mut commands, &mut meshes, &mut materials);
    spawn_camera(&mut commands);
    spawn_light(&mut commands);
    spawn_decals(&mut commands, &asset_server);
    spawn_buttons(&mut commands);
    spawn_help_text(&mut commands, &app_status);
}

examples/3d/light_textures.rs (line 155)

fn setup(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    app_status: Res<AppStatus>,
    render_device: Res<RenderDevice>,
    render_adapter: Res<RenderAdapter>,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    // Error out if clustered decals (and so light textures) aren't supported on the current platform.
    if !decal::clustered::clustered_decals_are_usable(&render_device, &render_adapter) {
        error!("Light textures aren't usable on this platform.");
        commands.write_message(AppExit::error());
    }

    spawn_cubes(&mut commands, &mut meshes, &mut materials);
    spawn_camera(&mut commands);
    spawn_light(&mut commands, &asset_server);
    spawn_buttons(&mut commands);
    spawn_help_text(&mut commands, &app_status);
    spawn_light_textures(&mut commands, &asset_server, &mut meshes, &mut materials);
}

pub fn send_event<E>(&mut self, event: E) -> &mut Commands<'w, 's>

where E: Message,

👎Deprecated since 0.17.0: Use Commands::write_message instead.

Writes an arbitrary Message.

This is a convenience method for writing events 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 events are performance-critical or very frequently sent, consider using a typed 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.

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<'_, '_>