Trait SystemCondition 

pub trait SystemCondition<Marker, In = ()>: IntoSystem<In, bool, Marker>
where
    Self::System: ReadOnlySystem,
    In: SystemInput,
{
    // Provided methods
    fn and_then<M, C>(
        self,
        then_run: C,
    ) -> CombinatorSystem<AndThenMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn and_eager<M, C>(
        self,
        other: C,
    ) -> CombinatorSystem<AndEagerMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn and<M, C>(
        self,
        then_run: C,
    ) -> CombinatorSystem<AndThenMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn nand_then<M, C>(
        self,
        then_run: C,
    ) -> CombinatorSystem<NandThenMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn nand_eager<M, C>(
        self,
        other: C,
    ) -> CombinatorSystem<NandEagerMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn nand<M, C>(
        self,
        nand: C,
    ) -> CombinatorSystem<NandThenMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn nor_else<M, C>(
        self,
        else_run: C,
    ) -> CombinatorSystem<NorElseMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn nor_eager<M, C>(
        self,
        other: C,
    ) -> CombinatorSystem<NorEagerMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn nor<M, C>(
        self,
        else_run: C,
    ) -> CombinatorSystem<NorElseMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn or_else<M, C>(
        self,
        else_run: C,
    ) -> CombinatorSystem<OrElseMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn or_eager<M, C>(
        self,
        other: C,
    ) -> CombinatorSystem<OrEagerMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn or<M, C>(
        self,
        else_run: C,
    ) -> CombinatorSystem<OrElseMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn xnor<M, C>(
        self,
        other: C,
    ) -> CombinatorSystem<XnorMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
    fn xor<M, C>(
        self,
        other: C,
    ) -> CombinatorSystem<XorMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>
       where C: SystemCondition<M, In> { ... }
}

A system that determines if one or more scheduled systems should run.

Implemented for functions and closures that convert into System<Out=bool> with read-only parameters.

Marker type parameter

SystemCondition trait has Marker type parameter, which has no special meaning, but exists to work around the limitation of Rust’s trait system.

Type parameter in return type can be set to <()> by calling IntoSystem::into_system, but usually have to be specified when passing a condition to a function.

fn not_condition<Marker>(a: impl SystemCondition<Marker>) -> impl SystemCondition<()> {
   IntoSystem::into_system(a.map(|x| !x))
}

Examples

A condition that returns true every other time it’s called.

fn every_other_time() -> impl SystemCondition<()> {
    IntoSystem::into_system(|mut flag: Local<bool>| {
        *flag = !*flag;
        *flag
    })
}

schedule.add_systems(my_system.run_if(every_other_time()));

A condition that takes a bool as an input and returns it unchanged.

fn identity() -> impl SystemCondition<(), In<bool>> {
    IntoSystem::into_system(|In(x): In<bool>| x)
}

app.add_systems(my_system.run_if(always_true.pipe(identity())));

Provided Methods

fn and_then<M, C>( self, then_run: C, ) -> CombinatorSystem<AndThenMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

Returns a new run condition that only returns true if both this one and the passed then_run return true.

The returned run condition is short-circuiting, meaning then_run will only be invoked if self returns true.

Short-circuiting may not be desired in all cases; when utilizing change detection, the then_run condition will react to changes since the last time that self returned true, which may introduce subtle inconsistencies if short-circuiting was not intended. Similar issues may arise for run conditions that rely on internal state, such as those using Local<T> parameters or MessageReader<T>, as they may not be updated every time the combined condition is evaluated.

See also and_eager, which always evaluates both conditions.

Examples

use bevy_ecs::prelude::*;

#[derive(Resource, PartialEq)]
struct R(u32);

schedule.add_systems(
    // The `resource_equals` run condition will panic since we don't initialize `R`,
    // just like if we used `Res<R>` in a system.
    my_system.run_if(resource_equals(R(0))),
);

Use .and_then() to avoid checking the condition.

schedule.add_systems(
    // `resource_equals` will only get run if the resource `R` exists.
    my_system.run_if(resource_exists::<R>.and_then(resource_equals(R(0)))),
);

Note that in this specific case, it’s better to just use the run condition resource_exists_and_equals.

