bevy-sequential-actions 0.15.0

#![warn(missing_docs, rustdoc::all)]

/*!
<div align="center">

# Bevy Sequential Actions

[![crates.io](https://img.shields.io/crates/v/bevy-sequential-actions?style=flat-square)](https://crates.io/crates/bevy-sequential-actions)
[![github.com](https://img.shields.io/github/stars/hikikones/bevy-sequential-actions?logo=github&style=flat-square)](https://github.com/hikikones/bevy-sequential-actions)
[![MIT/Apache 2.0](https://img.shields.io/crates/l/bevy-sequential-actions?style=flat-square)](https://github.com/hikikones/bevy-sequential-actions#license)

A simple library for managing and sequencing various actions in [Bevy](https://bevyengine.org).

<figure>
    <img src="https://github.com/user-attachments/assets/66b5b15e-96af-47bd-9371-eee8809d1294"/>
    <p><em>An entity with a queue of repeating actions</em></p>
</figure>

</div>

## 📜 Getting Started

#### Plugin

The quickest way for getting started is adding the [`SequentialActionsPlugin`] to your [`App`].

```rust,no_run
# use bevy_ecs::prelude::*;
# use bevy_app::prelude::*;
use bevy_sequential_actions::*;
#
# struct DefaultPlugins;
# impl Plugin for DefaultPlugins { fn build(&self, _app: &mut App) {} }

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, SequentialActionsPlugin))
        .run();
}
```

#### Implementing an Action

An action is anything that implements the [`Action`] trait.
The trait contains various methods that together defines the _lifecycle_ of an action.
From this, you can create any action that can last as long as you like,
and do as much as you like.

An entity with actions is referred to as an `agent`.

A simple wait action follows.

```rust,no_run
# use bevy_ecs::prelude::*;
# use bevy_sequential_actions::*;
#
# struct Time;
# impl Resource for Time {}
# impl Time { fn delta_seconds(&self) -> f32 { 0.0 } }
#
pub struct WaitAction {
    duration: f32, // Seconds
    remaining: Option<f32>, // None
}

impl Action for WaitAction {
    // By default, this method is called every frame in the Last schedule.
    fn is_finished(&self, agent: Entity, world: &World) -> bool {
        // Determine if wait timer has reached zero.
        world.get::<WaitTimer>(agent).unwrap().0 <= 0.0
    }

    // This method is called when an action is started.
    fn on_start(&mut self, agent: Entity, world: &mut World) -> bool {
        // Take remaining time (if paused), or use full duration.
        let duration = self.remaining.take().unwrap_or(self.duration);

        // Run the wait timer system on the agent.
        world.entity_mut(agent).insert(WaitTimer(duration));

        // Is action already finished?
        // Returning true here will immediately advance the action queue.
        self.is_finished(agent, world)
    }

    // This method is called when an action is stopped.
    fn on_stop(&mut self, agent: Option<Entity>, world: &mut World, reason: StopReason) {
        // Do nothing if agent has been despawned.
        let Some(agent) = agent else { return };

        // Take the wait timer component from the agent.
        let wait_timer = world.entity_mut(agent).take::<WaitTimer>();

        // Store remaining time when paused.
        if reason == StopReason::Paused {
            self.remaining = Some(wait_timer.unwrap().0);
        }
    }

    // Optional. This method is called when an action is added to the queue.
    fn on_add(&mut self, agent: Entity, world: &mut World) {}

    // Optional. This method is called when an action is removed from the queue.
    fn on_remove(&mut self, agent: Option<Entity>, world: &mut World) {}

    // Optional. The last method that is called with full ownership.
    fn on_drop(self: Box<Self>, agent: Option<Entity>, world: &mut World, reason: DropReason) {}
}

#[derive(Component)]
struct WaitTimer(f32);

fn wait_system(mut wait_timer_q: Query<&mut WaitTimer>, time: Res<Time>) {
    for mut wait_timer in &mut wait_timer_q {
        wait_timer.0 -= time.delta_seconds();
    }
}
```

#### Managing Actions

Actions can be added to any [`Entity`] with the [`SequentialActions`] marker component.
Adding and managing actions is done through the [`actions(agent)`](ActionsProxy::actions)
extension method implemented for both [`Commands`] and [`World`].
See the [`ManageActions`] trait for available methods.

```rust,no_run
# use bevy_app::AppExit;
# use bevy_ecs::prelude::*;
# use bevy_sequential_actions::*;
#
# struct EmptyAction;
# impl Action for EmptyAction {
#   fn is_finished(&self, _a: Entity, _w: &World) -> bool { true }
#   fn on_start(&mut self, _a: Entity, _w: &mut World) -> bool { true }
#   fn on_stop(&mut self, _a: Option<Entity>, _w: &mut World, _r: StopReason) {}
# }
#
fn setup(mut commands: Commands) {
#   let action_a = EmptyAction;
#   let action_b = EmptyAction;
#   let action_c = EmptyAction;
#   let action_d = EmptyAction;
#   let action_e = EmptyAction;
#   let action_f = EmptyAction;
#
    // Spawn entity with the marker component
    let agent = commands.spawn(SequentialActions).id();
    commands
        .actions(agent)
        // Add a single action
        .add(action_a)
        // Add more actions with a tuple
        .add((action_b, action_c))
        // Add a collection of actions
        .add(actions![action_d, action_e, action_f])
        // Add an anonymous action with a closure
        .add(|_agent, world: &mut World| -> bool {
            // on_start
            world.write_message(AppExit::Success);
            true
        });
}
```

#### ⚠️ Warning

Since you are given a mutable [`World`], you can in practice do _anything_.
Depending on what you do, the logic for advancing the action queue might not work properly.
There are a few things you should keep in mind:

* If you want to despawn an `agent` as an action, this should be done in [`on_start`](`Action::on_start`).
* The [`execute`](`ManageActions::execute`) and [`next`](`ManageActions::next`) methods should not be used,
  as that will immediately advance the action queue while inside any of the trait methods.
  Instead, you should return `true` in [`on_start`](`Action::on_start`).
* When adding new actions, you should set the [`start`](`ManageActions::start`) property to `false`.
  Otherwise, you will effectively call [`execute`](`ManageActions::execute`) which, again, should not be used.
  At worst, you will cause a **stack overflow** if the action adds itself.

    ```rust,no_run
    # use bevy_ecs::prelude::*;
    # use bevy_sequential_actions::*;
    # struct EmptyAction;
    # impl Action for EmptyAction {
    #   fn is_finished(&self, _a: Entity, _w: &World) -> bool { true }
    #   fn on_start(&mut self, _a: Entity, _w: &mut World) -> bool { true }
    #   fn on_stop(&mut self, _a: Option<Entity>, _w: &mut World, _r: StopReason) {}
    # }
    # struct TestAction;
    # impl Action for TestAction {
    #   fn is_finished(&self, _a: Entity, _w: &World) -> bool { true }
        fn on_start(&mut self, agent: Entity, world: &mut World) -> bool {
    #       let action_a = EmptyAction;
    #       let action_b = EmptyAction;
    #       let action_c = EmptyAction;
            world
                .actions(agent)
                .start(false) // Do not start next action
                .add((action_a, action_b, action_c));

            // Immediately advance the action queue
            true
        }
    #   fn on_stop(&mut self, _a: Option<Entity>, _w: &mut World, _r: StopReason) {}
    # }
    ```
*/

