bevy_gearbox 0.4.0

State machine system for the bevy game engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

use bevy::{ecs::component::Mutable, prelude::*};

use crate::{EnterState, ExitState, StateChildOf};

/// A component that when added to a state entity, will insert the contained component
/// `T` into the state machine's root entity when this state is entered.
#[derive(Component)]
pub struct StateComponent<T: Component>(pub T);

/// A component that when added to a state entity, will remove the component type `T`
/// from the state machine's root entity when this state is entered, and restore
/// the stored value when the state is exited.
#[derive(Component)]
pub struct StateInactiveComponent<T: Component + Clone>(pub T);

/// A generic system that adds a component `T` to the state machine's root entity
/// when a state with `StateComponent<T>` is entered.
pub fn state_component_enter<T: Component<Mutability = Mutable> + Clone>(
    enter_state: On<EnterState>,
    q_state_component: Query<&StateComponent<T>>,
    q_child_of: Query<&StateChildOf>,
    mut commands: Commands,
) {
    let entered_state = enter_state.target;
    let Ok(insert_component) = q_state_component.get(entered_state) else {
        return;
    };

    let root_entity = q_child_of.root_ancestor(entered_state);

    if root_entity != entered_state {
        commands.entity(root_entity).insert(insert_component.0.clone());
    }
}

/// A generic system that removes a component `T` from the state machine's root entity
/// when a state with `StateComponent<T>` is exited.
pub fn state_component_exit<T: Component>(
    exit_state: On<ExitState>,
    q_state_component: Query<&StateComponent<T>>,
    q_child_of: Query<&StateChildOf>,
    mut commands: Commands,
) {
    let exited_state = exit_state.target;
    if !q_state_component.contains(exited_state) {
        return;
    };

    let root_entity = q_child_of.root_ancestor(exited_state);

    if root_entity != exited_state {
        commands.entity(root_entity).remove::<T>();
    }
}

/// A generic system that removes a component `T` from the state machine's root entity
/// when a state with `StateInactiveComponent<T>` is entered.
pub fn state_inactive_component_enter<T: Component + Clone>(
    enter_state: On<EnterState>,
    q_state_inactive_component: Query<&StateInactiveComponent<T>>,
    q_child_of: Query<&StateChildOf>,
    mut commands: Commands,
) {
    let entered_state = enter_state.target;
    if !q_state_inactive_component.contains(entered_state) {
        return;
    };

    let root_entity = q_child_of.root_ancestor(entered_state);

    if root_entity != entered_state {
        commands.entity(root_entity).remove::<T>();
    }
}

/// A generic system that restores a component `T` to the state machine's root entity
/// when a state with `StateInactiveComponent<T>` is exited, using the stored clone.
pub fn state_inactive_component_exit<T: Component + Clone>(
    exit_state: On<ExitState>,
    q_state_inactive_component: Query<&StateInactiveComponent<T>>,
    q_child_of: Query<&StateChildOf>,
    mut commands: Commands,
) {
    let exited_state = exit_state.target;
    let Ok(remove_component) = q_state_inactive_component.get(exited_state) else {
        return;
    };

    let root_entity = q_child_of.root_ancestor(exited_state);

    if root_entity != exited_state {
        commands.entity(root_entity).insert(remove_component.0.clone());
    }
}

/// Helper trait to add state component observers to an App.
pub trait StateComponentAppExt {
    /// Registers both enter and exit observers for `StateComponent<T>`.
    /// This is a convenience method to avoid having to register both observers manually.
    fn add_state_component<T: Component<Mutability = Mutable> + Clone>(&mut self) -> &mut Self;
    
    /// Registers both enter and exit observers for `StateInactiveComponent<T>`.
    /// This is a convenience method to avoid having to register both observers manually.
    fn add_state_inactive_component<T: Component<Mutability = Mutable> + Clone>(&mut self) -> &mut Self;
}

impl StateComponentAppExt for App {
    fn add_state_component<T: Component<Mutability = Mutable> + Clone>(&mut self) -> &mut Self {
        self.add_observer(state_component_enter::<T>)
            .add_observer(state_component_exit::<T>)
    }
    
    fn add_state_inactive_component<T: Component<Mutability = Mutable> + Clone>(&mut self) -> &mut Self {
        self.add_observer(state_inactive_component_enter::<T>)
            .add_observer(state_inactive_component_exit::<T>)
    }
}

/// Event to reset a subtree rooted at the target entity.
#[derive(EntityEvent, Reflect)]
pub struct Reset { #[event_target] pub target: Entity }

impl Reset {
    pub fn new(entity: Entity) -> Self {
        Self { target: entity }
    }
}