Skip to main content

clairlune_scene/
anim.rs

1//! The seeded activity state machine (PLAN.md section 4.7).
2//!
3//! The state at time `t` is a pure function of `(activity, seed, t)`. To keep that
4//! cheap at any `t`, time is split into 60 s episodes. Each episode is seeded by
5//! `hash(seed, "animation", episode)`, starts in the `start` state and is simulated
6//! from its own beginning, so a lookup costs at most one episode of transitions.
7
8use crate::activity::Activity;
9use crate::hash::StableHasher;
10use crate::rng::Rng;
11
12/// Episode length.
13pub const EPISODE_MS: u64 = 60_000;
14/// One-shot state length when no sprite sheet gives one (placeholder art).
15pub const DEFAULT_ONE_SHOT_MS: u64 = 1_000;
16
17/// The state active at some time, and the span it occupies.
18#[derive(Clone, Debug, PartialEq, Eq)]
19pub struct StateAt {
20    pub state: String,
21    pub since_ms: u64,
22    pub until_ms: u64,
23}
24
25/// State at `t_ms`. `one_shot_ms` gives the play length of non-looping states
26/// (the sum of their sprite frame durations).
27pub fn state_at(
28    activity: &Activity,
29    seed: u64,
30    t_ms: u64,
31    one_shot_ms: &dyn Fn(&str) -> u64,
32) -> StateAt {
33    let episode = t_ms / EPISODE_MS;
34    let mut h = StableHasher::new();
35    h.write_u64(seed);
36    h.write_str("animation");
37    h.write_u64(episode);
38    let mut rng = Rng::from_u64(h.finish());
39
40    let mut state = activity.animation.start.as_str();
41    let mut since = episode * EPISODE_MS;
42    let end = since + EPISODE_MS;
43    loop {
44        let duration = match activity.animation.states.get(state) {
45            Some(def) if def.looping => {
46                let [lo, hi] = def.dwell_s.unwrap_or([1.0, 1.0]);
47                let (lo, hi) = ((lo * 1000.0).round() as u32, (hi * 1000.0).round() as u32);
48                u64::from(rng.range_u32(lo, hi.max(lo)))
49            }
50            _ => one_shot_ms(state).max(1),
51        };
52        // The episode boundary cuts the last state short; the next episode restarts.
53        let until = (since + duration).min(end);
54        if t_ms < until {
55            return StateAt {
56                state: state.to_string(),
57                since_ms: since,
58                until_ms: until,
59            };
60        }
61        since = until;
62        let successors = activity.successors(state);
63        let weights: Vec<u32> = successors.iter().map(|(_, w)| *w).collect();
64        state = successors[rng.weighted_index(&weights)].0;
65    }
66}
67
68#[cfg(test)]
69mod tests {
70    use super::*;
71    use crate::activity::Catalog;
72
73    fn one_shot(_: &str) -> u64 {
74        DEFAULT_ONE_SHOT_MS
75    }
76
77    #[test]
78    fn starts_in_start_and_restarts_each_episode() {
79        let cat = Catalog::builtin();
80        for a in &cat.activities {
81            for ep in 0..3 {
82                let s = state_at(a, 7, ep * EPISODE_MS, &one_shot);
83                assert_eq!(s.state, a.animation.start, "{}", a.id);
84                assert_eq!(s.since_ms, ep * EPISODE_MS);
85            }
86        }
87    }
88
89    #[test]
90    fn walks_only_valid_transitions_and_is_deterministic() {
91        let cat = Catalog::builtin();
92        for a in &cat.activities {
93            let mut prev: Option<StateAt> = None;
94            let mut t = 0;
95            while t < 3 * EPISODE_MS {
96                let s = state_at(a, 42, t, &one_shot);
97                assert_eq!(s, state_at(a, 42, t, &one_shot));
98                assert!(a.animation.states.contains_key(&s.state));
99                assert!(s.since_ms <= t && t < s.until_ms);
100                if let Some(p) = &prev
101                    && p != &s
102                    && !s.since_ms.is_multiple_of(EPISODE_MS)
103                {
104                    assert_eq!(p.until_ms, s.since_ms);
105                    assert!(a.successors(&p.state).iter().any(|(n, _)| *n == s.state));
106                }
107                prev = Some(s);
108                t += 250;
109            }
110        }
111    }
112
113    #[test]
114    fn looping_dwell_respects_bounds() {
115        let cat = Catalog::builtin();
116        let a = cat.get("warm_hands").unwrap();
117        let s = state_at(a, 3, 0, &one_shot);
118        let [lo, hi] = a.animation.states[&s.state].dwell_s.unwrap();
119        let len = s.until_ms - s.since_ms;
120        assert!(
121            len >= (lo * 1000.0) as u64 && len <= (hi * 1000.0) as u64,
122            "{len}"
123        );
124    }
125}