Examples found in repository

examples/ecs/run_conditions.rs (lines 36-41)

fn main() {
    println!();
    println!("For the first 2 seconds you will not be able to increment the counter");
    println!("Once that time has passed you can press space, enter, left mouse, right mouse or touch the screen to increment the counter");
    println!();

    App::new()
        .add_plugins(DefaultPlugins)
        .init_resource::<InputCounter>()
        .add_systems(
            Update,
            (
                increment_input_counter
                    // The common_conditions module has a few useful run conditions
                    // for checking resources and states. These are included in the prelude.
                    .run_if(resource_exists::<InputCounter>)
                    // `.or_else()` is a run condition combinator that only evaluates the second condition
                    // if the first condition returns `false`. This behavior is known as "short-circuiting",
                    // and is how the `||` operator works in Rust (as well as most C-family languages).
                    // In this case, the `has_user_input` run condition will be evaluated since the `Unused` resource has not been initialized.
                    .run_if(resource_exists::<Unused>.or_else(
                        // This is a custom run condition, defined using a system that returns
                        // a `bool` and which has read-only `SystemParam`s.
                        // Only a single run condition must return `true` in order for the system to run.
                        has_user_input,
                    )),
                print_input_counter
                    // `.and_then()` is a run condition combinator that only evaluates the second condition
                    // if the first condition returns `true`, analogous to the `&&` operator.
                    // In this case, the short-circuiting behavior prevents the second run condition from
                    // panicking if the `InputCounter` resource has not been initialized.
                    .run_if(resource_exists::<InputCounter>.and_then(
                        // This is a custom run condition in the form of a closure.
                        // This is useful for small, simple run conditions you don't need to reuse.
                        // All the normal rules still apply: all parameters must be read only except for local parameters.
                        |counter: Res<InputCounter>| counter.is_changed() && !counter.is_added(),
                    )),
                print_time_message
                    // This function returns a custom run condition, much like the common conditions module.
                    // It will only return true once 2 seconds have passed.
                    .run_if(time_passed(2.0))
                    // You can use the `not` condition from the common_conditions module
                    // to inverse a run condition. In this case it will return true if
                    // less than 2.5 seconds have elapsed since the app started.
                    .run_if(not(time_passed(2.5))),
            ),
        )
        .run();
}

fn and_eager<M, C>( self, other: C, ) -> CombinatorSystem<AndEagerMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

Returns a new run condition that only returns true if both this one and the passed then_run return true.

The returned run condition is eagerly evaluated, meaning it will always execute both run conditions in order.

When applied directly to a system using run_if, the use of this combinator is behaviorally identical to simply calling run_if multiple times. However, .and_eager may be more efficient, as it does not erase the types of the inner conditions when evaluating them, which may allow for compiler optimizations that are not possible with separate calls to run_if.

See also and_then, which short-circuits if self returns false.

Examples

schedule.add_systems(
    // both conditions will execute, even though the first one returned false
    my_system.run_if(returns_false.and_eager(returns_true)),
);

fn and<M, C>( self, then_run: C, ) -> CombinatorSystem<AndThenMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

👎Deprecated since 0.19.0:

use .and_then(...) instead, or .and_eager(...) to evaluate the conditions eagerly

Returns a new run condition that only returns true if both this one and the passed then_run return true.

fn nand_then<M, C>( self, then_run: C, ) -> CombinatorSystem<NandThenMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

Returns a new run condition that only returns false if both this one and the passed then_run return true.

The returned run condition is short-circuiting, meaning then_run will only be invoked if self returns true.

Short-circuiting may not be desired in all cases; when utilizing change detection, the then_run condition will react to changes since the last time that self returned true, which may introduce subtle inconsistencies if short-circuiting was not intended. Similar issues may arise for run conditions that rely on internal state, such as those using Local<T> parameters or MessageReader<T>, as they may not be updated every time the combined condition is evaluated.

See also nand_eager, which always evaluates both conditions.

Examples

schedule.add_systems(
    // The game_over_credits system will only execute if either the `in_state(PlayerState::Alive)`
    // run condition or `in_state(EnemyState::Alive)` run condition evaluates to `false`.
    game_over_credits.run_if(
        in_state(PlayerState::Alive).nand_then(in_state(EnemyState::Alive)),
    ),
);

