Struct ReactCommands

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

Struct that drives reactivity.

Obtained via Commands::react.

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.

All react command operations are deferred.

Implementations

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

pub fn commands(&mut self) -> Commands<'_, '_>

Returns a reborrow of the internal Commands with a shorter lifetime.

pub fn reborrow(&mut self) -> ReactCommands<'_, '_>

Returns a reborrow of self with a shorter lifetime.

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

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

• Does nothing if the entity does not exist.

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

Sends a broadcasted event.

• Reactors can listen for the event with the broadcast() trigger.
• Reactors can read the event with the BroadcastEvent system parameter.

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

Sends an entity-targeted event.

• Reactors can listen for the event with the entity_event() trigger.
• Reactors can read the event with the EntityEvent system parameter.

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

Triggers resource mutation reactions.

Useful for initializing state after a reactor is registered.

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

Revokes a reactor.

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

Registers a reactor triggered by ECS changes.

You can tie a reactor to multiple reaction triggers. 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.

Uses ReactorMode::Cleanup.

Example:

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

pub fn on_persistent<M>( &mut self, triggers: impl ReactionTriggerBundle, reactor: impl IntoSystem<(), (), M> + Send + Sync + 'static, ) -> SystemCommand

Registers a reactor triggered by ECS changes using ReactorMode::Persistent.

See Self::on.

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

Registers a reactor triggered by ECS changes using ReactorMode::Revokable.

See Self::on.

pub fn with( &mut self, triggers: impl ReactionTriggerBundle, sys_command: SystemCommand, mode: ReactorMode, ) -> Option<RevokeToken>

Registers a reactor triggered by ECS changes with a SystemCommand and ReactorMode.

You can tie a reactor to multiple reaction triggers. 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.

Note that you can call this method multiple times for the same SystemCommand to add triggers. It is highly recommended to use ReactorMode::Persistent in that case, otherwise your reactor may be despawned unexpectedly if a despawn() trigger is used or if you try to revoke any RevokeTokens associated with the reactor.

Returns None unless ReactorMode::Revokable is used.

Example:

let command = commands.spawn_system_command(my_reactor_system);
let mode = ReactorMode::Persistent;
commands.react().with((resource_mutation::<MyRes>(), mutation::<MyComponent>()), command, mode);

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

Registers a one-off reactor triggered by ECS changes.

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

If an empty trigger bundle is used then the system will be dropped without running.

Example:

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