├── .gitignore
├── Cargo.toml
├── LICENSE
├── src
    ├── plugin.rs
    ├── events.rs
    ├── transition.rs
    ├── tests.rs
    └── lib.rs
├── .github
    └── workflows
    │   └── ci.yml
├── examples
    └── signal.rs
└── README.md


/.gitignore:
--------------------------------------------------------------------------------
1 | /target
2 | /Cargo.lock
3 | 


--------------------------------------------------------------------------------
/Cargo.toml:
--------------------------------------------------------------------------------
 1 | [package]
 2 | name = "moonshine-behavior"
 3 | version = "0.4.0"
 4 | edition = "2021"
 5 | license = "MIT"
 6 | description = "Minimalistic state machine for Bevy game engine."
 7 | homepage = "https://github.com/Zeenobit/moonshine_behavior"
 8 | repository = "https://github.com/Zeenobit/moonshine_behavior"
 9 | 
10 | [dependencies]
11 | bevy_app = "0.17"
12 | bevy_ecs = "0.17"
13 | bevy_reflect = "0.17"
14 | bevy_log = "0.17"
15 | bevy_derive = "0.17"
16 | moonshine-kind = { version = "0.4.1" }
17 | moonshine-util = { version = "0.4" }
18 | 
19 | [dev-dependencies]
20 | bevy = "0.17"
21 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2023 Zeenobit
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/src/plugin.rs:
--------------------------------------------------------------------------------
 1 | use std::marker::PhantomData;
 2 | 
 3 | use bevy_app::prelude::*;
 4 | use moonshine_util::reflect::Registerable;
 5 | 
 6 | use crate::{Behavior, Memory, Transition, TransitionQueue};
 7 | 
 8 | /// A [`Plugin`] for any [`Behavior`] type.
 9 | ///
10 | /// This plugin must be added to the [`App`] for behavior [`Transitions`](Transition) to work correctly.
11 | /// You must also add the [`transition`](crate::transition::transition) system separately somewhere in your schedule.
12 | ///
13 | /// # Example
14 | /// ```rust
15 | /// use bevy::prelude::*;
16 | /// use moonshine_behavior::prelude::*;
17 | ///
18 | /// #[derive(Component, Debug, Reflect)]
19 | /// #[reflect(Component)]
20 | /// struct B;
21 | ///
22 | /// impl Behavior for B {}
23 | ///
24 | /// App::new()
25 | ///     .add_plugins(BehaviorPlugin::<B>::default())
26 | ///     .add_systems(Update, transition::<B>);
27 | ///
28 | /// // ...
29 | /// ```
30 | pub struct BehaviorPlugin<T: Behavior>(PhantomData<T>);
31 | 
32 | impl<T: Behavior> Default for BehaviorPlugin<T> {
33 |     fn default() -> Self {
34 |         Self(PhantomData)
35 |     }
36 | }
37 | 
38 | impl<T: Behavior + Registerable> Plugin for BehaviorPlugin<T> {
39 |     fn build(&self, app: &mut App) {
40 |         app.register_type::<Transition<T>>()
41 |             .register_type::<Memory<T>>()
42 |             .register_type::<TransitionQueue<T>>()
43 |             .register_required_components::<T, Transition<T>>();
44 |     }
45 | }
46 | 


--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
 1 | name: CI
 2 | 
 3 | on:
 4 |   push:
 5 |   pull_request:
 6 |     branches: [ "main" ]
 7 | 
 8 | env:
 9 |   CARGO_TERM_COLOR: always
10 |   # Sparse cargo registry for faster updates
11 |   CARGO_REGISTRIES_CRATES_IO_PROTOCOL: sparse
12 |   RUSTFLAGS: "-D warnings"
13 |   RUSTDOCFLAGS: '--deny warnings'
14 | 
15 | jobs:
16 |   lint:
17 |     runs-on: ubuntu-latest
18 |     steps:
19 |       - uses: actions/checkout@v3
20 |         with:
21 |           submodules: 'true'
22 |       - uses: dtolnay/rust-toolchain@master
23 |         with:
24 |           toolchain: stable
25 |           components: clippy
26 |       - name: Populate target directory from cache
27 |         uses: Swatinem/rust-cache@v2  
28 |         with:
29 |           save-if: ${{ github.ref == 'refs/heads/main' }}  
30 |       - name: Install alsa and udev
31 |         run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev libwayland-dev
32 |       - name: Run cargo clippy
33 |         run: cargo clippy --tests --examples
34 | 
35 |   format:
36 |     runs-on: ubuntu-latest
37 |     env:
38 |       RUSTFLAGS: "-D warnings"
39 |     steps:
40 |       - uses: actions/checkout@v3
41 |         with:
42 |           submodules: 'true'
43 |       - uses: dtolnay/rust-toolchain@master
44 |         with:
45 |           toolchain: stable
46 |           components: rustfmt
47 |       - name: Run cargo fmt
48 |         run: cargo fmt --check --all
49 | 
50 |   doc:
51 |     runs-on: ubuntu-latest
52 |     env:
53 |       RUSTFLAGS: "-D warnings"
54 |       RUSTDOCFLAGS: '--deny warnings'
55 |     steps:
56 |       - uses: actions/checkout@v3
57 |         with:
58 |           submodules: 'true'
59 |       - uses: dtolnay/rust-toolchain@master
60 |         with:
61 |           toolchain: stable
62 |       - name: Populate target directory from cache
63 |         uses: Swatinem/rust-cache@v2  
64 |         with:
65 |           save-if: ${{ github.ref == 'refs/heads/main' }}  
66 |       - name: Install alsa and udev
67 |         run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev libwayland-dev
68 |       - name: Run cargo doc
69 |         run: cargo doc --no-deps --all-features
70 | 
71 |   test:
72 |     runs-on: ubuntu-latest
73 |     steps:
74 |       - uses: actions/checkout@v3
75 |         with:
76 |           submodules: 'true'
77 |       - uses: dtolnay/rust-toolchain@master
78 |         with:
79 |           toolchain: stable
80 |       - name: Populate target directory from cache
81 |         uses: Swatinem/rust-cache@v2  
82 |         with:
83 |           save-if: ${{ github.ref == 'refs/heads/main' }}  
84 |       - name: Install alsa and udev
85 |         run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev libwayland-dev
86 |       - name: Run cargo test
87 |         run: cargo test --all-features --features bevy/x11 
88 |       - name: Run doc tests
89 |         run: LD_LIBRARY_PATH="$(rustc --print target-libdir)" cargo test --doc --features bevy/x11
90 | 


--------------------------------------------------------------------------------
/examples/signal.rs:
--------------------------------------------------------------------------------
  1 | use std::time::Duration;
  2 | 
  3 | use bevy::prelude::*;
  4 | use moonshine_behavior::prelude::*;
  5 | 
  6 | fn main() {
  7 |     App::new()
  8 |         .add_plugins((DefaultPlugins, BehaviorPlugin::<Signal>::default()))
  9 |         .add_systems(Startup, (setup, spawn_lights))
 10 |         .add_systems(
 11 |             Update,
 12 |             (update_signal, transition::<Signal>, update_lights).chain(),
 13 |         )
 14 |         .add_observer(signal_start)
 15 |         .add_observer(signal_pause)
 16 |         .add_observer(signal_resume)
 17 |         .add_observer(signal_activate)
 18 |         .add_observer(signal_stop)
 19 |         .run();
 20 | }
 21 | 
 22 | #[derive(Component, Debug, Reflect)]
 23 | #[reflect(Component)]
 24 | enum Signal {
 25 |     Green,
 26 |     Yellow(Duration),
 27 |     Red,
 28 | }
 29 | 
 30 | impl Behavior for Signal {
 31 |     fn filter_next(&self, next: &Self) -> bool {
 32 |         use Signal::*;
 33 |         match_next! {
 34 |             self => next,
 35 |             Green => Yellow(..),
 36 |             Yellow(..) => Red,
 37 |         }
 38 |     }
 39 | }
 40 | 
 41 | const GREEN_COLOR: Color = Color::srgb(0.2, 1., 0.);
 42 | const YELLOW_COLOR: Color = Color::srgb(1., 0.8, 0.);
 43 | const RED_COLOR: Color = Color::srgb(1., 0.2, 0.);
 44 | const OFF_COLOR: Color = Color::srgb(0.1, 0.1, 0.1);
 45 | 
 46 | #[derive(Component)]
 47 | #[require(Transform, GlobalTransform)]
 48 | struct GreenLight;
 49 | 
 50 | #[derive(Component)]
 51 | #[require(Transform, GlobalTransform)]
 52 | struct YellowLight;
 53 | 
 54 | #[derive(Component)]
 55 | #[require(Transform, GlobalTransform)]
 56 | struct RedLight;
 57 | 
 58 | fn setup(mut configs: ResMut<GizmoConfigStore>, mut commands: Commands) {
 59 |     const HELP_TEXT: &str = "
 60 |     Press 'Space' to start/reset the Signal cycle!\n";
 61 | 
 62 |     commands.spawn(Camera2d);
 63 |     commands.spawn(Text::new(HELP_TEXT));
 64 |     commands.spawn(Signal::Green);
 65 | 
 66 |     let (config, ..) = configs.config_mut::<DefaultGizmoConfigGroup>();
 67 |     config.enabled = true;
 68 |     config.line.width = 3.;
 69 | }
 70 | 
 71 | fn spawn_lights(mut commands: Commands) {
 72 |     commands.spawn((Transform::from_xyz(-50., 0., 0.), GreenLight));
 73 |     commands.spawn((Transform::from_xyz(0., 0., 0.), YellowLight));
 74 |     commands.spawn((Transform::from_xyz(50., 0., 0.), RedLight));
 75 | }
 76 | 
 77 | fn update_signal(
 78 |     time: Res<Time>,
 79 |     key: Res<ButtonInput<KeyCode>>,
 80 |     mut signal: Single<BehaviorMut<Signal>>,
 81 | ) {
 82 |     use Signal::*;
 83 | 
 84 |     match signal.current() {
 85 |         Green => {
 86 |             if key.just_pressed(KeyCode::Space) {
 87 |                 signal.start(Yellow(Duration::from_secs(3)));
 88 |             }
 89 |         }
 90 |         Yellow(mut duration) => {
 91 |             duration = duration.saturating_sub(time.delta());
 92 |             **signal = Yellow(duration);
 93 |             if duration.is_zero() {
 94 |                 signal.start(Red);
 95 |             }
 96 |         }
 97 |         Red => {
 98 |             if key.just_pressed(KeyCode::Space) {
 99 |                 signal.reset();
100 |             }
101 |         }
102 |     }
103 | }
104 | 
105 | fn update_lights(
106 |     mut gizmos: Gizmos,
107 |     query: Query<BehaviorRef<Signal>>,
108 |     green: Single<Entity, With<GreenLight>>,
109 |     yellow: Single<Entity, With<YellowLight>>,
110 |     red: Single<Entity, With<RedLight>>,
111 |     transform: Query<&GlobalTransform>,
112 | ) {
113 |     use Signal::*;
114 | 
115 |     let mut draw_circle = |entity: Entity, color: Color| {
116 |         let transform = transform.get(entity).unwrap();
117 |         gizmos.circle(transform.translation(), 20., color);
118 |     };
119 | 
120 |     for behavior in query.iter() {
121 |         // Rules for each light:
122 |         // - Stay on if it's the current signal
123 |         // - Dim if passed
124 |         // - Turn off otherwise
125 | 
126 |         if matches!(*behavior, Green) {
127 |             draw_circle(*green, GREEN_COLOR);
128 |         } else if behavior.iter().any(|b| matches!(b, Green)) {
129 |             draw_circle(*green, GREEN_COLOR.darker(0.6));
130 |         } else {
131 |             draw_circle(*green, OFF_COLOR);
132 |         }
133 | 
134 |         if matches!(*behavior, Yellow(..)) {
135 |             draw_circle(*yellow, YELLOW_COLOR);
136 |         } else if behavior.iter().any(|b| matches!(b, Yellow(..))) {
137 |             draw_circle(*yellow, YELLOW_COLOR.darker(0.6));
138 |         } else {
139 |             draw_circle(*yellow, OFF_COLOR);
140 |         }
141 | 
142 |         if matches!(*behavior, Red) {
143 |             draw_circle(*red, RED_COLOR);
144 |         } else if behavior.iter().any(|b| matches!(b, Red)) {
145 |             draw_circle(*red, RED_COLOR.darker(0.6));
146 |         } else {
147 |             draw_circle(*red, OFF_COLOR);
148 |         }
149 |     }
150 | }
151 | 
152 | fn signal_start(event: OnStart<Signal>, query: Query<BehaviorRef<Signal>>) {
153 |     let entity = event.instance.entity();
154 |     let Ok(behavior) = query.get(entity) else {
155 |         return;
156 |     };
157 | 
158 |     info!("{} Started: {:?}", event.instance, &behavior[event.index]);
159 | }
160 | 
161 | fn signal_pause(event: OnPause<Signal>, query: Query<BehaviorRef<Signal>>) {
162 |     let entity = event.instance.entity();
163 |     let Ok(behavior) = query.get(entity) else {
164 |         return;
165 |     };
166 | 
167 |     info!("{} Paused: {:?}", event.instance, &behavior[event.index]);
168 | }
169 | 
170 | fn signal_resume(event: OnResume<Signal>, query: Query<BehaviorRef<Signal>>) {
171 |     let entity = event.instance.entity();
172 |     let Ok(behavior) = query.get(entity) else {
173 |         return;
174 |     };
175 | 
176 |     info!("{} Resumed: {:?}", event.instance, &behavior[event.index]);
177 | }
178 | 
179 | fn signal_activate(event: OnActivate<Signal>, query: Query<BehaviorRef<Signal>>) {
180 |     let entity = event.instance.entity();
181 |     let Ok(behavior) = query.get(entity) else {
182 |         return;
183 |     };
184 | 
185 |     info!(
186 |         "{} Activated (Resume = {}): {:?}",
187 |         event.instance, event.resume, &behavior[event.index]
188 |     );
189 | }
190 | 
191 | fn signal_stop(event: OnStop<Signal>) {
192 |     info!("{} Stopped: {:?}", event.instance, event.behavior);
193 | }
194 | 


