Struct ReactCommands

pub struct ReactCommands<'w, 's> { /* private fields */ }

Drives reactivity.

Requires ReactPlugin.

Note that each time you register a reactor, it is assigned a unique system state (including unique Locals). To avoid leaking memory, be sure to revoke reactors when you are done with them. Despawn reactors are automatically cleaned up.

Ordering and determinism

ReactCommands requires exclusive access to an internal cache, which means the order of react events is fully specified. Reactors of the same type will react to an event in the order they are added, and react commands will be applied in the order they were invoked (note that all reactor registration is deferred). Reactions to a reactor will always be resolved immediately after the reactor ends, in the order they were queued (and so on up the reaction tree). A reactor’s component removals and entity despawns are queued alongside child reactions, which means a removal/despawn can only be ‘seen’ once its place in the queue has been processed. Reactors always schedule reactions to available removals/despawns after they run, so if you have [despawn A, reaction X, despawn B], and both despawns have reactions, then despawn A will be the first despawn reacted to at the end of reaction X (or at end of the first leaf node of a reaction branch stemming from X), before any of X’s despawns.

A reaction tree is single-threaded by default (it may be multi-threaded if you manually invoke a bevy schedule within the tree), so trees are deterministic. However, root-level reactive systems (systems that cause reactions but are not themselves reactors) are subject to the ordering constraints of their callers (e.g. a bevy app schedule), and reaction trees can only be initiated by calling apply_deferred(). This means the order that root-level reactors are queued, and the order of root-level removals/despawns, is unspecified by the react framework.

Notes

A reaction tree is like a multi-layered accordion of command queues that automatically expands and resolves itself. Of note, the ‘current’ structure of that accordion tree cannot be modified. For example, you cannot add a data event reactor after an instance of a data event of that type that is below you in the reaction tree and expect the new reactor will respond to that data event instance. Moreover, already-queued reactions/ react commands cannot be removed from the tree. However, modifications to the ECS world will be reflected in the behavior of future reactors, which may effect the structure of not-yet-expanded parts of the accordion.

Component removal and entity despawn reactions can only occur if you explicitly call react_to_removals(), react_to_despawns(), or react_to_all_removals_and_despawns(). We call those automatically in reaction trees, but if a root-level reactive system doesn’t cause any reactions then removals/despawns won’t be handled. For that reason, we recommand always pessimistically checking for removals/despawns manually after a call to apply_deferred after root-level reactive systems.

WARNING: All ordering constraints may be thrown out the window with bevy native command batching.

Implementations

impl<'w, 's> ReactCommands<'w, 's>

pub fn commands<'a>(&'a mut self) -> &'a mut Commands<'w, 's>

Access Commands.

pub fn insert<C: ReactComponent>(&mut self, entity: Entity, component: C)

Insert a ReactComponent to the specified entity. It can be queried with React<C>.

• Reactions are enacted after apply_deferred is invoked.
• Does nothing if the entity does not exist.

pub fn send<E: Send + Sync + 'static>(&mut self, event: E)

Send an event.

• The event is sent and reactions are enacted after apply_deferred is invoked.
• Reactors can access the event with the bevy [ReactEvent<E>] system parameter.

pub fn trigger_resource_mutation<R: ReactResource + Send + Sync + 'static>( &mut self, )

Trigger resource mutation reactions.

Useful for initializing state after a reactor is registered.

pub fn revoke(&mut self, token: RevokeToken)

Revoke a reactor.

• Entity reactors: revoked after apply_deferred is invoked.
• Component, despawn, resource, event reactors: revoked immediately.

pub fn on<I, Marker>( &mut self, triggers: impl ReactionTriggerBundle<I>, reactor: impl IntoSystem<I, (), Marker> + Send + Sync + 'static, ) -> RevokeToken

where I: Send + Sync + 'static,

Register a reactor triggered by ECS changes.

You can tie a reactor to multiple reaction triggers. Note that the entity-agnostic component triggers can only be bundled with each other: insertion(), mutation(), removal().

Duplicate triggers will be ignored.

Reactions are not merged together. If you register a reactor for triggers (resource_mutation::<A>(), resource_mutation::<B>()), then mutate A and B in succession, the reactor will execute twice.

Example:

rcommands.on((resource_mutation::<MyRes>(), component_mutation::<MyComponent>()), my_reactor_system);

pub fn on_despawn<Marker>( &mut self, entity: Entity, reactor: impl IntoSystem<(), (), Marker> + Send + Sync + 'static, ) -> Result<RevokeToken, ()>

Register a reactor to an entity despawn.

Despawn reactors are one-shot systems and will automatically clean themselves up when the entity despawns.

Returns Err if the entity does not exist.

Example:

rcommands.on_despawn(entity, my_reactor_system).expect("entity is missing");

pub fn once<I, Marker>( &mut self, triggers: impl ReactionTriggerBundle<I>, reactor: impl IntoSystem<I, (), Marker> + Send + Sync + 'static, ) -> RevokeToken

where I: Send + Sync + 'static,

Register a one-off reactor triggered by ECS changes.

Similar to Self::on except the reaction will run exactly once then get cleaned up.

Example:

// The reactor will run on the first mutation of either MyRes or MyComponent.
rcommands.once((resource_mutation::<MyRes>(), component_mutation::<MyComponent>()), my_reactor_system);

Trait Implementations

impl SystemParam for ReactCommands<'_, '_>

type State = FetchState

Used to store data which persists across invocations of a system.

type Item<'w, 's> = ReactCommands<'w, 's>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta, )

For the specified Archetype, registers the components accessed by this SystemParam (if applicable).

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during apply_deferred.

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> Self::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

impl<'w, 's> ReadOnlySystemParam for ReactCommands<'w, 's>

where Commands<'w, 's>: ReadOnlySystemParam, ResMut<'w, ReactCache>: ReadOnlySystemParam, Res<'w, AutoDespawner>: ReadOnlySystemParam,