Struct de_gui::commands::GuiCommands

pub struct GuiCommands<'w, 's> {
    commands: Commands<'w, 's>,
    text_props: Res<'w, TextProps>,
}

Fields

commands: Commands<'w, 's>

text_props: Res<'w, TextProps>

Implementations

impl<'w, 's> GuiCommands<'w, 's>

pub(crate) fn text_props(&self) -> &TextProps

Methods from Deref<Target = Commands<'w, 's>>

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.

Examples

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

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

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

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

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

Pushes a [Command] to the queue for creating a new empty [Entity], and returns its corresponding [EntityCommands].

See [World::spawn_empty] for more details.

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 and retrieve its id.
    let empty_entity = commands.spawn_empty().id();

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

See also

• spawn to spawn an entity with a bundle.
• spawn_batch to spawn entities with a bundle each.

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

Pushes a [Command] to the queue for creating a new [Entity] if the given one does not exists, and returns its corresponding [EntityCommands].

This method silently fails by returning [EntityCommands] even if the given Entity cannot be spawned.

See [World::get_or_spawn] for more details.

Note

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

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

where T: Bundle,

Pushes a [Command] to the queue for creating a new entity with the given [Bundle]’s components, and returns its corresponding [EntityCommands].

Example

use bevy_ecs::prelude::*;

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

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

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

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

    commands
        // Create a new entity with two components using a "tuple bundle".
        .spawn((Component1, Component2))
        // `spawn returns a builder, so you can insert more bundles like this:
        .insert((Strength(1), Agility(2)))
        // or insert single components like this:
        .insert(Label("hello world"));
}

See also

• spawn_empty to spawn an entity without any components.
• spawn_batch to spawn entities with a bundle each.

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

Returns the [EntityCommands] for the requested [Entity].

Panics

This method panics if the requested entity does not exist.

Example

use bevy_ecs::prelude::*;

#[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
    let entity = commands.spawn_empty().id();

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

See also

• get_entity for the fallible version.

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

Returns the [EntityCommands] for the requested [Entity], if it exists.

Returns None if the entity does not exist.

This method does not guarantee that EntityCommands will be successfully applied, since another command in the queue may delete the entity before them.

Example

use bevy_ecs::prelude::*;

#[derive(Component)]
struct Label(&'static str);
fn example_system(mut commands: Commands) {
    // Create a new, empty entity
    let entity = commands.spawn_empty().id();

    // Get the entity if it still exists, which it will in this case
    if let Some(mut entity_commands) = commands.get_entity(entity) {
        // adds a single component to the entity
        entity_commands.insert(Label("hello world"));
    }
}

See also

• entity for the panicking version.

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

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

Pushes a [Command] to the queue for creating entities with a particular [Bundle] type.

bundles_iter is a type that can be converted into a [Bundle] iterator (it can also be a collection).

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

Example

commands.spawn_batch(vec![
    (
        Name("Alice".to_string()),
        Score(0),
    ),
    (
        Name("Bob".to_string()),
        Score(0),
    ),
]);

See also

• spawn to spawn an entity with a bundle.
• spawn_empty to spawn an entity without any components.

pub fn insert_or_spawn_batch<I, B>(&mut self, bundles: I)

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

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

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

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

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

Note

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

pub fn init_resource<R>(&mut self)

where R: Resource + FromWorld,

Pushes a [Command] to the queue for inserting a [Resource] in the [World] with an inferred value.

The inferred value is determined by the [FromWorld] trait of the resource. When the command is applied, if the resource already exists, nothing happens.

See [World::init_resource] for more details.

Example

commands.init_resource::<Scoreboard>();

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

where R: Resource,

Pushes a [Command] to the queue for inserting a [Resource] in the [World] with a specific value.

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

See [World::insert_resource] for more details.

Example

commands.insert_resource(Scoreboard {
    current_score: 0,
    high_score: 0,
});

pub fn remove_resource<R>(&mut self)

where R: Resource,

Pushes a [Command] to the queue for removing a [Resource] from the [World].

See [World::remove_resource] for more details.

Example

commands.remove_resource::<Scoreboard>();

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

Runs the system corresponding to the given [SystemId]. Systems are ran in an exclusive and single threaded way. Running slow systems can become a bottleneck.

Calls World::run_system.

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_input] instead of running the system as a command.

pub fn run_system_with_input<I>(&mut self, id: SystemId<I>, input: I)

where I: 'static + Send,

Runs the system corresponding to the given [SystemId]. Systems are ran in an exclusive and single threaded way. Running slow systems can become a bottleneck.

Calls World::run_system_with_input.

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_input] instead of running the system as a command.

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

where C: Command,

Pushes a generic [Command] to the command queue.

command can be a built-in command, custom struct that implements [Command] or a closure that takes &mut World as an argument.

Example

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

struct AddToCounter(u64);

impl Command for AddToCounter {
    fn apply(self, world: &mut World) {
        let mut counter = world.get_resource_or_insert_with(Counter::default);
        counter.0 += self.0;
    }
}

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

Trait Implementations

impl<'w, 's> BodyTextCommands<'w, 's> for GuiCommands<'w, 's>

fn spawn_body_text( &mut self, style: OuterStyle, caption: impl Into<String> ) -> EntityCommands<'_>

impl<'w, 's> ButtonCommands<'w, 's> for GuiCommands<'w, 's>

fn spawn_button( &mut self, style: OuterStyle, caption: impl Into<String> ) -> EntityCommands<'_>

impl<'w, 's> Deref for GuiCommands<'w, 's>

type Target = Commands<'w, 's>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'w, 's> DerefMut for GuiCommands<'w, 's>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'w, 's> LabelCommands<'w, 's> for GuiCommands<'w, 's>

fn spawn_label( &mut self, style: OuterStyle, caption: impl Into<String> ) -> EntityCommands<'_>

impl SystemParam for GuiCommands<'_, '_>

type State = FetchState

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

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

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

fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State

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

fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta )

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

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

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

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

Creates a parameter to be passed into a SystemParamFunction.

impl<'w, 's> TextBoxCommands<'w, 's> for GuiCommands<'w, 's>

fn spawn_text_box( &mut self, style: OuterStyle, secret: bool ) -> EntityCommands<'_>

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

where Commands<'w, 's>: ReadOnlySystemParam, Res<'w, TextProps>: ReadOnlySystemParam,