Module system

Source
Expand description

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:

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