nett00n/skelly
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feature/match3/move-gems (#7)

Browse Source 
Reviewed-on: #7
Co-authored-by: Vladimir nett00n Budylnikov <git@nett00n.org>
Co-committed-by: Vladimir nett00n Budylnikov <git@nett00n.org>
This commit is contained in:
Vladimir nett00n Budylnikov
2025-09-25 11:48:08 +02:00
committed by nett00n
parent e76297b3f3
commit ea8c85d7ad
53 changed files with 2335 additions and 524 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/CLAUDE.md
View File

@@ -21,6 +21,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- Match-3 debug controls include gem count adjustment and board reroll
- Difficulty presets: Easy (3 gems), Normal (5 gems), Hard (8 gems)
- Gameplay mode switching: Space+Enter in game scene switches between match-3 and clickomania modes
- **Match-3 Gem Movement Testing**:
- Keyboard: Arrow keys or WASD to navigate, Enter to select/confirm
- Gamepad: D-pad to navigate, A button to select/confirm
- Visual feedback: Selected tiles glow brighter with scale and color effects
- Invalid swaps automatically revert after animation
- State machine: WAITING → SELECTING → SWAPPING → PROCESSING
- Test scripts located in `tests/` directory for system validation
- Use `test_logging.gd` to validate the logging system functionality
@@ -42,17 +48,27 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Key Development Guidelines
### Code Quality & Safety Standards
- **Memory Management**: Always use `queue_free()` instead of `free()` for node cleanup
- **Input Validation**: Validate all user inputs with bounds checking and type validation
- **Error Handling**: Implement comprehensive error handling with fallback mechanisms
- **Race Condition Prevention**: Use state flags to prevent concurrent operations
- **No Global State**: Avoid static variables; use instance-based architecture for testability
### Scene Management
- **ALWAYS** use `GameManager` for scene transitions - never call `get_tree().change_scene_to_file()` directly
- Scene paths are defined as constants in GameManager
- Error handling is built into GameManager for failed scene loads
- Use `GameManager.start_game_with_mode(mode)` to launch specific gameplay modes
- Supported gameplay modes: "match3", "clickomania"
- Supported gameplay modes: "match3", "clickomania" (validated with whitelist)
- GameManager prevents concurrent scene changes with `is_changing_scene` protection
### Autoload Usage
- Use autoloads for global state management only
- Prefer signals over direct access for loose coupling
- Don't access autoloads from deeply nested components
- **SettingsManager**: Features comprehensive input validation and error recovery
- **GameManager**: Protected against race conditions with state management
### Debug System Integration
- Connect to `DebugManager.debug_ui_toggled` signal for debug UI visibility
@@ -60,25 +76,32 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- Remove debug prints before committing unless permanently useful
### Logging System Usage
- **CRITICAL**: ALL print() and push_error() statements have been migrated to DebugManager
- **ALWAYS** use `DebugManager` logging functions instead of `print()`, `push_error()`, etc.
- Use appropriate log levels: INFO for general messages, WARN for issues, ERROR for failures
- Include meaningful categories to organize log output: `"GameManager"`, `"Match3"`, `"Settings"`
- Include meaningful categories to organize log output, eg: `"GameManager"`, `"Match3"`, `"Settings"`, `"DebugMenu"`
- Leverage structured logging for better debugging and production monitoring
- Use `DebugManager.set_log_level()` to control verbosity during development and testing
- The logging system provides unified output across all game systems
## Important File References
### Documentation Structure
- **`docs/MAP.md`** - Complete project architecture and structure
- **`docs/UI_COMPONENTS.md`** - Custom UI components
- **`docs/CODE_OF_CONDUCT.md`** - Coding standards and best practices
- **`docs/TESTING.md`** - Testing guidelines and conventions
- **This file** - Claude Code specific development guidelines
### Key Scripts to Understand
- `src/autoloads/GameManager.gd` - Scene transition patterns and gameplay mode management
- `src/autoloads/GameManager.gd` - Scene transition patterns with race condition protection
- `src/autoloads/SettingsManager.gd` - Settings management with comprehensive error handling
- `src/autoloads/DebugManager.gd` - Debug system integration
- `scenes/game/game.gd` - Main game scene with modular gameplay system
- `scenes/game/gameplays/match3_gameplay.gd` - Match-3 implementation reference
- `scenes/game/gameplays/match3_gameplay.gd` - Memory-safe Match-3 implementation with input validation
- `scenes/game/gameplays/tile.gd` - Instance-based tile behavior without global state
- `scenes/ui/DebugMenuBase.gd` - Unified debug menu base class
- `scenes/ui/SettingsMenu.gd` - Settings UI with input validation
- `scenes/game/gameplays/` - Individual gameplay mode implementations
- `project.godot` - Input actions and autoload definitions
@@ -99,14 +122,18 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- Run `test_logging.gd` after making changes to the logging system
### Common Implementation Patterns
- Scene transitions: Use `GameManager.start_game_with_mode()` and related methods
- Debug integration: Connect to `DebugManager` signals and initialize debug state
- Logging: Use `DebugManager.log_*()` functions with appropriate levels and categories
- Gameplay modes: Implement in `scenes/game/gameplays/` directory following modular pattern
- Scoring system: Connect `score_changed` signal from gameplay to main game scene
- Settings: Use `SettingsManager` for persistent configuration
- Audio: Use `AudioManager` for music and sound effects
- Localization: Use `LocalizationManager` for language switching
- **Scene transitions**: Use `GameManager.start_game_with_mode()` with built-in validation
- **Debug integration**: Connect to `DebugManager` signals and initialize debug state
- **Logging**: Use `DebugManager.log_*()` functions with appropriate levels and categories
- **Gameplay modes**: Implement in `scenes/game/gameplays/` directory following modular pattern
- **Scoring system**: Connect `score_changed` signal from gameplay to main game scene
- **Settings**: Use `SettingsManager` with automatic input validation and error recovery
- **Audio**: Use `AudioManager` for music and sound effects
- **Localization**: Use `LocalizationManager` for language switching
- **UI Components**: Extend `DebugMenuBase` for debug menus to avoid code duplication
- **Value Selection**: Use `ValueStepper` component for discrete option selection (language, resolution, difficulty)
- **Memory Management**: Use `queue_free()` and await frame completion for safe cleanup
- **Input Validation**: Always validate user inputs with type checking and bounds validation
### Logging Best Practices
```gdscript