--------------------------------------------------------------------------------
/src/events.rs:
--------------------------------------------------------------------------------
  1 | //! Each [`Behavior`] [`Transition`](crate::transition::Transition) triggers an [`Event`].
  2 | //!
  3 | //! You may use these events to react to transitions and define the behavior logic.
  4 | //!
  5 | //! ## Behavior Indices
  6 | //!
  7 | //! Most events contain a [`BehaviorIndex`] which may be used to identify the exact state associated with the event.
  8 | //! You may use [`Index`](std::ops::Index) operator to access the associated state.
  9 | //!
 10 | //! ## Initialization
 11 | //!
 12 | //! On spawn, several [`Behavior`] states may be activated at the same time. This can happen if the entity is reloaded from
 13 | //! disk or synchronized from the network, for example.
 14 | //!
 15 | //! For technical reasons, you may need to perform different logic in such cases.
 16 | //!
 17 | //! For example, considering the following scenario:
 18 | //! Let's imagine we're trying to model a car. When the car starts, we want to play an engine start audio clip.
 19 | //! However, if the car has been turned on, and is now being loaded from disk, we should skip the engine start audio clip.
 20 | //! You may use the `.initial` flag on the behavior events to branch your logic.
 21 | //!
 22 | //! # Example
 23 | //! ```rust
 24 | //! use bevy::prelude::*;
 25 | //! use moonshine_behavior::prelude::*;
 26 | //!
 27 | //! #[derive(Component, Debug, Reflect)]
 28 | //! #[reflect(Component)]
 29 | //! struct B;
 30 | //!
 31 | //! impl Behavior for B {}
 32 | //!
 33 | //! fn on_start(event: OnStart<B>, query: Query<BehaviorRef<B>>) {
 34 | //!     let behavior = query.get(*event.instance).unwrap();
 35 | //!     let state = &behavior[event.index];
 36 | //!
 37 | //!     if event.initial {
 38 | //!         /* Custom initialization logic */
 39 | //!     }
 40 | //!
 41 | //!     /* ... */
 42 | //! }
 43 | //!
 44 | //! fn on_pause(event: OnPause<B>, query: Query<BehaviorRef<B>>) {
 45 | //!     let behavior = query.get(*event.instance).unwrap();
 46 | //!     let state = &behavior[event.index];
 47 | //!     /* ... */
 48 | //! }
 49 | //!
 50 | //! fn on_resume(event: OnResume<B>, query: Query<BehaviorRef<B>>) {
 51 | //!     let behavior = query.get(*event.instance).unwrap();
 52 | //!     let state = &behavior[event.index];
 53 | //!     /* ... */
 54 | //! }
 55 | //!
 56 | //! fn on_activate(event: OnActivate<B>, query: Query<BehaviorRef<B>>) {
 57 | //!     let behavior = query.get(*event.instance).unwrap();
 58 | //!     let state = &behavior[event.index];
 59 | //!     /* ... */
 60 | //! }
 61 | //!
 62 | //! fn on_stop(event: OnStop<B>) {
 63 | //!     let state = &event.behavior;
 64 | //!     /* ... */
 65 | //! }
 66 | //! ```
 67 | //!
 68 | //! ##
 69 | 
 70 | use bevy_ecs::event::EntityTrigger;
 71 | use bevy_ecs::prelude::*;
 72 | use moonshine_kind::{impl_entity_event_from_instance, prelude::*};
 73 | 
 74 | use crate::transition::TransitionError;
 75 | use crate::{Behavior, BehaviorIndex};
 76 | 
 77 | /// An event which is triggered when a [`Behavior`] starts.
 78 | ///
 79 | /// See [`OnStart`] for a more ergonomic type alias for use in systems.
 80 | #[derive(Event)]
 81 | #[event(trigger = EntityTrigger)]
 82 | pub struct Start<T: Behavior> {
 83 |     /// Target of this [`EntityEvent`].
 84 |     pub instance: Instance<T>,
 85 |     /// The index of the behavior that was started.
 86 |     pub index: BehaviorIndex,
 87 |     /// If true, it implies the behavior is initializing. See [module documention](self) for details.
 88 |     pub initial: bool,
 89 | }
 90 | 
 91 | impl_entity_event_from_instance!(Start<T> where T: Behavior);
 92 | 
 93 | /// An event which is triggered when a [`Behavior`] is paused.
 94 | ///
 95 | /// See [`OnPause`] for a more ergonomic type alias for use in systems.
 96 | #[derive(Event)]
 97 | #[event(trigger = EntityTrigger)]
 98 | pub struct Pause<T: Behavior> {
 99 |     /// Target of this [`EntityEvent`].
100 |     pub instance: Instance<T>,
101 |     /// The index of the behavior that was paused.
102 |     pub index: BehaviorIndex,
103 | }
104 | 
105 | impl_entity_event_from_instance!(Pause<T> where T: Behavior);
106 | 
107 | /// An event which is triggered when a [`Behavior`] is resumed.
108 | ///
109 | /// See [`OnResume`] for a more ergonomic type alias for use in systems.
110 | #[derive(Event)]
111 | #[event(trigger = EntityTrigger)]
112 | pub struct Resume<T: Behavior> {
113 |     /// Target of this [`EntityEvent`].
114 |     pub instance: Instance<T>,
115 |     /// The index of the behavior that was resumed.
116 |     pub index: BehaviorIndex,
117 | }
118 | 
119 | impl_entity_event_from_instance!(Resume<T> where T: Behavior);
120 | 
121 | /// An event which is triggered when a [`Behavior`] is started OR resumed.
122 | ///
123 | /// See [`OnActivate`] for a more ergonomic type alias for use in systems.
124 | #[derive(Event)]
125 | #[event(trigger = EntityTrigger)]
126 | pub struct Activate<T: Behavior> {
127 |     /// Target of this [`EntityEvent`].
128 |     pub instance: Instance<T>,
129 |     /// The index of the behavior that was activated.
130 |     pub index: BehaviorIndex,
131 |     /// Whether the behavior was resumed or started.
132 |     pub resume: bool,
133 |     /// If true, it implies the behavior is initializing. See [module documention](self) for details.
134 |     pub initial: bool,
135 | }
136 | 
137 | impl_entity_event_from_instance!(Activate<T> where T: Behavior);
138 | 
139 | // TODO: OnSuspend, This gets tricky because the behavior state is already gone in `OnStop` ...
140 | 
141 | /// An event which is triggered when a [`Behavior`] is stopped.
142 | ///
143 | /// Unlike other events, this one does not provide a behavior index.
144 | ///
145 | /// See [`OnStop`] for a more ergonomic type alias for use in systems.
146 | #[derive(Event)]
147 | #[event(trigger = EntityTrigger)]
148 | pub struct Stop<T: Behavior> {
149 |     /// Target of this [`EntityEvent`].
150 |     pub instance: Instance<T>,
151 |     /// The index of the behavior that was stopped.
152 |     pub index: BehaviorIndex,
153 |     /// The behavior that was stopped.
154 |     pub behavior: T,
155 |     /// If true, it indicates the behavior was stopped because it was interrupted.
156 |     pub interrupt: bool,
157 | }
158 | 
159 | impl_entity_event_from_instance!(Stop<T> where T: Behavior);
160 | 
161 | /// An event which is triggered when a [`TransitionError`] occurs.
162 | ///
163 | /// See [`OnError`] for a more ergonomic type alias for use in systems.
164 | #[derive(Event)]
165 | #[event(trigger = EntityTrigger)]
166 | pub struct Error<T: Behavior> {
167 |     /// Target of this [`EntityEvent`].
168 |     pub instance: Instance<T>,
169 |     /// The associated [`TransitionError`].
170 |     pub error: TransitionError<T>,
171 | }
172 | 
173 | impl_entity_event_from_instance!(Error<T> where T: Behavior);
174 | 
175 | /// Alias for [`On<Start<T>>`](`Start`)
176 | pub type OnStart<'w, 't, T> = On<'w, 't, Start<T>>;
177 | 
178 | /// Alias for [`On<Pause<T>>`](`Pause`)
179 | pub type OnPause<'w, 't, T> = On<'w, 't, Pause<T>>;
180 | 
181 | /// Alias for [`On<Resume<T>>`](`Resume`)
182 | pub type OnResume<'w, 't, T> = On<'w, 't, Resume<T>>;
183 | 
184 | /// Alias for [`On<Activate<T>>`](`Activate`)
185 | pub type OnActivate<'w, 't, T> = On<'w, 't, Activate<T>>;
186 | 
187 | /// Alias for [`On<Stop<T>>`](`Stop`)
188 | pub type OnStop<'w, 't, T> = On<'w, 't, Stop<T>>;
189 | 
190 | /// Alias for [`On<Error<T>>`](`Error`)
191 | pub type OnError<'w, 't, T> = On<'w, 't, Error<T>>;
192 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # 🎚️ Moonshine Behavior
  2 | 
  3 | [![crates.io](https://img.shields.io/crates/v/moonshine-behavior)](https://crates.io/crates/moonshine-behavior)
  4 | [![downloads](https://img.shields.io/crates/dr/moonshine-behavior?label=downloads)](https://crates.io/crates/moonshine-behavior)
  5 | [![docs.rs](https://docs.rs/moonshine-behavior/badge.svg)](https://docs.rs/moonshine-behavior)
  6 | [![license](https://img.shields.io/crates/l/moonshine-behavior)](https://github.com/Zeenobit/moonshine_behavior/blob/main/LICENSE)
  7 | [![stars](https://img.shields.io/github/stars/Zeenobit/moonshine_behavior)](https://github.com/Zeenobit/moonshine_behavior)
  8 | 
  9 | Minimalistic state machine for [Bevy](https://github.com/bevyengine/bevy) entities.
 10 | 
 11 | ## Overview
 12 | 
 13 | This crates is designed to provide a simple, stack-based implementation of state machines for Bevy entities.
 14 | 
 15 | ### Features
 16 | 
 17 | - Simple: Minimal overhead for defining and setting up behaviors.
 18 | - Behaviors can be started, paused, resumed, and stopped.
 19 | - Event driven API which allows systems to react to behavior state change per entity.
 20 | - Multiple behaviors with different types may exist on the same entity to define complex state machines.
 21 | 
 22 | ## Usage
 23 | 
 24 | A behavior, typically implemented as an `enum`, is a [`Component`] which represents some state of its entity. Each behavior is associated with a **Stack**.
 25 | 
 26 | When a new behavior starts, the current state is removed from the entity and pushed onto the stack (if resumable) and paused.
 27 | 
 28 | When a behavior stops, the previous state is removed from the stack and inserted back into the entity.
 29 | 
 30 | ### Setup
 31 | 
 32 | #### 1. Define your behavior data as a [`Component`](https://docs.rs/bevy/latest/bevy/ecs/component/trait.Component.html)
 33 | 
 34 | Behaviors are often implemented as an `enum` since they are ideal for representing finite state machines. However, this is not a strict requirement. Any `struct` may also be used to represent behavior states.
 35 | 
 36 | ```rust
 37 | use bevy::prelude::*;
 38 | 
 39 | #[derive(Component, Debug, Reflect)]
 40 | #[reflect(Component)]
 41 | enum Bird {
 42 |     /* ... */
 43 | }
 44 | ```
 45 | 
 46 | #### 2. Implement the [`Behavior`] trait:
 47 | 
 48 | ```rust
 49 | use bevy::prelude::*;
 50 | use moonshine_behavior::prelude::*;
 51 | 
 52 | #[derive(Component, Debug, Reflect)]
 53 | #[reflect(Component)]
 54 | enum Bird {
 55 |     Idle,
 56 |     Fly,
 57 |     Sleep,
 58 |     Chirp,
 59 | }
 60 | 
 61 | impl Behavior for Bird {
 62 |     fn filter_next(&self, next: &Self) -> bool {
 63 |         use Bird::*;
 64 |         match_next! {
 65 |             self => next,
 66 |             Idle => Sleep | Fly | Chirp,
 67 |             Fly => Chirp,
 68 |         }
 69 |     }
 70 | }
 71 | ```
 72 | 
 73 | This trait defines the possible transitions for your behavior.
 74 | 
 75 | In this example:
 76 |   - a bird may sleep, fly, or chirp when idle
 77 |   - a bird may chirp when flying
 78 |   - a bird may not do anything else when sleeping or chirping
 79 | 
 80 | This trait has additional methods for more advanced usage. See [`Behavior`] trait documentation for full details.
 81 | 
 82 | #### 3. Register the `Behavior` and its transition:
 83 | Add a [`BehaviorPlugin`] and the [`transition`] system to your [`App`] to trigger behavior transitions whenever you want.
 84 | ```rust
 85 | use bevy::prelude::*;
 86 | use moonshine_behavior::prelude::*;
 87 | 
 88 | #[derive(Component, Debug, Reflect)]
 89 | #[reflect(Component)]
 90 | enum Bird {
 91 |     /* ... */
 92 | }
 93 | 
 94 | impl Behavior for Bird {
 95 |     /* ... */
 96 | }
 97 | 
 98 | let mut app = App::new();
 99 | app.add_plugins(BehaviorPlugin::<Bird>::default())
100 |     .add_systems(Update, transition::<Bird>);
101 | ```
102 | 
103 | You may define your systems before or after the `transition` system.
104 | 
105 | Usually, systems that cause behavior change should run before transition while systems that handle behavior logic should run after transition. However, this is not a strict requirement. Just be mindful of frame delays!
106 |   
107 | #### 4. Spawn
108 | 
109 | The first instance of `T` which is inserted into the entity is defined as the **Initial Behavior**:
110 | ```rust,ignore
111 | fn spawn_bird(mut commands: Commands) {
112 |     commands.spawn(Bird::Idle); // <--- Bird starts in Idle state
113 | }
114 | ```
115 | 
116 | You may also spawn a bird with a [`Transition`]:
117 | ```rust,ignore
118 | fn spawn_bird(mut commands: Commands) {
119 |     commands.spawn((Bird::Idle, Next(Bird::Chirp))); // <--- Bird starts in Idle state and then Chirps!
120 | }
121 | ```
122 | 
123 | Or maybe even a [`TransitionSequence`]:
124 | 
125 | ```rust,ignore
126 | fn spawn_bird(mut commands: Commands) {
127 |     commands.spawn((
128 |         Bird::Idle,
129 |         TransitionSequence::wait_for(Bird::Chirp).then(Bird::Fly)
130 |     ));
131 | }
132 | ```
133 | 
134 | #### 5. Query
135 | 
136 | To manage the behavior of an entity, you may use the [`BehaviorRef<T>`] and [`BehaviorMut<T>`] [`Query`] terms:
137 | 
138 | ```rust,ignore
139 | fn update_bird(mut query: Query<BehaviorMut<Bird>>) {
140 |     for mut behavior in query.iter_mut() {
141 |         match behavior.current() {
142 |             Bird::Idle => {
143 |                 // Do something when the bird is idle
144 |             }
145 |             Bird::Chirp => {
146 |                 // TODO: Play Chirp sound!
147 |                 behavior.stop(); // <-- Go back to the previous state
148 |             }
149 |             _ => { /* ... */ }
150 |         }
151 |     }
152 | }
153 | ```
154 | 
155 | `BehaviorRef<T>` is a read-only reference to the current behavior and the entire stack.
156 | 
157 | `BehaviorMut<T>` extends `BehaviorRef<T>` and allows you to modify the behavior as well.
158 | 
159 | Note that you may also access your behavior as `&T` or `&mut T` directly (it is just a component after all!).
160 | 
161 | `Transition<T>` is also directly accessible as a component, however it is more ergonomic to use `BehaviorMut<T>` for transitions.
162 | 
163 | ### Transitions
164 | 
165 | When a transition is requested, it is not invoked immediately. Instead, it is invoked whenever the registered [`transition`] system is run.
166 | You may register your systems before or after `transition::<T>` to perform any logic as required.
167 | 
168 | > ⚠️ **WARNING**<br/>
169 | > In most cases, only one transition is allowed per entity, per cycle.
170 | >
171 | > This is by design to allow each state to get at least one active frame.
172 | >
173 | > The exception to this is during an interruption or a reset, where multiple behaviors may be stopped at once.
174 | 
175 | To invoke a transition, you may use the [`BehaviorMut<T>`]. There are several methods for invoking transitions:
176 | 
177 | - [`start`] Pauses the current behavior and starts a new one.
178 | - [`interrupt_start`] Stops all behaviors which [yield][`filter_yield`] to the new behavior, and then starts the new behavior.
179 | - [`interrupt_resume`] Stops all behaviors above a given index in the stack and resumes it.
180 | - [`interrupt_stop`] Stops all behaviors above and including given index in the stack, resuming the previous one.
181 | - [`stop`] Stops the current behavior and resumes the previous one.
182 | - [`reset`] Stops all behaviors and resets the entity to its initial state.
183 | 
184 | Regardless of the method used, all transition may fail if:
185 | - The new behavior does not allow the new behavior to start at the exact time of [`transition`]. See [`filter_next`].
186 | - The current behavior is the initial behavior and a stop is requested. The initial behavior may never be stopped.
187 | 
188 | To completely stop the behavior, including the initial, you must remove the entire behavior from the entity.
189 | To do this, use [`remove_with_require::<T>()`](https://docs.rs/bevy/latest/bevy/ecs/prelude/struct.EntityCommands.html#method.remove_with_requires) to remove the initial behavior and the entire behavior stack.
190 | 
191 | ### Events
192 | 
193 | When a transition is invoked, several behavior [`events`] are triggered.
194 | You may use the following triggers to react to these events:
195 | 
196 | - [`OnStart<T>`] - Triggered when a new behavior starts.
197 | - [`OnPause<T>`] - Triggered when a behavior is paused as the next one starts.
198 | - [`OnResume<T>`] - Triggered when a behavior is resumed as the previous one stops.
199 | - [`OnActivate<T>`] - Triggered when a behavior is activated (started OR resumed).
200 | - [`OnStop<T>`] - Triggered when a behavior stops.
201 | 
202 | See [`events`] documentation for more details.
203 | 
204 | ### Hooks
205 | 
206 | In addition to events, you may also use hooks to perform immediate actions during a [`transition`]. Hooks are methods on the [`Behavior`] trait which may optionally be implemented by you:
207 | 
208 | ```rust,ignore
209 | impl Behavior for Bird {
210 |     fn on_start(&self, _previous: Option<&Self>, mut commands: InstanceCommands<Self>) {
211 |         match self {
212 |             Bird::Chirp => {
213 |                 commands.insert(PlayAudio { /* ... */});
214 |             }
215 |             _ => { /* ... */ }
216 |         }
217 |     }
218 | }
219 | ```
220 | 
221 | These hook commands would be executed immediately after [`transition`] is invoked. They are mainly useful when trying to minimize frame delays between state changes.
222 | 
223 | ## Examples
224 | 
225 | See [signal.rs](examples/signal.rs) for a complete example.
226 | 
227 | ## Support
228 | 
229 | Please [post an issue](https://github.com/Zeenobit/moonshine_behavior/issues/new) for any bugs, questions, or suggestions.
230 | 
231 | You may also contact me on the official [Bevy Discord](https://discord.gg/bevy) server as **@Zeenobit**.
232 | 
233 | [`Entity`]:https://docs.rs/bevy/latest/bevy/ecs/entity/struct.Entity.html
234 | [`Component`]:https://docs.rs/bevy/latest/bevy/ecs/component/trait.Component.html
235 | [`App`]:https://docs.rs/bevy/latest/bevy/app/struct.App.html
236 | [`Query`]:https://docs.rs/bevy/latest/bevy/ecs/system/struct.Query.html
237 | [`Behavior`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/trait.Behavior.html
238 | [`BehaviorPlugin`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.BehaviorPlugin.html
239 | [`transition`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/fn.transition.html
240 | [`Transition`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.Transition.html
241 | [`TransitionSequence`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.TransitionSequence.html
242 | [`BehaviorEvent`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.BehaviorEvent.html
243 | [`events`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/events/index.html
244 | [`OnStart<T>`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/events/struct.Start.html
245 | [`OnStop<T>`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/events/struct.Stop.html
246 | [`OnPause<T>`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/events/struct.Reset.html
247 | [`OnResume<T>`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/events/struct.Resume.html
248 | [`OnActivate<T>`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/events/struct.Activate.html
249 | [`BehaviorRef<T>`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.BehaviorRef.html
250 | [`BehaviorMut<T>`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.BehaviorMut.html
251 | [`start`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.BehaviorMutItem.html#method.start
252 | [`interrupt_start`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.BehaviorMutItem.html#method.interrupt_start
253 | [`interrupt_resume`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.BehaviorMutItem.html#method.interrupt_resume
254 | [`interrupt_stop`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.BehaviorMutItem.html#method.interrupt_stop
255 | [`stop`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.BehaviorMutItem.html#method.stop
256 | [`reset`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/struct.BehaviorMutItem.html#method.reset
257 | [`filter_yield`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/trait.Behavior.html#method.filter_yield
258 | [`filter_next`]:https://docs.rs/moonshine-behavior/latest/moonshine_behavior/trait.Behavior.html#method.filter_next


--------------------------------------------------------------------------------
/src/transition.rs:
--------------------------------------------------------------------------------
  1 | //! A [`Behavior`] is controlled using [`Transition`].
  2 | //!
  3 | //! Transitions are processed by the [`transition`] system.
  4 | 
  5 | use std::collections::VecDeque;
  6 | use std::fmt::Debug;
  7 | 
  8 | use bevy_ecs::event::EntityTrigger;
  9 | use bevy_ecs::prelude::*;
 10 | use bevy_log::prelude::*;
 11 | use bevy_reflect::prelude::*;
 12 | use moonshine_kind::prelude::*;
 13 | use moonshine_util::prelude::*;
 14 | 
 15 | use crate::events::Start;
 16 | use crate::{
 17 |     Behavior, BehaviorHooks, BehaviorIndex, BehaviorItem, BehaviorMut, BehaviorMutItem, Memory,
 18 | };
 19 | 
 20 | pub use self::Transition::{Interrupt, Next, Previous};
 21 | 
 22 | /// A [`Component`] which controls transitions between [`Behavior`] states.
 23 | ///
 24 | /// This component is automatically registered as a required component for all types
 25 | /// which implement the [`Behavior`] trait and and have their [`BehaviorPlugin`](crate::plugin::BehaviorPlugin) added.
 26 | #[derive(Component, Clone, Debug, Reflect)]
 27 | #[require(Expect<T>, Memory<T>)]
 28 | #[reflect(Component)]
 29 | pub enum Transition<T: Behavior> {
 30 |     #[doc(hidden)]
 31 |     None,
 32 |     /// Starts the next behavior.
 33 |     Next(T),
 34 |     /// Starts an [`Interruption`].
 35 |     Interrupt(Interruption<T>),
 36 |     /// Stops the current behavior and resumes the previous one.
 37 |     Previous,
 38 | }
 39 | 
 40 | impl<T: Behavior> Transition<T> {
 41 |     /// Returns `true` if there are no pending transitions.
 42 |     pub fn is_none(&self) -> bool {
 43 |         matches!(self, Self::None)
 44 |     }
 45 | 
 46 |     fn take(&mut self) -> Self {
 47 |         std::mem::replace(self, Transition::None)
 48 |     }
 49 | }
 50 | 
 51 | impl<T: Behavior> Default for Transition<T> {
 52 |     fn default() -> Self {
 53 |         Self::None
 54 |     }
 55 | }
 56 | 
 57 | /// A system which processes [`Behavior`] [`Transitions`](Transition).
 58 | #[allow(clippy::type_complexity)]
 59 | pub fn transition<T: Behavior>(
 60 |     mut query: Query<
 61 |         (Instance<T>, BehaviorMut<T>, Option<&mut TransitionQueue<T>>),
 62 |         Or<(Changed<Transition<T>>, With<TransitionQueue<T>>)>,
 63 |     >,
 64 |     mut commands: Commands,
 65 | ) {
 66 |     for (instance, mut behavior, queue_opt) in &mut query {
 67 |         let entity = instance.entity();
 68 | 
 69 |         if behavior.is_added() {
 70 |             let mut stack: VecDeque<T> = behavior
 71 |                 .memory
 72 |                 .bypass_change_detection()
 73 |                 .drain(..)
 74 |                 .collect();
 75 | 
 76 |             if !stack.is_empty() {
 77 |                 let mut initial = stack.pop_front().unwrap();
 78 |                 let current = {
 79 |                     std::mem::swap(behavior.current.as_mut(), &mut initial);
 80 |                     initial
 81 |                 };
 82 | 
 83 |                 stack.push_back(current);
 84 |             }
 85 | 
 86 |             behavior.invoke_start(None, commands.instance(instance));
 87 |             commands.queue(move |world: &mut World| {
 88 |                 world.trigger_with(
 89 |                     Start {
 90 |                         instance,
 91 |                         index: BehaviorIndex::initial(),
 92 |                         initial: true,
 93 |                     },
 94 |                     EntityTrigger,
 95 |                 );
 96 |             });
 97 | 
 98 |             for state in stack {
 99 |                 let _ = behavior.push(instance, state, true, &mut commands);
100 |             }
101 |         }
102 | 
103 |         // Index of the stopped behavior, if applicable.
104 |         let mut stop_index = None;
105 | 
106 |         let mut interrupt_queue = false;
107 | 
108 |         match behavior.transition.take() {
109 |             Next(next) => {
110 |                 interrupt_queue = !behavior.push(instance, next, false, &mut commands);
111 |             }
112 |             Previous => {
113 |                 stop_index = Some(behavior.current_index());
114 |                 interrupt_queue = !behavior.pop(instance, &mut commands);
115 |             }
116 |             Interrupt(Interruption::Start(next)) => {
117 |                 behavior.interrupt(instance, next, &mut commands);
118 |                 interrupt_queue = true;
119 |             }
120 |             Interrupt(Interruption::Resume(index)) => {
121 |                 behavior.clear(instance, index, &mut commands);
122 |                 interrupt_queue = true;
123 |             }
124 |             _ => {}
125 |         }
126 | 
127 |         let Some(queue) = queue_opt else {
128 |             continue;
129 |         };
130 | 
131 |         if interrupt_queue {
132 |             debug!("{instance:?}: queue interrupted");
133 |             commands.entity(entity).remove::<TransitionQueue<T>>();
134 |         } else if queue.is_empty() {
135 |             debug!("{instance:?}: queue finished");
136 |             commands.entity(entity).remove::<TransitionQueue<T>>();
137 |         } else {
138 |             TransitionQueue::update(queue, instance, behavior, stop_index);
139 |         }
140 |     }
141 | }
142 | 
143 | /// A specific kind of [`Transition`] which may stop active behaviors before activating a new one.
144 | #[derive(Debug, Clone, Reflect)]
145 | pub enum Interruption<T: Behavior> {
146 |     /// An interruption which stops any behavior which [yields](Behavior::filter_yield)
147 |     /// to the given behavior, and then starts it.
148 |     Start(T),
149 |     /// An interruption which resumes a behavior at the given index by stopping all other behaviors above it in the stack.
150 |     Resume(BehaviorIndex),
151 | }
152 | 
153 | #[doc(hidden)]
154 | #[deprecated(since = "0.2.1", note = "use `Changed<Transition<T>>` instead")]
155 | pub type TransitionChanged<T> = Or<(Changed<Transition<T>>, With<TransitionQueue<T>>)>;
156 | 
157 | /// Represents an error during [`transition`].
158 | #[derive(Debug, PartialEq, Reflect)]
159 | pub enum TransitionError<T: Behavior> {
160 |     /// The given behavior was rejected by [`filter_next`](Behavior::filter_next).
161 |     RejectedNext(T),
162 |     /// Initial behavior may not be stopped.
163 |     NoPrevious,
164 | }
165 | 
166 | #[doc(hidden)]
167 | #[deprecated(since = "0.3.1", note = "use `TransitionQueue` instead")]
168 | pub type TransitionSequence<T> = TransitionQueue<T>;
169 | 
170 | /// A queue of transitions to be invoked automatically.
171 | #[derive(Component, Reflect)]
172 | #[reflect(Component)]
173 | #[require(Expect<Transition<T>>)]
174 | pub struct TransitionQueue<T: Behavior> {
175 |     queue: VecDeque<TransitionQueueItem<T>>,
176 |     wait_for: Option<BehaviorIndex>,
177 | }
178 | 
179 | impl<T: Behavior> TransitionQueue<T> {
180 |     /// Creates a new [`TransitionQueue`] which starts each given behavior in order.
181 |     ///
182 |     /// Unlike [`TransitionQueue::sequence`], a chain does not wait for the behaviors to stop
183 |     /// and starts the behaviors on top of each other. This is useful when you wish to load a set of
184 |     /// states onto the behavior stack (i.e. "Bird must Fly *and* Chirp").
185 |     ///
186 |     /// You must ensure that each transition in the chain is allowed (see [`Behavior::filter_next`]).
187 |     /// The sequence will stop if any transition fails.
188 |     pub fn chain(items: impl IntoIterator<Item = T>) -> Self {
189 |         Self {
190 |             queue: VecDeque::from_iter(items.into_iter().map(TransitionQueueItem::Start)),
191 |             wait_for: None,
192 |         }
193 |     }
194 | 
195 |     /// Creates a new [`TransitionQueue`] which starts each given behavior in order,
196 |     /// waiting for each one to stop before starting the next.
197 |     ///
198 |     /// Unlike [`TransitionQueue::chain`], a sequence waits for each behavior to stop before starting the next.
199 |     /// This is useful when you want to queue some actions after each other (e.g. "Bird must Chirp, *then* Fly").
200 |     ///
201 |     /// You must ensure each transition from the current behavior to all elements in
202 |     /// the sequence is allowed (see [`Behavior::filter_next`]).
203 |     /// The sequence will stop if any transition fails.
204 |     pub fn sequence(items: impl IntoIterator<Item = T>) -> Self {
205 |         Self {
206 |             queue: VecDeque::from_iter(items.into_iter().map(TransitionQueueItem::StartWait)),
207 |             wait_for: None,
208 |         }
209 |     }
210 | 
211 |     /// Creates an empty [`TransitionQueue`].
212 |     pub fn empty() -> Self {
213 |         Self {
214 |             queue: VecDeque::new(),
215 |             wait_for: None,
216 |         }
217 |     }
218 | 
219 |     /// Creates a new [`TransitionQueue`] which starts with the given [`Behavior`].
220 |     pub fn start(next: T) -> Self {
221 |         let mut sequence = Self::empty();
222 |         sequence.push(TransitionQueueItem::Start(next));
223 |         sequence
224 |     }
225 | 
226 |     /// Creates a new [`TransitionQueue`] which starts by stopping the current [`Behavior`].
227 |     pub fn stop() -> Self {
228 |         let mut sequence = Self::empty();
229 |         sequence.push(TransitionQueueItem::Stop);
230 |         sequence
231 |     }
232 | 
233 |     /// Creates a new [`TransitionQueue`] which starts with the given [`Behavior`] and waits for it to stop.
234 |     pub fn wait_for(next: T) -> Self {
235 |         Self::empty().then_wait_for(next)
236 |     }
237 | 
238 |     /// Returns `true` if the [`TransitionQueue`] is empty.
239 |     pub fn is_empty(&self) -> bool {
240 |         self.queue.is_empty()
241 |     }
242 | 
243 |     /// Returns the number of transitions in the [`TransitionQueue`].
244 |     pub fn len(&self) -> usize {
245 |         self.queue.len()
246 |     }
247 | 
248 |     /// Extends the [`TransitionQueue`] by starting the next [`Behavior`].
249 |     pub fn then(mut self, next: T) -> Self {
250 |         self.push(TransitionQueueItem::Start(next));
251 |         self
252 |     }
253 | 
254 |     /// Extends the [`TransitionQueue`] by starting the next [`Behavior`] if and only if `condition` is true.
255 |     ///
256 |     /// This is just a convenient shortcut useful when creating complex queues, for example:
257 |     /// ```
258 |     /// use bevy::prelude::*;
259 |     /// use moonshine_behavior::prelude::*;
260 |     ///
261 |     /// #[derive(Component, Debug)]
262 |     /// pub enum Foo {
263 |     ///     Bar,
264 |     ///     Baz,
265 |     /// }
266 |     ///
267 |     /// impl Behavior for Foo {}
268 |     ///
269 |     /// fn make_queue(baz: bool) -> TransitionQueue<Foo> {
270 |     ///     TransitionQueue::start(Foo::Bar).then_if(baz, Foo::Baz)
271 |     /// }
272 |     /// ```
273 |     pub fn then_if(self, condition: bool, next: T) -> Self {
274 |         if condition {
275 |             return self.then(next);
276 |         }
277 |         self
278 |     }
279 | 
280 |     /// Extends the [`TransitionQueue`] by starting the next [`Behavior`] and waiting for it to stop.
281 |     pub fn then_wait_for(mut self, next: T) -> Self {
282 |         self.push(TransitionQueueItem::StartWait(next));
283 |         self
284 |     }
285 | 
286 |     /// Extends the [`TransitionQueue`] by stopping the current [`Behavior`].
287 |     pub fn then_stop(mut self) -> Self {
288 |         self.push(TransitionQueueItem::Stop);
289 |         self
290 |     }
291 | 
292 |     fn push(&mut self, next: TransitionQueueItem<T>) {
293 |         self.queue.push_back(next);
294 |     }
295 | }
296 | 
297 | impl<T: Behavior> TransitionQueue<T> {
298 |     pub(crate) fn update(
299 |         mut this: Mut<Self>,
300 |         instance: Instance<T>,
301 |         mut behavior: BehaviorMutItem<T>,
302 |         stop_index: Option<BehaviorIndex>,
303 |     ) {
304 |         debug_assert!(!this.is_empty());
305 | 
306 |         if let Some(wait_index) = this.wait_for {
307 |             if let Some(stop_index) = stop_index {
308 |                 if wait_index != stop_index {
309 |                     return;
310 |                 }
311 |             } else {
312 |                 return;
313 |             }
314 |         }
315 | 
316 |         debug!("{instance:?}: queue length = {:?}", this.len());
317 | 
318 |         if let Some(element) = this.queue.pop_front() {
319 |             use TransitionQueueItem::*;
320 |             match element {
321 |                 Start(next) => {
322 |                     this.wait_for = None;
323 |                     behavior.start(next);
324 |                 }
325 |                 StartWait(next) => {
326 |                     this.wait_for = Some(behavior.current_index().next());
327 |                     behavior.start(next);
328 |                 }
329 |                 Stop => {
330 |                     this.wait_for = None;
331 |                     behavior.stop();
332 |                 }
333 |             }
334 |         }
335 |     }
336 | }
337 | 
338 | #[derive(Debug, Reflect)]
339 | enum TransitionQueueItem<T: Behavior> {
340 |     Start(T),
341 |     StartWait(T),
342 |     Stop,
343 | }
344 | 


--------------------------------------------------------------------------------
/src/tests.rs:
--------------------------------------------------------------------------------
  1 | #![allow(clippy::type_complexity)]
  2 | 
  3 | use bevy::{ecs::system::RunSystemOnce, prelude::*};
  4 | 
  5 | use crate::events::Error;
  6 | use crate::prelude::*;
  7 | 
  8 | use self::T::*;
  9 | 
 10 | #[derive(Component, Default, Clone, Copy, Debug, PartialEq, Eq, Reflect)]
 11 | enum T {
 12 |     #[default]
 13 |     A,
 14 |     B,
 15 |     C,
 16 |     D,
 17 | }
 18 | 
 19 | impl Behavior for T {
 20 |     fn filter_next(&self, next: &Self) -> bool {
 21 |         match_next! {
 22 |             self => next,
 23 |             A => B | D,
 24 |             B => C,
 25 |             C => D,
 26 |         }
 27 |     }
 28 | 
 29 |     fn filter_yield(&self, next: &Self) -> bool {
 30 |         match_next! {
 31 |             self => next,
 32 |             B => D,
 33 |         }
 34 |     }
 35 | 
 36 |     fn on_start(&self, _: Option<&Self>, mut commands: InstanceCommands<Self>) {
 37 |         match self {
 38 |             A => commands.insert(TA),
 39 |             B => commands.insert(TB),
 40 |             C => commands.insert(TC),
 41 |             D => commands.insert(TD),
 42 |         };
 43 |     }
 44 | 
 45 |     fn on_stop(&self, _: &Self, mut commands: InstanceCommands<Self>) {
 46 |         match self {
 47 |             A => commands.remove::<TA>(),
 48 |             B => commands.remove::<TB>(),
 49 |             C => commands.remove::<TC>(),
 50 |             D => commands.remove::<TD>(),
 51 |         };
 52 |     }
 53 | }
 54 | 
 55 | #[derive(Component)]
 56 | struct TA;
 57 | 
 58 | #[derive(Component)]
 59 | struct TB;
 60 | 
 61 | #[derive(Component)]
 62 | struct TC;
 63 | 
 64 | #[derive(Component)]
 65 | struct TD;
 66 | 
 67 | #[derive(Resource)]
 68 | struct ErrorTriggered;
 69 | 
 70 | fn app() -> App {
 71 |     let mut app = App::new();
 72 |     app.add_plugins((MinimalPlugins, BehaviorPlugin::<T>::default()))
 73 |         .add_systems(Update, transition::<T>);
 74 |     app
 75 | }
 76 | 
 77 | #[test]
 78 | fn initial() {
 79 |     let mut app = app();
 80 |     app.world_mut().spawn(A);
 81 |     app.update();
 82 |     assert_eq!(
 83 |         app.world_mut()
 84 |             .run_system_once(|q: Single<BehaviorRef<T>, With<TA>>| { **q })
 85 |             .unwrap(),
 86 |         A
 87 |     );
 88 | }
 89 | 
 90 | #[test]
 91 | fn initial_load() {
 92 |     let mut app = app();
 93 |     app.world_mut().spawn((
 94 |         C,
 95 |         // Simulate loading from saved data:
 96 |         crate::Memory {
 97 |             stack: [A, B].into(),
 98 |         },
 99 |     ));
100 |     app.update();
101 | 
102 |     assert_eq!(
103 |         app.world_mut()
104 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, With<TB>, With<TC>)>| { **q })
105 |             .unwrap(),
106 |         C
107 |     );
108 | }
109 | 
110 | #[test]
111 | fn push() {
112 |     let mut app = app();
113 |     app.world_mut().spawn((A, Next(B)));
114 |     app.update();
115 |     assert_eq!(
116 |         app.world_mut()
117 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, With<TB>)>| {
118 |                 (q.previous().copied(), *q.current())
119 |             })
120 |             .unwrap(),
121 |         (Some(A), B)
122 |     );
123 | }
124 | 
125 | #[test]
126 | fn push_error() {
127 |     let mut app = app();
128 |     let e = app.world_mut().spawn((A, Next(C))).id();
129 | 
130 |     app.add_observer(
131 |         move |event: On<Error<T>>,
132 |               q: Single<BehaviorRef<T>, (With<TA>, Without<TC>)>,
133 |               mut commands: Commands| {
134 |             assert_eq!(**q, A);
135 |             assert_eq!(event.instance, e);
136 |             commands.insert_resource(ErrorTriggered);
137 |         },
138 |     );
139 | 
140 |     app.update();
141 |     assert!(app.world().contains_resource::<ErrorTriggered>());
142 | }
143 | 
144 | #[test]
145 | fn pop() {
146 |     let mut app = app();
147 |     app.world_mut().spawn((A, Next(B)));
148 |     app.update();
149 |     app.world_mut()
150 |         .run_system_once(|mut q: Single<BehaviorMut<T>, (With<TA>, With<TB>)>| {
151 |             q.stop();
152 |         })
153 |         .unwrap();
154 |     app.update();
155 |     assert_eq!(
156 |         app.world_mut()
157 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, Without<TB>)>| {
158 |                 (q.previous().copied(), *q.current())
159 |             })
160 |             .unwrap(),
161 |         (None, A)
162 |     );
163 | }
164 | 
165 | #[test]
166 | fn pop_initial() {
167 |     let mut app = app();
168 |     let e = app.world_mut().spawn((A, Previous::<T>)).id();
169 | 
170 |     app.add_observer(
171 |         move |event: On<Error<T>>, q: Single<BehaviorRef<T>, With<TA>>, mut commands: Commands| {
172 |             assert_eq!(**q, A);
173 |             assert_eq!(event.instance, e);
174 |             commands.insert_resource(ErrorTriggered);
175 |         },
176 |     );
177 | 
178 |     app.update();
179 |     assert!(app.world().contains_resource::<ErrorTriggered>());
180 | }
181 | 
182 | #[test]
183 | fn queue() {
184 |     let mut app = app();
185 |     app.world_mut().spawn((
186 |         A,
187 |         TransitionQueue::start(B) // A -> B
188 |             .then(C) // B -> C
189 |             .then_wait_for(D) // C -> D -> C
190 |             .then_stop() //  C -> B
191 |             .then_stop() // B -> A
192 |             .then(D), // A -> D
193 |     ));
194 |     app.update(); // None -> A
195 |     app.update(); // A -> B
196 |     assert_eq!(
197 |         app.world_mut()
198 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, With<TB>)>| {
199 |                 (q.previous().copied(), *q.current())
200 |             })
201 |             .unwrap(),
202 |         (Some(A), B)
203 |     );
204 | 
205 |     app.update(); // B -> C
206 |     assert_eq!(
207 |         app.world_mut()
208 |             .run_system_once(
209 |                 |q: Single<BehaviorRef<T>, (With<TA>, With<TB>, With<TC>)>| {
210 |                     (q.previous().copied(), *q.current())
211 |                 }
212 |             )
213 |             .unwrap(),
214 |         (Some(B), C)
215 |     );
216 | 
217 |     app.update(); // C -> D
218 |     assert_eq!(
219 |         app.world_mut()
220 |             .run_system_once(
221 |                 |q: Single<BehaviorRef<T>, (With<TA>, With<TB>, With<TC>, With<TD>)>| {
222 |                     (q.previous().copied(), *q.current())
223 |                 }
224 |             )
225 |             .unwrap(),
226 |         (Some(C), D)
227 |     );
228 | 
229 |     // Stop D
230 |     app.world_mut()
231 |         .run_system_once(|mut q: Single<BehaviorMut<T>>| {
232 |             q.stop();
233 |         })
234 |         .unwrap();
235 |     app.update(); // D -> C
236 |     assert_eq!(
237 |         app.world_mut()
238 |             .run_system_once(
239 |                 |q: Single<BehaviorRef<T>, (With<TA>, With<TB>, With<TC>, Without<TD>)>| {
240 |                     (q.previous().copied(), *q.current())
241 |                 }
242 |             )
243 |             .unwrap(),
244 |         (Some(B), C)
245 |     );
246 | 
247 |     app.update(); // C -> B
248 |     assert_eq!(
249 |         app.world_mut()
250 |             .run_system_once(
251 |                 |q: Single<BehaviorRef<T>, (With<TA>, With<TB>, Without<TC>, Without<TD>)>| {
252 |                     (q.previous().copied(), *q.current())
253 |                 }
254 |             )
255 |             .unwrap(),
256 |         (Some(A), B)
257 |     );
258 | 
259 |     app.update(); // B -> A
260 |     assert_eq!(
261 |         app.world_mut()
262 |             .run_system_once(
263 |                 |q: Single<BehaviorRef<T>, (With<TA>, Without<TB>, Without<TC>, Without<TD>)>| {
264 |                     (q.previous().copied(), *q.current())
265 |                 }
266 |             )
267 |             .unwrap(),
268 |         (None, A)
269 |     );
270 | 
271 |     app.update(); // A -> D
272 |     assert_eq!(
273 |         app.world_mut()
274 |             .run_system_once(
275 |                 |q: Single<BehaviorRef<T>, (With<TA>, Without<TB>, Without<TC>, With<TD>)>| {
276 |                     (q.previous().copied(), *q.current())
277 |                 }
278 |             )
279 |             .unwrap(),
280 |         (Some(A), D)
281 |     );
282 | 
283 |     // Queue should be done, check again to be sure:
284 |     app.update();
285 |     assert_eq!(
286 |         app.world_mut()
287 |             .run_system_once(
288 |                 |q: Single<BehaviorRef<T>, (With<TA>, Without<TB>, Without<TC>, With<TD>)>| {
289 |                     (q.previous().copied(), *q.current())
290 |                 }
291 |             )
292 |             .unwrap(),
293 |         (Some(A), D)
294 |     );
295 |     assert!(app
296 |         .world_mut()
297 |         .run_system_once(|q: Query<&TransitionQueue<T>>| { q.single().is_err() })
298 |         .unwrap());
299 | }
300 | 
301 | #[test]
302 | fn chain() {
303 |     let mut app = app();
304 | 
305 |     // A -> B -> C -> D
306 |     app.world_mut()
307 |         .spawn((A, TransitionQueue::chain([B, C, D])));
308 | 
309 |     app.update(); // A
310 |     assert_eq!(
311 |         app.world_mut()
312 |             .run_system_once(|q: Single<BehaviorRef<T>, With<TA>>| {
313 |                 (q.previous().copied(), *q.current())
314 |             })
315 |             .unwrap(),
316 |         (None, A)
317 |     );
318 | 
319 |     app.update(); // A -> B
320 |     assert_eq!(
321 |         app.world_mut()
322 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, With<TB>)>| {
323 |                 (q.previous().copied(), *q.current())
324 |             })
325 |             .unwrap(),
326 |         (Some(A), B)
327 |     );
328 | 
329 |     app.update(); // A -> B -> C
330 |     assert_eq!(
331 |         app.world_mut()
332 |             .run_system_once(
333 |                 |q: Single<BehaviorRef<T>, (With<TA>, With<TB>, With<TC>)>| {
334 |                     (q.previous().copied(), *q.current())
335 |                 }
336 |             )
337 |             .unwrap(),
338 |         (Some(B), C)
339 |     );
340 | 
341 |     app.update(); // A -> B -> C -> D
342 |     assert_eq!(
343 |         app.world_mut()
344 |             .run_system_once(
345 |                 |q: Single<BehaviorRef<T>, (With<TA>, With<TB>, With<TC>, With<TD>)>| {
346 |                     (q.previous().copied(), *q.current())
347 |                 }
348 |             )
349 |             .unwrap(),
350 |         (Some(C), D)
351 |     );
352 | 
353 |     // Queue should be done, check again to be sure:
354 |     app.update();
355 |     assert_eq!(
356 |         app.world_mut()
357 |             .run_system_once(
358 |                 |q: Single<BehaviorRef<T>, (With<TA>, With<TB>, With<TC>, With<TD>)>| {
359 |                     (q.previous().copied(), *q.current())
360 |                 }
361 |             )
362 |             .unwrap(),
363 |         (Some(C), D)
364 |     );
365 |     assert!(app
366 |         .world_mut()
367 |         .run_system_once(|q: Query<&TransitionQueue<T>>| { q.single().is_err() })
368 |         .unwrap());
369 | }
370 | 
371 | #[test]
372 | fn sequence() {
373 |     let mut app = app();
374 | 
375 |     // A -> B, A -> D
376 |     app.world_mut()
377 |         .spawn((A, TransitionQueue::sequence([B, D])));
378 | 
379 |     app.update(); // A
380 |     assert_eq!(
381 |         app.world_mut()
382 |             .run_system_once(|q: Single<BehaviorMut<T>, With<TA>>| {
383 |                 (q.previous().copied(), *q.current())
384 |             })
385 |             .unwrap(),
386 |         (None, A)
387 |     );
388 | 
389 |     app.update(); // A -> B
390 |     assert_eq!(
391 |         app.world_mut()
392 |             .run_system_once(|mut q: Single<BehaviorMut<T>, (With<TA>, With<TB>)>| {
393 |                 q.stop();
394 |                 (q.previous().copied(), *q.current())
395 |             })
396 |             .unwrap(),
397 |         (Some(A), B)
398 |     );
399 | 
400 |     app.update(); // A
401 |     assert_eq!(
402 |         app.world_mut()
403 |             .run_system_once(|q: Single<BehaviorRef<T>, With<TA>>| {
404 |                 (q.previous().copied(), *q.current())
405 |             })
406 |             .unwrap(),
407 |         (None, A)
408 |     );
409 | 
410 |     app.update(); // A -> D
411 |     assert_eq!(
412 |         app.world_mut()
413 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, With<TD>)>| {
414 |                 (q.previous().copied(), *q.current())
415 |             })
416 |             .unwrap(),
417 |         (Some(A), D)
418 |     );
419 | 
420 |     // Queue should be done, check again to be sure:
421 |     app.update();
422 |     assert_eq!(
423 |         app.world_mut()
424 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, With<TD>)>| {
425 |                 (q.previous().copied(), *q.current())
426 |             })
427 |             .unwrap(),
428 |         (Some(A), D)
429 |     );
430 |     assert!(app
431 |         .world_mut()
432 |         .run_system_once(|q: Query<&TransitionQueue<T>>| { q.single().is_err() })
433 |         .unwrap());
434 | }
435 | 
436 | #[test]
437 | fn interrupt_start() {
438 |     let mut app = app();
439 |     app.world_mut().spawn((A, Next(B)));
440 |     app.update();
441 |     assert_eq!(
442 |         app.world_mut()
443 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, With<TB>)>| {
444 |                 (q.previous().copied(), *q.current())
445 |             })
446 |             .unwrap(),
447 |         (Some(A), B)
448 |     );
449 | 
450 |     app.world_mut()
451 |         .run_system_once(|mut q: Single<BehaviorMut<T>>| {
452 |             q.interrupt_start(D);
453 |         })
454 |         .unwrap();
455 |     app.update();
456 |     assert_eq!(
457 |         app.world_mut()
458 |             .run_system_once(
459 |                 |q: Single<BehaviorRef<T>, (With<TA>, Without<TB>, With<TD>)>| {
460 |                     (q.previous().copied(), *q.current())
461 |                 }
462 |             )
463 |             .unwrap(),
464 |         (Some(A), D)
465 |     );
466 | }
467 | 
468 | #[test]
469 | fn interrupt_resume() {
470 |     let mut app = app();
471 |     app.world_mut().spawn((A, Next(B)));
472 |     app.update();
473 | 
474 |     app.world_mut()
475 |         .run_system_once(|mut q: Single<BehaviorMut<T>>| {
476 |             q.start(C);
477 |         })
478 |         .unwrap();
479 |     app.update();
480 | 
481 |     assert_eq!(
482 |         app.world_mut()
483 |             .run_system_once(
484 |                 |q: Single<BehaviorRef<T>, (With<TA>, With<TB>, With<TC>)>| {
485 |                     (q.previous().copied(), *q.current())
486 |                 }
487 |             )
488 |             .unwrap(),
489 |         (Some(B), C)
490 |     );
491 | 
492 |     app.world_mut()
493 |         .run_system_once(|mut q: Single<BehaviorMut<T>>| {
494 |             let index = q.current_index().previous().unwrap();
495 |             q.interrupt_resume(index);
496 |         })
497 |         .unwrap();
498 |     app.update();
499 |     assert_eq!(
500 |         app.world_mut()
501 |             .run_system_once(
502 |                 |q: Single<BehaviorRef<T>, (With<TA>, With<TB>, Without<TC>)>| {
503 |                     (q.previous().copied(), *q.current())
504 |                 }
505 |             )
506 |             .unwrap(),
507 |         (Some(A), B)
508 |     );
509 | }
510 | 
511 | #[test]
512 | fn interrupt_stop() {
513 |     let mut app = app();
514 |     app.world_mut().spawn((A, Next(B)));
515 |     app.update();
516 | 
517 |     app.world_mut()
518 |         .run_system_once(|mut q: Single<BehaviorMut<T>>| {
519 |             q.start(C);
520 |         })
521 |         .unwrap();
522 |     app.update();
523 | 
524 |     assert_eq!(
525 |         app.world_mut()
526 |             .run_system_once(
527 |                 |q: Single<BehaviorRef<T>, (With<TA>, With<TB>, With<TC>)>| {
528 |                     (q.previous().copied(), *q.current())
529 |                 }
530 |             )
531 |             .unwrap(),
532 |         (Some(B), C)
533 |     );
534 | 
535 |     app.world_mut()
536 |         .run_system_once(|mut q: Single<BehaviorMut<T>>| {
537 |             let index = q.current_index().previous().unwrap();
538 |             q.interrupt_stop(index);
539 |         })
540 |         .unwrap();
541 |     app.update();
542 |     assert_eq!(
543 |         app.world_mut()
544 |             .run_system_once(
545 |                 |q: Single<BehaviorRef<T>, (With<TA>, Without<TB>, Without<TC>)>| {
546 |                     (q.previous().copied(), *q.current())
547 |                 }
548 |             )
549 |             .unwrap(),
550 |         (None, A)
551 |     );
552 | }
553 | 
554 | #[test]
555 | fn interrupt_start_push() {
556 |     let mut app = app();
557 |     app.world_mut().spawn((A, Next(B)));
558 |     app.update();
559 |     assert_eq!(
560 |         app.world_mut()
561 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, With<TB>)>| {
562 |                 (q.previous().copied(), *q.current())
563 |             })
564 |             .unwrap(),
565 |         (Some(A), B)
566 |     );
567 | 
568 |     app.world_mut()
569 |         .run_system_once(|mut q: Single<BehaviorMut<T>>| {
570 |             q.interrupt_start(C);
571 |         })
572 |         .unwrap();
573 |     app.update();
574 |     assert_eq!(
575 |         app.world_mut()
576 |             .run_system_once(
577 |                 |q: Single<BehaviorRef<T>, (With<TA>, With<TB>, With<TC>)>| {
578 |                     (q.previous().copied(), *q.current())
579 |                 }
580 |             )
581 |             .unwrap(),
582 |         (Some(B), C)
583 |     );
584 | }
585 | 
586 | #[test]
587 | fn interrupt_error() {
588 |     let mut app = app();
589 |     let e = app.world_mut().spawn((A, Next(B))).id();
590 | 
591 |     app.update();
592 |     assert_eq!(
593 |         app.world_mut()
594 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, With<TB>)>| {
595 |                 (q.previous().copied(), *q.current())
596 |             })
597 |             .unwrap(),
598 |         (Some(A), B)
599 |     );
600 | 
601 |     app.world_mut()
602 |         .run_system_once(|mut q: Single<BehaviorMut<T>>| {
603 |             q.interrupt_start(A);
604 |         })
605 |         .unwrap();
606 | 
607 |     app.add_observer(
608 |         move |event: On<Error<T>>, q: Single<BehaviorRef<T>, With<TA>>, mut commands: Commands| {
609 |             assert_eq!(**q, B);
610 |             assert_eq!(event.instance, e);
611 |             commands.insert_resource(ErrorTriggered);
612 |         },
613 |     );
614 | 
615 |     app.update();
616 |     assert_eq!(
617 |         app.world_mut()
618 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, With<TB>)>| {
619 |                 (q.previous().copied(), *q.current())
620 |             })
621 |             .unwrap(),
622 |         (Some(A), B)
623 |     );
624 | }
625 | 
626 | #[test]
627 | fn try_start() {
628 |     let mut app = app();
629 |     app.world_mut().spawn(A);
630 |     app.update();
631 | 
632 |     assert_eq!(
633 |         app.world_mut()
634 |             .run_system_once(|mut q: Single<BehaviorMut<T>>| {
635 |                 q.try_start(B).unwrap();
636 |                 q.try_start(D)
637 |             })
638 |             .unwrap(),
639 |         Err(D)
640 |     );
641 | 
642 |     app.update();
643 |     assert_eq!(
644 |         app.world_mut()
645 |             .run_system_once(|q: Single<BehaviorRef<T>, (With<TA>, With<TB>)>| {
646 |                 (q.previous().copied(), *q.current())
647 |             })
648 |             .unwrap(),
649 |         (Some(A), B)
650 |     );
651 | }
652 | 


--------------------------------------------------------------------------------
/src/lib.rs:
--------------------------------------------------------------------------------
   1 | #![doc = include_str!("../README.md")]
   2 | #![warn(missing_docs)]
   3 | #![allow(clippy::match_single_binding)] // For default trait method impls
   4 | #![allow(clippy::match_like_matches_macro)]
   5 | 
   6 | /// Common elements for [`Behavior`] query and management.
   7 | pub mod prelude {
   8 |     pub use crate::{Behavior, BehaviorIndex, BehaviorItem, BehaviorMut, BehaviorRef};
   9 |     pub use moonshine_kind::{Instance, InstanceCommands};
  10 | 
  11 |     pub use crate::transition::{
  12 |         transition, Interrupt, Interruption, Next, Previous, Transition, TransitionQueue,
  13 |     };
  14 | 
  15 |     pub use crate::events::{OnActivate, OnPause, OnResume, OnStart, OnStop};
  16 |     pub use crate::plugin::BehaviorPlugin;
  17 | 
  18 |     pub use crate::match_next;
  19 | 
  20 |     #[allow(deprecated)]
  21 |     pub use crate::transition::TransitionSequence;
  22 | }
  23 | 
  24 | pub mod events;
  25 | pub mod transition;
  26 | 
  27 | mod plugin;
  28 | 
  29 | #[cfg(test)]
  30 | mod tests;
  31 | 
  32 | use std::fmt::Debug;
  33 | use std::mem::{replace, swap};
  34 | use std::ops::{Deref, DerefMut, Index, IndexMut};
  35 | 
  36 | use bevy_derive::{Deref, DerefMut};
  37 | use bevy_ecs::change_detection::MaybeLocation;
  38 | use bevy_ecs::component::{Mutable, Tick};
  39 | use bevy_ecs::event::EntityTrigger;
  40 | use bevy_ecs::{prelude::*, query::QueryData};
  41 | use bevy_log::prelude::*;
  42 | use bevy_reflect::prelude::*;
  43 | use moonshine_kind::prelude::*;
  44 | 
  45 | pub use plugin::BehaviorPlugin;
  46 | 
  47 | use crate::events::{Activate, Error, Pause, Resume, Start, Stop};
  48 | 
  49 | use self::transition::*;
  50 | 
  51 | /// Any [`Component`] which may be used as a [`Behavior`].
  52 | ///
  53 | /// # Usage
  54 | ///
  55 | /// A [`Behavior`] is a component which represents a set of finite states. This makes `enum` the ideal data structure
  56 | /// to implement this trait, however this is not a strict requirement.
  57 | pub trait Behavior: Component<Mutability = Mutable> + Debug + Sized {
  58 |     /// Called when an interrupt is requested.
  59 |     ///
  60 |     /// If this returns `true`, the current behavior will stop to allow the next behavior to start.
  61 |     /// The initial behavior is never allowed to yield.
  62 |     fn filter_yield(&self, next: &Self) -> bool {
  63 |         match_next! {
  64 |             self => next,
  65 |             _ => _,
  66 |         }
  67 |     }
  68 | 
  69 |     /// Called before a new behavior is started.
  70 |     ///
  71 |     /// If this returns `false`, the transition fails.
  72 |     /// See [`Error`] for details on how to handle transition failures.
  73 |     fn filter_next(&self, next: &Self) -> bool {
  74 |         match_next! {
  75 |             self => next,
  76 |             _ => _,
  77 |         }
  78 |     }
  79 | 
  80 |     /// Called after a behavior is paused.
  81 |     ///
  82 |     /// If this returns `false`, the paused behavior will be stopped immediatedly and discarded.
  83 |     /// No [`Pause`] event will be sent in this case.
  84 |     fn is_resumable(&self) -> bool {
  85 |         match self {
  86 |             _ => true,
  87 |         }
  88 |     }
  89 | 
  90 |     /// Called during [`transition`](transition::transition) just after the behavior is started.
  91 |     fn on_start(&self, _previous: Option<&Self>, _commands: InstanceCommands<Self>) {}
  92 | 
  93 |     /// Called during [`transition`](transition::transition) just after the behavior is paused.
  94 |     fn on_pause(&self, _current: &Self, _commands: InstanceCommands<Self>) {}
  95 | 
  96 |     /// Called during [`transition`](transition::transition) just after the behavior is resumed.
  97 |     fn on_resume(&self, _previous: &Self, _commands: InstanceCommands<Self>) {}
  98 | 
  99 |     /// Called during [`transition`](transition::transition) just after the behavior is stopped.
 100 |     fn on_stop(&self, _current: &Self, _commands: InstanceCommands<Self>) {}
 101 | 
 102 |     /// Called during [`transition`](transition::transition) just after the behavior is started *or* resumed.
 103 |     fn on_activate(&self, _previous: Option<&Self>, _commands: InstanceCommands<Self>) {}
 104 | 
 105 |     /// Called during [`transition`](transition::transition) just after the behavior is paused *or* stopped.
 106 |     fn on_suspend(&self, _current: &Self, _commands: InstanceCommands<Self>) {}
 107 | }
 108 | 
 109 | #[doc(hidden)]
 110 | trait BehaviorHooks: Behavior {
 111 |     fn invoke_start(&self, previous: Option<&Self>, mut commands: InstanceCommands<Self>) {
 112 |         self.on_start(previous, commands.reborrow());
 113 |         self.on_activate(previous, commands);
 114 |     }
 115 | 
 116 |     fn invoke_pause(&self, current: &Self, mut commands: InstanceCommands<Self>) {
 117 |         self.on_suspend(current, commands.reborrow());
 118 |         self.on_pause(current, commands);
 119 |     }
 120 | 
 121 |     fn invoke_resume(&self, previous: &Self, mut commands: InstanceCommands<Self>) {
 122 |         self.on_resume(previous, commands.reborrow());
 123 |         self.on_activate(Some(previous), commands);
 124 |     }
 125 | 
 126 |     fn invoke_stop(&self, current: &Self, mut commands: InstanceCommands<Self>) {
 127 |         self.on_suspend(current, commands.reborrow());
 128 |         self.on_stop(current, commands);
 129 |     }
 130 | }
 131 | 
 132 | impl<T: Behavior> BehaviorHooks for T {}
 133 | 
 134 | /// Common interface for querying [`Behavior`] state using a [`BehaviorRef`] or [`BehaviorMut`].
 135 | pub trait BehaviorItem {
 136 |     #[doc(hidden)]
 137 |     type Behavior: Behavior;
 138 | 
 139 |     /// Returns the current [`Behavior`] state.
 140 |     fn current(&self) -> &Self::Behavior;
 141 | 
 142 |     /// Returns the previous [`Behavior`] state in the stack.
 143 |     ///
 144 |     /// # Usage
 145 |     ///
 146 |     /// Note that this is **NOT** the previously active state.
 147 |     /// Instead, this is the previous state which was active before the current one was started.
 148 |     ///
 149 |     /// To access the previously active state, handle [`Stop`] instead.
 150 |     fn previous(&self) -> Option<&Self::Behavior>;
 151 | 
 152 |     /// Returns the [`BehaviorIndex`] associated with the current [`Behavior`] state.
 153 |     #[deprecated(since = "0.3.1", note = "use `current_index` instead")]
 154 |     fn index(&self) -> BehaviorIndex {
 155 |         self.current_index()
 156 |     }
 157 | 
 158 |     /// Returns the [`BehaviorIndex`] associated with the current [`Behavior`] state.
 159 |     fn current_index(&self) -> BehaviorIndex;
 160 | 
 161 |     /// Returns `true` if the given [`BehaviorIndex`] matches a state in this [`Behavior`] stack.
 162 |     fn has_index(&self, index: BehaviorIndex) -> bool {
 163 |         index <= self.current_index()
 164 |     }
 165 | 
 166 |     /// Returns an iterator over all ([`BehaviorIndex`], [`Behavior`]) pairs in the stack, including the current one.
 167 |     ///
 168 |     /// The iterator is ordered from the initial behavior (index = 0) to the current one.
 169 |     fn enumerate(&self) -> impl Iterator<Item = (BehaviorIndex, &Self::Behavior)> + '_;
 170 | 
 171 |     /// Returns an iterator over all [`Behavior`] states in the stack, including the current one.
 172 |     ///
 173 |     /// The iterator is ordered from the initial behavior (index = 0) to the current one.
 174 |     fn iter(&self) -> impl Iterator<Item = &Self::Behavior> + '_ {
 175 |         self.enumerate().map(|(_, behavior)| behavior)
 176 |     }
 177 | 
 178 |     /// Returns a reference to the [`Behavior`] at the given [`BehaviorIndex`], if it exists.
 179 |     fn get(&self, index: BehaviorIndex) -> Option<&Self::Behavior>;
 180 | 
 181 |     /// Returns `true` if there is any pending [`Transition`] for this [`Behavior`].
 182 |     ///
 183 |     /// # Usage
 184 |     ///
 185 |     /// By design, only one transition is allowed per [`transition`](crate::transition::transition) cycle.
 186 |     ///
 187 |     /// The only exception to this rule is if the behavior is interrupted or reset where multiple states
 188 |     /// may be stopped within a single cycle.
 189 |     ///
 190 |     /// If a transition is requested while another is pending, it would be overriden.
 191 |     /// The transition helper methods [`start`](BehaviorMutItem::start), [`interrupt_start`](BehaviorMutItem::interrupt_start),
 192 |     /// [`stop`](BehaviorMutItem::stop) and [`reset`](BehaviorMutItem::reset) all trigger a warning in this case.
 193 |     ///
 194 |     /// Because of this, this method is useful to avoid unintentional transition overrides.
 195 |     fn has_transition(&self) -> bool;
 196 | }
 197 | 
 198 | /// Query data for a [`Behavior`].
 199 | ///
 200 | /// # Usage
 201 | ///
 202 | /// This provides a read-only reference to the current behavior state and all previous states in the stack.
 203 | ///
 204 | /// Additionally, it provides methods to check for pending transitions ([`has_transition`](BehaviorRefItem::has_transition)),
 205 | /// and the current behavior index ([`index`](BehaviorRefItem::index)).
 206 | #[derive(QueryData)]
 207 | pub struct BehaviorRef<T: Behavior> {
 208 |     current: Ref<'static, T>,
 209 |     memory: &'static Memory<T>,
 210 |     transition: &'static Transition<T>,
 211 | }
 212 | 
 213 | impl<T: Behavior> BehaviorRef<T> {
 214 |     /// Creates a new [`BehaviorRef`] item from an [`EntityRef`].
 215 |     pub fn from_entity(entity: EntityRef) -> Option<BehaviorRefItem<T>> {
 216 |         Some(BehaviorRefItem {
 217 |             current: entity.get_ref::<T>()?,
 218 |             memory: entity.get::<Memory<T>>()?,
 219 |             transition: entity.get::<Transition<T>>()?,
 220 |         })
 221 |     }
 222 | }
 223 | 
 224 | impl<T: Behavior> BehaviorItem for BehaviorRefItem<'_, '_, T> {
 225 |     type Behavior = T;
 226 | 
 227 |     fn current(&self) -> &T {
 228 |         &self.current
 229 |     }
 230 | 
 231 |     fn current_index(&self) -> BehaviorIndex {
 232 |         BehaviorIndex(self.memory.len())
 233 |     }
 234 | 
 235 |     fn previous(&self) -> Option<&T> {
 236 |         self.memory.last()
 237 |     }
 238 | 
 239 |     fn enumerate(&self) -> impl Iterator<Item = (BehaviorIndex, &T)> + '_ {
 240 |         self.memory
 241 |             .iter()
 242 |             .enumerate()
 243 |             .map(|(index, item)| (BehaviorIndex(index), item))
 244 |             .chain(std::iter::once((self.current_index(), self.current())))
 245 |     }
 246 | 
 247 |     fn get(&self, BehaviorIndex(index): BehaviorIndex) -> Option<&T> {
 248 |         if index == self.memory.stack.len() {
 249 |             Some(self.current())
 250 |         } else {
 251 |             self.memory.get(index)
 252 |         }
 253 |     }
 254 | 
 255 |     fn has_transition(&self) -> bool {
 256 |         !self.transition.is_none()
 257 |     }
 258 | }
 259 | 
 260 | impl<T: Behavior> Deref for BehaviorRefItem<'_, '_, T> {
 261 |     type Target = T;
 262 | 
 263 |     fn deref(&self) -> &Self::Target {
 264 |         self.current()
 265 |     }
 266 | }
 267 | 
 268 | impl<T: Behavior> AsRef<T> for BehaviorRefItem<'_, '_, T> {
 269 |     fn as_ref(&self) -> &T {
 270 |         &self.current
 271 |     }
 272 | }
 273 | 
 274 | impl<T: Behavior> DetectChanges for BehaviorRefItem<'_, '_, T> {
 275 |     fn is_added(&self) -> bool {
 276 |         self.current.is_added()
 277 |     }
 278 | 
 279 |     fn is_changed(&self) -> bool {
 280 |         self.current.is_changed()
 281 |     }
 282 | 
 283 |     fn last_changed(&self) -> Tick {
 284 |         self.current.last_changed()
 285 |     }
 286 | 
 287 |     fn added(&self) -> Tick {
 288 |         self.current.added()
 289 |     }
 290 | 
 291 |     fn changed_by(&self) -> MaybeLocation {
 292 |         self.current.changed_by()
 293 |     }
 294 | }
 295 | 
 296 | impl<T: Behavior> Index<BehaviorIndex> for BehaviorRefItem<'_, '_, T> {
 297 |     type Output = T;
 298 | 
 299 |     fn index(&self, BehaviorIndex(index): BehaviorIndex) -> &Self::Output {
 300 |         if index == self.memory.stack.len() {
 301 |             self.current()
 302 |         } else {
 303 |             &self.memory[index]
 304 |         }
 305 |     }
 306 | }
 307 | 
 308 | /// Query data for a [`Behavior`] with mutable access.
 309 | ///
 310 | /// # Usage
 311 | ///
 312 | /// This provides a mutable reference to the current behavior state and all previous states in the stack.
 313 | ///
 314 | /// See [`BehaviorRef`] for more details.
 315 | #[derive(QueryData)]
 316 | #[query_data(mutable)]
 317 | pub struct BehaviorMut<T: Behavior> {
 318 |     current: Mut<'static, T>,
 319 |     memory: &'static mut Memory<T>,
 320 |     transition: &'static mut Transition<T>,
 321 | }
 322 | 
 323 | impl<T: Behavior> BehaviorItem for BehaviorMutReadOnlyItem<'_, '_, T> {
 324 |     type Behavior = T;
 325 | 
 326 |     fn current(&self) -> &T {
 327 |         &self.current
 328 |     }
 329 | 
 330 |     fn current_index(&self) -> BehaviorIndex {
 331 |         BehaviorIndex(self.memory.len())
 332 |     }
 333 | 
 334 |     fn previous(&self) -> Option<&T> {
 335 |         self.memory.last()
 336 |     }
 337 | 
 338 |     fn enumerate(&self) -> impl Iterator<Item = (BehaviorIndex, &T)> + '_ {
 339 |         self.memory
 340 |             .iter()
 341 |             .enumerate()
 342 |             .map(|(index, item)| (BehaviorIndex(index), item))
 343 |             .chain(std::iter::once((self.current_index(), self.current())))
 344 |     }
 345 | 
 346 |     fn get(&self, BehaviorIndex(index): BehaviorIndex) -> Option<&T> {
 347 |         if index == self.memory.stack.len() {
 348 |             Some(self.current())
 349 |         } else {
 350 |             self.memory.get(index)
 351 |         }
 352 |     }
 353 | 
 354 |     fn has_transition(&self) -> bool {
 355 |         !self.transition.is_none()
 356 |     }
 357 | }
 358 | 
 359 | impl<T: Behavior> Deref for BehaviorMutReadOnlyItem<'_, '_, T> {
 360 |     type Target = T;
 361 | 
 362 |     fn deref(&self) -> &Self::Target {
 363 |         self.current()
 364 |     }
 365 | }
 366 | 
 367 | impl<T: Behavior> AsRef<T> for BehaviorMutReadOnlyItem<'_, '_, T> {
 368 |     fn as_ref(&self) -> &T {
 369 |         self.current.as_ref()
 370 |     }
 371 | }
 372 | 
 373 | impl<T: Behavior> DetectChanges for BehaviorMutReadOnlyItem<'_, '_, T> {
 374 |     fn is_added(&self) -> bool {
 375 |         self.current.is_added()
 376 |     }
 377 | 
 378 |     fn is_changed(&self) -> bool {
 379 |         self.current.is_changed()
 380 |     }
 381 | 
 382 |     fn last_changed(&self) -> Tick {
 383 |         self.current.last_changed()
 384 |     }
 385 | 
 386 |     fn added(&self) -> Tick {
 387 |         self.current.added()
 388 |     }
 389 | 
 390 |     fn changed_by(&self) -> MaybeLocation {
 391 |         self.current.changed_by()
 392 |     }
 393 | }
 394 | 
 395 | impl<T: Behavior> Index<BehaviorIndex> for BehaviorMutReadOnlyItem<'_, '_, T> {
 396 |     type Output = T;
 397 | 
 398 |     fn index(&self, BehaviorIndex(index): BehaviorIndex) -> &Self::Output {
 399 |         if index == self.memory.stack.len() {
 400 |             self.current()
 401 |         } else {
 402 |             &self.memory[index]
 403 |         }
 404 |     }
 405 | }
 406 | 
 407 | impl<T: Behavior> BehaviorItem for BehaviorMutItem<'_, '_, T> {
 408 |     type Behavior = T;
 409 | 
 410 |     fn current(&self) -> &T {
 411 |         &self.current
 412 |     }
 413 | 
 414 |     fn current_index(&self) -> BehaviorIndex {
 415 |         BehaviorIndex(self.memory.len())
 416 |     }
 417 | 
 418 |     fn previous(&self) -> Option<&T> {
 419 |         self.memory.last()
 420 |     }
 421 | 
 422 |     fn enumerate(&self) -> impl Iterator<Item = (BehaviorIndex, &Self::Behavior)> + '_ {
 423 |         self.memory
 424 |             .iter()
 425 |             .enumerate()
 426 |             .map(|(index, item)| (BehaviorIndex(index), item))
 427 |             .chain(std::iter::once((self.current_index(), self.current())))
 428 |     }
 429 | 
 430 |     fn get(&self, BehaviorIndex(index): BehaviorIndex) -> Option<&T> {
 431 |         if index == self.memory.stack.len() {
 432 |             Some(self.current())
 433 |         } else {
 434 |             self.memory.get(index)
 435 |         }
 436 |     }
 437 | 
 438 |     fn has_transition(&self) -> bool {
 439 |         !self.transition.is_none()
 440 |     }
 441 | }
 442 | 
 443 | impl<T: Behavior> BehaviorMutItem<'_, '_, T> {
 444 |     /// Returns the current [`Behavior`] state as a mutable.
 445 |     pub fn current_mut(&mut self) -> &mut T {
 446 |         self.current.as_mut()
 447 |     }
 448 | 
 449 |     /// Returns the previous [`Behavior`] state as a mutable.
 450 |     ///
 451 |     /// See [`BehaviorRefItem::previous`] for more details.
 452 |     pub fn previous_mut(&mut self) -> Option<&mut T> {
 453 |         self.memory.last_mut()
 454 |     }
 455 | 
 456 |     /// Returns a mutable iterator over all [`Behavior`] states in the stack, including the current one.
 457 |     ///
 458 |     /// See [`BehaviorRefItem::iter`] for more details.
 459 |     pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut T> + '_ {
 460 |         self.memory
 461 |             .iter_mut()
 462 |             .chain(std::iter::once(self.current.as_mut()))
 463 |     }
 464 | 
 465 |     /// Returns a mutable iterator over all ([`BehaviorIndex`], [`Behavior`]) pairs in the stack, including the current one.
 466 |     ///
 467 |     /// See [`BehaviorRefItem::enumerate`] for more details.
 468 |     pub fn enumerate_mut(&mut self) -> impl Iterator<Item = (BehaviorIndex, &mut T)> + '_ {
 469 |         let current_index = self.current_index();
 470 |         self.memory
 471 |             .iter_mut()
 472 |             .enumerate()
 473 |             .map(|(index, item)| (BehaviorIndex(index), item))
 474 |             .chain(std::iter::once((current_index, self.current.as_mut())))
 475 |     }
 476 | 
 477 |     /// Starts the given `next` behavior.
 478 |     ///
 479 |     /// This operation pushes the current behavior onto the stack and inserts the new behavior.
 480 |     ///
 481 |     /// Note that this will fail if the current behavior rejects `next` through [`Behavior::filter_next`].
 482 |     /// See [`Error`] for details on how to handle transition failures.
 483 |     #[track_caller]
 484 |     pub fn start(&mut self, next: T) {
 485 |         self.start_with_caller(next, MaybeLocation::caller());
 486 |     }
 487 | 
 488 |     /// Attempts to start the given `next` behavior if there are no pending transitions and the
 489 |     /// current behavior allows it.
 490 |     ///
 491 |     /// Note that it's still possible for the transition to fail if the current behavior mutates
 492 |     /// in such a way as to no longer allow the transition between the time this function is called
 493 |     /// and when the [`transition`](crate::transition::transition) system runs.
 494 |     ///
 495 |     /// Do **NOT** use this method to react to transition failures.
 496 |     /// See [`Error`] for details on how to correctly handle transition failures.
 497 |     ///
 498 |     /// # Usage
 499 |     ///
 500 |     /// This is similar to [`start`](BehaviorMutItem::start) but will return an error containing
 501 |     /// the given `next` behavior if it fails.
 502 |     ///
 503 |     /// This is useful for fire-and-forget transitions where you don't want to override a
 504 |     /// pending transition or may expect a transition failure.
 505 |     ///
 506 |     /// If multiple systems call this method before transition, only the first one will succeed.
 507 |     #[track_caller]
 508 |     pub fn try_start(&mut self, next: T) -> Result<(), T> {
 509 |         if self.has_transition() || !self.filter_next(&next) {
 510 |             return Err(next);
 511 |         }
 512 | 
 513 |         self.start_with_caller(next, MaybeLocation::caller());
 514 |         Ok(())
 515 |     }
 516 | 
 517 |     fn start_with_caller(&mut self, next: T, caller: MaybeLocation) {
 518 |         self.set_transition(Next(next), caller);
 519 |     }
 520 | 
 521 |     /// Interrupts the current behavior and starts the given `next` behavior.
 522 |     ///
 523 |     /// This operation stops all behaviors which yield to the new behavior and pushes it onto the stack.
 524 |     /// See [`Behavior::filter_yield`] for details on how to define how states yield to each other.
 525 |     ///
 526 |     /// This also removes any remaining [`TransitionSequence`] steps.
 527 |     ///
 528 |     /// The initial behavior is never allowed to yield.
 529 |     ///
 530 |     /// Note that this will fail if the first non-yielding behavior rejects `next` through [`Behavior::filter_next`].
 531 |     /// See [`Error`] for details on how to handle transition failures.
 532 |     #[track_caller]
 533 |     pub fn interrupt_start(&mut self, next: T) {
 534 |         self.interrupt_start_with_caller(next, MaybeLocation::caller());
 535 |     }
 536 | 
 537 |     /// Attempts to interrupt the current behavior and start the given `next` behavior.
 538 |     ///
 539 |     /// This is similar to [`interrupt_start`](BehaviorMutItem::interrupt_start) but will fail if there is a pending transition.
 540 |     #[track_caller]
 541 |     pub fn try_interrupt_start(&mut self, next: T) -> Result<(), T> {
 542 |         if self.has_transition() {
 543 |             return Err(next);
 544 |         }
 545 | 
 546 |         self.interrupt_start_with_caller(next, MaybeLocation::caller());
 547 |         Ok(())
 548 |     }
 549 | 
 550 |     fn interrupt_start_with_caller(&mut self, next: T, caller: MaybeLocation) {
 551 |         self.set_transition(Interrupt(Interruption::Start(next)), caller);
 552 |     }
 553 | 
 554 |     /// Stops all behaviors above and including the given [`BehaviorIndex`].
 555 |     ///
 556 |     /// This also removes any remaining [`TransitionSequence`] steps.
 557 |     ///
 558 |     /// The initial behavior is never allowed to yield.
 559 |     #[track_caller]
 560 |     pub fn interrupt_stop(&mut self, index: BehaviorIndex) {
 561 |         self.interrupt_resume_with_caller(index.previous().unwrap(), MaybeLocation::caller());
 562 |     }
 563 | 
 564 |     /// Attempts to stop all behaviors above and including the given [`BehaviorIndex`].
 565 |     ///
 566 |     /// This is similar to [`interrupt_stop`](BehaviorMutItem::interrupt_stop) but will fail if:
 567 |     /// - There is a pending transition
 568 |     /// - The given `index` is the initial behavior
 569 |     /// - The given `index` is not in the stack
 570 |     #[track_caller]
 571 |     pub fn try_interrupt_stop(&mut self, index: BehaviorIndex) -> Result<(), BehaviorIndex> {
 572 |         if self.has_transition() || !self.has_index(index) {
 573 |             return Err(index);
 574 |         }
 575 | 
 576 |         let Some(previous_index) = index.previous() else {
 577 |             return Err(index);
 578 |         };
 579 | 
 580 |         self.interrupt_resume_with_caller(previous_index, MaybeLocation::caller());
 581 |         Ok(())
 582 |     }
 583 | 
 584 |     /// Stops all behaviors above the given [`BehaviorIndex`] and resume the behavior at that index.
 585 |     ///
 586 |     /// This also removes any remaining [`TransitionSequence`] steps.
 587 |     #[track_caller]
 588 |     pub fn interrupt_resume(&mut self, index: BehaviorIndex) {
 589 |         self.interrupt_resume_with_caller(index, MaybeLocation::caller());
 590 |     }
 591 | 
 592 |     /// Attempts to stop all behaviors above the given [`BehaviorIndex`] and resume the behavior at that index.
 593 |     ///
 594 |     /// This is similar to [`interrupt_resume`](BehaviorMutItem::interrupt_resume) but will fail if:
 595 |     /// - There is a pending transition
 596 |     /// - The given `index` is not in the stack
 597 |     #[track_caller]
 598 |     pub fn try_interrupt_resume(&mut self, index: BehaviorIndex) -> Result<(), BehaviorIndex> {
 599 |         if self.has_transition() || !self.has_index(index) {
 600 |             return Err(index);
 601 |         }
 602 | 
 603 |         self.interrupt_resume_with_caller(index, MaybeLocation::caller());
 604 |         Ok(())
 605 |     }
 606 | 
 607 |     fn interrupt_resume_with_caller(&mut self, index: BehaviorIndex, caller: MaybeLocation) {
 608 |         self.set_transition(Interrupt(Interruption::Resume(index)), caller);
 609 |     }
 610 | 
 611 |     /// Stops the current behavior.
 612 |     ///
 613 |     /// This operation pops the current behavior off the stack and resumes the previous behavior.
 614 |     ///
 615 |     /// Note that this will fail if the current behavior is the initial behavior.
 616 |     /// See [`Error`] for details on how to handle transition failures.
 617 |     #[track_caller]
 618 |     pub fn stop(&mut self) {
 619 |         self.stop_with_caller(MaybeLocation::caller());
 620 |     }
 621 | 
 622 |     /// Attempts to stop the current behavior.
 623 |     ///
 624 |     /// This is similar to [`stop`](BehaviorMutItem::stop) but will fail if:
 625 |     /// - There is a pending transition
 626 |     /// - The current behavior is the initial behavior
 627 |     #[track_caller]
 628 |     pub fn try_stop(&mut self) -> bool {
 629 |         if self.has_transition() || self.memory.is_empty() {
 630 |             return false;
 631 |         }
 632 | 
 633 |         self.stop_with_caller(MaybeLocation::caller());
 634 |         true
 635 |     }
 636 | 
 637 |     fn stop_with_caller(&mut self, caller: MaybeLocation) {
 638 |         self.set_transition(Previous, caller);
 639 |     }
 640 | 
 641 |     /// Stops the current and all previous behaviors and resumes the initial behavior.
 642 |     ///
 643 |     /// This operation clears the stack and resumes the initial behavior. It can never fail.
 644 |     /// If the stack is empty (i.e. initial behavior), it does nothing.
 645 |     #[track_caller]
 646 |     pub fn reset(&mut self) {
 647 |         self.interrupt_resume_with_caller(BehaviorIndex::initial(), MaybeLocation::caller());
 648 |     }
 649 | 
 650 |     /// Attempts to reset the current behavior.
 651 |     ///
 652 |     /// This is similar to [`reset`](BehaviorMutItem::reset) but will fail if there is a pending transition.
 653 |     #[track_caller]
 654 |     pub fn try_reset(&mut self) -> bool {
 655 |         if self.has_transition() {
 656 |             return false;
 657 |         }
 658 | 
 659 |         self.interrupt_resume_with_caller(BehaviorIndex::initial(), MaybeLocation::caller());
 660 |         true
 661 |     }
 662 | 
 663 |     fn set_transition(&mut self, transition: Transition<T>, caller: MaybeLocation) {
 664 |         let previous = replace(self.transition.as_mut(), transition);
 665 |         if !previous.is_none() {
 666 |             warn!(
 667 |                 "transition override ({caller})): {previous:?} -> {:?}",
 668 |                 *self.transition
 669 |             );
 670 |         }
 671 |     }
 672 | 
 673 |     fn push(
 674 |         &mut self,
 675 |         instance: Instance<T>,
 676 |         mut next: T,
 677 |         initial: bool,
 678 |         commands: &mut Commands,
 679 |     ) -> bool {
 680 |         if self.filter_next(&next) {
 681 |             let previous = {
 682 |                 swap(self.current.as_mut(), &mut next);
 683 |                 next
 684 |             };
 685 |             self.invoke_start(Some(&previous), commands.instance(instance));
 686 |             let index = self.memory.len();
 687 |             if previous.is_resumable() {
 688 |                 let next_index = index + 1;
 689 |                 debug!(
 690 |                     "{instance:?}: {previous:?} (#{index}) -> {:?} (#{next_index})",
 691 |                     *self.current
 692 |                 );
 693 | 
 694 |                 previous.invoke_pause(&self.current, commands.instance(instance));
 695 | 
 696 |                 commands.queue(move |world: &mut World| {
 697 |                     world.trigger_with(
 698 |                         Pause {
 699 |                             instance,
 700 |                             index: BehaviorIndex(index),
 701 |                         },
 702 |                         EntityTrigger,
 703 |                     );
 704 |                     world.trigger_with(
 705 |                         Start {
 706 |                             instance,
 707 |                             index: BehaviorIndex(next_index),
 708 |                             initial,
 709 |                         },
 710 |                         EntityTrigger,
 711 |                     );
 712 |                     world.trigger_with(
 713 |                         Activate {
 714 |                             instance,
 715 |                             index: BehaviorIndex(next_index),
 716 |                             resume: false,
 717 |                             initial,
 718 |                         },
 719 |                         EntityTrigger,
 720 |                     );
 721 |                 });
 722 | 
 723 |                 self.memory.push(previous);
 724 |             } else {
 725 |                 debug!(
 726 |                     "{instance:?}: {previous:?} (#{index}) -> {:?} (#{index})",
 727 |                     *self.current
 728 |                 );
 729 | 
 730 |                 previous.invoke_stop(&self.current, commands.instance(instance));
 731 | 
 732 |                 commands.queue(move |world: &mut World| {
 733 |                     world.trigger_with(
 734 |                         Stop {
 735 |                             instance,
 736 |                             index: BehaviorIndex(index),
 737 |                             behavior: previous,
 738 |                             interrupt: false,
 739 |                         },
 740 |                         EntityTrigger,
 741 |                     );
 742 |                     world.trigger_with(
 743 |                         Start {
 744 |                             instance,
 745 |                             index: BehaviorIndex(index),
 746 |                             initial,
 747 |                         },
 748 |                         EntityTrigger,
 749 |                     );
 750 |                     world.trigger_with(
 751 |                         Activate {
 752 |                             instance,
 753 |                             index: BehaviorIndex(index),
 754 |                             resume: false,
 755 |                             initial,
 756 |                         },
 757 |                         EntityTrigger,
 758 |                     );
 759 |                 })
 760 |             }
 761 |             true
 762 |         } else {
 763 |             warn!(
 764 |                 "{instance:?}: transition {:?} -> {next:?} is not allowed",
 765 |                 *self.current
 766 |             );
 767 | 
 768 |             commands.queue(move |world: &mut World| {
 769 |                 world.trigger_with(
 770 |                     Error {
 771 |                         instance,
 772 |                         error: TransitionError::RejectedNext(next),
 773 |                     },
 774 |                     EntityTrigger,
 775 |                 );
 776 |             });
 777 | 
 778 |             false
 779 |         }
 780 |     }
 781 | 
 782 |     fn interrupt(&mut self, instance: Instance<T>, next: T, commands: &mut Commands) {
 783 |         while self.filter_yield(&next) && !self.memory.is_empty() {
 784 |             let index = self.memory.len();
 785 |             if let Some(mut next) = self.memory.pop() {
 786 |                 let previous = {
 787 |                     swap(self.current.as_mut(), &mut next);
 788 |                     next
 789 |                 };
 790 |                 debug!("{instance:?}: {:?} (#{index}) -> Interrupt", previous);
 791 |                 previous.invoke_stop(&self.current, commands.instance(instance));
 792 | 
 793 |                 commands.queue(move |world: &mut World| {
 794 |                     world.trigger_with(
 795 |                         Stop {
 796 |                             instance,
 797 |                             index: BehaviorIndex(index),
 798 |                             behavior: previous,
 799 |                             interrupt: true,
 800 |                         },
 801 |                         EntityTrigger,
 802 |                     );
 803 |                 });
 804 |             }
 805 |         }
 806 | 
 807 |         self.push(instance, next, false, commands);
 808 |     }
 809 | 
 810 |     fn pop(&mut self, instance: Instance<T>, commands: &mut Commands) -> bool {
 811 |         let index = self.memory.len();
 812 | 
 813 |         if let Some(mut next) = self.memory.pop() {
 814 |             let next_index = self.memory.len();
 815 |             debug!(
 816 |                 "{instance:?}: {:?} (#{index}) -> {next:?} (#{next_index})",
 817 |                 *self.current
 818 |             );
 819 |             let previous = {
 820 |                 swap(self.current.as_mut(), &mut next);
 821 |                 next
 822 |             };
 823 |             self.invoke_resume(&previous, commands.instance(instance));
 824 |             previous.invoke_stop(&self.current, commands.instance(instance));
 825 | 
 826 |             commands.queue(move |world: &mut World| {
 827 |                 world.trigger_with(
 828 |                     Stop {
 829 |                         instance,
 830 |                         index: BehaviorIndex(index),
 831 |                         behavior: previous,
 832 |                         interrupt: false,
 833 |                     },
 834 |                     EntityTrigger,
 835 |                 );
 836 |                 world.trigger_with(
 837 |                     Resume {
 838 |                         instance,
 839 |                         index: BehaviorIndex(next_index),
 840 |                     },
 841 |                     EntityTrigger,
 842 |                 );
 843 |                 world.trigger_with(
 844 |                     Activate {
 845 |                         instance,
 846 |                         index: BehaviorIndex(next_index),
 847 |                         resume: true,
 848 |                         initial: false,
 849 |                     },
 850 |                     EntityTrigger,
 851 |                 );
 852 |             });
 853 |             true
 854 |         } else {
 855 |             warn!(
 856 |                 "{instance:?}: transition {:?} -> None is not allowed",
 857 |                 *self.current
 858 |             );
 859 | 
 860 |             commands.queue(move |world: &mut World| {
 861 |                 world.trigger_with(
 862 |                     Error {
 863 |                         instance,
 864 |                         error: TransitionError::<T>::NoPrevious,
 865 |                     },
 866 |                     EntityTrigger,
 867 |                 );
 868 |             });
 869 | 
 870 |             false
 871 |         }
 872 |     }
 873 | 
 874 |     fn clear(&mut self, instance: Instance<T>, index: BehaviorIndex, commands: &mut Commands) {
 875 |         // Stop all states except the one above the given index
 876 |         while self.current_index() > index.next() {
 877 |             let index = self.memory.len();
 878 |             let previous = self.memory.pop().unwrap();
 879 |             let next = self.memory.last().unwrap();
 880 |             debug!("{instance:?}: {:?} (#{index}) -> Interrupt", previous);
 881 |             previous.invoke_stop(next, commands.instance(instance));
 882 | 
 883 |             commands.queue(move |world: &mut World| {
 884 |                 world.trigger_with(
 885 |                     Stop {
 886 |                         instance,
 887 |                         index: BehaviorIndex(index),
 888 |                         behavior: previous,
 889 |                         interrupt: true,
 890 |                     },
 891 |                     EntityTrigger,
 892 |                 );
 893 |             });
 894 |         }
 895 | 
 896 |         // Pop the state above the given index
 897 |         self.pop(instance, commands);
 898 |     }
 899 | }
 900 | 
 901 | impl<T: Behavior> Deref for BehaviorMutItem<'_, '_, T> {
 902 |     type Target = T;
 903 | 
 904 |     fn deref(&self) -> &Self::Target {
 905 |         self.current()
 906 |     }
 907 | }
 908 | 
 909 | impl<T: Behavior> DerefMut for BehaviorMutItem<'_, '_, T> {
 910 |     fn deref_mut(&mut self) -> &mut Self::Target {
 911 |         self.current_mut()
 912 |     }
 913 | }
 914 | 
 915 | impl<T: Behavior> DetectChanges for BehaviorMutItem<'_, '_, T> {
 916 |     fn is_added(&self) -> bool {
 917 |         self.current.is_added()
 918 |     }
 919 | 
 920 |     fn is_changed(&self) -> bool {
 921 |         self.current.is_changed()
 922 |     }
 923 | 
 924 |     fn last_changed(&self) -> Tick {
 925 |         self.current.last_changed()
 926 |     }
 927 | 
 928 |     fn added(&self) -> Tick {
 929 |         self.current.added()
 930 |     }
 931 | 
 932 |     fn changed_by(&self) -> MaybeLocation {
 933 |         self.current.changed_by()
 934 |     }
 935 | }
 936 | 
 937 | impl<T: Behavior> DetectChangesMut for BehaviorMutItem<'_, '_, T> {
 938 |     type Inner = T;
 939 | 
 940 |     fn set_changed(&mut self) {
 941 |         self.current.set_changed()
 942 |     }
 943 | 
 944 |     fn set_last_changed(&mut self, last_changed: Tick) {
 945 |         self.current.set_last_changed(last_changed)
 946 |     }
 947 | 
 948 |     fn bypass_change_detection(&mut self) -> &mut Self::Inner {
 949 |         self.current.bypass_change_detection()
 950 |     }
 951 | 
 952 |     fn set_added(&mut self) {
 953 |         self.current.set_added()
 954 |     }
 955 | 
 956 |     fn set_last_added(&mut self, last_added: Tick) {
 957 |         self.current.set_last_added(last_added)
 958 |     }
 959 | }
 960 | 
 961 | impl<T: Behavior> AsRef<T> for BehaviorMutItem<'_, '_, T> {
 962 |     fn as_ref(&self) -> &T {
 963 |         self.current.as_ref()
 964 |     }
 965 | }
 966 | 
 967 | impl<T: Behavior> AsMut<T> for BehaviorMutItem<'_, '_, T> {
 968 |     fn as_mut(&mut self) -> &mut T {
 969 |         self.current.as_mut()
 970 |     }
 971 | }
 972 | 
 973 | impl<T: Behavior> Index<BehaviorIndex> for BehaviorMutItem<'_, '_, T> {
 974 |     type Output = T;
 975 | 
 976 |     fn index(&self, BehaviorIndex(index): BehaviorIndex) -> &Self::Output {
 977 |         if index == self.memory.stack.len() {
 978 |             self.current()
 979 |         } else {
 980 |             &self.memory[index]
 981 |         }
 982 |     }
 983 | }
 984 | 
 985 | impl<T: Behavior> IndexMut<BehaviorIndex> for BehaviorMutItem<'_, '_, T> {
 986 |     fn index_mut(&mut self, BehaviorIndex(index): BehaviorIndex) -> &mut Self::Output {
 987 |         if index == self.memory.stack.len() {
 988 |             self.current_mut()
 989 |         } else {
 990 |             &mut self.memory[index]
 991 |         }
 992 |     }
 993 | }
 994 | 
 995 | /// A numeric index which represents the position of a [`Behavior`] in the stack.
 996 | ///
 997 | /// This index may be used to uniquely identify each behavior state.
 998 | /// The initial behavior always has the index of `0`, and the current behavior always has the highest index (length of the stack).
 999 | #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, PartialOrd, Ord, Reflect)]
1000 | pub struct BehaviorIndex(usize);
1001 | 
1002 | impl BehaviorIndex {
1003 |     /// Returns the index of the initial behavior. This is always `0`.
1004 |     pub fn initial() -> Self {
1005 |         Self(0)
1006 |     }
1007 | 
1008 |     /// Returns the index of the behavior before this one, if exists.
1009 |     pub fn previous(self) -> Option<Self> {
1010 |         if self == BehaviorIndex::initial() {
1011 |             return None;
1012 |         }
1013 | 
1014 |         Some(Self(self.0.saturating_sub(1)))
1015 |     }
1016 | 
1017 |     fn next(self) -> Self {
1018 |         Self(self.0.saturating_add(1))
1019 |     }
1020 | }
1021 | 
1022 | #[derive(Component, Deref, DerefMut, Reflect)]
1023 | #[reflect(Component)]
1024 | struct Memory<T: Behavior> {
1025 |     stack: Vec<T>,
1026 | }
1027 | 
1028 | impl<T: Behavior> Default for Memory<T> {
1029 |     fn default() -> Self {
1030 |         Self {
1031 |             stack: Vec::default(),
1032 |         }
1033 |     }
1034 | }
1035 | 
1036 | /// A convenient macro for implementation of [`Behavior::filter_next`].
1037 | ///
1038 | /// # Usage
1039 | /// For any given pair of states `curr` and `next`, this match expands into a match arm such that:
1040 | /// ```rust,ignore
1041 | /// match curr {
1042 | ///     From => matches!(next, To)
1043 | /// }
1044 | /// ```
1045 | /// where `From` is the current possible state, and `To` is the next allowed state.
1046 | ///
1047 | /// # Example
1048 | ///
1049 | /// ```rust
1050 | /// # use bevy::prelude::*;
1051 | /// # use moonshine_behavior::prelude::*;
1052 | /// #[derive(Component, Debug)]
1053 | /// enum Soldier {
1054 | ///     Idle,
1055 | ///     Crouch,
1056 | ///     Fire,
1057 | ///     Sprint,
1058 | ///     Jump,
1059 | /// }
1060 | ///
1061 | /// impl Behavior for Soldier {
1062 | ///     fn filter_next(&self, next: &Self) -> bool {
1063 | ///         use Soldier::*;
1064 | ///         match_next! {
1065 | ///             self => next,
1066 | ///             Idle => Crouch | Sprint | Fire | Jump,
1067 | ///             Crouch => Sprint | Fire,
1068 | ///             Sprint => Jump,
1069 | ///         }
1070 | ///     }
1071 | /// }
1072 | ///
1073 | /// # assert!(Soldier::Idle.filter_next(&Soldier::Crouch));
1074 | /// # assert!(!Soldier::Sprint.filter_next(&Soldier::Fire));
1075 | /// ```
1076 | #[macro_export]
1077 | macro_rules! match_next {
1078 |     { $curr:ident => $next:ident, $($from:pat => $to:pat),* $(,)? } => {
1079 |         match $curr {
1080 |             $(
1081 |                 $from => matches!($next, $to),
1082 |             )*
1083 |             #[allow(unreachable_patterns)]
1084 |             _ => false,
1085 |         }
1086 |     };
1087 | }
1088 | 


--------------------------------------------------------------------------------