Equivalent logic can be achieved by using not in concert with and_then:

schedule.add_systems(
    game_over_credits.run_if(
        not(in_state(PlayerState::Alive).and_then(in_state(EnemyState::Alive))),
    ),
);

fn nand_eager<M, C>( self, other: C, ) -> CombinatorSystem<NandEagerMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

Returns a new run condition that only returns false if both this one and the passed then_run return true.

The returned run condition is eagerly evaluated, meaning it will always execute both run conditions in order.

See also nand_then, which short-circuits if self returns false.

fn nand<M, C>( self, nand: C, ) -> CombinatorSystem<NandThenMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

👎Deprecated since 0.19.0:

use .nand_then(...) instead, or .nand_eager(…)` to evaluate the conditions eagerly

Returns a new run condition that only returns false if both this one and the passed then_run return true.

fn nor_else<M, C>( self, else_run: C, ) -> CombinatorSystem<NorElseMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

Returns a new run condition that only returns true if both this one and the passed else_run return false.

The returned run condition is short-circuiting, meaning else_run will only be invoked if self returns true.

Short-circuiting may not be desired in all cases; when utilizing change detection, the else_run condition will react to changes since the last time that self returned true, which may introduce subtle inconsistencies if short-circuiting was not intended. Similar issues may arise for run conditions that rely on internal state, such as those using Local<T> parameters or MessageReader<T>, as they may not be updated every time the combined condition is evaluated.

See also nor_eager, which always evaluates both conditions.

Examples

use bevy::prelude::*;

#[derive(States, Debug, Clone, PartialEq, Eq, Hash)]
pub enum WeatherState {
    Sunny,
    Cloudy,
}

#[derive(States, Debug, Clone, PartialEq, Eq, Hash)]
pub enum SoilState {
    Fertilized,
    NotFertilized,
}

app.add_systems(
    // The slow_plant_growth system will only execute if both the `in_state(WeatherState::Sunny)`
    // run condition and `in_state(SoilState::Fertilized)` run condition evaluate to `false`.
    slow_plant_growth.run_if(
        in_state(WeatherState::Sunny).nor_else(in_state(SoilState::Fertilized)),
    ),
);

Equivalent logic can be achieved by using not in concert with or:

app.add_systems(
    slow_plant_growth.run_if(
        not(in_state(WeatherState::Sunny).or_else(in_state(SoilState::Fertilized))),
    ),
);

fn nor_eager<M, C>( self, other: C, ) -> CombinatorSystem<NorEagerMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

Returns a new run condition that only returns true if both this one and the passed else_run return false.

The returned run condition is eagerly evaluated, meaning it will always execute both run conditions in order.

See also nor_else, which short-circuits if self returns true.

fn nor<M, C>( self, else_run: C, ) -> CombinatorSystem<NorElseMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

👎Deprecated since 0.19.0:

use .nor_else(...) instead, or .nor_eager(...) to evaluate the conditions eagerly

Returns a new run condition that only returns true if both this one and the passed else_run return false.

fn or_else<M, C>( self, else_run: C, ) -> CombinatorSystem<OrElseMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

Returns a new run condition that returns true if either this one or the passed or return true.

The returned run condition is short-circuiting, meaning or will only be invoked if self returns false.

Short-circuiting may not be desired in all cases; when utilizing change detection, the else_run condition will react to changes since the last time that self returned false, which may introduce subtle inconsistencies if short-circuiting was not intended. Similar issues may arise for run conditions that rely on internal state, such as those using Local<T> parameters or MessageReader<T>, as they may not be updated every time the combined condition is evaluated.

See also or_eager, which always evaluates both conditions.

Examples

use bevy_ecs::prelude::*;

#[derive(Resource, PartialEq)]
struct A(u32);

#[derive(Resource, PartialEq)]
struct B(u32);

app.add_systems(
    // Only run the system if either `A` or `B` exist.
    my_system.run_if(resource_exists::<A>.or(resource_exists::<B>)),
);

Examples found in repository

examples/ecs/run_conditions.rs (lines 25-30)

fn main() {
    println!();
    println!("For the first 2 seconds you will not be able to increment the counter");
    println!("Once that time has passed you can press space, enter, left mouse, right mouse or touch the screen to increment the counter");
    println!();

    App::new()
        .add_plugins(DefaultPlugins)
        .init_resource::<InputCounter>()
        .add_systems(
            Update,
            (
                increment_input_counter
                    // The common_conditions module has a few useful run conditions
                    // for checking resources and states. These are included in the prelude.
                    .run_if(resource_exists::<InputCounter>)
                    // `.or_else()` is a run condition combinator that only evaluates the second condition
                    // if the first condition returns `false`. This behavior is known as "short-circuiting",
                    // and is how the `||` operator works in Rust (as well as most C-family languages).
                    // In this case, the `has_user_input` run condition will be evaluated since the `Unused` resource has not been initialized.
                    .run_if(resource_exists::<Unused>.or_else(
                        // This is a custom run condition, defined using a system that returns
                        // a `bool` and which has read-only `SystemParam`s.
                        // Only a single run condition must return `true` in order for the system to run.
                        has_user_input,
                    )),
                print_input_counter
                    // `.and_then()` is a run condition combinator that only evaluates the second condition
                    // if the first condition returns `true`, analogous to the `&&` operator.
                    // In this case, the short-circuiting behavior prevents the second run condition from
                    // panicking if the `InputCounter` resource has not been initialized.
                    .run_if(resource_exists::<InputCounter>.and_then(
                        // This is a custom run condition in the form of a closure.
                        // This is useful for small, simple run conditions you don't need to reuse.
                        // All the normal rules still apply: all parameters must be read only except for local parameters.
                        |counter: Res<InputCounter>| counter.is_changed() && !counter.is_added(),
                    )),
                print_time_message
                    // This function returns a custom run condition, much like the common conditions module.
                    // It will only return true once 2 seconds have passed.
                    .run_if(time_passed(2.0))
                    // You can use the `not` condition from the common_conditions module
                    // to inverse a run condition. In this case it will return true if
                    // less than 2.5 seconds have elapsed since the app started.
                    .run_if(not(time_passed(2.5))),
            ),
        )
        .run();
}

fn or_eager<M, C>( self, other: C, ) -> CombinatorSystem<OrEagerMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

Returns a new run condition that returns true if either this one or the passed or return true.

The returned run condition is eagerly evaluated, meaning it will always execute both run conditions in order.

See also or_else, which short-circuits if self returns true.

Examples found in repository

examples/math/render_primitives.rs (line 45)

fn main() {
    let mut app = App::new();

    app.add_plugins(DefaultPlugins)
        .init_state::<PrimitiveSelected>()
        .init_state::<CameraActive>();

    // cameras
    app.add_systems(Startup, (setup_cameras, setup_lights, setup_ambient_light))
        .add_systems(
            Update,
            (
                update_active_cameras.run_if(state_changed::<CameraActive>),
                switch_cameras.run_if(input_just_pressed(KeyCode::KeyC)),
            ),
        );

    // text

    // PostStartup since we need the cameras to exist
    app.add_systems(PostStartup, setup_text);
    app.add_systems(
        Update,
        (update_text.run_if(state_changed::<PrimitiveSelected>),),
    );

    // primitives
    app.add_systems(Startup, (spawn_primitive_2d, spawn_primitive_3d))
        .add_systems(
            Update,
            (
                switch_to_next_primitive.run_if(input_just_pressed(KeyCode::ArrowUp)),
                switch_to_previous_primitive.run_if(input_just_pressed(KeyCode::ArrowDown)),
                draw_gizmos_2d.run_if(in_mode(CameraActive::Dim2)),
                draw_gizmos_3d.run_if(in_mode(CameraActive::Dim3)),
                update_primitive_meshes.run_if(
                    state_changed::<PrimitiveSelected>.or_eager(state_changed::<CameraActive>),
                ),
                rotate_primitive_2d_meshes,
                rotate_primitive_3d_meshes,
            ),
        );

    app.run();
}

examples/diagnostics/log_diagnostics.rs (line 51)

fn main() {
    App::new()
        .add_plugins((
            // The diagnostics plugins need to be added after DefaultPlugins as they use e.g. the time plugin for timestamps.
            DefaultPlugins,
            // Adds a system that prints diagnostics to the console.
            // The other diagnostics plugins can still be used without this if you want to use them in an ingame overlay for example.
            LogDiagnosticsPlugin::default(),
            // Adds frame time, FPS and frame count diagnostics.
            FrameTimeDiagnosticsPlugin::default(),
            // Adds an entity count diagnostic.
            EntityCountDiagnosticsPlugin::default(),
            // Adds cpu and memory usage diagnostics for systems and the entire game process.
            SystemInformationDiagnosticsPlugin,
            // Forwards various diagnostics from the render app to the main app.
            // These are pretty verbose but can be useful to pinpoint performance issues.
            bevy::render::diagnostic::RenderDiagnosticsPlugin,
        ))
        // No rendering diagnostics are emitted unless something is drawn to the screen,
        // so we spawn a small scene.
        .add_systems(Startup, setup)
        .add_systems(Update, filters_inputs)
        .add_systems(
            Update,
            update_commands.run_if(
                resource_exists_and_changed::<LogDiagnosticsStatus>
                    .or_eager(resource_exists_and_changed::<LogDiagnosticsFilters>),
            ),
        )
        .run();
}

fn or<M, C>( self, else_run: C, ) -> CombinatorSystem<OrElseMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

👎Deprecated since 0.19.0:

use .or_else(...) instead, or .or_eager(...) to eagerly evaluate both conditions

Returns a new run condition that returns true if either this one or the passed or return true.

fn xnor<M, C>( self, other: C, ) -> CombinatorSystem<XnorMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

Returns a new run condition that only returns true if self and xnor both return false or both return true.

The returned run condition is eagerly evaluated, meaning it will always execute both run conditions in order.

Examples

use bevy::prelude::*;

#[derive(States, Debug, Clone, PartialEq, Eq, Hash)]
pub enum CoffeeMachineState {
    Heating,
    Brewing,
    Inactive,
}

#[derive(States, Debug, Clone, PartialEq, Eq, Hash)]
pub enum TeaKettleState {
    Heating,
    Steeping,
    Inactive,
}

app.add_systems(
    // The take_drink_orders system will only execute if the `in_state(CoffeeMachineState::Inactive)`
    // run condition and `in_state(TeaKettleState::Inactive)` run conditions both evaluate to `false`,
    // or both evaluate to `true`.
    take_drink_orders.run_if(
        in_state(CoffeeMachineState::Inactive).xnor(in_state(TeaKettleState::Inactive))
    ),
);

Equivalent logic can be achieved by using not in concert with xor:

app.add_systems(
    take_drink_orders.run_if(
        not(in_state(CoffeeMachineState::Inactive).xor(in_state(TeaKettleState::Inactive)))
    ),
);

fn xor<M, C>( self, other: C, ) -> CombinatorSystem<XorMarker, Self::System, <C as IntoSystem<In, bool, M>>::System>

where C: SystemCondition<M, In>,

Returns a new run condition that only returns true if either self or xor return true, but not both.

The returned run condition is eagerly evaluated, meaning it will always execute both run conditions in order.

Examples

use bevy::prelude::*;

#[derive(States, Debug, Clone, PartialEq, Eq, Hash)]
pub enum CoffeeMachineState {
    Heating,
    Brewing,
    Inactive,
}

#[derive(States, Debug, Clone, PartialEq, Eq, Hash)]
pub enum TeaKettleState {
    Heating,
    Steeping,
    Inactive,
}

app.add_systems(
    // The prepare_beverage system will only execute if either the `in_state(CoffeeMachineState::Inactive)`
    // run condition or `in_state(TeaKettleState::Inactive)` run condition evaluates to `true`,
    // but not both.
    prepare_beverage.run_if(
        in_state(CoffeeMachineState::Inactive).xor(in_state(TeaKettleState::Inactive))
    ),
);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<Marker, In, F> SystemCondition<Marker, In> for F

where In: SystemInput, F: IntoSystem<In, bool, Marker>, <F as IntoSystem<In, bool, Marker>>::System: ReadOnlySystem,