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 by setting the GLOBAL_ERROR_HANDLER.

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

fn handle_tasks(mut commands: Commands, mut transform_tasks: Query<&mut ComputeTransform>) {
    for 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);
        }
    }
}

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

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

                    // Pretend this is a time-intensive function. :)
                    async_std::task::sleep(duration).await;

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

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

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

                        world
                            .entity_mut(entity)
                            // Add our new `Mesh3d` and `MeshMaterial3d` to our tagged entity
                            .insert((
                                Mesh3d(box_mesh_handle),
                                MeshMaterial3d(box_material_handle),
                                transform,
                            ))
                            // Task is complete, so remove task component from entity
                            .remove::<ComputeTransform>();
                    });

                    command_queue
                });

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

examples/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::thread_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.r#gen::<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 45)

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

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

    use super::{despawn_screen, 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)))
            // When exiting the state, despawn everything that was spawned for this screen
            .add_systems(OnExit(GameState::Splash), despawn_screen::<OnSplashScreen>);
    }

    // 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((
            Node {
                align_items: AlignItems::Center,
                justify_content: JustifyContent::Center,
                width: Val::Percent(100.0),
                height: Val::Percent(100.0),
                ..default()
            },
            OnSplashScreen,
            children![(
                ImageNode::new(icon),
                Node {
                    // This will set the logo to be 200px wide, and auto adjust its height
                    width: Val::Px(200.0),
                    ..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()).finished() {
            game_state.set(GameState::Menu);
        }
    }
}

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

    use super::{despawn_screen, 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)))
            .add_systems(OnExit(GameState::Game), despawn_screen::<OnGameScreen>);
    }

    // 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((
            Node {
                width: Val::Percent(100.0),
                height: Val::Percent(100.0),
                // 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(Val::Px(50.0)),
                            ..default()
                        },
                    ),
                    (
                        Text::default(),
                        Node {
                            margin: UiRect::all(Val::Px(50.0)),
                            ..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()).finished() {
            game_state.set(GameState::Menu);
        }
    }
}

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

    use super::{despawn_screen, 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)
            .add_systems(OnExit(MenuState::Main), despawn_screen::<OnMainMenuScreen>)
            // Systems to handle the settings menu screen
            .add_systems(OnEnter(MenuState::Settings), settings_menu_setup)
            .add_systems(
                OnExit(MenuState::Settings),
                despawn_screen::<OnSettingsMenuScreen>,
            )
            // 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)),),
            )
            .add_systems(
                OnExit(MenuState::SettingsDisplay),
                despawn_screen::<OnDisplaySettingsMenuScreen>,
            )
            // 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)),
            )
            .add_systems(
                OnExit(MenuState::SettingsSound),
                despawn_screen::<OnSoundSettingsMenuScreen>,
            )
            // 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: Val::Px(300.0),
            height: Val::Px(65.0),
            margin: UiRect::all(Val::Px(20.0)),
            justify_content: JustifyContent::Center,
            align_items: AlignItems::Center,
            ..default()
        };
        let button_icon_node = Node {
            width: Val::Px(30.0),
            // 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: Val::Px(10.0),
            ..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((
            Node {
                width: Val::Percent(100.0),
                height: Val::Percent(100.0),
                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(Val::Px(50.0)),
                            ..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: Val::Px(200.0),
            height: Val::Px(65.0),
            margin: UiRect::all(Val::Px(20.0)),
            justify_content: JustifyContent::Center,
            align_items: AlignItems::Center,
            ..default()
        };

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

        commands.spawn((
            Node {
                width: Val::Percent(100.0),
                height: Val::Percent(100.0),
                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: Val::Px(200.0),
                height: Val::Px(65.0),
                margin: UiRect::all(Val::Px(20.0)),
                justify_content: JustifyContent::Center,
                align_items: AlignItems::Center,
                ..default()
            }
        }
        fn button_text_style() -> impl Bundle {
            (
                TextFont {
                    font_size: 33.0,
                    ..default()
                },
                TextColor(TEXT_COLOR),
            )
        }

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

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

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

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: Val::Percent(100.),
                height: Val::Percent(100.),
                justify_content: JustifyContent::Center,
                align_items: AlignItems::Center,
                ..default()
            },
            children![(
                Button,
                Node {
                    width: Val::Px(150.),
                    height: Val::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: Val::Percent(100.),
                height: Val::Percent(100.),
                justify_content: JustifyContent::Center,
                align_items: AlignItems::Center,
                ..default()
            },
            children![(
                Button,
                Node {
                    width: Val::Px(150.),
                    height: Val::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 17)

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 {
        let mut cmd = commands.spawn((
            Sprite {
                image: rect.texture,
                custom_size: Some(rect.size),
                image_mode: rect.image_mode,
                ..default()
            },
            rect.transform,
        ));

        cmd.with_children(|builder| {
            builder.spawn((
                Text2d::new(rect.text),
                TextLayout::new_with_justify(JustifyText::Center),
                TextFont::from_font_size(15.),
                Transform::from_xyz(0., -0.5 * rect.size.y - 10., 0.),
                bevy::sprite::Anchor::TopCenter,
            ));
        });
    }
}

fn setup_texture_atlas(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut texture_atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
) {
    commands.spawn(Camera2d);
    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 {
        let mut cmd = 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,
        ));

        cmd.with_children(|builder| {
            builder.spawn((
                Text2d::new(sprite_sheet.text),
                TextLayout::new_with_justify(JustifyText::Center),
                TextFont::from_font_size(15.),
                Transform::from_xyz(0., -0.5 * sprite_sheet.size.y - 10., 0.),
                bevy::sprite::Anchor::TopCenter,
            ));
        });
    }
}

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/ecs/system_param.rs
• examples/3d/irradiance_volumes.rs
• examples/ui/button.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/3d/reflection_probes.rs
• examples/2d/sprite.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/ecs/change_detection.rs
• examples/3d/fog.rs
• examples/app/log_layers_ecs.rs
• examples/asset/multi_asset_sync.rs
• examples/2d/mesh2d.rs
• examples/ecs/component_hooks.rs
• examples/2d/sprite_flipping.rs
• examples/window/screenshot.rs
• examples/math/render_primitives.rs
• examples/ecs/generic_system.rs
• examples/movement/physics_in_fixed_timestep.rs
• examples/stress_tests/many_gizmos.rs
• examples/animation/gltf_skinned_mesh.rs
• examples/games/alien_cake_addict.rs
• examples/shader/animate_shader.rs
• examples/audio/pitch.rs
• examples/async_tasks/async_compute.rs
• examples/3d/query_gltf_primitives.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/audio/audio_control.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/dev_tools/fps_overlay.rs
• examples/camera/2d_top_down_camera.rs
• examples/2d/pixel_grid_snap.rs
• examples/shader/fallback_image.rs
• examples/shader/custom_phase_item.rs
• examples/3d/motion_blur.rs
• examples/3d/3d_viewport_to_world.rs
• examples/gizmos/2d_gizmos.rs
• examples/3d/clustered_decals.rs
• examples/shader/shader_material.rs
• examples/shader/shader_material_glsl.rs
• examples/asset/extra_source.rs
• examples/shader/texture_binding_array.rs
• examples/ui/window_fallthrough.rs
• examples/asset/hot_asset_reloading.rs
• examples/ecs/parallel_query.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/shader/custom_vertex_attribute.rs
• examples/ecs/entity_disabling.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/animation/morph_targets.rs
• examples/shader/shader_defs.rs
• examples/3d/post_processing.rs
• examples/3d/clearcoat.rs
• examples/3d/3d_scene.rs
• examples/diagnostics/log_diagnostics.rs
• examples/asset/embedded_asset.rs
• examples/2d/sprite_sheet.rs
• examples/shader/custom_post_processing.rs
• examples/ui/font_atlas_debug.rs
• examples/animation/animation_graph.rs
• examples/shader/compute_shader_game_of_life.rs
• examples/3d/color_grading.rs
• examples/shader/shader_material_screenspace_texture.rs
• examples/3d/pcss.rs
• examples/3d/tonemapping.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/3d/parenting.rs
• examples/window/window_drag_move.rs
• examples/3d/animated_material.rs
• examples/3d/depth_of_field.rs
• examples/camera/custom_projection.rs
• examples/animation/animated_mesh_events.rs
• examples/3d/skybox.rs
• examples/3d/load_gltf.rs
• examples/3d/two_passes.rs
• examples/window/scale_factor_override.rs
• examples/3d/lines.rs
• examples/input/text_input.rs
• examples/stress_tests/many_materials.rs
• examples/animation/animated_mesh.rs
• examples/camera/2d_screen_shake.rs
• examples/shader/extended_material_bindless.rs
• examples/stress_tests/many_glyphs.rs
• examples/stress_tests/text_pipeline.rs
• examples/3d/update_gltf_scene.rs
• examples/shader/custom_render_phase.rs
• examples/3d/atmosphere.rs
• examples/3d/order_independent_transparency.rs
• examples/shader/storage_buffer.rs
• examples/2d/mesh2d_vertex_color_texture.rs
• examples/ecs/hierarchy.rs
• examples/3d/fog_volumes.rs
• examples/3d/generate_custom_mesh.rs
• examples/2d/wireframe_2d.rs
• examples/stress_tests/many_sprites.rs
• examples/audio/soundtrack.rs
• examples/animation/color_animation.rs
• examples/window/low_power.rs
• examples/audio/spatial_audio_2d.rs
• examples/movement/smooth_follow.rs
• examples/3d/mesh_ray_cast.rs
• examples/ui/relative_cursor_position.rs
• examples/3d/vertex_colors.rs
• examples/shader/extended_material.rs
• examples/picking/simple_picking.rs
• examples/shader/custom_shader_instancing.rs
• examples/ui/ui_material.rs
• examples/animation/animation_events.rs
• examples/games/contributors.rs
• examples/3d/orthographic.rs
• examples/testbed/2d.rs
• examples/shader/specialized_mesh_pipeline.rs
• examples/picking/debug_picking.rs
• examples/3d/spherical_area_lights.rs
• examples/2d/2d_shapes.rs
• examples/ecs/observers.rs
• examples/ui/ui_scaling.rs
• examples/math/bounding_2d.rs
• examples/transforms/transform.rs
• examples/2d/2d_viewport_to_world.rs
• examples/window/multiple_windows.rs
• examples/stress_tests/many_animated_sprites.rs
• examples/ui/ui_texture_atlas.rs
• examples/stress_tests/many_text2d.rs
• examples/gizmos/axes.rs
• examples/2d/bloom_2d.rs
• examples/ecs/relationships.rs
• examples/3d/occlusion_culling.rs
• examples/math/custom_primitives.rs
• examples/camera/first_person_view_model.rs
• examples/ui/ghost_nodes.rs
• examples/asset/alter_sprite.rs
• examples/app/headless_renderer.rs
• examples/ui/overflow_debug.rs
• examples/animation/eased_motion.rs
• examples/3d/ssao.rs
• examples/3d/wireframe.rs
• examples/stress_tests/transform_hierarchy.rs
• examples/stress_tests/many_buttons.rs
• examples/shader/automatic_instancing.rs
• examples/audio/spatial_audio_3d.rs
• examples/ecs/error_handling.rs
• examples/camera/projection_zoom.rs
• examples/2d/rotation.rs
• examples/ui/ui_texture_slice.rs
• examples/3d/visibility_range.rs
• examples/3d/specular_tint.rs
• examples/2d/sprite_animation.rs
• examples/math/cubic_splines.rs
• examples/testbed/3d.rs
• examples/2d/cpu_draw.rs
• examples/animation/animated_mesh_control.rs
• examples/stress_tests/many_cameras_lights.rs
• examples/3d/volumetric_fog.rs
• examples/3d/texture.rs
• examples/animation/animated_ui.rs
• examples/time/virtual_time.rs
• examples/3d/shadow_caster_receiver.rs
• examples/ui/ui_texture_slice_flip_and_tile.rs
• examples/window/monitor_info.rs
• examples/stress_tests/many_lights.rs
• examples/ui/size_constraints.rs
• examples/gizmos/3d_gizmos.rs
• examples/games/stepping.rs
• examples/3d/bloom_3d.rs
• examples/3d/anti_aliasing.rs
• examples/ui/transparency_ui.rs
• examples/transforms/align.rs
• examples/3d/decal.rs
• examples/math/random_sampling.rs
• examples/ui/render_ui_to_texture.rs
• examples/ui/ui_texture_atlas_slice.rs
• examples/shader/gpu_readback.rs
• examples/picking/sprite_picking.rs
• examples/2d/mesh2d_alpha_mode.rs
• examples/3d/scrolling_fog.rs
• examples/2d/mesh2d_arcs.rs
• examples/asset/repeated_texture.rs
• examples/ecs/iter_combinations.rs
• examples/ui/text_wrap_debug.rs
• examples/2d/mesh2d_manual.rs
• examples/asset/alter_mesh.rs
• examples/2d/sprite_slice.rs
• examples/3d/transparency_3d.rs
• examples/asset/asset_settings.rs
• examples/ui/text.rs
• examples/2d/mesh2d_repeated_texture.rs
• examples/3d/3d_shapes.rs
• examples/3d/meshlet.rs
• examples/gizmos/light_gizmos.rs
• examples/3d/render_to_texture.rs
• examples/3d/pbr.rs
• examples/3d/spotlight.rs
• examples/asset/asset_loading.rs
• examples/3d/auto_exposure.rs
• examples/ui/overflow.rs
• examples/ui/flex_layout.rs
• examples/ui/overflow_clip_margin.rs
• examples/animation/easing_functions.rs
• examples/stress_tests/bevymark.rs
• examples/shader/shader_prepass.rs
• examples/ui/display_and_visibility.rs
• examples/ui/tab_navigation.rs
• examples/games/breakout.rs
• examples/picking/mesh_picking.rs
• examples/3d/shadow_biases.rs
• examples/stress_tests/many_foxes.rs
• examples/3d/split_screen.rs
• examples/ui/z_index.rs
• examples/games/desk_toy.rs
• examples/2d/text2d.rs
• examples/math/sampling_primitives.rs
• examples/2d/texture_atlas.rs
• examples/3d/parallax_mapping.rs
• examples/ui/directional_navigation.rs
• examples/3d/deferred_rendering.rs
• examples/animation/custom_skinned_mesh.rs
• examples/3d/blend_modes.rs
• examples/stress_tests/many_cubes.rs
• examples/3d/lighting.rs
• examples/animation/animated_transform.rs
• examples/ui/box_shadow.rs
• examples/3d/camera_sub_view.rs
• examples/ui/text_debug.rs
• examples/ui/grid.rs
• examples/3d/transmission.rs
• examples/ui/borders.rs
• examples/ui/scroll.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 85)

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

examples/state/computed_states.rs (line 407)

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

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/games/loading_screen.rs
• examples/ecs/removal_detection.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/3d/reflection_probes.rs
• examples/window/screenshot.rs
• examples/3d/depth_of_field.rs
• examples/ui/tab_navigation.rs
• examples/ecs/observer_propagation.rs
• examples/shader/custom_shader_instancing.rs
• examples/app/log_layers_ecs.rs
• examples/3d/pbr.rs
• examples/asset/asset_decompression.rs
• examples/ecs/entity_disabling.rs
• examples/window/window_settings.rs
• examples/animation/morph_targets.rs
• examples/ecs/error_handling.rs
• examples/testbed/3d.rs
• examples/animation/animated_mesh_control.rs
• examples/games/game_menu.rs
• examples/3d/anisotropy.rs
• examples/3d/clearcoat.rs
• examples/3d/clustered_decals.rs
• examples/3d/tonemapping.rs
• examples/3d/order_independent_transparency.rs
• examples/3d/irradiance_volumes.rs
• examples/3d/shadow_caster_receiver.rs
• examples/ecs/fallible_params.rs
• examples/3d/pcss.rs
• examples/games/stepping.rs
• examples/3d/visibility_range.rs
• examples/window/custom_cursor_image.rs
• examples/3d/edit_material_on_gltf.rs
• examples/ecs/hierarchy.rs
• examples/audio/soundtrack.rs
• examples/3d/lightmaps.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/games/breakout.rs
• examples/3d/ssr.rs
• examples/animation/animated_mesh_events.rs
• examples/window/monitor_info.rs
• examples/animation/animation_graph.rs
• examples/async_tasks/async_compute.rs
• examples/math/random_sampling.rs
• examples/stress_tests/transform_hierarchy.rs
• examples/animation/animation_masks.rs
• examples/ui/text_wrap_debug.rs
• examples/3d/deferred_rendering.rs
• examples/testbed/ui.rs
• examples/math/sampling_primitives.rs
• examples/3d/anti_aliasing.rs
• examples/3d/mixed_lighting.rs
• examples/ecs/component_hooks.rs
• examples/3d/ssao.rs
• examples/stress_tests/many_foxes.rs
• examples/3d/bloom_3d.rs
• examples/2d/bloom_2d.rs
• examples/ui/directional_navigation.rs
• examples/animation/custom_skinned_mesh.rs
• examples/animation/animated_transform.rs
• examples/3d/transmission.rs
• examples/ui/text_debug.rs
• examples/ui/borders.rs
• examples/ui/scroll.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 147)

fn explode_mine(trigger: Trigger<Explode>, query: Query<&Mine>, mut commands: Commands) {
    // If a triggered event is targeting a specific entity you can access it with `.target()`
    let id = trigger.target();
    let Ok(mut entity) = commands.get_entity(id) else {
        return;
    };
    info!("Boom! {} exploded.", id.index());
    entity.despawn();
    let mine = query.get(id).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 103)

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

    let mut rng = rand::thread_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.r#gen::<f32>());
            let rotation = Quat::from_rotation_z(rng.r#gen::<f32>());
            let scale = Vec3::splat(rng.r#gen::<f32>() * 2.0);

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

examples/stress_tests/many_text2d.rs (line 150)

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.r#gen::<f32>());
            let rotation = Quat::from_rotation_z(rng.r#gen::<f32>());
            let scale = Vec3::splat(rng.r#gen::<f32>() * 2.0);
            let color = Hsla::hsl(rng.gen_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 {
                    JustifyText::Center
                } else {
                    JustifyText::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 74-89)

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 = thread_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.gen_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 57-71)

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.gen_range(-5.0..5.0);
            let y = rng.gen_range(0.0..3.0);
            let z = rng.gen_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),
                ))
                .with_children(|builder| {
                    builder.spawn((
                        Mesh3d(sphere_mesh.clone()),
                        MeshMaterial3d(red_emissive.clone()),
                    ));
                    builder.spawn((
                        Mesh3d(sphere_mesh_direction.clone()),
                        MeshMaterial3d(maroon_emissive.clone()),
                        Transform::from_translation(Vec3::Z * -0.1),
                        NotShadowCaster,
                    ));
                });
        }
    }

    // camera
    commands.spawn((
        Camera3d::default(),
        Camera {
            hdr: true,
            ..default()
        },
        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: Val::Px(12.0),
            left: Val::Px(12.0),
            ..default()
        },
    ));
}

