Crate bevy_kot_ecs

Expand description

§ECS

ReactCommands makes it easy to register and unregister ECS hooks. Reactors are most useful when you need to pass information (e.g. entity IDs) into a reaction system.

A reactor will run in the first apply_deferred after its reaction trigger is detected. If a reactor triggers other reactors, they will run immediately after the initial reactor (until the entire tree of reactions terminates). Recursive reactions are currently not supported.

§Registering Reactors

Reactors are registered with ReactCommands. You must specify a ‘reaction trigger’:

fn setup(mut rcommands: ReactCommands)
{
    rcommands.on(resource_mutation::<A>(),
        |a: ReactRes<A>|
        {
            //...
        }
    );
}

The available reaction triggers are:

resource_mutation<R: ReactResource>()
insertion<C: ReactComponent>()
mutation<C: ReactComponent>()
removal<C: ReactComponent>()
[entity_insertion<C: ReactComponent>(entity)]
[entity_mutation<C: ReactComponent>(entity)]
[entity_removal<C: ReactComponent>(entity)]
event<E>()

A reactor can be associated with multiple reaction triggers:

fn setup(mut rcommands: ReactCommands)
{
    rcommands.on((resource_mutation::<A>(), entity_insertion<B>(entity)),
        move |a: ReactRes<A>, q: Query<&B>|
        {
            q.get(entity);
            //...etc.
        }
    );
}

§Revoking Reactors

Reactors can be revoked with RevokeTokens obtained on registration.

let token = rcommands.on(resource_mutation::<A>(), || { todo!(); });
rcommands.revoke(token);

§Trigger Type: Resource Mutation

Add a reactive resource to your app:

#[derive(ReactResource)]
struct Counter(u32);

app.add_plugins(ReactPlugin)
    .add_react_resource(Counter);

Mutate the resource:

fn increment(mut rcommands: ReactCommands, mut counter: ReactResMut<Counter>)
{
    counter.get_mut(&mut rcommands).0 += 1;
}

React to the resource mutation:

fn setup(mut rcommands: ReactCommands)
{
    rcommands.on(resource_mutation::<Counter>(),
        |counter: ReactRes<Counter>|
        {
            println!("count: {}", counter.0);
        }
    );
}

§Trigger Type: Component Insertion/Mutation/Removal

#[derive(ReactComponent)]
struct Health(u16);

fn setup(mut rcommands: ReactCommands)
{
    let entity = rcommands.commands().spawn_empty().id();
    rcommands.insert(entity, Health(0u16));

    rcommands.on(entity_mutation::<Health>(entity)
        move |q: Query<&React<Health>>|
        {
            let health = q.get(entity).unwrap();
            println!("health: {}", health.0);
        }
    );
}

fn add_health(mut rcommands: ReactCommands, mut q: Query<&mut React<Health>>)
{
    for health in q.iter_mut()
    {
        health.get_mut(&mut rcommands).0 += 10;
    }
}

Entity-agnostic triggers (insertion<C>(), mutation<C>(), removal<C>()) can only be grouped with each other, since their reactor requires an In<Entity> system parameter:

#[derive(ReactComponent)]
struct A;
#[derive(ReactComponent)]
struct B;

rcommands.on((insertion::<A>(), removal::<B>()),
    |In(entity): In<Entity>, a: Query<(Option<&React<A>>, Option<&React<B>>)>|
    {
        //...
    }
);

§Trigger Type: Events

Register a react event:

app.add_react_event::<u32>();

Send an event:

rcommands.send(0u32);

React to the event, using the ReactEventReader to access event data:

rcommands.on(event::<u32>(),
    |mut events: ReactEventReader<u32>|
    {
        for event in events.iter()
        {
            println!("react u32: {}", event);
        }
    }
);

§Trigger Type: Despawns

React to despawns with the ReactCommands::on_despawn() method:

rcommands.on_despawn(entity, move || println!("entity despawned: {}", entity));

§One-off Reactors

If you only want a reactor to run once, use ReactCommands::once():

let entity = rcommands.commands().spawn(Player);
rcommands.once(event::<ResetEverything>(),
    move |world: &mut World|
    {
        world.despawn(entity);
    }
);

Structs§

