Vladimir nett00n Budylnikov
742e4251fb
- Fix memory leaks in match3_gameplay.gd with proper queue_free() usage - Add comprehensive error handling and fallback mechanisms to SettingsManager - Resolve scene loading race conditions in GameManager with state protection - Remove problematic static variables from tile.gd, replace with instance-based approach - Consolidate duplicate debug menu classes into shared DebugMenuBase - Add input validation across all user input paths for security and stability
387 lines
16 KiB
Markdown
387 lines
16 KiB
Markdown
# Skelly - Project Structure Map
|
|
|
|
## Overview
|
|
Skelly is a Godot 4.4 game project featuring multiple gameplay modes with skeleton character themes. The project supports match-3 puzzle gameplay with planned clickomania gameplay through a modular gameplay architecture. It follows a modular structure with clear separation between scenes, autoloads, assets, and data.
|
|
|
|
## Project Root Structure
|
|
|
|
```
|
|
skelly/
|
|
├── .claude/ # Claude Code configuration
|
|
├── .godot/ # Godot engine generated files (ignored)
|
|
├── assets/ # Game assets (sprites, audio, textures)
|
|
├── data/ # Game data and configuration files
|
|
├── docs/ # Documentation
|
|
├── localization/ # Internationalization files
|
|
├── scenes/ # Godot scenes (.tscn) and scripts (.gd)
|
|
├── src/ # Source code organization
|
|
├── tests/ # Test scripts and validation utilities
|
|
├── project.godot # Main Godot project configuration
|
|
└── icon.svg # Project icon
|
|
```
|
|
|
|
## Core Architecture
|
|
|
|
### Autoloads (Global Singletons)
|
|
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 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`)
|
|
- Controls music and sound effects
|
|
- Manages audio bus configuration
|
|
- Uses: `data/default_bus_layout.tres`
|
|
|
|
3. **GameManager** (`src/autoloads/GameManager.gd`)
|
|
- 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`)
|
|
- Language switching functionality
|
|
- Works with Godot's built-in internationalization system
|
|
- Uses translation files in `localization/`
|
|
|
|
5. **DebugManager** (`src/autoloads/DebugManager.gd`)
|
|
- 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
|
|
|
|
### Main Scenes
|
|
```
|
|
main.tscn (Entry Point)
|
|
├── PressAnyKeyScreen.tscn
|
|
├── MainMenu.tscn
|
|
└── SettingsMenu.tscn
|
|
|
|
game.tscn (Gameplay Container)
|
|
├── GameplayContainer (Dynamic content)
|
|
├── UI/ScoreDisplay
|
|
├── BackButton
|
|
└── DebugToggle
|
|
```
|
|
|
|
### Game Flow
|
|
1. **Main Scene** (`scenes/main/main.tscn` + `Main.gd`)
|
|
- Application entry point
|
|
- Manages "Press Any Key" screen
|
|
- Transitions to main menu
|
|
- Dynamic menu loading system
|
|
|
|
2. **Press Any Key Screen** (`scenes/main/PressAnyKeyScreen.tscn` + `PressAnyKeyScreen.gd`)
|
|
- Initial splash screen
|
|
- Input detection for any key/button
|
|
- Signals to main scene for transition
|
|
|
|
3. **Main Menu** (`scenes/ui/MainMenu.tscn` + `MainMenu.gd`)
|
|
- Primary navigation hub
|
|
- Start game, settings, quit options
|
|
- Connected to GameManager for scene transitions
|
|
|
|
4. **Settings Menu** (`scenes/ui/SettingsMenu.tscn` + `SettingsMenu.gd`)
|
|
- User preferences interface
|
|
- Language selection
|
|
- Audio volume controls
|
|
- Connected to SettingsManager and AudioManager
|
|
|
|
5. **Game Scene** (`scenes/game/game.tscn` + `game.gd`)
|
|
- Main gameplay container with modular gameplay system
|
|
- Dynamic loading of gameplay modes into GameplayContainer
|
|
- Global score management and display
|
|
- Back button for navigation to main menu
|
|
- Gameplay mode switching support (Space+Enter debug key)
|
|
- Bridge between UI and individual gameplay implementations
|
|
|
|
### UI Components
|
|
```
|
|
scenes/ui/
|
|
├── DebugToggle.tscn + DebugToggle.gd # Now 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
|
|
└── SettingsMenu.tscn + SettingsMenu.gd # With comprehensive input validation
|
|
```
|
|
|
|
**Code Quality Improvements:**
|
|
- **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
|
|
|
|
## Modular Gameplay System
|
|
|
|
The game now uses a modular gameplay architecture where different game modes can be dynamically loaded into the main game scene.
|
|
|
|
### Gameplay Architecture
|
|
- **Main Game Scene** (`scenes/game/game.gd`) - Container and coordinator
|
|
- **Gameplay Directory** (`scenes/game/gameplays/`) - Individual gameplay implementations
|
|
- **Dynamic Loading** - Gameplay scenes loaded at runtime based on mode selection
|
|
- **Signal-based Communication** - Gameplays communicate with main scene via signals
|
|
|
|
### Current Gameplay Modes
|
|
|
|
#### Match-3 Mode (`scenes/game/gameplays/match3_gameplay.tscn`)
|
|
1. **Match3 Controller** (`scenes/game/gameplays/match3_gameplay.gd`)
|
|
- 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 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
|
|
- Will integrate with same scoring and UI systems as match-3
|
|
|
|
### Debug System
|
|
- Global debug state via DebugManager with proper initialization
|
|
- Debug toggle available on all major scenes (MainMenu, SettingsMenu, PressAnyKeyScreen, Game)
|
|
- Match-3 specific debug UI panel with gem count controls and difficulty presets
|
|
- Gem count controls (+/- buttons) with difficulty presets (Easy: 3, Normal: 5, Hard: 8)
|
|
- Board reroll functionality for testing
|
|
- F12 toggle support across all scenes
|
|
- Debug prints reduced in production code
|
|
|
|
## Asset Organization
|
|
|
|
### Audio (`assets/audio/`)
|
|
```
|
|
audio/
|
|
├── music/ # Background music files
|
|
└── sfx/ # Sound effects
|
|
```
|
|
|
|
### Visual Assets (`assets/`)
|
|
```
|
|
assets/
|
|
├── audio/
|
|
│ ├── music/ # Background music files
|
|
│ └── sfx/ # Sound effects
|
|
├── sprites/
|
|
│ ├── characters/skeleton/ # Character artwork
|
|
│ ├── gems/ # Match-3 gem sprites
|
|
│ └── ui/ # User interface elements
|
|
├── textures/
|
|
│ └── backgrounds/ # Background images
|
|
├── fonts/ # Custom fonts
|
|
└── sources.yaml # Asset metadata and attribution
|
|
```
|
|
|
|
### Asset Management (`assets/sources.yaml`)
|
|
**REQUIRED**: Every asset added to the project must be documented in `assets/sources.yaml` with:
|
|
- **Source information** - Where the asset came from (URL, artist, store, etc.)
|
|
- **License details** - Usage rights, attribution requirements, commercial permissions
|
|
- **Attribution text** - Exact text to use for credits if required
|
|
- **Modification notes** - Any changes made to the original asset
|
|
- **Usage context** - Where and how the asset is used in the project
|
|
|
|
**Example format:**
|
|
```yaml
|
|
audio:
|
|
music:
|
|
"Space Horror InGame Music (Exploration) _Clement Panchout.wav":
|
|
source: "https://freesound.org/people/ClementPanchout/"
|
|
license: "CC BY 4.0"
|
|
attribution: "Space Horror InGame Music by Clement Panchout"
|
|
modifications: "Converted to WAV, loop points adjusted"
|
|
usage: "Background music for all gameplay scenes"
|
|
|
|
sprites:
|
|
gems:
|
|
"gem_blue.png":
|
|
source: "Created in-house"
|
|
license: "Project proprietary"
|
|
attribution: "Skelly development team"
|
|
modifications: "None"
|
|
usage: "Match-3 blue gem sprite"
|
|
```
|
|
|
|
## Data & Configuration
|
|
|
|
### 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
|
|
- Input map configurations
|
|
- **Gem Movement Controls**:
|
|
- `select_gem`: Enter key, Gamepad A button
|
|
- `move_up/down/left/right`: Arrow keys, WASD, Gamepad D-pad
|
|
- Rendering settings
|
|
- Audio bus references
|
|
|
|
## Key Dependencies & Connections
|
|
|
|
### Signal Connections
|
|
```
|
|
PressAnyKeyScreen --[any_key_pressed]--> Main
|
|
MainMenu --[open_settings]--> Main
|
|
SettingsMenu --[back_to_main_menu]--> Main
|
|
DebugManager --[debug_toggled]--> All scenes with DebugToggle
|
|
GameplayModes --[score_changed]--> Game Scene
|
|
Game Scene --[score updates]--> UI/ScoreDisplay
|
|
```
|
|
|
|
### Scene References
|
|
```
|
|
GameManager --> main.tscn, game.tscn
|
|
GameManager --> scenes/game/gameplays/*.tscn (via GAMEPLAY_SCENES constant)
|
|
Main --> MainMenu.tscn, SettingsMenu.tscn
|
|
Game --> GameplayContainer (dynamic loading of gameplay scenes)
|
|
Game --> scenes/game/gameplays/match3_gameplay.tscn, clickomania_gameplay.tscn
|
|
```
|
|
|
|
### Asset Dependencies
|
|
```
|
|
AudioManager --> assets/audio/music/
|
|
SettingsManager --> localization/languages.json
|
|
AudioManager --> data/default_bus_layout.tres
|
|
Asset Management --> assets/sources.yaml (required for all assets)
|
|
```
|
|
|
|
## 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", "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
|
|
```
|
|
[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
|
|
- 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
|
|
- Internationalization support for English/Russian
|
|
|
|
### Architecture Patterns
|
|
1. **Autoload Pattern** - Global managers as singletons
|
|
2. **Signal-Based Communication** - Loose coupling between components
|
|
3. **Modular Gameplay Architecture** - Dynamic loading of gameplay modes
|
|
4. **Scene Composition** - Modular scene loading and management
|
|
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.
|