kiran 1.0.0

Kiran — AI-native game engine for AGNOS
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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

//! Game state machine — menu → playing → paused transitions.

use serde::{Deserialize, Serialize};

/// A game state with enter/exit lifecycle.
pub trait GameState: Send {
    /// Return the state's display name.
    fn name(&self) -> &str;
    /// Called when transitioning into this state.
    fn on_enter(&mut self, _world: &mut crate::World) {}
    /// Called when transitioning out of this state.
    fn on_exit(&mut self, _world: &mut crate::World) {}
    /// Called each frame while this state is active.
    fn update(&mut self, _world: &mut crate::World) {}
}

/// State machine resource managing game state transitions.
pub struct StateMachine {
    states: Vec<Box<dyn GameState>>,
    current: usize,
    pending_transition: Option<usize>,
}

impl StateMachine {
    /// Create a state machine with the given initial state.
    ///
    /// # Examples
    ///
    /// ```
    /// use kiran::state::{StateMachine, NamedState};
    ///
    /// let mut sm = StateMachine::new(Box::new(NamedState("menu".into())));
    /// let playing = sm.add_state(Box::new(NamedState("playing".into())));
    /// assert_eq!(sm.current_name(), "menu");
    /// assert_eq!(sm.state_count(), 2);
    /// ```
    pub fn new(initial: Box<dyn GameState>) -> Self {
        Self {
            states: vec![initial],
            current: 0,
            pending_transition: None,
        }
    }

    /// Add a state to the machine. Returns its index.
    pub fn add_state(&mut self, state: Box<dyn GameState>) -> usize {
        let idx = self.states.len();
        self.states.push(state);
        idx
    }

    /// Request a transition to a state by index.
    pub fn transition_to(&mut self, index: usize) {
        if index < self.states.len() {
            self.pending_transition = Some(index);
        }
    }

    /// Apply pending transition (call between frames).
    pub fn apply_transition(&mut self, world: &mut crate::World) {
        if let Some(next) = self.pending_transition.take() {
            self.states[self.current].on_exit(world);
            self.current = next;
            self.states[self.current].on_enter(world);
        }
    }

    /// Update the current state.
    pub fn update(&mut self, world: &mut crate::World) {
        self.states[self.current].update(world);
    }

    /// Current state name.
    #[must_use]
    pub fn current_name(&self) -> &str {
        self.states[self.current].name()
    }

    /// Current state index.
    #[must_use]
    #[inline]
    pub fn current_index(&self) -> usize {
        self.current
    }

    /// Number of registered states.
    #[must_use]
    #[inline]
    pub fn state_count(&self) -> usize {
        self.states.len()
    }
}

/// Simple named state (no custom logic).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NamedState(pub String);

impl GameState for NamedState {
    fn name(&self) -> &str {
        &self.0
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn state_machine_basic() {
        let mut sm = StateMachine::new(Box::new(NamedState("menu".into())));
        let playing = sm.add_state(Box::new(NamedState("playing".into())));
        let paused = sm.add_state(Box::new(NamedState("paused".into())));

        assert_eq!(sm.current_name(), "menu");
        assert_eq!(sm.state_count(), 3);

        let mut world = crate::World::new();

        sm.transition_to(playing);
        sm.apply_transition(&mut world);
        assert_eq!(sm.current_name(), "playing");

        sm.transition_to(paused);
        sm.apply_transition(&mut world);
        assert_eq!(sm.current_name(), "paused");
    }

    #[test]
    fn state_machine_no_transition() {
        let mut sm = StateMachine::new(Box::new(NamedState("idle".into())));
        let mut world = crate::World::new();
        sm.apply_transition(&mut world); // no pending
        assert_eq!(sm.current_name(), "idle");
    }

    #[test]
    fn state_machine_invalid_index() {
        let mut sm = StateMachine::new(Box::new(NamedState("menu".into())));
        sm.transition_to(999); // invalid
        let mut world = crate::World::new();
        sm.apply_transition(&mut world);
        assert_eq!(sm.current_name(), "menu"); // unchanged
    }

    #[test]
    fn state_machine_update() {
        let mut sm = StateMachine::new(Box::new(NamedState("game".into())));
        let mut world = crate::World::new();
        sm.update(&mut world); // should not panic
    }
}