skelly/docs/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

"Skelly" is a Godot 4.4 mobile game project featuring multiple gameplay modes within a unified game framework. The project currently supports match-3 puzzle gameplay with planned support for clickomania gameplay. It includes a modular gameplay system, menu system, settings management, audio handling, localization support, and a comprehensive debug system.

**For detailed project architecture, see `docs/MAP.md`**

## Development Commands

### Running the Project
- Open project in Godot Editor: Import `project.godot`
- Run project: Press F5 in Godot Editor or use "Play" button
- Debug: Use Godot's built-in debugger and remote inspector
- Debug UI: Press F12 in-game or use debug button to toggle debug panels

### Testing & Development
- Debug mode can be toggled with F12 key or debug button UI (available on all major scenes)
- 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

### Audio Configuration
- Music: Located in `assets/audio/music/` directory with loop configuration in AudioManager
- Sound effects: UI clicks and game audio managed through audio bus system
- Audio buses: "Music" and "SFX" buses configured in `data/default_bus_layout.tres`

### Localization
- Translations stored in `localization/` as `.translation` files
- Currently supports English and Russian
- New translations: Add to `project.godot` internationalization section

### Asset Management
- **CRITICAL**: Every asset must be documented in `assets/sources.yaml` before committing
- Include source, license, attribution, modifications, and usage information
- Verify license compatibility with project requirements
- Commit asset files and sources.yaml together in the same commit

## 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" (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
- Use F12 key for global debug toggle
- 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, 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 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` - 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

## Development Workflow

### Before Making Changes
1. Check `docs/MAP.md` for architecture understanding
2. Review `docs/CODE_OF_CONDUCT.md` for coding standards
3. Understand existing patterns before implementing new features
4. If adding assets, prepare `assets/sources.yaml` documentation

### Testing Changes
- Run project with F5 in Godot Editor
- Test debug UI with F12 toggle
- Verify scene transitions work correctly
- Check mobile compatibility if UI changes made
- Use relevant test scripts from `tests/` directory to validate system functionality
- Run `test_logging.gd` after making changes to the logging system

### Common Implementation Patterns
- **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
# ✅ Good logging practices
DebugManager.log_info("Scene transition completed", "GameManager")
DebugManager.log_warn("Settings file not found, using defaults", "Settings")
DebugManager.log_error("Failed to load audio resource: " + audio_path, "AudioManager")

# ❌ Avoid these patterns
print("debug")  # Use structured logging instead
push_error("error")  # Use DebugManager.log_error() with category
```

### Asset Management Workflow
```yaml
# ✅ Required assets/sources.yaml entry format
audio:
  music:
    "background_music.ogg":
      source: "https://freesound.org/people/artist/sounds/123456/"
      license: "CC BY 4.0"
      attribution: "Background Music by Artist Name"
      modifications: "Converted to OGG, adjusted volume"
      usage: "Main menu and gameplay background music"

# ✅ Proper commit workflow
# 1. Add asset to appropriate assets/ subdirectory
# 2. Update assets/sources.yaml with complete metadata
# 3. git add both files together
# 4. Commit with descriptive message including attribution
```