Module system

Tools for controlling behavior in an ECS application.

Systems define how an ECS based application behaves. Systems are added to a Schedule, which is then run. A system is usually written as a normal function, which is automatically converted into a system.

System functions can have parameters, through which one can query and mutate Bevy ECS state. Only types that implement SystemParam can be used, automatically fetching data from the World.

System functions often look like this:

fn update_score_system(
    mut query: Query<(&Player, &mut Score)>,
    mut round: ResMut<Round>,
) {
    for (player, mut score) in &mut query {
        if player.alive {
            score.0 += round.0;
        }
    }
    round.0 += 1;
}

System ordering

By default, the execution of systems is parallel and not deterministic. Not all systems can run together: if a system mutably accesses data, no other system that reads or writes that data can be run at the same time. These systems are said to be incompatible.

The relative order in which incompatible systems are run matters. When this is not specified, a system order ambiguity exists in your schedule. You can explicitly order systems:

• by calling the .before(this_system) or .after(that_system) methods when adding them to your schedule
• by adding them to a SystemSet, and then using .configure_sets(ThisSet.before(ThatSet)) syntax to configure many systems at once
• through the use of .add_systems((system_a, system_b, system_c).chain())

Example

// Configure these systems to run in order using `chain()`.
schedule.add_systems((print_first, print_last).chain());
// Prints "HelloWorld!"
schedule.run(&mut world);

// Configure this system to run in between the other two systems
// using explicit dependencies.
schedule.add_systems(print_mid.after(print_first).before(print_last));
// Prints "Hello, World!"
schedule.run(&mut world);

fn print_first() {
    print!("Hello");
}
fn print_mid() {
    print!(", ");
}
fn print_last() {
    println!("World!");
}

System parameter list

Following is the complete list of accepted types as system parameters:

• Query
• Res and Option<Res>
• ResMut and Option<ResMut>
• Commands
• Local
• EventReader
• EventWriter
• NonSend and Option<NonSend>
• NonSendMut and Option<NonSendMut>
• RemovedComponents
• SystemName
• SystemChangeTick
• Archetypes (Provides Archetype metadata)
• Bundles (Provides Bundles metadata)
• Components (Provides Components metadata)
• Entities (Provides Entities metadata)
• All tuples between 1 to 16 elements where each element implements SystemParam
• () (unit primitive type)

Re-exports

pub use crate::change_detection::NonSendMut;

pub use crate::change_detection::Res;

pub use crate::change_detection::ResMut;

Modules

lifetimeless

Contains type aliases for built-in SystemParams with 'static lifetimes. This makes it more convenient to refer to these types in contexts where explicit lifetime annotations are required.

Structs

AdapterSystem

A System that takes the output of S and transforms it by applying Func to it.

CombinatorSystem

A System defined by combining two other systems. The behavior of this combinator is specified by implementing the Combine trait. For a full usage example, see the docs for Combine.

Commands

A Command queue to perform structural changes to the World.

Deferred

A SystemParam that stores a buffer which gets applied to the World during apply_deferred. This is used internally by Commands to defer World mutations.

EntityCommands

A list of commands that will be run to modify an entity.

ExclusiveFunctionSystem

A function system that runs with exclusive World access.

FunctionSystem

The System counter part of an ordinary function.

In

Wrapper type to mark a SystemParam as an input.

Local

A system local SystemParam.

NonSend

Shared borrow of a non-Send resource.

ParallelCommands

An alternative to Commands that can be used in parallel contexts, such as those in Query::par_iter

ParamSet

A collection of potentially conflicting SystemParams allowed by disjoint access.

Query

System parameter that provides selective access to the Component data stored in a World.

QueryLens

Type returned from Query::transmute_lens containing the new QueryState.

RegisterSystem

The Command type for registering one shot systems from Commands.

RemovedSystem

A system that has been removed from the registry. It contains the system and whether or not it has been initialized.

RunSystemWithInput

The Command type for World::run_system or World::run_system_with_input.

StaticSystemParam

A helper for using system parameters in generic contexts

SystemBuilder

Builder struct used to construct state for SystemParam passed to a system.

SystemChangeTick

A SystemParam that reads the previous and current change ticks of the system.

SystemId

An identifier for a registered system.

SystemMeta

The metadata of a System.

SystemName

SystemParam that returns the name of the system which it is used in.

SystemState

Holds on to persistent state required to drive SystemParam for a System.

WithEntity

Turns an EntityCommand type into a Command type.

Enums

RegisteredSystemError

An operation with stored systems failed.

Traits

Adapt

Customizes the behavior of an AdapterSystem

BuildableSystemParam

A parameter that can be built with SystemBuilder

Combine

Customizes the behavior of a CombinatorSystem.

EntityCommand

A Command which gets executed for a given Entity.

ExclusiveSystemParam

A parameter that can be used in an exclusive system (a system with an &mut World parameter). Any parameters implementing this trait must come after the &mut World parameter.

ExclusiveSystemParamFunction

A trait implemented for all exclusive system functions that can be used as Systems.

IntoObserverSystem

Implemented for systems that convert into ObserverSystem.

IntoSystem

Conversion trait to turn something into a System.

ObserverSystem

Implemented for systems that have an Observer as the first argument.

ReadOnlySystem

System types that do not modify the World when run. This is implemented for any systems whose parameters all implement ReadOnlySystemParam.

ReadOnlySystemParam

A SystemParam that only reads a given World.

Resource

A type that can be inserted into a World as a singleton.

RunSystemOnce

Trait used to run a system immediately on a World.

System

An ECS system that can be added to a Schedule

SystemBuffer

Types that can be used with Deferred<T> in systems. This allows storing system-local data which is used to defer World mutations.

SystemParam

A parameter that can be used in a System.

SystemParamFunction

A trait implemented for all functions that can be used as Systems.

Functions

assert_is_read_only_system

Ensure that a given function is a read-only system.

assert_is_system

Ensure that a given function is a system.

assert_system_does_not_conflict

Ensures that the provided system doesn’t with itself.

Type Aliases

BoxedSystem

A convenience type alias for a boxed System trait object.

ExclusiveSystemParamItem

Shorthand way of accessing the associated type ExclusiveSystemParam::Item for a given ExclusiveSystemParam.

PipeSystem

A System created by piping the output of the first system into the input of the second.

RunSystem

The Command type for World::run_system.

SystemParamItem

Shorthand way of accessing the associated type SystemParam::Item for a given SystemParam.

Derive Macros

Resource

SystemParam

Implement SystemParam to use a struct as a parameter in a system