use std::{collections::VecDeque, fmt::Debug};

use bevy_app::prelude::*;
use bevy_derive::{Deref, DerefMut};
use bevy_ecs::{lifecycle::HookContext, prelude::*, query::QueryFilter, world::DeferredWorld};
use bevy_log::{debug, warn};

mod commands;
mod macros;
mod plugin;
mod traits;
mod world;

pub use commands::*;
pub use plugin::*;
pub use traits::*;
pub use world::*;

/// A boxed [`Action`].
pub type BoxedAction = Box<dyn Action>;

/// Marker component for entities with actions.
///
/// This component is all that is needed for spawning an agent that you can add actions to.
/// Required components will bring in the necessary components,
/// namely [CurrentAction] and [ActionQueue].
///
/// If you do not care for the marker,
/// or perhaps don't want to use required components,
/// there is still the [ActionsBundle] for spawning an agent as before.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Component)]
#[require(CurrentAction, ActionQueue)]
pub struct SequentialActions;

/// The component bundle that all entities with actions must have.
#[derive(Default, Bundle)]
pub struct ActionsBundle {
    current: CurrentAction,
    queue: ActionQueue,
}

impl ActionsBundle {
    /// Creates a new [`Bundle`] that contains the necessary components
    /// that all entities with actions must have.
    pub const fn new() -> Self {
        Self {
            current: CurrentAction(None),
            queue: ActionQueue(VecDeque::new()),
        }
    }

