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}