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
// Prints "Hello, World!" each frame.
app
.add_system(print_first.before(print_mid))
.add_system(print_mid)
.add_system(print_last.after(print_mid));
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)
Modules
Structs
- Densely and efficiently stores a queue of heterogenous types implementing
Command
. - A
SystemParam
that stores a buffer which gets applied to theWorld
duringapply_system_buffers
. 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
. Command
to log the components of a given entity. SeeEntityCommands::log_components
.- Shared borrow of a non-
Send
resource. - Unique 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. - Shared borrow of a
Resource
. - Unique mutable borrow of a
Resource
. - 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 trait implemented for all exclusive system functions that can be used as
System
s. - An extension trait providing the
IntoPipeSystem::pipe
method to pass input from one system into the next. - 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.
Type Definitions
- A convenience type alias for a boxed
System
trait object. - 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