# 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 a match-3 puzzle game within a broader game framework. The project includes a 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
- Match-3 debug controls include gem count adjustment and board reroll
- Difficulty presets: Easy (3 gems), Normal (5 gems), Hard (8 gems)

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

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

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

## Important File References

### Documentation Structure
- **`docs/MAP.md`** - Complete project architecture and structure
- **`docs/CODE_OF_CONDUCT.md`** - Coding standards and best practices
- **This file** - Claude Code specific development guidelines

### Key Scripts to Understand
- `src/autoloads/GameManager.gd` - Scene transition patterns
- `src/autoloads/DebugManager.gd` - Debug system integration
- `scenes/match3/match3.gd` - Match-3 implementation reference
- `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

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

### Common Implementation Patterns
- Scene transitions: Use `GameManager.change_to_scene()` methods
- Debug integration: Connect to `DebugManager` signals
- Settings: Use `SettingsManager` for persistent configuration
- Audio: Use `AudioManager` for music and sound effects
- Localization: Use `LocalizationManager` for language switching