docs: document player character (Pom) and input handling (#65)

src/features/input/mod.rs

@@ -11,6 +11,7 @@ use bevy::window::PrimaryWindow;
 
 pub mod utils;
 
+/// Handles user input for the game.
 pub struct InputPlugin;
 
 impl Plugin for InputPlugin {
@@ -45,6 +46,7 @@ impl Plugin for InputPlugin {
     }
 }
 
+/// Handles right-click movement input.
 fn move_click(
     mut move_messages: MessageWriter<MoveMessage>,
     mouse_btn: Res<ButtonInput<MouseButton>>,
@@ -75,6 +77,7 @@ fn move_click(
     }
 }
 
+/// Handles left-click interactions (tile selection, shovel).
 fn interact_click(
     mut tile_click_messages: MessageWriter<TileClickMessage>,
     mouse_btn: Res<ButtonInput<MouseButton>>,
@@ -174,6 +177,7 @@ fn interact_click(
         }
     }
 }
+/// Handles debug interactions (shift + left click).
 fn debug_click(
     mouse_btn: Res<ButtonInput<MouseButton>>,
     keys: Res<ButtonInput<KeyCode>>,
@@ -220,6 +224,7 @@ fn debug_click(
     }
 }
 
+/// Pauses/resumes the phase timer on Space press.
 fn phase_timer_pause(
     mut pause_messages: MessageWriter<PhaseTimerPauseMessage>,
     keys: Res<ButtonInput<KeyCode>>,
@@ -229,12 +234,14 @@ fn phase_timer_pause(
     }
 }
 
+/// Skips to the next phase on Enter press.
 fn next_phase(mut messages: MessageWriter<NextPhaseMessage>, keys: Res<ButtonInput<KeyCode>>) {
     if keys.just_pressed(KeyCode::Enter) {
         messages.write(NextPhaseMessage);
     }
 }
 
+/// Opens the shop on 'P' press.
 fn shop_keybind(
     keys: Res<ButtonInput<KeyCode>>,
     mut commands: Commands,
@@ -254,6 +261,7 @@ fn shop_keybind(
     }
 }
 
