diff --git a/src/features/notification/components.rs b/src/features/notification/components.rs index 3f1f2b0..db48b3f 100644 --- a/src/features/notification/components.rs +++ b/src/features/notification/components.rs @@ -1,5 +1,6 @@ use crate::prelude::*; +/// Resource managing active notifications. #[derive(Resource)] pub struct Notifications { items: Vec<(Notification, NotificationLevel)>, @@ -44,18 +45,22 @@ impl Notifications { } } +/// Marker for the UI node containing notifications. #[derive(Component)] pub struct NotificationContainer; +/// Component tracking the lifetime of a displayed notification. #[derive(Component)] pub struct NotificationLifetime(pub Timer); +/// Data for a single notification. #[derive(Component)] pub struct Notification { pub title: Option, pub message: String, } +/// Severity level of a notification. #[derive(Component)] pub enum NotificationLevel { Info, diff --git a/src/features/notification/mod.rs b/src/features/notification/mod.rs index 29e3c8f..479f740 100644 --- a/src/features/notification/mod.rs +++ b/src/features/notification/mod.rs @@ -7,6 +7,7 @@ use components::{NotificationContainer, NotificationLifetime, Notifications}; pub mod components; pub mod ui; +/// Plugin for the notification system. pub struct NotificationPlugin; impl Plugin for NotificationPlugin { @@ -17,12 +18,12 @@ impl Plugin for NotificationPlugin { } } -/// Spawns the notification container up +/// Spawns the notification container up. fn setup(mut commands: Commands) { commands.spawn(notification_container()); } -/// Spawns/Despawns UI elements for each item in the `Notifications` Resource +/// Spawns/Despawns UI elements for each item in the `Notifications` Resource. fn handle_notification( mut commands: Commands, mut notifications: ResMut, diff --git a/src/features/notification/ui.rs b/src/features/notification/ui.rs index 231bb2e..9844a32 100644 --- a/src/features/notification/ui.rs +++ b/src/features/notification/ui.rs @@ -1,6 +1,7 @@ use super::components::*; use crate::prelude::*; +/// Creates the notification container UI bundle. pub fn notification_container() -> impl Bundle { ( NotificationContainer, @@ -16,6 +17,7 @@ pub fn notification_container() -> impl Bundle { ) } +/// Spawns a single notification UI element. pub fn spawn_notification( commands: &mut Commands, content: Notification, diff --git a/src/features/phase/components.rs b/src/features/phase/components.rs index be541f6..7dc430d 100644 --- a/src/features/phase/components.rs +++ b/src/features/phase/components.rs @@ -1,6 +1,7 @@ use super::utils::format_time; use crate::prelude::*; +/// Represents the different states of the Pomodoro timer. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub enum Phase { Break { duration: f32 }, @@ -37,9 +38,11 @@ impl Phase { } } +/// Resource holding the current phase state. #[derive(Resource, Debug, Serialize, Deserialize, Clone)] pub struct CurrentPhase(pub Phase); +/// Configuration for phase durations. #[derive(Resource, Debug, Serialize, Deserialize, Clone)] pub struct TimerSettings { pub focus_duration: u32, @@ -59,6 +62,7 @@ impl Default for TimerSettings { } } +/// Tracks statistics for the current session. #[derive(Resource, Debug, Default, Serialize, Deserialize, Clone)] pub struct SessionTracker { pub completed_focus_phases: u32, diff --git a/src/features/phase/messages.rs b/src/features/phase/messages.rs index 620aad1..52dd5cc 100644 --- a/src/features/phase/messages.rs +++ b/src/features/phase/messages.rs @@ -1,12 +1,15 @@ use crate::prelude::*; +/// Message sent when a phase timer reaches zero. #[derive(Message)] pub struct PhaseTimerFinishedMessage { pub phase: Phase, } +/// Message to toggle pause state. #[derive(Message)] pub struct PhaseTimerPauseMessage; +/// Message to proceed to the next phase. #[derive(Message)] pub struct NextPhaseMessage; diff --git a/src/features/phase/mod.rs b/src/features/phase/mod.rs index 1a63fba..d730262 100644 --- a/src/features/phase/mod.rs +++ b/src/features/phase/mod.rs @@ -7,6 +7,7 @@ pub mod components; pub mod messages; pub mod utils; +/// Plugin managing the Pomodoro phase timer and state. pub struct PhasePlugin; impl Plugin for PhasePlugin { @@ -36,6 +37,7 @@ impl Plugin for PhasePlugin { } } +/// Debug system to shorten phase duration for testing. #[cfg(debug_assertions)] fn debug_short_phase_duration( mut phase_res: ResMut, @@ -55,6 +57,7 @@ fn debug_short_phase_duration( } } +/// Updates the current phase duration from settings. fn load_rules(mut phase_res: ResMut, settings: Res) { let phase = &mut phase_res.0; @@ -71,6 +74,7 @@ fn load_rules(mut phase_res: ResMut, settings: Res) } } +/// Ticks the phase timer and handles completion. fn tick_timer( mut commands: Commands, asset_server: Res, @@ -107,7 +111,7 @@ fn tick_timer( } } -/// Rewards the player at the end of a focus phase with `berries_per_focus_minute` * `focus_duration` +/// Rewards the player at the end of a focus phase with `berries_per_focus_minute` * `focus_duration`. fn grant_focus_rewards( mut messages: MessageReader, config: Res, @@ -147,6 +151,7 @@ fn grant_focus_rewards( } } +/// Toggles pause state of the timer. fn handle_pause( mut messages: MessageReader, mut phase_res: ResMut, @@ -171,6 +176,7 @@ fn handle_pause( } } +/// Transitions to the next phase based on current state. pub fn next_phase( current_phase: &mut CurrentPhase, session_tracker: &mut SessionTracker, @@ -204,6 +210,7 @@ pub fn next_phase( } } +/// Handles transition to the next phase after user confirmation. pub fn handle_continue( mut messages: MessageReader, mut phase_res: ResMut, diff --git a/src/features/phase/utils.rs b/src/features/phase/utils.rs index fb280fe..cc352a1 100644 --- a/src/features/phase/utils.rs +++ b/src/features/phase/utils.rs @@ -1,3 +1,4 @@ +/// Formats seconds into MM:SS or HH:MM:SS string. pub fn format_time(seconds: f32) -> String { let seconds = seconds.max(0.0) as u32; diff --git a/src/features/savegame/components.rs b/src/features/savegame/components.rs index 5aa082e..4ed2aaf 100644 --- a/src/features/savegame/components.rs +++ b/src/features/savegame/components.rs @@ -2,9 +2,11 @@ use crate::prelude::*; use std::fs; use std::path::PathBuf; +/// Resource containing the path to the current save file. #[derive(Resource, Clone, Debug)] pub struct SavegamePath(pub PathBuf); +/// Metadata about a savegame. #[derive(Debug)] pub struct SavegameInfo { pub path: SavegamePath, @@ -13,11 +15,13 @@ pub struct SavegameInfo { pub completed_focus: u32, } +/// Helper for partial JSON deserialization. #[derive(Deserialize)] struct PartialSaveData { session_tracker: PartialSessionTracker, } +/// Helper for partial JSON deserialization of session stats. #[derive(Deserialize)] struct PartialSessionTracker { completed_focus_phases: u32, @@ -26,6 +30,7 @@ struct PartialSessionTracker { } impl SavegamePath { + /// Constructs a new path for a specific save index. pub fn new(index: u32) -> Self { let base_path = get_internal_path().unwrap_or_else(|| { println!( @@ -41,6 +46,7 @@ impl SavegamePath { Self(base_path.join(format!("savegame-{}.json", index))) } + /// Lists all available savegames. pub fn list() -> Vec { let mut savegames = Vec::new(); @@ -88,6 +94,7 @@ impl SavegamePath { savegames } + /// Returns a path for a new savegame (incremented index). pub fn next() -> Self { let savegames = Self::list(); let next_index = savegames.last().map(|s| s.index + 1).unwrap_or(0); @@ -95,11 +102,13 @@ impl SavegamePath { } } +/// Markers for savegame UI. #[derive(Component)] pub enum RootMarker { PopupSavegameLoad, } +/// Buttons for savegame management. #[derive(Component)] pub enum ButtonType { SavegameLoad { savegame_path: SavegamePath }, diff --git a/src/features/savegame/messages.rs b/src/features/savegame/messages.rs index 3c03fad..6dbfdfa 100644 --- a/src/features/savegame/messages.rs +++ b/src/features/savegame/messages.rs @@ -1,7 +1,9 @@ use crate::prelude::*; +/// Trigger to save the current game. #[derive(Message)] pub struct SavegameDumpMessage; +/// Trigger to load a game from disk. #[derive(Message)] pub struct SavegameLoadMessage; diff --git a/src/features/savegame/mod.rs b/src/features/savegame/mod.rs index 3be631f..ca6441b 100644 --- a/src/features/savegame/mod.rs +++ b/src/features/savegame/mod.rs @@ -10,6 +10,7 @@ pub mod components; pub mod messages; pub mod ui; +/// Plugin dealing with savegame loading and saving. pub struct SavegamePlugin; impl Plugin for SavegamePlugin { @@ -25,6 +26,7 @@ impl Plugin for SavegamePlugin { } } +/// The structure of a save file. #[derive(Serialize, Deserialize)] struct SaveData { grid_width: u32, @@ -37,6 +39,7 @@ struct SaveData { inventory: Vec, } +/// Serializes game state and writes it to a file. fn dump_savegame( mut messages: MessageReader, save_path: Res, @@ -106,6 +109,7 @@ fn dump_savegame( } } +/// Reads a save file and restores game state. fn load_savegame( mut commands: Commands, mut messages: MessageReader, @@ -174,7 +178,7 @@ fn load_savegame( } } -/// Resets all components/resources loaded by `load_savegame` +/// Resets all components/resources loaded by `load_savegame`. fn reset_savegame( mut commands: Commands, grid: Res, diff --git a/src/features/savegame/ui/load.rs b/src/features/savegame/ui/load.rs index 729cea4..8871061 100644 --- a/src/features/savegame/ui/load.rs +++ b/src/features/savegame/ui/load.rs @@ -1,6 +1,7 @@ use super::super::components::{ButtonType, RootMarker}; use crate::{features::savegame::messages::SavegameLoadMessage, prelude::*}; +/// Spawns the "Load Game" popup. pub fn spawn_load_popup(commands: &mut Commands) { spawn_popup( commands, @@ -88,6 +89,7 @@ pub fn spawn_load_popup(commands: &mut Commands) { ); } +/// Handles interactions in the load popup. pub fn load_popup_handler( mut commands: Commands, mut next_state: ResMut>, diff --git a/src/features/wonderevent/components.rs b/src/features/wonderevent/components.rs index 822f738..43c232a 100644 --- a/src/features/wonderevent/components.rs +++ b/src/features/wonderevent/components.rs @@ -1,5 +1,6 @@ use crate::prelude::*; +/// Defines the bounds of the grid for the server. #[derive(Debug, Serialize, Deserialize, PartialEq, Clone)] pub struct MaxFieldSize { #[serde(rename = "minX")] @@ -12,12 +13,14 @@ pub struct MaxFieldSize { pub max_y: u32, } +/// Coordinates for a wonder event target. #[derive(Debug, Serialize, Deserialize, PartialEq, Clone)] pub struct Position { pub x: u32, pub y: u32, } +/// WebSocket messages exchanged with the wonder event server. #[derive(Debug, Serialize, Deserialize, PartialEq, Clone)] #[serde(tag = "messageType")] pub enum WonderEventMessage { diff --git a/src/features/wonderevent/mod.rs b/src/features/wonderevent/mod.rs index 164eabe..aa7dd08 100644 --- a/src/features/wonderevent/mod.rs +++ b/src/features/wonderevent/mod.rs @@ -9,20 +9,25 @@ use url::Url; pub mod components; +/// Plugin managing random wonder events via WebSocket. pub struct WonderEventPlugin; +/// Message to initiate a wonder event request. #[derive(Message)] pub struct RequestWonderEvent { pub url_str: String, pub max_field_size: MaxFieldSize, } +/// Resource holding the channel sender for wonder events. #[derive(Resource)] pub struct WonderEventSender(pub Sender); +/// Resource holding the channel receiver for wonder events. #[derive(Resource)] pub struct WonderEventReceiver(pub Mutex>); +/// Component for animated floating text effects. #[derive(Component)] struct FloatingText { timer: Timer, @@ -49,11 +54,13 @@ impl Plugin for WonderEventPlugin { } } +/// Tracks if an event has already triggered this phase. #[derive(Resource, Default)] struct WonderEventState { triggered_for_current_phase: bool, } +/// Checks if the focus phase is halfway through to trigger an event. fn check_halfway_focus( mut state: ResMut, phase_res: Res, @@ -95,6 +102,7 @@ fn check_halfway_focus( } } +/// Spawns a thread to request a wonder event from the server. fn handle_wonder_event_trigger( mut events: MessageReader, sender: Res, @@ -159,6 +167,7 @@ fn handle_wonder_event_trigger( } } +/// Processes responses from the wonder event server. fn handle_wonder_event_response( receiver: Res, grid: Res, @@ -241,6 +250,7 @@ fn handle_wonder_event_response( } } +/// Updates floating text positions and lifetimes. fn animate_floating_text( mut commands: Commands, time: Res