# 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 that features a match-3 puzzle game within a broader game framework. The project includes a menu system, settings management, audio handling, and localization support.

## Project Structure

### Core Architecture
- **Autoloaded Singletons**: The project uses four global singletons (autoloads) defined in `project.godot`:
  - `SettingsManager` - Handles game settings and configuration
  - `AudioManager` - Manages music and sound effects with volume controls
  - `GameManager` - Handles scene transitions and game state
  - `LocalizationManager` - Manages multi-language support (English/Russian)

### Directory Structure
- `scripts/` - Global singleton scripts and utility classes
- `scenes/` - Game scenes including main game and match-3 components
  - `match3/` - Specialized match-3 game implementation
- `ui/` - User interface scenes (MainMenu, SettingsMenu, PressAnyKeyScreen)
- `audio/` - Music and sound effect files
- `resources/` - Game assets (textures, sprites, animations)
- `localization/` - Translation files for internationalization

### Scene Management Flow
1. Main entry point: `scenes/main.tscn` with press-any-key screen
2. Menu navigation: MainMenu → SettingsMenu (with back navigation)
3. Game flow: MainMenu → Game scene → Match3 game integration
4. All scene transitions handled through `GameManager` singleton

### Match-3 Game System
- Located in `scenes/match3/`
- Grid-based (8x8) tile matching system
- Implements match detection, tile dropping, and grid refilling
- Uses tile instances with position-based grid management
- Automatic cascade matching after tile drops

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

### Audio Configuration
- Music: Located in `audio/` 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 `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 Components

### AudioManager (`scripts/AudioManager.gd`)
- Handles background music with looping
- Manages UI sound effects (click sounds)
- Volume control integration with SettingsManager
- Automatic audio bus configuration

### Match3 Game (`scenes/match3/match3.gd`)
- 8x8 grid system with 5 tile types
- Match detection in horizontal and vertical directions
- Tile dropping physics with position-based movement
- Recursive match clearing and grid refilling

### Scene Navigation
- All scene changes go through GameManager for consistency
- Scene paths defined as constants in GameManager
- Error handling for failed scene loads

## Input System
- Custom input actions defined in `project.godot`:
  - `ui_pause` - Space key or gamepad button
  - `any_key` - Multiple inputs for menu progression
  - `ui_menu_toggle` - Escape key or gamepad button

## Asset Attribution
Asset sources documented in `sources.yaml` including:
- Music from Clement Panchout
- Sound effects from Freesound
- Sprites and textures from various itch.io creators