feature/match3/move-gems (#7)

Reviewed-on: #7
Co-authored-by: Vladimir nett00n Budylnikov <git@nett00n.org>
Co-committed-by: Vladimir nett00n Budylnikov <git@nett00n.org>

docs/MAP.md

@@ -26,9 +26,11 @@ skelly/
 Located in `src/autoloads/`, these scripts are automatically loaded when the game starts:
 
 1. **SettingsManager** (`src/autoloads/SettingsManager.gd`)
-   - Manages game settings and user preferences
-   - Handles configuration file I/O
-   - Provides language selection functionality
+   - Manages game settings and user preferences with comprehensive error handling
+   - Robust configuration file I/O with fallback mechanisms
+   - Input validation for all setting values and range checking
+   - JSON parsing with detailed error recovery and default language fallback
+   - Provides language selection functionality with validation
    - Dependencies: `localization/languages.json`
 
 2. **AudioManager** (`src/autoloads/AudioManager.gd`)
@@ -37,10 +39,11 @@ Located in `src/autoloads/`, these scripts are automatically loaded when the gam
    - Uses: `data/default_bus_layout.tres`
 
 3. **GameManager** (`src/autoloads/GameManager.gd`)
-   - Central game state management and gameplay mode coordination
-   - Scene transitions between main/game scenes
-   - Gameplay mode selection and launching (match3, clickomania)
-   - Navigation flow control
+   - Central game state management and gameplay mode coordination with race condition protection
+   - Safe scene transitions with concurrent change prevention and validation
+   - Gameplay mode selection and launching with input validation (match3, clickomania)
+   - Error handling for scene loading failures and fallback mechanisms
+   - Navigation flow control with state protection
    - References: main.tscn, game.tscn and individual gameplay scenes
 
 4. **LocalizationManager** (`src/autoloads/LocalizationManager.gd`)
@@ -107,12 +110,23 @@ game.tscn (Gameplay Container)
 ### UI Components
 ```
 scenes/ui/
-├── DebugToggle.tscn + DebugToggle.gd    # Now available on all major scenes
-├── DebugMenu.tscn + DebugMenu.gd        # Match-3 debug controls
-├── MainMenu.tscn + MainMenu.gd
-└── SettingsMenu.tscn + SettingsMenu.gd
+├── components/
+│   └── ValueStepper.tscn + ValueStepper.gd     # Reusable arrow-based value selector
+├── DebugToggle.tscn + DebugToggle.gd           # Available on all major scenes
+├── DebugMenuBase.gd                            # Unified base class for debug menus
+├── DebugMenu.tscn + DebugMenu.gd               # Global debug controls (extends DebugMenuBase)
+├── Match3DebugMenu.gd                          # Match-3 specific debug controls (extends DebugMenuBase)
+├── MainMenu.tscn + MainMenu.gd                 # With gamepad/keyboard navigation
+└── SettingsMenu.tscn + SettingsMenu.gd         # With comprehensive input validation
 ```
 
+**Code Quality Improvements:**
+- **ValueStepper Component**: Reusable arrow-based selector for discrete values (language, resolution, difficulty)
+- **DebugMenuBase.gd**: Eliminates 90% code duplication between debug menu classes
+- **Input Validation**: All user inputs are validated and sanitized before processing
+- **Error Recovery**: Robust error handling with fallback mechanisms throughout UI
+- **Navigation Support**: Full gamepad/keyboard navigation across all menus
+
 ## Modular Gameplay System
 
 The game now uses a modular gameplay architecture where different game modes can be dynamically loaded into the main game scene.
@@ -127,18 +141,31 @@ The game now uses a modular gameplay architecture where different game modes can
 
 #### Match-3 Mode (`scenes/game/gameplays/match3_gameplay.tscn`)
 1. **Match3 Controller** (`scenes/game/gameplays/match3_gameplay.gd`)
-   - Grid management (8x8 default)
-   - Match detection algorithms
-   - Tile dropping and refilling
-   - Gem pool management (3-8 gem types)
-   - Debug UI integration
+   - Grid management (8x8 default) with memory-safe node cleanup
+   - Match detection algorithms with bounds checking and null validation
+   - Tile dropping and refilling with proper signal connections
+   - Gem pool management (3-8 gem types) with instance-based architecture
+   - Debug UI integration with input validation
    - Score reporting via `score_changed` signal
+   - **Memory Safety**: Uses `queue_free()` with proper frame waiting to prevent crashes
+   - **Gem Movement System**: Keyboard and gamepad input for tile selection and swapping
+     - State machine: WAITING → SELECTING → SWAPPING → PROCESSING
+     - Adjacent tile validation (horizontal/vertical neighbors only)
+     - Match validation (swaps must create matches or revert)
+     - Smooth tile position animations with Tween
+     - Cursor-based navigation with visual highlighting and bounds checking
 
 2. **Tile System** (`scenes/game/gameplays/tile.gd` + `Tile.tscn`)
-   - Individual tile behavior
-   - Gem type management
-   - Visual representation
+   - Individual tile behavior with instance-based architecture (no global state)
+   - Gem type management with input validation and bounds checking
+   - Visual representation with scaling and color modulation
    - Group membership for coordination
+   - **Visual Feedback System**: Multi-state display for game interaction
+     - Selection visual feedback (scale and color modulation)
+     - State management (normal, highlighted, selected)
+     - Signal-based communication with gameplay controller
+     - Smooth animations with Tween system
+   - **Memory Safety**: Proper resource management and cleanup
 
 #### Clickomania Mode (`scenes/game/gameplays/clickomania_gameplay.tscn`)
 - Planned implementation for clickomania-style gameplay
@@ -288,8 +315,18 @@ DebugManager.log_error("Failed to load audio resource")
 
 # Logging with custom categories for better organization
 DebugManager.log_debug("Grid regenerated with 64 tiles", "Match3")
-DebugManager.log_info("Language changed to: en", "SettingsManager")
+DebugManager.log_info("Language changed to: en", "Settings")
 DebugManager.log_error("Invalid scene path provided", "GameManager")
+
+# Standard categories in use:
+# - GameManager: Scene transitions, gameplay mode management
+# - Match3: Match-3 gameplay, grid operations, tile interactions
+# - Settings: Settings management, language changes
+# - Game: Main game scene, mode switching
+# - MainMenu: Main menu interactions
+# - PressAnyKey: Press any key screen
+# - Clickomania: Clickomania gameplay mode
+# - DebugMenu: Debug menu operations
 ```
 
 ### Log Format
@@ -322,6 +359,16 @@ if DebugManager._should_log(DebugManager.LogLevel.DEBUG):
 ### Current Implementation Status
 - Modular gameplay system with dynamic loading architecture
 - Match-3 system with 8x8 grid and configurable gem pools
+- **Interactive Match-3 Gameplay**: Keyboard and gamepad gem movement system
+  - Keyboard: Arrow key navigation with Enter to select/confirm (WASD also supported)
+  - Gamepad: D-pad navigation with A button to select/confirm
+  - Visual feedback: Tile highlighting, selection indicators, smooth animations
+  - Game logic: Adjacent-only swaps, match validation, automatic revert on invalid moves
+  - State machine: WAITING → SELECTING → SWAPPING → PROCESSING states
+- **Comprehensive Logging System**: All print()/push_error() statements migrated to DebugManager
+  - Structured logging with categories: GameManager, Match3, Settings, Game, MainMenu, etc.
+  - Multiple log levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
+  - Debug mode integration with level filtering
 - Global scoring system integrated across gameplay modes
 - Debug UI system with F12 toggle functionality across all major scenes
 - Scene transition system via GameManager with gameplay mode support