cuqueclicker_lib/save/
mod.rs

1//! Save persistence with versioned migration chain.
2//!
3//! Wire format on disk: a single JSON object with a `"version": u32` field.
4//! Pre-versioned saves (no field) are treated as V1 by [`migrate::peek_version`].
5//! Each version has a frozen struct in `versions/vN.rs` and a conversion into
6//! the next version's struct, walked end-to-end on load.
7//!
8//! Once shipped, a `versions/vN.rs` is FROZEN. New schema changes go in
9//! `vN+1.rs` together with a `From<vN> for vN+1` impl and a unit test. See
10//! the "Save versioning" section in `CLAUDE.md` for the full policy.
11//!
12//! Callers (the `Persistence` impls under `platform/`) should never touch
13//! `serde_json` on `GameState` directly — go through [`load_from_str`] /
14//! [`save_to_string`] so the version dispatch stays in one place.
15
16pub mod migrate;
17pub mod versions;
18
19use crate::game::state::GameState;
20
21/// The version number every fresh save is written as. Bump in lockstep
22/// with adding a new `versions/vN.rs` and routing it in [`load_from_str`].
23pub const CURRENT_VERSION: u32 = 2;
24
25/// Best-effort load from a JSON string. Falls back to a default state if
26/// the input is malformed at any layer of the chain. The result is always
27/// passed through [`GameState::migrate_runtime`] so ephemeral
28/// `#[serde(skip)]` fields (flash vecs, count-up tweens, etc.) are seeded.
29///
30/// Versions outside the known set deserialize as default — this is
31/// pessimistic on purpose (a future version is more likely to have new
32/// fields than the current code can interpret).
33pub fn load_from_str(json: &str) -> GameState {
34    match migrate::peek_version(json) {
35        1 => match serde_json::from_str::<versions::v1::GameStateV1>(json) {
36            Ok(v1) => versions::v2::GameStateV2::from(v1)
37                .into_current()
38                .migrate_runtime(),
39            Err(_) => GameState::default().migrate_runtime(),
40        },
41        2 => match serde_json::from_str::<versions::v2::GameStateV2>(json) {
42            Ok(v2) => v2.into_current().migrate_runtime(),
43            Err(_) => GameState::default().migrate_runtime(),
44        },
45        _ => GameState::default().migrate_runtime(),
46    }
47}
48
49/// Serialize the live state to its on-disk JSON form. The `version` field
50/// is whatever the caller has on `state` — `GameState::default()` and the
51/// migration chain both stamp [`CURRENT_VERSION`], so the only way to write
52/// a wrong version is to mutate `state.version` by hand, which nothing does.
53pub fn save_to_string(state: &GameState) -> serde_json::Result<String> {
54    serde_json::to_string_pretty(state)
55}
56
57#[cfg(test)]
58mod tests {
59    use super::*;
60
61    #[test]
62    fn pre_versioned_json_loads_through_v1() {
63        // A save written by main (no `version` field, today's shape) must
64        // load without losing data.
65        let legacy = r#"{
66            "cuques": 1234.5,
67            "total_clicks": 99,
68            "lifetime_cuques": 1234.5,
69            "best_fps": 0.0,
70            "golden_caught": 0,
71            "fingerers_owned": {"index_finger": 7},
72            "achievements_earned": ["first_finger"],
73            "upgrades_earned": ["click_mult_1"],
74            "prestige": 0,
75            "total_play_ticks": 0,
76            "buffs": []
77        }"#;
78        let s = load_from_str(legacy);
79        assert_eq!(s.version, CURRENT_VERSION);
80        assert_eq!(s.cuques, 1234.5);
81        assert_eq!(s.total_clicks, 99);
82        assert_eq!(s.fingerer_count("index_finger"), 7);
83        assert!(s.has_upgrade("click_mult_1"));
84        assert!(s.has_achievement("first_finger"));
85    }
86
87    #[test]
88    fn malformed_json_falls_back_to_default() {
89        let s = load_from_str("{ not valid json");
90        assert_eq!(s.cuques, 0.0);
91        assert_eq!(s.version, CURRENT_VERSION);
92    }
93
94    #[test]
95    fn round_trip_through_save_to_string_preserves_state() {
96        let original = GameState {
97            cuques: 4242.0,
98            total_clicks: 17,
99            ..GameState::default()
100        };
101        let json = save_to_string(&original).expect("serialize");
102        let loaded = load_from_str(&json);
103        assert_eq!(loaded.cuques, 4242.0);
104        assert_eq!(loaded.total_clicks, 17);
105        assert_eq!(loaded.version, CURRENT_VERSION);
106    }
107}
cuqueclicker_lib/save/mod.rs

cuqueclicker_lib/save/
mod.rs
