Module system

bevy::ecs

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 return type

Systems added to a schedule through add_systems may either return empty () or a Result. Other contexts (like one shot systems) allow systems to return arbitrary values.

§System parameter list

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

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:

Modules§

command
Contains the definition of the Command trait, as well as the blanket implementation of the trait for closures.
entity_command
Contains the definition of the EntityCommand trait, as well as the blanket implementation of the trait for closures.
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 ApplyDeferred. 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.
If
A SystemParam that wraps another parameter and causes its system to skip instead of failing when the parameter is invalid.
IfBuilder
A SystemParamBuilder for a If.
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.
NonSendMarker
A dummy type that is !Send, to force systems to run on the main thread.
NonSendMut
Unique borrow of a non-Send resource.
OptionBuilder
A SystemParamBuilder for an Option.
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
A 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.
RemovedSystem
A system that has been removed from the registry. It contains the system and whether or not it has been initialized.
Res
Shared borrow of a Resource.
ResMut
Unique mutable borrow of a Resource.
ResultBuilder
A SystemParamBuilder for a Result of SystemParamValidationError.
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.
SystemParamValidationError
An error that occurs when a system parameter is not valid, used by system executors to determine what to do with a system.
SystemState
Holds on to persistent state required to drive SystemParam for a System.
SystemStateFlags
Bitflags representing system states and requirements.
WithInputFromWrapper
Constructed in IntoSystem::with_input_from.
WithInputWrapper
See IntoSystem::with_input for details.

Enums§

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.
Command
A World mutation.
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.
IntoResult
A type that may be converted to the output of a System. This is used to allow systems to return either a plain value or a Result.
IntoSystem
Conversion trait to turn something into a System.
ObserverSystem
Implemented for Systems that have On 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.
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§

BoxedReadOnlySystem
A convenience type alias for a boxed ReadOnlySystem trait object.
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.
ScheduleSystem
Type alias for a BoxedSystem that a Schedule can store.
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§

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