+/// Closes popups on Escape press.
 fn popup_keybind(
     mut close_popup_messages: MessageWriter<ClosePopupMessage>,
     keys: Res<ButtonInput<KeyCode>>,

src/features/input/utils.rs

@@ -1,6 +1,7 @@
 use crate::prelude::*;
 use bevy::window::PrimaryWindow;
 
+/// Converts mouse position to grid coordinates, respecting UI blocks.
 pub fn mouse_to_grid(
     window: Single<&Window, With<PrimaryWindow>>,
     camera: Single<(&Camera, &GlobalTransform), With<Camera2d>>,

src/features/pom/actions.rs

@@ -1,5 +1,6 @@
 use crate::{features::phase::components::SessionTracker, prelude::*};
 
+/// Actions Pom can perform on tiles.
 #[derive(Clone, Debug, PartialEq)]
 pub enum InteractionAction {
     Plant(ItemType),

src/features/pom/components.rs

@@ -2,20 +2,24 @@ use crate::features::pom::actions::InteractionAction;
 use crate::prelude::*;
 use std::collections::VecDeque;
 
+/// Marker component for the main character.
 #[derive(Component)]
 pub struct Pom;
 
+/// Current logical position on the grid.
 #[derive(Component, Serialize, Deserialize, Clone, Copy, Default)]
 pub struct GridPosition {
     pub x: u32,
     pub y: u32,
 }
 
+/// Queue of grid positions to visit.
 #[derive(Component, Default)]
 pub struct PathQueue {
     pub steps: VecDeque<(u32, u32)>,
 }
 
+/// Movement direction state for animation.
 #[derive(Component, Default)]
 pub enum MovingState {
     #[default]
@@ -38,6 +42,7 @@ impl MovingState {
     }
 }
 
+/// Target tile and action for pending interaction.
 #[derive(Component, Default)]
 pub struct InteractionTarget {
     pub target: Option<(u32, u32)>,

src/features/pom/messages.rs

@@ -1,17 +1,20 @@
 use crate::features::pom::actions::InteractionAction;
 use crate::prelude::*;
 
+/// Request to move Pom to a specific tile.
 #[derive(Message)]
 pub struct MoveMessage {
     pub x: u32,
     pub y: u32,
 }
 
+/// Notification that a move request was invalid.
 #[derive(Message)]
 pub struct InvalidMoveMessage {
     pub message: String,
 }
 
+/// Request to start an interaction sequence.
 #[derive(Message)]
 pub struct InteractStartMessage {
     pub x: u32,
@@ -19,6 +22,7 @@ pub struct InteractStartMessage {
     pub action: InteractionAction,
 }
 
+/// Notification that a tile was clicked (requesting context menu).
 #[derive(Message)]
 pub struct TileClickMessage {
     pub x: u32,

src/features/pom/mod.rs

@@ -11,6 +11,7 @@ pub mod messages;
 pub mod ui;
 pub mod utils;
 
+/// Plugin controlling the main character (Pom) behavior.
 pub struct PomPlugin;
 
 impl Plugin for PomPlugin {
@@ -34,6 +35,7 @@ impl Plugin for PomPlugin {
     }
 }
 
+/// Draws the path Pom will follow using gizmos.
 fn draw_path(
     mut gizmos: Gizmos,
     query: Query<(&Transform, &PathQueue), With<Pom>>,
@@ -65,6 +67,7 @@ fn draw_path(
     }
 }
 
+/// Spawns the Pom character.
 fn setup(mut commands: Commands, asset_server: Res<AssetServer>, config: Res<GameConfig>) {
     commands.spawn((
         Pom,
@@ -87,12 +90,14 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>, config: Res<Gam
     ));
 }
 
+/// Despawns the Pom character.
 fn cleanup(mut commands: Commands, pom_query: Query<Entity, With<Pom>>) {
     for pom_entity in pom_query.iter() {
         commands.entity(pom_entity).despawn();
     }
 }
 
+/// Calculates path for manual movement requests.
 fn handle_move(
     mut move_messages: MessageReader<MoveMessage>,
     mut invalid_move_messages: MessageWriter<InvalidMoveMessage>,
@@ -127,6 +132,7 @@ fn handle_move(
     }
 }
 
+/// Calculates path to interaction target.
 fn handle_interact(
     mut interact_messages: MessageReader<InteractStartMessage>,
     mut pom_query: Query<(&GridPosition, &mut PathQueue, &mut InteractionTarget)>,
@@ -184,6 +190,7 @@ fn handle_interact(
     }
 }
 
+/// Executes the pending interaction when target is reached.
 pub fn perform_interaction(
     mut pom_query: Query<(&GridPosition, &mut InteractionTarget, &PathQueue)>,
     grid: Res<Grid>,
@@ -239,6 +246,7 @@ pub fn perform_interaction(
     }
 }
 
+/// Moves the Pom character along the path.
 fn move_pom(
     time: Res<Time>,
     mut query: Query<(
@@ -288,6 +296,7 @@ fn move_pom(
     }
 }
 
+/// Updates Pom animation based on movement state.
 fn update_pom(asset_server: Res<AssetServer>, mut query: Query<(&MovingState, &mut AseAnimation)>) {
     for (moving_state, mut animation) in query.iter_mut() {
         match moving_state {

src/features/pom/ui/context_menu.rs

@@ -4,11 +4,13 @@ use crate::features::ui::utils::ui_blocks;
 use crate::prelude::*;
 use bevy::window::PrimaryWindow;
 
+/// Marker for context menu UI root.
 #[derive(Component)]
 pub enum RootMarker {
     ContextMenu,
 }
 
+/// Buttons available in the context menu.
 #[derive(Component)]
 pub enum ButtonType {
     Interact {
@@ -19,6 +21,7 @@ pub enum ButtonType {
     Cancel,
 }
 
+/// Spawns the context menu at the clicked tile position.
 pub fn open_context_menu(
     mut commands: Commands,
     mut tile_click_messages: MessageReader<TileClickMessage>,
@@ -87,6 +90,7 @@ pub fn open_context_menu(
     }
 }
 
+/// Closes context menu when clicking elsewhere.
 pub fn click_outside_context_menu(
     mut commands: Commands,
     mouse_btn: Res<ButtonInput<MouseButton>>,
@@ -107,6 +111,7 @@ pub fn click_outside_context_menu(
     }
 }
 
+/// Handles context menu button clicks.
 pub fn buttons(
     mut commands: Commands,
     mut button_query: Query<(&Interaction, &ButtonType), (Changed<Interaction>, With<Button>)>,
@@ -133,6 +138,7 @@ pub fn buttons(
     }
 }
 
+/// Closes context menu on ClosePopupMessage.
 pub fn close_context_menu(
     mut commands: Commands,
     mut close_popup_reader: MessageReader<ClosePopupMessage>,

src/features/pom/ui/mod.rs

@@ -2,6 +2,7 @@ use crate::prelude::*;
 
 pub mod context_menu;
 
+/// Plugin for Pom-related UI (context menu).
 pub struct PomUiPlugin;
 
 impl Plugin for PomUiPlugin {

src/features/pom/utils.rs

@@ -2,6 +2,7 @@ use crate::prelude::*;
 use std::cmp::Ordering;
 use std::collections::{BinaryHeap, HashMap, HashSet, VecDeque};
 
+/// A star pathfinding node.
 #[derive(Copy, Clone, Eq, PartialEq)]
 pub struct Node {
     x: u32,
@@ -25,11 +26,12 @@ impl PartialOrd for Node {
     }
 }
 
+/// Calculates Manhattan distance between two points.
 pub fn manhattan_distance(x1: u32, y1: u32, x2: u32, y2: u32) -> u32 {
     x1.abs_diff(x2) + y1.abs_diff(y2)
 }
 
-/// Checks if Pom would be trapped in a small, isolated area if a specific tile is blocked
+/// Checks if Pom would be trapped in a small, isolated area if a specific tile is blocked.
 pub fn is_trapped<F>(
     start: (u32, u32),
     blocked_pos: (u32, u32),
@@ -98,6 +100,7 @@ where
     visited.len() < min_safe_area
 }
 
+/// Finds a path from start to end using A* algorithm.
 pub fn find_path(
     start: (u32, u32),
     end: (u32, u32),