Skip to main content

voxel_framework/
settings.rs

1//! Persistent user settings saved to `worlds/{world_name}/settings.json`.
2//!
3//! [`PersistedSettings`] captures the four in-game slider values (FOV, SFX
4//! volume, render distance, mouse sensitivity) and writes them to disk when the
5//! player closes the Settings menu.  On next launch the game reads this file and
6//! patches the config resources before inserting them, so the player's choices
7//! survive across sessions.
8//!
9//! # Usage
10//!
11//! ```rust,no_run
12//! use voxel_framework::settings::PersistedSettings;
13//!
14//! // Save
15//! let settings = PersistedSettings {
16//!     fov_degrees: 90.0,
17//!     sfx_volume: 0.8,
18//!     render_distance_chunks: 10,
19//!     sensitivity_pct: 100,
20//! };
21//! settings.save("my_world");
22//!
23//! // Load
24//! if let Some(saved) = PersistedSettings::load("my_world") {
25//!     println!("Loaded FOV: {}", saved.fov_degrees);
26//! }
27//! ```
28
29use serde::{Deserialize, Serialize};
30
31/// User-adjustable settings persisted to `worlds/{world_name}/settings.json`.
32///
33/// All four fields map directly to the in-game sliders exposed by
34/// [`crate::ui::PauseMenuPlugin`]:
35///
36/// | Field | Slider | Range |
37/// |-------|--------|-------|
38/// | `fov_degrees` | Field of View | 50–120 |
39/// | `sfx_volume` | SFX Volume | 0.0–1.0 |
40/// | `render_distance_chunks` | Render Distance | 4–32 (even) |
41/// | `sensitivity_pct` | Mouse Sensitivity | 10–100 |
42#[derive(Debug, Clone, Serialize, Deserialize)]
43pub struct PersistedSettings {
44    /// Vertical field-of-view in degrees. Valid range: `50.0`–`120.0`.
45    pub fov_degrees: f32,
46    /// SFX volume in the range `[0.0, 1.0]`.
47    pub sfx_volume: f32,
48    /// Render distance in chunks (even values only). Valid range: `4`–`32`.
49    pub render_distance_chunks: u32,
50    /// Mouse sensitivity as a percentage of the default.
51    /// `100` = default ("Minecraft-like" feel), `10` = slowest.
52    /// The underlying [`crate::player::Player::sensitivity`] multiplier is
53    /// `sensitivity_pct / 100`, combined internally with the hidden
54    /// `MOUSE_SCALE` constant (rad/px) to produce camera rotation per mouse
55    /// pixel.
56    pub sensitivity_pct: u32,
57}
58
59impl PersistedSettings {
60    /// Saves these settings to `worlds/{world_name}/settings.json`.
61    ///
62    /// Creates the directory if it does not exist. Silently ignores I/O errors
63    /// so that a read-only filesystem does not crash the game.
64    pub fn save(&self, world_name: &str) {
65        let dir = format!("worlds/{}", world_name);
66        let _ = std::fs::create_dir_all(&dir);
67        let path = format!("{}/settings.json", dir);
68        if let Ok(json) = serde_json::to_string_pretty(self) {
69            let _ = std::fs::write(path, json);
70        }
71    }
72
73    /// Loads settings from `worlds/{world_name}/settings.json`.
74    ///
75    /// Returns `None` if the file does not exist or cannot be parsed (e.g. on
76    /// the first run before any settings have been saved).
77    pub fn load(world_name: &str) -> Option<Self> {
78        let path = format!("worlds/{}/settings.json", world_name);
79        let data = std::fs::read_to_string(path).ok()?;
80        serde_json::from_str(&data).ok()
81    }
82}