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 fallback error handler panics. It can be configured via the FallbackErrorHandler resource.

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

The error module provides some simple error handlers for convenience.

Implementations

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

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

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

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

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

pub fn rebound_to<'q>(&self, queue: &'q mut CommandQueue) -> Commands<'w, 'q>

Returns a new Commands that writes commands to the provided CommandQueue instead of the one from self.

This is useful if you have a Commands that writes to one queue and you want one that writes to another.

Note that you’re responsible for ensuring the queue eventually writes its commands to the world. One way to do this is calling Commands::append on a Commands that writes to the world queue. Failure to write a queue may result in entities being allocated but never spawned, which means those entity IDs are never freed for reuse.

The original Commands isn’t mutated or borrowed after this returns, so you can keep using it.

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

fn handle_tasks(
    mut commands: Commands,
    mut transform_tasks: Query<(Entity, &mut ComputeTransform)>,
) {
    for (entity, mut task) in &mut transform_tasks {
        // Use `check_ready` to efficiently poll the task without blocking the main thread.
        if let Some(mut commands_queue) = check_ready(&mut task.0) {
            // Append the returned command queue to execute it later.
            commands.append(&mut commands_queue);
            // Task is complete, so remove the task component from the entity.
            commands.entity(entity).remove::<ComputeTransform>();
        }
    }
}

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

Spawns a new empty Entity and returns its corresponding EntityCommands.

Example

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

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

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

See also

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

Examples found in repository

examples/async_tasks/async_compute.rs (line 74)

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

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

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

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

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

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

                    command_queue
                });

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

examples/stress_tests/transform_hierarchy.rs (line 405)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

            cmd.id()
        };

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

        ents.push(child_entity);
    }

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

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

where T: Bundle,

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

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

Example

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

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

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

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

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

See also

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

Examples found in repository

examples/showcase/game_menu.rs (line 48)

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

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

    use super::GameState;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    // This system updates the settings when a new value for a setting is selected, and marks
    // the button as the one currently selected
    fn setting_button<T: Resource<Mutability = Mutable> + Component + PartialEq + Copy>(
        interaction_query: Query<
            (&Interaction, &Setting<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.0 {
                *previous_button_color = NORMAL_BUTTON.into();
                commands.entity(previous_button).remove::<SelectedOption>();
                commands.entity(entity).insert(SelectedOption);
                *setting = button_setting.0;
            }
        }
    }

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

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

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

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

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

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

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

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

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

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

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

examples/state/custom_transitions.rs (line 222)

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

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

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

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

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

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

examples/state/states.rs (line 54)

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