    /// Creates a new [`Bundle`] with specified `capacity` for the action queue.
    pub fn with_capacity(capacity: usize) -> Self {
        Self {
            current: CurrentAction(None),
            queue: ActionQueue(VecDeque::with_capacity(capacity)),
        }
    }
}

/// The current action for an `agent`.
#[derive(Debug, Default, Component, Deref, DerefMut)]
pub struct CurrentAction(Option<BoxedAction>);

impl CurrentAction {
    /// The [`on_remove`](bevy_ecs::lifecycle::ComponentHooks::on_remove) component lifecycle hook
    /// used by [`SequentialActionsPlugin`] for cleaning up the current action when an `agent` is despawned.
    pub fn on_remove_hook(mut world: DeferredWorld, ctx: HookContext) {
        let agent = ctx.entity;
        let mut current_action = world.get_mut::<Self>(agent).unwrap();
        if let Some(mut action) = current_action.take() {
            world.commands().queue(move |world: &mut World| {
                action.on_stop(None, world, StopReason::Canceled);
                action.on_remove(None, world);
                action.on_drop(None, world, DropReason::Done);
            });
        }
    }

    /// [`Observer`] for cleaning up the current action when an `agent` is despawned.
    pub fn on_remove_trigger<F: QueryFilter>(
        remove: On<Remove, Self>,
        mut query: Query<&mut Self, F>,
        mut commands: Commands,
    ) {
        let agent = remove.entity;
        if let Ok(mut current_action) = query.get_mut(agent)
            && let Some(mut action) = current_action.take()
        {
            commands.queue(move |world: &mut World| {
                action.on_stop(None, world, StopReason::Canceled);
                action.on_remove(None, world);
                action.on_drop(None, world, DropReason::Done);
            });
        }
    }
}

/// The action queue for an `agent`.
#[derive(Debug, Default, Component, Deref, DerefMut)]
pub struct ActionQueue(VecDeque<BoxedAction>);

impl ActionQueue {
    /// The [`on_remove`](bevy_ecs::lifecycle::ComponentHooks::on_remove) component lifecycle hook
    /// used by [`SequentialActionsPlugin`] for cleaning up the action queue when an `agent` is despawned.
    pub fn on_remove_hook(mut world: DeferredWorld, ctx: HookContext) {
        let agent = ctx.entity;
        let mut action_queue = world.get_mut::<Self>(agent).unwrap();
        if !action_queue.is_empty() {
            let actions = std::mem::take(&mut action_queue.0);
            world.commands().queue(move |world: &mut World| {
                for mut action in actions {
                    action.on_remove(None, world);
                    action.on_drop(None, world, DropReason::Cleared);
                }
            });
        }
    }

    /// [`Observer`] for cleaning up the action queue when an `agent` is despawned.
    pub fn on_remove_trigger<F: QueryFilter>(
        remove: On<Remove, Self>,
        mut query: Query<&mut Self, F>,
        mut commands: Commands,
    ) {
        let agent = remove.entity;
        if let Ok(mut action_queue) = query.get_mut(agent)
            && !action_queue.is_empty()
        {
            let actions = std::mem::take(&mut action_queue.0);
            commands.queue(move |world: &mut World| {
                for mut action in actions {
                    action.on_remove(None, world);
                    action.on_drop(None, world, DropReason::Cleared);
                }
            });
        }
    }
}

/// Configuration for actions to be added.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AddConfig {
    /// Start the next action in the queue if nothing is currently running.
    pub start: bool,
    /// The queue order for actions to be added.
    pub order: AddOrder,
}

impl AddConfig {
    /// Returns a new configuration for actions to be added.
    pub const fn new(start: bool, order: AddOrder) -> Self {
        Self { start, order }
    }
}

impl Default for AddConfig {
    fn default() -> Self {
        Self::new(true, AddOrder::Back)
    }
}

/// The queue order for actions to be added.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
pub enum AddOrder {
    /// An action is added to the back of the queue.
    #[default]
    Back,
    /// An action is added to the front of the queue.
    Front,
}

/// The reason why an [`Action`] was stopped.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StopReason {
    /// The action was finished.
    Finished,
    /// The action was canceled.
    Canceled,
    /// The action was paused.
    Paused,
}

/// The reason why an [`Action`] was dropped.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DropReason {
    /// The action is considered done as it was either finished or canceled
    /// without being skipped or cleared from the action queue.
    Done,
    /// The action was skipped. This happens either deliberately,
    /// or because an action was added to an `agent` that does not exist or is missing a component.
    Skipped,
    /// The action queue was cleared. This happens either deliberately,
    /// or because an `agent` was despawned.
    Cleared,
}