Struct SequentialActionsPlugin

pub struct SequentialActionsPlugin;

The Plugin for this library that you can add to your App.

This plugin adds the check_actions system to the Last schedule for action queue advancement, and also two hooks for cleaning up actions from despawned agents.

Finally, it also contains various static methods for modifying the action queue.

Implementations

impl SequentialActionsPlugin

pub fn check_actions<F: QueryFilter>( action_q: Query<'_, '_, (Entity, &CurrentAction), F>, world: &World, commands: Commands<'_, '_>, )

The System used by SequentialActionsPlugin. It is responsible for checking all agents for finished actions and advancing the action queue.

The query filter F is used for filtering agents. Use the unit type () for no filtering.

Example

App::new()
    .add_systems(Last, SequentialActionsPlugin::check_actions::<()>)
    .run();

pub fn add_action( agent: Entity, config: AddConfig, action: impl IntoBoxedAction, world: &mut World, )

Adds a single action to agent with specified config.

pub fn add_actions<I>( agent: Entity, config: AddConfig, actions: I, world: &mut World, )

where I: DoubleEndedIterator<Item = BoxedAction> + ExactSizeIterator + Debug,

Adds a collection of actions to agent with specified config. An empty collection does nothing.

pub fn execute_actions(agent: Entity, world: &mut World)

Starts the next action in the queue for agent, but only if there is no current action.

pub fn stop_current_action(agent: Entity, reason: StopReason, world: &mut World)

Stops the current action for agent with specified reason.

Examples found in repository

examples/custom.rs (line 162)

    fn check_actions_exclusive(
        world: &mut World,
        mut finished: Local<Vec<Entity>>,
        mut agent_q: Local<QueryState<(Entity, &CurrentAction), F>>,
    ) {
        // Collect all agents with finished action
        finished.extend(agent_q.iter(world).filter_map(|(agent, current_action)| {
            current_action
                .as_ref()
                .and_then(|action| action.is_finished(agent, world).then_some(agent))
        }));

        // Do something with the finished list if you want.
        // Perhaps sort by some identifier for deterministic behavior.

        // Advance the action queue
        for agent in finished.drain(..) {
            SequentialActionsPlugin::stop_current_action(agent, StopReason::Finished, world);
            SequentialActionsPlugin::start_next_action(agent, world);
        }
    }

pub fn start_next_action(agent: Entity, world: &mut World)

Starts the next action in the queue for agent.

This will loop until any next action is not immediately finished or the queue is empty. Since this may trigger an infinite loop, a counter is used in debug build that panics when reaching a sufficient target.

The loop will also break if agent already has a current action. This is likely a user error, and so a warning will be emitted.

Examples found in repository

examples/custom.rs (line 163)

    fn check_actions_exclusive(
        world: &mut World,
        mut finished: Local<Vec<Entity>>,
        mut agent_q: Local<QueryState<(Entity, &CurrentAction), F>>,
    ) {
        // Collect all agents with finished action
        finished.extend(agent_q.iter(world).filter_map(|(agent, current_action)| {
            current_action
                .as_ref()
                .and_then(|action| action.is_finished(agent, world).then_some(agent))
        }));

        // Do something with the finished list if you want.
        // Perhaps sort by some identifier for deterministic behavior.

        // Advance the action queue
        for agent in finished.drain(..) {
            SequentialActionsPlugin::stop_current_action(agent, StopReason::Finished, world);
            SequentialActionsPlugin::start_next_action(agent, world);
        }
    }

pub fn skip_actions(agent: Entity, n: usize, world: &mut World)

Skips the next n actions in the queue for agent.

pub fn clear_actions(agent: Entity, world: &mut World)

Clears the action queue for agent.

Current action is stopped as canceled.

Trait Implementations

impl Plugin for SequentialActionsPlugin

fn build(&self, app: &mut App)

Configures the App to which this plugin is added.

fn ready(&self, _app: &App) -> bool

Has the plugin finished its setup? This can be useful for plugins that need something asynchronous to happen before they can finish their setup, like the initialization of a renderer. Once the plugin is ready, finish should be called.

fn finish(&self, _app: &mut App)

Finish adding this plugin to the App, once all plugins registered are ready. This can be useful for plugins that depends on another plugin asynchronous setup, like the renderer.

fn cleanup(&self, _app: &mut App)

Runs after all plugins are built and finished, but before the app schedule is executed. This can be useful if you have some resource that other plugins need during their build step, but after build you want to remove it and send it to another thread.

fn name(&self) -> &str

Configures a name for the Plugin which is primarily used for checking plugin uniqueness and debugging.

fn is_unique(&self) -> bool

If the plugin can be meaningfully instantiated several times in an App, override this method to return false.