fn setup_menu(mut commands: Commands) {
    let button_entity = commands
        .spawn((
            Node {
                // center button
                width: percent(100),
                height: percent(100),
                justify_content: JustifyContent::Center,
                align_items: AlignItems::Center,
                ..default()
            },
            children![(
                Button,
                Node {
                    width: px(150),
                    height: px(65),
                    // horizontally center child text
                    justify_content: JustifyContent::Center,
                    // vertically center child text
                    align_items: AlignItems::Center,
                    ..default()
                },
                BackgroundColor(NORMAL_BUTTON),
                children![(
                    Text::new("Play"),
                    TextFont {
                        font_size: FontSize::Px(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/2d/sprite_scale.rs (line 14)

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

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

    let rects = [
        Rect {
            size: Vec2::new(100., 225.),
            text: "Stretched".to_string(),
            transform: Transform::from_translation(Vec3::new(-570., 230., 0.)),
            texture: square.clone(),
            image_mode: SpriteImageMode::Auto,
        },
        Rect {
            size: Vec2::new(100., 225.),
            text: "Fill Center".to_string(),
            transform: Transform::from_translation(Vec3::new(-450., 230., 0.)),
            texture: square.clone(),
            image_mode: SpriteImageMode::Scale(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::FitCenter),
        },
    ];

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

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

    let sprite_sheets = [
        SpriteSheet {
            size: Vec2::new(120., 50.),
            text: "Stretched".to_string(),
            transform: Transform::from_translation(Vec3::new(-570., -200., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Auto,
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
        SpriteSheet {
            size: Vec2::new(120., 50.),
            text: "Fill Center".to_string(),
            transform: Transform::from_translation(Vec3::new(-570., -300., 0.)),
            texture: gabe.clone(),
            image_mode: SpriteImageMode::Scale(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::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(SpriteScalingMode::FitEnd),
            atlas: gabe_atlas.clone(),
            indices: animation_indices_gabe.clone(),
            timer: AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
        },
    ];

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

examples/gizmos/anchored_text_gizmos.rs (line 18)

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

Additional examples can be found in:

• examples/gizmos/text_gizmos_font.rs
• 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/asset/asset_saving_with_subassets.rs
• examples/ui/widgets/button.rs
• examples/ui/widgets/standard_widgets.rs
• examples/ui/widgets/standard_widgets_observers.rs
• examples/ecs/one_shot_systems.rs
• examples/audio/audio.rs
• examples/asset/custom_asset_reader.rs
• examples/window/transparent_window.rs
• examples/ecs/extraction.rs
• tests/3d/test_skinned_mesh_bounds.rs
• examples/3d/mixed_lighting.rs
• examples/time/timers.rs
• examples/2d/sprite.rs
• examples/gizmos/2d_text_gizmos.rs
• examples/asset/asset_decompression.rs
• examples/ecs/removal_detection.rs
• examples/3d/reflection_probes.rs
• examples/2d/move_sprite.rs
• examples/2d/rotate_to_cursor.rs
• examples/3d/light_probe_blending.rs
• examples/app/logs.rs
• examples/audio/decodable.rs
• examples/app/log_layers_ecs.rs
• examples/ecs/change_detection.rs
• examples/usage/context_menu.rs
• examples/camera/pan_camera_controller.rs
• examples/3d/fog.rs
• examples/asset/multi_asset_sync.rs
• examples/gltf/gltf_extension_mesh_2d.rs
• examples/audio/play_sound_effect.rs
• examples/ecs/delayed_commands.rs
• examples/gizmos/3d_text_gizmos.rs
• examples/2d/mesh2d.rs
• examples/2d/dynamic_mip_generation.rs
• examples/asset/web_asset.rs
• examples/ecs/component_hooks.rs
• examples/2d/sprite_flipping.rs
• examples/window/persisting_window_settings.rs
• examples/window/screenshot.rs
• examples/movement/physics_in_fixed_timestep.rs
• examples/camera/2d_screen_shake.rs
• examples/async_tasks/async_channel_pattern.rs
• examples/math/render_primitives.rs
• examples/gltf/gltf_extension_animation_graph.rs
• examples/ecs/generic_system.rs
• examples/stress_tests/many_gizmos.rs
• examples/scene/world_serialization.rs
• examples/gltf/gltf_skinned_mesh.rs
• examples/showcase/alien_cake_addict.rs
• examples/3d/mirror.rs
• examples/3d/pccm.rs
• examples/shader/animate_shader.rs
• examples/async_tasks/async_compute.rs
• examples/ecs/state_scoped.rs
• examples/audio/pitch.rs
• examples/ecs/observer_propagation.rs
• examples/2d/sprite_tile.rs
• examples/gltf/query_gltf_primitives.rs
• examples/3d/lightmaps.rs
• examples/shader/shader_material_2d.rs
• examples/shader/shader_material_wesl.rs
• examples/shader_advanced/render_depth_to_texture.rs
• examples/ecs/fallible_params.rs
• examples/3d/ssr.rs
• examples/gltf/custom_gltf_vertex_attribute.rs
• examples/ecs/ecs_guide.rs
• examples/camera/2d_top_down_camera.rs
• examples/2d/pixel_grid_snap.rs
• examples/shader/fallback_image.rs
• examples/shader_advanced/custom_phase_item.rs
• examples/shader_advanced/fullscreen_material.rs
• examples/3d/motion_blur.rs
• examples/ecs/hotpatching_systems.rs
• examples/3d/3d_viewport_to_world.rs
• examples/camera/free_camera_controller.rs
• examples/dev_tools/fps_overlay.rs
• examples/3d/clustered_decals.rs
• examples/shader/shader_material.rs
• examples/shader/shader_material_glsl.rs
• examples/gizmos/2d_gizmos.rs
• examples/asset/extra_source.rs
• examples/shader_advanced/texture_binding_array.rs
• examples/ui/scroll_and_overflow/scrollbars.rs
• examples/ui/window_fallthrough.rs
• examples/app/externally_driven_headless_renderer.rs
• examples/asset/hot_asset_reloading.rs
• examples/ecs/parallel_query.rs
• examples/shader_advanced/manual_material.rs
• examples/3d/light_textures.rs
• examples/audio/audio_control.rs
• examples/async_tasks/external_source_external_thread.rs
• examples/2d/transparency_2d.rs
• examples/showcase/loading_screen.rs
• examples/transforms/3d_rotation.rs
• examples/transforms/scale.rs
• examples/ecs/entity_disabling.rs
• examples/shader_advanced/custom_vertex_attribute.rs
• examples/ui/text/font_atlas_debug.rs
• examples/animation/morph_targets.rs
• tests/window/minimizing.rs
• tests/window/resizing.rs
• examples/3d/atmospheric_fog.rs
• examples/transforms/translation.rs
• examples/shader/shader_defs.rs
• examples/gltf/load_gltf_extras.rs
• examples/shader/compute_shader_game_of_life.rs
• examples/asset/embedded_asset.rs
• examples/3d/color_grading.rs
• examples/window/scale_factor_override.rs
• examples/2d/sprite_sheet.rs
• examples/window/window_drag_move.rs
• examples/ecs/callbacks.rs
• examples/3d/tonemapping.rs
• examples/3d/parenting.rs
• examples/animation/animation_graph.rs
• examples/3d/post_processing.rs
• examples/3d/rotate_environment_map.rs
• examples/app/settings.rs
• examples/ui/text/editable_text_filter.rs
• examples/shader/shader_material_screenspace_texture.rs
• examples/3d/depth_of_field.rs
• examples/ui/images/image_node.rs
• examples/camera/camera_orbit.rs
• examples/shader/shader_material_bindless.rs
• examples/gltf/edit_material_on_gltf.rs
• examples/remote/server.rs
• examples/audio/soundtrack.rs
• examples/animation/animation_masks.rs
• examples/3d/anisotropy.rs
• examples/3d/animated_material.rs
• examples/3d/pcss.rs
• examples/shader_advanced/custom_post_processing.rs
• examples/3d/clearcoat.rs
• examples/camera/custom_projection.rs
• examples/animation/animated_mesh_events.rs
• examples/picking/custom_hit_data.rs
• examples/gltf/load_gltf.rs
• examples/3d/two_passes.rs
• examples/stress_tests/many_materials.rs
• examples/diagnostics/log_diagnostics.rs
• examples/animation/animated_mesh.rs
• examples/stress_tests/many_glyphs.rs
• examples/shader/extended_material_bindless.rs
• examples/3d/clustered_decal_maps.rs
• examples/shader_advanced/custom_render_phase.rs
• examples/dev_tools/infinite_grid.rs
• examples/gltf/update_gltf_scene.rs
• examples/stress_tests/text_pipeline.rs
• examples/3d/skybox.rs
• examples/3d/fog_volumes.rs
• examples/3d/lines.rs
• examples/shader/storage_buffer.rs
• examples/window/low_power.rs
• examples/2d/mesh2d_vertex_color_texture.rs
• examples/3d/order_independent_transparency.rs
• examples/shader/array_texture.rs
• examples/ecs/hierarchy.rs
• examples/3d/generate_custom_mesh.rs
• examples/2d/wireframe_2d.rs
• examples/3d/mesh_ray_cast.rs
• examples/stress_tests/many_sprites.rs
• examples/stress_tests/many_sprite_meshes.rs
• examples/animation/color_animation.rs
• examples/audio/spatial_audio_2d.rs
• examples/picking/simple_picking.rs
• examples/movement/smooth_follow.rs
• examples/2d/tilemap_chunk.rs
• examples/ui/relative_cursor_position.rs
• examples/shader/extended_material.rs
• examples/ui/ui_material.rs
• examples/3d/vertex_colors.rs
• examples/animation/animated_mesh_control.rs
• examples/animation/animation_events.rs
• examples/asset/generated_assets.rs
• examples/shader_advanced/custom_shader_instancing.rs
• tests/window/desktop_request_redraw.rs
• examples/ui/text/font_weights.rs
• examples/3d/orthographic.rs
• examples/showcase/contributors.rs
• examples/testbed/2d.rs
• examples/picking/debug_picking.rs
• examples/remote/app_under_test.rs
• examples/shader_advanced/specialized_mesh_pipeline.rs
• examples/window/multiple_windows.rs
• examples/ui/ui_scaling.rs
• examples/3d/spherical_area_lights.rs
• examples/math/bounding_2d.rs
• examples/2d/2d_viewport_to_world.rs
• examples/usage/cooldown.rs
• examples/stress_tests/many_morph_targets.rs
• examples/transforms/transform.rs
• examples/ui/images/ui_texture_atlas.rs
• examples/stress_tests/many_animated_sprites.rs
• examples/2d/bloom_2d.rs
• examples/stress_tests/many_animated_sprite_meshes.rs
• examples/stress_tests/many_text2d.rs
• examples/ui/text/font_variations.rs
• examples/camera/first_person_view_model.rs
• examples/ecs/observers.rs
• examples/gizmos/axes.rs
• examples/app/headless_renderer.rs
• examples/ecs/relationships.rs
• examples/3d/occlusion_culling.rs
• examples/3d/ssao.rs
• examples/animation/animated_ui.rs
• examples/ui/layout/ghost_nodes.rs
• examples/ui/scroll_and_overflow/overflow_debug.rs
• examples/3d/atmosphere.rs
• examples/app/render_recovery.rs
• examples/stress_tests/many_buttons.rs
• examples/animation/eased_motion.rs
• examples/stress_tests/many_gradients.rs
• examples/stress_tests/transform_hierarchy.rs
• examples/audio/spatial_audio_3d.rs
• examples/shader/automatic_instancing.rs
• examples/asset/alter_sprite.rs
• examples/ui/text/text_input.rs
• examples/ecs/error_handling.rs
• examples/camera/projection_zoom.rs
• examples/2d/rotation.rs
• examples/3d/rect_light.rs
• examples/ui/images/ui_texture_slice.rs
• examples/3d/specular_tint.rs
• examples/ui/widgets/viewport_node.rs
• examples/camera/2d_on_ui.rs
• examples/3d/visibility_range.rs
• examples/2d/sprite_animation.rs
• examples/math/cubic_splines.rs
• examples/ui/text/ime_support.rs
• examples/window/monitor_info.rs
• examples/3d/volumetric_fog.rs
• examples/2d/tilemap_chunk_orientation.rs
• examples/2d/cpu_draw.rs
• tests/3d/test_invalid_skinned_mesh.rs
• examples/stress_tests/many_cameras_lights.rs
• examples/3d/texture.rs
• examples/time/virtual_time.rs
• examples/ui/images/ui_texture_slice_flip_and_tile.rs
• examples/3d/shadow_caster_receiver.rs
• examples/3d/wireframe.rs
• examples/3d/bloom_3d.rs
• examples/stress_tests/many_lights.rs
• examples/ui/layout/size_constraints.rs
• examples/3d/anti_aliasing.rs
• examples/ui/text/text_background_colors.rs
• examples/testbed/ui.rs
• examples/ui/text/generic_font_families.rs
• examples/gizmos/3d_gizmos.rs
• examples/picking/dragdrop_picking.rs
• examples/transforms/align.rs
• examples/ui/styling/transparency_ui.rs
• examples/ui/layout/anchor_layout.rs
• examples/3d/decal.rs
• examples/math/random_sampling.rs
• examples/testbed/3d.rs
• examples/ui/images/ui_texture_atlas_slice.rs
• examples/picking/sprite_picking.rs
• examples/showcase/stepping.rs
• examples/2d/mesh2d_alpha_mode.rs
• examples/2d/mesh2d_arcs.rs
• examples/3d/scrolling_fog.rs
• examples/ecs/iter_combinations.rs
• examples/shader_advanced/compute_mesh.rs
• examples/ui/text/text_wrap_debug.rs
• examples/3d/render_to_texture.rs
• examples/2d/mesh2d_manual.rs
• examples/2d/sprite_slice.rs
• examples/ui/styling/stacked_gradients.rs
• examples/gizmos/transform_gizmo.rs
• examples/3d/transparency_3d.rs
• examples/asset/repeated_texture.rs
• examples/asset/asset_saving.rs
• examples/asset/asset_settings.rs
• examples/shader/gpu_readback.rs
• examples/2d/mesh2d_repeated_texture.rs
• examples/3d/spotlight.rs
• examples/asset/alter_mesh.rs
• examples/3d/meshlet.rs
• examples/ui/text/system_fonts.rs
• examples/3d/pbr.rs
• examples/ui/ui_target_camera.rs
• examples/math/custom_primitives.rs
• examples/3d/auto_exposure.rs
• examples/animation/easing_functions.rs
• examples/asset/asset_loading.rs
• examples/window/multi_window_text.rs
• examples/ui/scroll_and_overflow/overflow.rs
• examples/ui/scroll_and_overflow/overflow_clip_margin.rs
• examples/gizmos/light_gizmos.rs
• examples/ui/layout/flex_layout.rs
• examples/stress_tests/bevymark_3d.rs
• examples/shader/shader_prepass.rs
• examples/ui/widgets/vertical_slider.rs
• examples/stress_tests/bevymark.rs
• examples/ui/layout/display_and_visibility.rs
• examples/3d/shadow_biases.rs
• examples/ui/widgets/tab_navigation.rs
• examples/ui/scroll_and_overflow/drag_to_scroll.rs
• examples/3d/split_screen.rs
• examples/2d/2d_shapes.rs
• examples/showcase/breakout.rs
• examples/ui/scroll_and_overflow/scroll.rs
• examples/picking/mesh_picking.rs
• examples/3d/solari.rs
• examples/ui/layout/z_index.rs
• examples/ui/render_ui_to_texture.rs
• examples/ui/images/image_node_resizing.rs
• examples/ui/text/strikethrough_and_underline.rs
• examples/showcase/desk_toy.rs
• examples/3d/parallax_mapping.rs
• examples/ui/navigation/directional_navigation.rs
• examples/2d/texture_atlas.rs
• examples/stress_tests/many_foxes.rs
• examples/ui/text/multiple_text_inputs.rs
• examples/ui/ui_drag_and_drop.rs
• examples/3d/deferred_rendering.rs
• examples/ui/styling/box_shadow.rs
• examples/3d/contact_shadows.rs
• examples/ui/text/text.rs
• examples/2d/text2d.rs
• examples/3d/3d_shapes.rs
• examples/animation/custom_skinned_mesh.rs
• examples/usage/debug_frustum_culling.rs
• examples/3d/blend_modes.rs
• examples/animation/animated_transform.rs
• examples/3d/lighting.rs
• examples/ui/styling/borders.rs
• examples/ui/text/letter_spacing.rs
• examples/3d/camera_sub_view.rs
• examples/ui/navigation/directional_navigation_overrides.rs
• examples/ui/text/text_debug.rs
• examples/ui/layout/grid.rs
• examples/3d/transmission.rs
• examples/ui/ui_transform.rs
• examples/stress_tests/many_cubes.rs
• examples/ui/text/font_query.rs
• examples/ui/text/multiline_text_input.rs
• examples/ui/styling/gradients.rs
• examples/testbed/full_ui.rs

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

Returns the EntityCommands for the given Entity.

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

Example

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

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

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

See also

• get_entity for the fallible version.

Examples found in repository

examples/state/custom_transitions.rs (line 166)

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

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

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

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

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

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

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

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

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

examples/state/states.rs (line 118)

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

examples/state/sub_states.rs (line 87)

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

examples/remote/server.rs (line 86)

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

examples/state/computed_states.rs (line 406)

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

examples/stress_tests/many_buttons.rs (line 322)

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

Additional examples can be found in:

• examples/ecs/generic_system.rs
• examples/usage/context_menu.rs
• examples/3d/light_textures.rs
• examples/showcase/loading_screen.rs
• examples/ecs/contiguous_query.rs
• examples/ecs/removal_detection.rs
• examples/ui/widgets/standard_widgets_observers.rs
• examples/async_tasks/external_source_external_thread.rs
• examples/3d/volumetric_fog.rs
• examples/asset/multi_asset_sync.rs
• examples/ecs/one_shot_systems.rs
• examples/gizmos/transform_gizmo.rs
• examples/ecs/extraction.rs
• examples/window/screenshot.rs
• examples/3d/reflection_probes.rs
• examples/3d/depth_of_field.rs
• examples/ui/widgets/tab_navigation.rs
• examples/ecs/observer_propagation.rs
• examples/ecs/entity_disabling.rs
• examples/shader_advanced/custom_shader_instancing.rs
• examples/3d/pbr.rs
• examples/asset/asset_decompression.rs
• examples/asset/asset_saving.rs
• examples/animation/morph_targets.rs
• examples/app/log_layers_ecs.rs
• examples/picking/dragdrop_picking.rs
• examples/animation/animated_mesh_control.rs
• examples/ecs/error_handling.rs
• examples/window/window_settings.rs
• examples/testbed/3d.rs
• tests/3d/test_skinned_mesh_bounds.rs
• examples/ui/widgets/standard_widgets.rs
• examples/3d/anisotropy.rs
• examples/3d/clearcoat.rs
• examples/3d/clustered_decals.rs
• examples/showcase/game_menu.rs
• examples/gltf/gltf_extension_animation_graph.rs
• examples/usage/cooldown.rs
• examples/asset/asset_saving_with_subassets.rs
• examples/3d/order_independent_transparency.rs
• examples/3d/tonemapping.rs
• examples/3d/ssr.rs
• examples/ecs/delayed_commands.rs
• examples/3d/pccm.rs
• examples/3d/irradiance_volumes.rs
• examples/3d/shadow_caster_receiver.rs
• examples/3d/mirror.rs
• examples/audio/soundtrack.rs
• examples/ecs/fallible_params.rs
• examples/showcase/stepping.rs
• examples/3d/pcss.rs
• examples/window/custom_cursor_image.rs
• examples/ecs/hierarchy.rs
• examples/2d/dynamic_mip_generation.rs
• examples/3d/lightmaps.rs
• tests/window/desktop_request_redraw.rs
• examples/animation/animated_mesh.rs
• examples/3d/visibility_range.rs
• examples/math/bounding_2d.rs
• examples/ecs/relationships.rs
• examples/3d/occlusion_culling.rs
• examples/animation/eased_motion.rs
• examples/3d/clustered_decal_maps.rs
• examples/showcase/alien_cake_addict.rs
• examples/ui/text/text_input.rs
• examples/showcase/breakout.rs
• examples/gltf/edit_material_on_gltf.rs
• examples/window/monitor_info.rs
• examples/animation/animated_mesh_events.rs
• examples/async_tasks/async_compute.rs
• examples/animation/animation_graph.rs
• examples/3d/blend_modes.rs
• examples/3d/light_probe_blending.rs
• examples/stress_tests/many_morph_targets.rs
• examples/math/random_sampling.rs
• examples/stress_tests/transform_hierarchy.rs
• examples/ui/text/text_wrap_debug.rs
• examples/animation/animation_masks.rs
• examples/3d/deferred_rendering.rs
• examples/3d/solari.rs
• examples/testbed/ui.rs
• examples/3d/mixed_lighting.rs
• examples/diagnostics/log_diagnostics.rs
• examples/ecs/component_hooks.rs
• examples/3d/ssao.rs
• examples/ui/scroll_and_overflow/scroll.rs
• tests/3d/test_invalid_skinned_mesh.rs
• examples/3d/bloom_3d.rs
• examples/ui/navigation/directional_navigation.rs
• examples/2d/bloom_2d.rs
• examples/stress_tests/many_foxes.rs
• examples/3d/contact_shadows.rs
• examples/3d/anti_aliasing.rs
• examples/animation/custom_skinned_mesh.rs
• examples/animation/animated_transform.rs
• examples/3d/transmission.rs
• examples/ui/navigation/directional_navigation_overrides.rs
• examples/ui/text/text_debug.rs
• examples/ui/widgets/feathers_gallery.rs

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

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

Errors

Returns InvalidEntityError if the requested entity does not exist.

Example

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

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

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

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

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

See also

• entity for the infallible version.

Examples found in repository

examples/ecs/observers.rs (line 165)

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

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

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

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

Errors

Returns EntityNotSpawnedError if the requested entity does not exist.

Example

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

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

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

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

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

See also

• entity for the infallible version.

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

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

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

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

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

Example

use bevy_ecs::prelude::*;

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

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

See also

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

Examples found in repository

examples/ecs/contiguous_query.rs (lines 59-66)

fn setup(mut commands: Commands) {
    let mut i = 0;
    commands.spawn_batch(std::iter::from_fn(move || {
        i += 1;
        if i == 10_000 {
            None
        } else {
            Some((Health(i as f32 * 5.0), HealthDecay(0.9)))
        }
    }));
}

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/3d/order_independent_transparency.rs (line 345)

fn spawn_auto_instancing_test(
    commands: &mut Commands,
    meshes: &mut Assets<Mesh>,
    materials: &mut Assets<StandardMaterial>,
    asset_server: Res<AssetServer>,
) {
    let render_layers = RenderLayers::layer(1);

    let cube = meshes.add(Cuboid::new(1.0, 1.0, 1.0));
    let material_handle = materials.add(StandardMaterial {
        alpha_mode: AlphaMode::Blend,
        base_color_texture: Some(asset_server.load("textures/slice_square.png")),
        ..Default::default()
    });
    let mut bundles = Vec::with_capacity(3 * 3 * 3);

    for z in -1..=1 {
        for y in -1..=1 {
            for x in -1..=1 {
                bundles.push((
                    Mesh3d(cube.clone()),
                    MeshMaterial3d(material_handle.clone()),
                    Transform::from_xyz(x as f32 * 2.0, y as f32 * 2.0, z as f32 * 2.0),
                    render_layers.clone(),
                ));
            }
        }
    }
    commands.spawn_batch(bundles);
}

examples/stress_tests/many_sprites.rs (line 99)

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

    let mut rng = rand::rng();

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

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

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

    // Spawns the camera

    commands.spawn(Camera2d);

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

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

examples/stress_tests/many_sprite_meshes.rs (line 101)

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

    let mut rng = rand::rng();

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

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

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

    // Spawns the camera

    commands.spawn(Camera2d);

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

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

examples/stress_tests/bevymark_3d.rs (line 397)

fn spawn_cubes(
    commands: &mut Commands,
    args: &Args,
    counter: &mut BevyCounter,
    spawn_count: usize,
    cube_resources: &mut CubeResources,
    waves_to_simulate: Option<usize>,
    wave: usize,
) {
    let batch_material = cube_resources.materials[wave % cube_resources.materials.len()].clone();

    let spawn_y = VOLUME_SIZE.y / 2.0 - HALF_CUBE_SIZE;
    let spawn_z = -VOLUME_SIZE.z / 2.0 + HALF_CUBE_SIZE;

    let batch = (0..spawn_count)
        .map(|_| {
            let spawn_pos = Vec3::new(
                (cube_resources.transform_rng.random::<f32>() - 0.5) * VOLUME_SIZE.x,
                spawn_y,
                spawn_z,
            );

            let (transform, velocity) = cube_velocity_transform(
                spawn_pos,
                &mut cube_resources.velocity_rng,
                waves_to_simulate,
                FIXED_DELTA_TIME,
            );

            let material = if args.vary_per_instance {
                cube_resources
                    .materials
                    .choose(&mut cube_resources.material_rng)
                    .unwrap()
                    .clone()
            } else {
                batch_material.clone()
            };

            (
                Mesh3d(cube_resources.cube_mesh.clone()),
                MeshMaterial3d(material),
                transform,
                Cube { velocity },
            )
        })
        .collect::<Vec<_>>();
    commands.spawn_batch(batch);

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

Additional examples can be found in:

• examples/stress_tests/many_text2d.rs
• examples/stress_tests/many_lights.rs
• examples/3d/spotlight.rs
• examples/stress_tests/bevymark.rs

pub fn queue(&mut self, command: impl Command)

Pushes a generic Command to the command queue.

If the Command returns a Result, it will be handled using the fallback 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 for AddToCounter {
    type Out = Result;

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

Examples found in repository

examples/app/settings.rs (line 127)

fn change_count(
    mut counter: ResMut<Counter>,
    keyboard: Res<ButtonInput<KeyCode>>,
    mut commands: Commands,
) {
    let mut changed = false;
    if keyboard.just_pressed(KeyCode::Space) {
        counter.count += 1;
        changed = true;
    }
    if keyboard.just_pressed(KeyCode::Backspace) || keyboard.just_pressed(KeyCode::Delete) {
        counter.count -= 1;
        changed = true;
    }

    if changed {
        commands.queue(SaveSettingsDeferred(Duration::from_secs_f32(0.1)));
    }
}

fn on_window_close(mut close: MessageReader<WindowCloseRequested>, mut commands: Commands) {
    // Save settings immediately, then quit.
    if let Some(_close_event) = close.read().next() {
        commands.queue(SaveSettingsSync::IfChanged);
        commands.write_message(AppExit::Success);
    }
}

examples/window/persisting_window_settings.rs (line 111)

fn update_window_settings(
    mut move_events: MessageReader<WindowMoved>,
    mut resize_events: MessageReader<WindowResized>,
    windows: Query<&mut Window>,
    window_settings: ResMut<WindowSettings>,
    mut commands: Commands,
) {
    let Ok(window) = windows.single() else {
        return;
    };

    let mut window_changed = false;
    for _ in move_events.read() {
        window_changed = true;
    }

    for _ in resize_events.read() {
        window_changed = true;
    }

    if window_changed && store_window_settings(window_settings, window) {
        commands.queue(SaveSettingsDeferred(Duration::from_secs_f32(0.5)));
    }
}

fn store_window_settings(mut window_settings: ResMut<WindowSettings>, window: &Window) -> bool {
    window_settings.set_if_neq(WindowSettings {
        position: match window.position {
            WindowPosition::At(pos) => Some(pos),
            _ => None,
        },
        size: Some(UVec2::new(
            window.resolution.width() as u32,
            window.resolution.height() as u32,
        )),
        fullscreen: window.mode != WindowMode::Windowed,
    })
}

fn on_window_close(mut close: MessageReader<WindowCloseRequested>, mut commands: Commands) {
    // Save settings immediately, then quit.
    if let Some(_close_event) = close.read().next() {
        commands.queue(SaveSettingsSync::IfChanged);
        commands.write_message(AppExit::Success);
    }
}

pub fn queue_handled( &mut self, command: impl Command, error_handler: fn(BevyError, ErrorContext), )

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 fallback 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 for AddToCounter {
    type Out = Result;

    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 186-197)

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

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

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

pub fn queue_silenced(&mut self, command: impl Command)

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

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

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

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

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

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

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

Fallible

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

It will internally return a TryInsertBatchError, which will be handled by the fallback 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 fallback 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 375)

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

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

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

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

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

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

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

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

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

Fallible

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

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

pub fn init_resource<R>(&mut self)

where R: Resource + FromWorld,

Inserts a Resource into the World with an inferred value.

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

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

Example

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

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

Examples found in repository

examples/shader_advanced/custom_phase_item.rs (line 211)

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

examples/diagnostics/log_diagnostics.rs (line 89)

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    // circular base
    commands.spawn((
        Mesh3d(meshes.add(Circle::new(4.0))),
        MeshMaterial3d(materials.add(Color::WHITE)),
        Transform::from_rotation(Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2)),
    ));
    // cube
    commands.spawn((
        Mesh3d(meshes.add(Cuboid::new(1.0, 1.0, 1.0))),
        MeshMaterial3d(materials.add(Color::srgb_u8(124, 144, 255))),
        Transform::from_xyz(0.0, 0.5, 0.0),
    ));
    // light
    commands.spawn((
        PointLight {
            shadow_maps_enabled: true,
            ..default()
        },
        Transform::from_xyz(4.0, 8.0, 4.0),
    ));
    // camera
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(-2.5, 4.5, 9.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));

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

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

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

where R: Resource,

Inserts a Resource into the World with a specific value.

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

Example

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

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

Examples found in repository

examples/audio/pitch.rs (line 22)

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

examples/async_tasks/async_channel_pattern.rs (line 91)

fn setup_channel(mut commands: Commands) {
    let (sender, receiver) = crossbeam_channel::unbounded();
    commands.insert_resource(CubeChannel { sender, receiver });
}

/// A channel for communicating between async tasks and the main thread.
#[derive(Resource)]
struct CubeChannel {
    sender: Sender<CubeFinished>,
    receiver: Receiver<CubeFinished>,
}

/// Represents the completion of a cube task, containing the cube's transform
#[derive(Debug)]
struct CubeFinished {
    transform: Transform,
}

/// Resource holding the mesh handle for the box (used for spawning cubes)
#[derive(Resource, Deref)]
struct BoxMeshHandle(Handle<Mesh>);

/// Resource holding the material handle for the box (used for spawning cubes)
#[derive(Resource, Deref)]
struct BoxMaterialHandle(Handle<StandardMaterial>);

/// Sets up the shared mesh and material for the cubes.
fn setup_assets(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    // Create and store a cube mesh
    let box_mesh_handle = meshes.add(Cuboid::new(0.4, 0.4, 0.4));
    commands.insert_resource(BoxMeshHandle(box_mesh_handle));

    // Create and store a red material
    let box_material_handle = materials.add(Color::srgb(1.0, 0.2, 0.3));
    commands.insert_resource(BoxMaterialHandle(box_material_handle));
}

examples/app/headless_renderer.rs (lines 314-316)

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

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

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

examples/shader_advanced/custom_shader_instancing.rs (lines 243-246)

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

examples/shader_advanced/custom_render_phase.rs (lines 174-177)

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

Additional examples can be found in:

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

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

where R: Resource + PartialEq,

Inserts a Resource into the World with a specific value if the resource is different or missing.

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/showcase/desk_toy.rs (line 267)

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

examples/asset/multi_asset_sync.rs (line 278)

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: impl Into<SystemId> + Send)

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/callbacks.rs (line 51)

fn run_callbacks(mut commands: Commands, query: Query<&Callback>) {
    for callback in query.iter() {
        commands.run_system(callback.system_id);
    }
}

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/showcase/loading_screen.rs (line 107)

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: impl Into<SystemId<I>> + Send, 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/showcase/loading_screen.rs (line 74)

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

examples/ecs/callbacks.rs (lines 23-25)

fn setup_callbacks(mut commands: Commands) {
    let trivial_callback = Callback {
        system_id: commands.register_system(|| {
            println!("This is the trivial callback system");
        }),
    };

    let ordinary_system_callback = Callback {
        system_id: commands.register_system(|query: Query<&Callback>| {
            let n_callbacks = query.iter().len();
            println!("This is the ordinary callback system. There are currently {n_callbacks} callbacks in the world.");
        }),
    };

    let exclusive_callback = Callback {
        system_id: commands.register_system(|world: &mut World| {
            let n_entities = world.entities().len();
            println!("This is the exclusive callback system. There are currently {n_entities} entities in the world.");
        }),
    };

    commands.spawn(trivial_callback);
    commands.spawn(ordinary_system_callback);
    commands.spawn(exclusive_callback);
}

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.

To use the supplied input, the system should have a SystemInput as the first parameter.

The first time this method is called for a particular system, it will register the system and store its SystemId in a CachedSystemId resource for later.

If you would rather manage the SystemId yourself, or register multiple copies of the same system, use Commands::register_system instead.

Limitations

This method only accepts ZST (zero-sized) systems to guarantee that any two systems of the same type must be equal. This means that closures that capture the environment, and function pointers, are not accepted.

If you want to access values from the environment within a system, consider passing them in as inputs.

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

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

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

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

Examples found in repository

examples/asset/asset_saving.rs (lines 195-198)

fn on_drag_start(event: On<Pointer<DragStart>>, mut commands: Commands) {
    commands.trigger(TryPlot {
        entity: event.entity,
        location: event.pointer_location.clone(),
    });
}

fn on_drag(event: On<Pointer<Drag>>, mut commands: Commands) {
    commands.trigger(TryPlot {
        entity: event.entity,
        location: event.pointer_location.clone(),
    });
}

examples/usage/context_menu.rs (line 66)

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

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

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

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

    let pos = event.pos;

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

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

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

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

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

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

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

examples/ecs/observer_propagation.rs (line 74)

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

examples/ui/scroll_and_overflow/scroll.rs (line 46)

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

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

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

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

examples/ui/navigation/directional_navigation.rs (lines 449-471)

fn interact_with_focused_button(
    action_state: Res<ActionState>,
    input_focus: Res<InputFocus>,
    mut commands: Commands,
) {
    if action_state
        .pressed_actions
        .contains(&DirectionalNavigationAction::Select)
        && let Some(focused_entity) = input_focus.get()
    {
        commands.trigger(Pointer::new(
            PointerId::Mouse,
            Location {
                target: NormalizedRenderTarget::None {
                    width: 0,
                    height: 0,
                },
                position: Vec2::ZERO,
            },
            Click {
                button: PointerButton::Primary,
                hit: HitData {
                    camera: Entity::PLACEHOLDER,
                    depth: 0.0,
                    position: None,
                    normal: None,
                    extra: None,
                },
                count: 1,
                duration: Duration::from_secs_f32(0.1),
            },
            focused_entity,
        ));
    }
}

examples/ui/navigation/directional_navigation_overrides.rs (lines 842-864)

fn interact_with_focused_button(
    action_state: Res<ActionState>,
    input_focus: Res<InputFocus>,
    mut commands: Commands,
) {
    if action_state
        .pressed_actions
        .contains(&DirectionalNavigationAction::Select)
        && let Some(focused_entity) = input_focus.get()
    {
        commands.trigger(Pointer::new(
            PointerId::Mouse,
            Location {
                target: NormalizedRenderTarget::None {
                    width: 0,
                    height: 0,
                },
                position: Vec2::ZERO,
            },
            Click {
                button: PointerButton::Primary,
                hit: HitData {
                    camera: Entity::PLACEHOLDER,
                    depth: 0.0,
                    position: None,
                    normal: None,
                    extra: None,
                },
                count: 1,
                duration: Duration::from_secs_f32(0.1),
            },
            focused_entity,
        ));
    }
}

Additional examples can be found in:

• examples/ui/images/image_node_resizing.rs
• examples/ecs/observers.rs
• examples/showcase/breakout.rs
• examples/ui/widgets/feathers_gallery.rs

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

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

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

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

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

observer can be any system whose first parameter is On.

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

Panics

Panics if the given system is an exclusive system.

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

where M: Message,

Writes an arbitrary Message.

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

Performance

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

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

Examples found in repository

tests/window/desktop_request_redraw.rs (line 105)

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

examples/app/settings.rs (line 135)

fn on_window_close(mut close: MessageReader<WindowCloseRequested>, mut commands: Commands) {
    // Save settings immediately, then quit.
    if let Some(_close_event) = close.read().next() {
        commands.queue(SaveSettingsSync::IfChanged);
        commands.write_message(AppExit::Success);
    }
}

examples/window/persisting_window_settings.rs (line 133)

fn on_window_close(mut close: MessageReader<WindowCloseRequested>, mut commands: Commands) {
    // Save settings immediately, then quit.
    if let Some(_close_event) = close.read().next() {
        commands.queue(SaveSettingsSync::IfChanged);
        commands.write_message(AppExit::Success);
    }
}

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

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

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

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

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

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

pub fn 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<'w, 's> CommandsSceneExt for Commands<'w, 's>

fn spawn_scene<S>(&mut self, scene: S) -> EntityCommands<'_>

where S: Scene,

Spawns the given Scene as soon as Commands are applied. This will resolve the Scene (using Scene::resolve). If that fails (for example, if there are dependencies that have not been loaded yet), it will log a SpawnSceneError as an error. If resolving the Scene is successful, the scene will be spawned.

fn queue_spawn_scene<S>(&mut self, scene: S) -> EntityCommands<'_>

where S: Scene,

Queues the scene to be spawned. This will evaluate the scene’s dependencies (via Scene::register_dependencies) and queue it to be resolved and spawned after all of the dependencies have been loaded. If a SpawnSceneError occurs, it will be logged as an error.

fn spawn_scene_list<L>(&mut self, scenes: L)

where L: SceneList,

Spawns the given SceneList as soon as Commands are applied. This will resolve the scene list (using SceneList::resolve_list). If that fails (for example, if there are dependencies that have not been loaded yet), it will log a SpawnSceneError as an error. If resolving the Scene is successful, the scene list will be spawned.

fn queue_spawn_scene_list<L>(&mut self, scenes: L)

where L: SceneList,

Queues the scene_list to be spawned. This will evaluate the scene_list’s dependencies (via Scene::register_dependencies) and queue it to be resolved and spawned after all of the dependencies have been loaded. If a SpawnSceneError occurs, it will be logged as an error.

impl CommandsStatesExt for Commands<'_, '_>

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

where S: FreelyMutableState,

Sets the next state the app should move to.

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

where S: FreelyMutableState,

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

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

fn delayed(&mut self) -> DelayedCommands<'w, '_>

Returns a DelayedCommands instance that can be used to queue commands to be submitted at a later point in time.

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

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

impl Send for Commands<'_, '_>

impl Sync for Commands<'_, '_>

impl SystemParam for Commands<'_, '_>

type State = FetchState

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

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

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state(world: &mut World) -> <Commands<'_, '_> as SystemParam>::State

Creates a new instance of this param’s State.

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

Registers any World access used by this SystemParam.

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

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during ApplyDeferred.

fn queue( state: &mut <Commands<'_, '_> as SystemParam>::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

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

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

Creates a parameter to be passed into a SystemParamFunction.