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_set(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>
&World
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
- A collection of common adapters for piping the result of a system.
- Contains type aliases for built-in
SystemParam
s with'static
lifetimes. This can make it more convenient to refer to these types in contexts where explicit lifetime annotations are required.
Structs
- Densely and efficiently stores a queue of heterogenous types implementing
Command
. - A
SystemParam
that stores a buffer which gets applied to theWorld
duringapply_deferred
. This is used internally byCommands
to deferWorld
mutations. - A
Command
that despawns a specific entity. This will emit a warning if the entity does not exist. - 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
. Command
to log the components of a given entity. SeeEntityCommands::log_components
.- 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. - A helper for using system parameters in generic contexts
- A
SystemParam
that reads the previous and current change ticks of the system. - The metadata of a
System
. - Name of the system that corresponds to this
crate::system::SystemState
. - Holds on to persistent state required to drive
SystemParam
for aSystem
. - Turns an
EntityCommand
type into aCommand
type.
Enums
Traits
- Customizes the behavior of a
CombinatorSystem
. - A
World
mutation. - 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. - Conversion trait to turn something into a
System
. 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. - 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. - 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