Module system

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:

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
ParamSet
() (unit primitive type)

In addition, the following parameters can be used when constructing a dynamic system with SystemParamBuilder, but will only provide an empty value when used with an ordinary system:

FilteredResources
FilteredResourcesMut
DynSystemParam
Vec<P> where P: SystemParam
ParamSet<Vec<P>> where P: SystemParam

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.
CachedSystemId: A cached SystemId distinguished by the unique function type of its system.
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.
DynParamBuilder: A SystemParamBuilder for a DynSystemParam. See the DynSystemParam docs for examples.
DynSystemParam: A SystemParam with a type that can be configured at runtime.
DynSystemParamState: The SystemParam::State for a DynSystemParam.
EntityCommands: A list of commands that will be run to modify an entity.
EntityEntryCommands: A wrapper around EntityCommands with convenience methods for working with a specified component type.
ExclusiveFunctionSystem: A function system that runs with exclusive World access.
FilteredResourcesMutParamBuilder: A SystemParamBuilder for a FilteredResourcesMut. See the FilteredResourcesMut docs for examples.
FilteredResourcesParamBuilder: A SystemParamBuilder for a FilteredResources. See the FilteredResources docs for examples.
FunctionSystem: The System counter part of an ordinary function.
In: A SystemInput type which denotes that a System receives an input value of type T from its caller.
InMut: A SystemInput type which denotes that a System receives a mutable reference to a value of type T from its caller.
InRef: A SystemInput type which denotes that a System receives a read-only reference to a value of type T from its caller.
IntoAdapterSystem: An IntoSystem creating an instance of AdapterSystem.
IntoPipeSystem: An IntoSystem creating an instance of PipeSystem.
Local: A system local SystemParam.
LocalBuilder: A SystemParamBuilder for a Local. The provided value will be used as the initial value of the Local.
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.
ParamBuilder: A SystemParamBuilder for any SystemParam that uses its default initialization.
ParamSet: A collection of potentially conflicting SystemParams allowed by disjoint access.
ParamSetBuilder: A SystemParamBuilder for a ParamSet.
PipeSystem: A System created by piping the output of the first system into the input of the second.
Populated: System parameter that works very much like Query except it always contains at least one matching entity.
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.
QueryParamBuilder: A SystemParamBuilder for a Query. This takes a closure accepting an &mut QueryBuilder and uses the builder to construct the query’s state. This can be used to add additional filters, or to configure the components available to FilteredEntityRef or FilteredEntityMut.
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.
RunSystemCachedWith: The Command type for running a cached one-shot system from Commands.
RunSystemWithInput: The Command type for World::run_system or World::run_system_with_input.
Single: System parameter that provides access to single entity’s components, much like Query::single/Query::single_mut.
StaticSystemInput: A helper for using SystemInputs in generic contexts.
StaticSystemParam: A helper for using system parameters in generic contexts
SystemChangeTick: A SystemParam that reads the previous and current change ticks of the system.
SystemId: An identifier for a registered system.
SystemIdMarker: Marker Component for identifying SystemId Entitys.
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.
UnregisterSystem: The Command type for unregistering one-shot systems from Commands.

Enums§

ParamWarnPolicy: State machine for emitting warnings when system params are invalid.
RegisteredSystemError: An operation with stored systems failed.
RunSystemError: Running system failed.

Traits§

Adapt: Customizes the behavior of an AdapterSystem
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 a Trigger 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.
SystemInput: Trait for types that can be used as input to Systems.
SystemParam: A parameter that can be used in a System.
SystemParamBuilder: A builder that can create a SystemParam.
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 conflict 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.
RunSystem: The Command type for World::run_system.
SystemIn: Shorthand way to get the System::In for a System as a SystemInput::Inner.
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

Module systemCopy item path