examples/stress_tests/bevymark.rs (line 452)

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.r#gen::<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.r#gen(),
                            bird_resources.color_rng.r#gen(),
                            bird_resources.color_rng.r#gen(),
                        )
                    } 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.r#gen::<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.r#gen(),
        bird_resources.color_rng.r#gen(),
        bird_resources.color_rng.r#gen(),
    );
}

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 180-191)

fn failing_commands(mut commands: Commands) {
    commands
        // This entity doesn't exist!
        .entity(Entity::from_raw(12345678))
        // 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 insert_or_spawn_batch<I, B>(&mut self, bundles_iter: I)

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

👎Deprecated since 0.16.0: This can cause extreme performance problems when used with lots of arbitrary free entities. See #18054 on GitHub.

Pushes a Command to the queue for creating entities, if needed, and for adding a bundle to each entity.

bundles_iter is a type that can be converted into an (Entity, Bundle) iterator (it can also be a collection).

When the command is applied, for each (Entity, Bundle) pair in the given bundles_iter, the Entity is spawned, if it does not exist already. Then, the Bundle is added to the entity.

This method is equivalent to iterating bundles_iter, calling spawn for each bundle, and passing it to insert, but it is faster due to memory pre-allocation.

Note

Spawning a specific entity value is rarely the right choice. Most apps should use Commands::spawn_batch. This method should generally only be used for sharing entities across apps, and only when they have a scheme worked out to share an ID space (which doesn’t happen by default).

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

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/custom_phase_item.rs (line 217)

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

examples/camera/2d_screen_shake.rs (line 62)

fn setup_scene(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<ColorMaterial>>,
) {
    // World where we move the player
    commands.spawn((
        Mesh2d(meshes.add(Rectangle::new(1000., 700.))),
        MeshMaterial2d(materials.add(Color::srgb(0.2, 0.2, 0.3))),
    ));

    // Player
    commands.spawn((
        Player,
        Mesh2d(meshes.add(Rectangle::new(50.0, 100.0))), // Rectangle size (width, height)
        MeshMaterial2d(materials.add(Color::srgb(0.25, 0.94, 0.91))), // RGB values must be in range 0.0 to 1.0
        Transform::from_xyz(0., 0., 2.),
    ));

    commands.spawn((
        Mesh2d(meshes.add(Rectangle::new(50.0, 50.0))), // Rectangle size (width, height)
        MeshMaterial2d(materials.add(Color::srgb(0.85, 0.0, 0.2))), // RGB values must be in range 0.0 to 1.0
        Transform::from_xyz(-450.0, 200.0, 2.),
    ));

    commands.spawn((
        Mesh2d(meshes.add(Rectangle::new(70.0, 50.0))), // Rectangle size (width, height)
        MeshMaterial2d(materials.add(Color::srgb(0.5, 0.8, 0.2))), // RGB values must be in range 0.0 to 1.0
        Transform::from_xyz(450.0, -150.0, 2.),
    ));
    commands.init_resource::<ScreenShake>();
}

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 325-327)

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

