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.