add logging

docs/MAP.md

@@ -15,8 +15,9 @@ skelly/
 ├── localization/               # Internationalization files
 ├── scenes/                     # Godot scenes (.tscn) and scripts (.gd)
 ├── src/                        # Source code organization
-├── project.godot              # Main Godot project configuration
-└── icon.svg                   # Project icon
+├── tests/                      # Test scripts and validation utilities
+├── project.godot               # Main Godot project configuration
+└── icon.svg                    # Project icon
 ```
 
 ## Core Architecture
@@ -48,10 +49,13 @@ Located in `src/autoloads/`, these scripts are automatically loaded when the gam
    - Uses translation files in `localization/`
 
 5. **DebugManager** (`src/autoloads/DebugManager.gd`)
-   - Global debug state management
+   - Global debug state management and centralized logging system
    - Debug UI visibility control
    - F12 toggle functionality
    - Signal-based debug system
+   - Structured logging with configurable log levels (TRACE, DEBUG, INFO, WARN, ERROR, FATAL)
+   - Timestamp-based log formatting with category support
+   - Runtime log level filtering for development and production builds
 
 ## Scene Hierarchy & Flow
 
@@ -175,11 +179,23 @@ assets/
 ### Game Data (`data/`)
 - `default_bus_layout.tres` - Audio bus configuration for Godot
 
+### Documentation (`docs/`)
+- `MAP.md` - Project architecture and structure overview
+- `CLAUDE.md` - Claude Code development guidelines
+- `CODE_OF_CONDUCT.md` - Coding standards and best practices
+- `TESTING.md` - Testing guidelines and conventions
+
 ### Localization (`localization/`)
 - `languages.json` - Available language definitions
 - `MainStrings.en.translation` - English translations
 - `MainStrings.ru.translation` - Russian translations
 
+### Testing & Validation (`tests/`)
+- `test_logging.gd` - DebugManager logging system validation
+- `README.md` - Brief directory overview (see docs/TESTING.md for full guidelines)
+- Future test scripts for individual components and integration testing
+- Temporary test utilities for development and debugging
+
 ### Project Configuration
 - `project.godot` - Main Godot project settings
   - Autoload definitions
@@ -215,6 +231,58 @@ SettingsManager --> localization/languages.json
 AudioManager --> data/default_bus_layout.tres
 ```
 
+## Logging System
+
+The project uses a centralized logging system implemented in DebugManager for consistent, structured logging throughout the application.
+
+### Log Levels
+```
+TRACE (0)  - Detailed execution tracing (debug mode only)
+DEBUG (1)  - Development debugging information (debug mode only)
+INFO (2)   - General application information (always visible)
+WARN (3)   - Warning messages that don't break functionality
+ERROR (4)  - Error conditions that may affect functionality
+FATAL (5)  - Critical errors that may cause application failure
+```
+
+### Usage Examples
+```gdscript
+# Basic logging with automatic categorization
+DebugManager.log_info("Game started successfully")
+DebugManager.log_warn("Settings file not found, using defaults")
+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_error("Invalid scene path provided", "GameManager")
+```
+
+### Log Format
+```
+[timestamp] LEVEL [category]: message
+Example: [2025-09-24T10:48:08] INFO [GameManager]: Loading main scene
+```
+
+### Runtime Configuration
+```gdscript
+# Set minimum log level (filters out lower priority messages)
+DebugManager.set_log_level(DebugManager.LogLevel.WARN)
+
+# Get current log level
+var current_level = DebugManager.get_log_level()
+
+# Check if a specific level would be logged
+if DebugManager._should_log(DebugManager.LogLevel.DEBUG):
+    # Expensive debug calculation here
+```
+
+### Integration with Godot Systems
+- **WARN/ERROR/FATAL** levels automatically call `push_warning()` and `push_error()`
+- **TRACE/DEBUG** levels only display when debug mode is enabled
+- **INFO** and higher levels always display regardless of debug mode
+- All levels respect the configured minimum log level threshold
+
 ## Development Notes
 
 ### Current Implementation Status
@@ -233,5 +301,6 @@ AudioManager --> data/default_bus_layout.tres
 5. **Data-Driven Configuration** - JSON for settings and translations
 6. **Component Architecture** - Reusable UI and game components
 7. **Centralized Scoring System** - Global score management across gameplay modes
+8. **Structured Logging System** - Centralized logging with level-based filtering and formatted output
 
-This structure provides a clean separation of concerns, making the codebase maintainable and extensible for future features.
+This structure provides a clean separation of concerns, making the codebase maintainable and extensible for future features.