skelly/docs/MAP.md

# Skelly - Project Structure Map

## Overview
Skelly is a Godot 4.4 game project featuring a match-3 puzzle game with skeleton character themes. The project follows a modular architecture with clear separation between scenes, autoloads, assets, and data.

## Project Root Structure

```
skelly/
├── .claude/                    # Claude Code configuration
├── .godot/                     # Godot engine generated files (ignored)
├── assets/                     # Game assets (sprites, audio, textures)
├── data/                       # Game data and configuration files
├── docs/                       # Documentation
├── localization/               # Internationalization files
├── scenes/                     # Godot scenes (.tscn) and scripts (.gd)
├── src/                        # Source code organization
├── project.godot              # Main Godot project configuration
└── icon.svg                   # Project icon
```

## Core Architecture

### Autoloads (Global Singletons)
Located in `src/autoloads/`, these scripts are automatically loaded when the game starts:

1. **SettingsManager** (`src/autoloads/SettingsManager.gd`)
   - Manages game settings and user preferences
   - Handles configuration file I/O
   - Provides language selection functionality
   - Dependencies: `localization/languages.json`

2. **AudioManager** (`src/autoloads/AudioManager.gd`)
   - Controls music and sound effects
   - Manages audio bus configuration
   - Uses: `data/default_bus_layout.tres`

3. **GameManager** (`src/autoloads/GameManager.gd`)
   - Central game state management
   - Scene transitions between main/game/match3
   - Navigation flow control
   - References: main.tscn, game.tscn, match3.tscn

4. **LocalizationManager** (`src/autoloads/LocalizationManager.gd`)
   - Language switching functionality
   - Works with Godot's built-in internationalization system
   - Uses translation files in `localization/`

5. **DebugManager** (`src/autoloads/DebugManager.gd`)
   - Global debug state management
   - Debug UI visibility control
   - F12 toggle functionality
   - Signal-based debug system

## Scene Hierarchy & Flow

### Main Scenes
```
main.tscn (Entry Point)
├── PressAnyKeyScreen.tscn
├── MainMenu.tscn
└── SettingsMenu.tscn
```

### Game Flow
1. **Main Scene** (`scenes/main/main.tscn` + `Main.gd`)
   - Application entry point
   - Manages "Press Any Key" screen
   - Transitions to main menu
   - Dynamic menu loading system

2. **Press Any Key Screen** (`scenes/main/PressAnyKeyScreen.tscn` + `PressAnyKeyScreen.gd`)
   - Initial splash screen
   - Input detection for any key/button
   - Signals to main scene for transition

3. **Main Menu** (`scenes/ui/MainMenu.tscn` + `MainMenu.gd`)
   - Primary navigation hub
   - Start game, settings, quit options
   - Connected to GameManager for scene transitions

4. **Settings Menu** (`scenes/ui/SettingsMenu.tscn` + `SettingsMenu.gd`)
   - User preferences interface
   - Language selection
   - Audio volume controls
   - Connected to SettingsManager and AudioManager

5. **Game Scene** (`scenes/game/game.tscn` + `game.gd`)
   - Main gameplay container
   - Loads match-3 instance
   - Back button for navigation
   - Bridge between UI and game logic

6. **Match-3 Game** (`scenes/match3/match3.tscn` + `match3.gd`)
   - Core puzzle game implementation
   - Grid-based tile system
   - Debug UI integration
   - Gem management system

### UI Components
```
scenes/ui/
├── DebugButton.tscn + DebugButton.gd
├── MainMenu.tscn + MainMenu.gd
└── SettingsMenu.tscn + SettingsMenu.gd
```

## Match-3 Game System

### Core Components
1. **Match3 Controller** (`scenes/match3/match3.gd`)
   - Grid management (8x8 default)
   - Match detection algorithms
   - Tile dropping and refilling
   - Gem pool management (3-8 gem types)
   - Debug UI integration

2. **Tile System** (`scenes/match3/tile.gd` + `Tile.tscn`)
   - Individual tile behavior
   - Gem type management
   - Visual representation
   - Group membership for coordination

### Debug System
- Global debug state via DebugManager
- Match-3 specific debug UI panel
- Gem count controls (+/- buttons)
- Difficulty presets (Easy: 3 gems, Normal: 5 gems, Hard: 8 gems)
- Reroll functionality
- F12 toggle support

## Asset Organization

### Audio (`assets/audio/`)
```
audio/
├── music/          # Background music files
└── sfx/           # Sound effects
```

### Visual Assets (`assets/`)
```
assets/
├── sprites/
│   ├── characters/skeleton/    # Character artwork
│   ├── gems/                   # Match-3 gem sprites
│   └── ui/                     # User interface elements
├── textures/
│   └── backgrounds/            # Background images
└── fonts/                      # Custom fonts
```

## Data & Configuration

### Game Data (`data/`)
- `default_bus_layout.tres` - Audio bus configuration for Godot

### Localization (`localization/`)
- `languages.json` - Available language definitions
- `MainStrings.en.translation` - English translations
- `MainStrings.ru.translation` - Russian translations

### Project Configuration
- `project.godot` - Main Godot project settings
  - Autoload definitions
  - Input map configurations
  - Rendering settings
  - Audio bus references

## Key Dependencies & Connections

### Signal Connections
```
PressAnyKeyScreen --[any_key_pressed]--> Main
MainMenu --[open_settings]--> Main
SettingsMenu --[back_to_main_menu]--> Main
DebugManager --[debug_toggled, debug_ui_toggled]--> Match3
```

### Scene References
```
GameManager --> main.tscn, game.tscn, match3.tscn
Main --> MainMenu.tscn, SettingsMenu.tscn
Game --> match3.tscn (instantiated)
```

### Asset Dependencies
```
AudioManager --> assets/audio/music/
SettingsManager --> localization/languages.json
AudioManager --> data/default_bus_layout.tres
```

## Development Notes

### Current Implementation Status
- Match-3 system with 8x8 grid and configurable gem pools
- Debug UI system with F12 toggle functionality
- Scene transition system via GameManager
- Internationalization support for English/Russian

### Architecture Patterns
1. **Autoload Pattern** - Global managers as singletons
2. **Signal-Based Communication** - Loose coupling between components
3. **Scene Composition** - Modular scene loading and management
4. **Data-Driven Configuration** - JSON for settings and translations
5. **Component Architecture** - Reusable UI and game components

This structure provides a clean separation of concerns, making the codebase maintainable and extensible for future features.