examples/async_tasks/async_compute.rs (line 39)

fn add_assets(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    let box_mesh_handle = meshes.add(Cuboid::new(0.25, 0.25, 0.25));
    commands.insert_resource(BoxMeshHandle(box_mesh_handle));

    let box_material_handle = materials.add(Color::srgb(1.0, 0.2, 0.3));
    commands.insert_resource(BoxMaterialHandle(box_material_handle));
}

examples/asset/processing/asset_processing.rs (lines 240-246)

fn setup(mut commands: Commands, assets: Res<AssetServer>) {
    // This the final processed versions of `assets/a.cool.ron` and `assets/foo.c.cool.ron`
    // Check out their counterparts in `imported_assets` to see what the outputs look like.
    commands.insert_resource(TextAssets {
        a: assets.load("a.cool.ron"),
        b: assets.load("foo/b.cool.ron"),
        c: assets.load("foo/c.cool.ron"),
        d: assets.load("d.cool.ron"),
        e: assets.load("embedded://asset_processing/e.txt"),
    });
}

Additional examples can be found in:

• 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/animation/morph_targets.rs
• examples/games/game_menu.rs
• examples/shader/compute_shader_game_of_life.rs
• examples/remote/server.rs
• examples/ui/font_atlas_debug.rs
• examples/3d/skybox.rs
• examples/asset/multi_asset_sync.rs
• examples/testbed/3d.rs
• examples/state/custom_transitions.rs
• examples/state/states.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/animation_graph.rs
• examples/animation/animated_mesh_events.rs
• examples/math/cubic_splines.rs
• examples/2d/cpu_draw.rs
• examples/animation/animated_mesh_control.rs
• examples/transforms/align.rs
• examples/math/random_sampling.rs
• examples/shader/gpu_readback.rs
• examples/state/computed_states.rs
• examples/animation/animation_masks.rs
• examples/games/alien_cake_addict.rs
• examples/3d/auto_exposure.rs
• examples/stress_tests/bevymark.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 266)

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(&mut self, event: impl Event)

