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
andOption<Res>
ResMut
andOption<ResMut>
Commands
Local
EventReader
EventWriter
NonSend
andOption<NonSend>
NonSendMut
andOption<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§
- Contains type aliases for built-in
SystemParam
s with'static
lifetimes. This makes it more convenient to refer to these types in contexts where explicit lifetime annotations are required.
Structs§
- A
SystemParam
that stores a buffer which gets applied to theWorld
duringapply_deferred
. This is used internally byCommands
to deferWorld
mutations. - A list of commands that will be run to modify an entity.
- A function system that runs with exclusive
World
access. - The
System
counter part of an ordinary function. - Wrapper type to mark a
SystemParam
as an input. - A system local
SystemParam
. - Shared borrow of a non-
Send
resource. - An alternative to
Commands
that can be used in parallel contexts, such as those inQuery::par_iter
- A collection of potentially conflicting
SystemParam
s allowed by disjoint access. - Type returned from
Query::transmute_lens
containing the newQueryState
. - A system that has been removed from the registry. It contains the system and whether or not it has been initialized.
- A helper for using system parameters in generic contexts
- Builder struct used to construct state for
SystemParam
passed to a system. - A
SystemParam
that reads the previous and current change ticks of the system. - An identifier for a registered system.
- The metadata of a
System
. SystemParam
that returns the name of the system which it is used in.- Holds on to persistent state required to drive
SystemParam
for aSystem
. - Turns an
EntityCommand
type into aCommand
type.
Enums§
- An operation with stored systems failed.
Traits§
- Customizes the behavior of an
AdapterSystem
- A parameter that can be built with
SystemBuilder
- Customizes the behavior of a
CombinatorSystem
. - 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. - A trait implemented for all exclusive system functions that can be used as
System
s. - Implemented for systems that convert into
ObserverSystem
. - Conversion trait to turn something into a
System
. - Implemented for systems that have an
Observer
as the first argument. System
types that do not modify theWorld
when run. This is implemented for any systems whose parameters all implementReadOnlySystemParam
.- A
SystemParam
that only reads a givenWorld
. - A type that can be inserted into a
World
as a singleton. - Trait used to run a system immediately on a
World
. - An ECS system that can be added to a
Schedule
- Types that can be used with
Deferred<T>
in systems. This allows storing system-local data which is used to deferWorld
mutations. - A parameter that can be used in a
System
. - A trait implemented for all functions that can be used as
System
s.
Functions§
- Ensure that a given function is a read-only system.
- Ensure that a given function is a system.
- Ensures that the provided system doesn’t with itself.
Type Aliases§
- A convenience type alias for a boxed
System
trait object. - Shorthand way of accessing the associated type
ExclusiveSystemParam::Item
for a givenExclusiveSystemParam
. - A
System
created by piping the output of the first system into the input of the second. - The
Command
type forWorld::run_system
. - Shorthand way of accessing the associated type
SystemParam::Item
for a givenSystemParam
.
Derive Macros§
- Implement
SystemParam
to use a struct as a parameter in a system