AutoDespawnSignal: RAII handle to a despawn signal.
AutoDespawner: Creates AutoDespawnSignals.
CallId: An identifier for CallableSystems. Each identifier represents a unique system context.
CallOnce: Callback wrapper for FnOnce functions. Implements Command.
CallOnceWith: Callback wrapper that lets you call with a value once. The helper returned by .call_with() implements Command.
Callback: Callback wrapper. Implements Command.
CallbackWith: Callback wrapper that lets you call with a value. The helper returned by .call_with() implements Command.
Callwith: Callback wrapper with a specific call value baked in. Implements Command.
CallwithOnce: Callback wrapper with a specific call value baked in. Implements Command.
EntityInsertion: Reaction trigger for ReactComponent insertions on a specific entity.
EntityMutation: Reaction trigger for ReactComponent mutations on a specific entity.
EntityRemoval: Reaction trigger for ReactComponent removals from a specific entity.
Event: Reaction trigger for events.
IdMappedSystems: Tracks named systems.
Insertion: Reaction trigger for ReactComponent insertions on any entity.
Mutation: Reaction trigger for ReactComponent mutations on any entity.
React: Component wrapper that enables reacting to component mutations.
ReactCommands: Drives reactivity.
ReactEventReader: Provides access to react events of type E.
ReactPlugin
ReactRes: Immutable reader for reactive resources.
ReactResMut: Mutable wrapper for reactive resources.
Removal: Reaction trigger for ReactComponent removals from any entity.
ResourceMutation: Reaction trigger for ReactResource mutations.
RevokeToken: Token for revoking reactors.
SysCall: Callback wrapper that mimics syscall (without an implicit call to apply_deferred).
SysId: System identifier for referencing spawned systems.
SysName: System identifier for use in named systems.

Enums§

CallbackSystem: Represents a system callback.
ReactorType

Traits§

AutoDespawnAppExt: Extends the App API with a method to set up auto despawning.
BasicCallableSystem: Implemented types can be called like normal functions.
CallableSystem: Implemented types can be called like normal functions.
ReactComponent: Tag trait for reactive components.
ReactEventAppExt: Extends the App API with reactive event methods.
ReactResAppExt
ReactResCommandsExt
ReactResWorldExt: Extends the World API with reactive resource methods.
ReactResource: Tag trait for reactive resources.
ReactionTrigger: Helper trait for registering reactors with ReactCommands.
ReactionTriggerBundle: Helper trait for registering reactors with ReactCommands.
SystemCallerCommandsExt

Functions§

call: Call a callable system (one function argument).
call_basic: Call a callable system (no function arguments).
entity_insertion: Obtain a EntityInsertion reaction trigger.
entity_mutation: Obtain a EntityMutation reaction trigger.
entity_removal: Obtain a EntityRemoval reaction trigger.
event: Obtain an [Event] reaction trigger.
insertion: Obtain a Insertion reaction trigger.
mutation: Obtain a Mutation reaction trigger.
named_syscall: Execute a named system on some data then apply the system’s deferred commands.
named_syscall_direct: Directly invoke a named system.
prep_fncall: Wrap a Fn system in a system that consumes the system input.
react_to_all_removals_and_despawns: Iteratively react to component removals and entity despawns until all reaction chains have ended.
react_to_despawns: React to tracked despawns.
react_to_removals: React to component removals.
reactor_registration
register_named_system: Register a named system for future use.
register_named_system_from
removal: Obtain a Removal reaction trigger.
resource_mutation: Obtain a ResourceMutation reaction trigger.
spawn_rc_system: Spawn a ref-counted system.
spawn_rc_system_from: Spawn a ref-counted system.
spawn_system: Spawn a system as an entity.
spawn_system_from: Spawn a system as an entity.
spawned_syscall: Execute a pre-spawned system on some data then apply the system’s deferred commands.
syscall: Execute a system on some data then apply the system’s deferred commands.
try_add_component_to_entity: Try to add a component to an entity.
try_callback: Try to invoke the callback C on entity.
try_callback_with: Try to invoke the callback C on entity with value.
try_remove_component_from_entity: Try to remove a component from an entity.
try_set_component: Try to set the value of a component on an entity.
try_update_component_if_different: Try to update the value of a component on an entity.

Derive Macros§

ReactComponent
ReactResource
Style
StyleBundle

Crate bevy_kot_ecsCopy item path