# 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
- 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

### 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"

### 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

### 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
- **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"`
- Leverage structured logging for better debugging and production monitoring
- Use `DebugManager.set_log_level()` to control verbosity during development and testing

## Important File References

### Documentation Structure
- **`docs/MAP.md`** - Complete project architecture and structure
- **`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/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/` - 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()` 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

### 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
```