Sends a “global” Trigger without any targets.

This will run any Observer of the given Event that isn’t scoped to specific targets.

Examples found in repository

examples/ecs/observers.rs (lines 154-157)

fn explode_mine(trigger: Trigger<Explode>, query: Query<&Mine>, mut commands: Commands) {
    // If a triggered event is targeting a specific entity you can access it with `.target()`
    let id = trigger.target();
    let Ok(mut entity) = commands.get_entity(id) else {
        return;
    };
    info!("Boom! {} exploded.", id.index());
    entity.despawn();
    let mine = query.get(id).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())
    {
        if mouse_button_input.just_pressed(MouseButton::Left) {
            commands.trigger(ExplodeMines { pos, radius: 1.0 });
        }
    }
}

pub fn trigger_targets( &mut self, event: impl Event, targets: impl TriggerTargets + Send + Sync + 'static, )

Sends a Trigger for the given targets.

This will run any Observer of the given Event watching those targets.

Examples found in repository

examples/ecs/observer_propagation.rs (line 75)

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

examples/ecs/observers.rs (line 32)

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(
            |trigger: Trigger<ExplodeMines>,
             mines: Query<&Mine>,
             index: Res<SpatialIndex>,
             mut commands: Commands| {
                // You can access the trigger data via the `Observer`
                let event = trigger.event();
                // Access resources
                for e in index.get_nearby(event.pos) {
                    // Run queries
                    let mine = mines.get(e).unwrap();
                    if mine.pos.distance(event.pos) < mine.size + event.radius {
                        // And queue commands, including triggering additional events
                        // Here we trigger the `Explode` event for entity `e`
                        commands.trigger_targets(Explode, e);
                    }
                }
            },
        )
        // 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();
}

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

fn interact_with_focused_button(
    action_state: Res<ActionState>,
    input_focus: Res<InputFocus>,
    mut commands: Commands,
) {
    if action_state
        .pressed_actions
        .contains(&DirectionalNavigationAction::Select)
    {
        if let Some(focused_entity) = input_focus.0 {
            commands.trigger_targets(
                Pointer::<Click> {
                    target: 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::Image(
                            bevy_render::camera::ImageRenderTarget {
                                handle: Handle::default(),
                                scale_factor: FloatOrd(1.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),
                    },
                },
                focused_entity,
            );
        }
    }
}

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.

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

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

where E: Event,

Sends an arbitrary Event.

This is a convenience method for sending events without requiring an EventWriter.

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 EventWriter 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, system_meta: &mut SystemMeta, ) -> <Commands<'_, '_> as SystemParam>::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

unsafe fn new_archetype( state: &mut <Commands<'_, '_> as SystemParam>::State, archetype: &Archetype, system_meta: &mut SystemMeta, )

For the specified Archetype, registers the components accessed by this SystemParam (if applicable).a

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