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§
- lifetimeless
- 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§
- Adapter
System - A
System
that takes the output ofS
and transforms it by applyingFunc
to it. - Combinator
System - A
System
defined by combining two other systems. The behavior of this combinator is specified by implementing theCombine
trait. For a full usage example, see the docs forCombine
. - Commands
- A
Command
queue to perform structural changes to theWorld
. - Deferred
- A
SystemParam
that stores a buffer which gets applied to theWorld
duringapply_deferred
. This is used internally byCommands
to deferWorld
mutations. - Entity
Commands - A list of commands that will be run to modify an entity.
- Exclusive
Function System - A function system that runs with exclusive
World
access. - Function
System - The
System
counter part of an ordinary function. - In
- Wrapper type to mark a
SystemParam
as an input. - Local
- A system local
SystemParam
. - NonSend
- Shared borrow of a non-
Send
resource. - Parallel
Commands - An alternative to
Commands
that can be used in parallel contexts, such as those inQuery::par_iter
- Param
Set - A collection of potentially conflicting
SystemParam
s allowed by disjoint access. - Query
- System parameter that provides selective access to the
Component
data stored in aWorld
. - Query
Lens - Type returned from
Query::transmute_lens
containing the newQueryState
. - Register
System - The
Command
type for registering one shot systems from Commands. - Removed
System - A system that has been removed from the registry. It contains the system and whether or not it has been initialized.
- RunSystem
With Input - The
Command
type forWorld::run_system
orWorld::run_system_with_input
. - Static
System Param - A helper for using system parameters in generic contexts
- System
Builder - Builder struct used to construct state for
SystemParam
passed to a system. - System
Change Tick - A
SystemParam
that reads the previous and current change ticks of the system. - System
Id - An identifier for a registered system.
- System
Meta - The metadata of a
System
. - System
Name SystemParam
that returns the name of the system which it is used in.- System
State - Holds on to persistent state required to drive
SystemParam
for aSystem
. - With
Entity - Turns an
EntityCommand
type into aCommand
type.
Enums§
- Registered
System Error - An operation with stored systems failed.
Traits§
- Adapt
- Customizes the behavior of an
AdapterSystem
- Buildable
System Param - A parameter that can be built with
SystemBuilder
- Combine
- Customizes the behavior of a
CombinatorSystem
. - Entity
Command - A
Command
which gets executed for a givenEntity
. - Exclusive
System Param - 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. - Exclusive
System Param Function - A trait implemented for all exclusive system functions that can be used as
System
s. - Into
Observer System - Implemented for systems that convert into
ObserverSystem
. - Into
System - Conversion trait to turn something into a
System
. - Observer
System - Implemented for systems that have an
Observer
as the first argument. - Read
Only System System
types that do not modify theWorld
when run. This is implemented for any systems whose parameters all implementReadOnlySystemParam
.- Read
Only System Param - A
SystemParam
that only reads a givenWorld
. - Resource
- A type that can be inserted into a
World
as a singleton. - RunSystem
Once - Trait used to run a system immediately on a
World
. - System
- An ECS system that can be added to a
Schedule
- System
Buffer - Types that can be used with
Deferred<T>
in systems. This allows storing system-local data which is used to deferWorld
mutations. - System
Param - A parameter that can be used in a
System
. - System
Param Function - A trait implemented for all functions that can be used as
System
s.
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 with itself.
Type Aliases§
- Boxed
System - A convenience type alias for a boxed
System
trait object. - Exclusive
System Param Item - Shorthand way of accessing the associated type
ExclusiveSystemParam::Item
for a givenExclusiveSystemParam
. - Pipe
System - A
System
created by piping the output of the first system into the input of the second. - RunSystem
- The
Command
type forWorld::run_system
. - System
Param Item - Shorthand way of accessing the associated type
SystemParam::Item
for a givenSystemParam
.
Derive Macros§
- Resource
- System
Param - Implement
SystemParam
to use a struct as a parameter in a system