skelly/docs/MAP.md

Skelly - Project Structure Map

Overview

Skelly is a Godot 4.4 game project featuring multiple gameplay modes with skeleton character themes. The project supports match-3 puzzle gameplay with planned clickomania gameplay through a modular gameplay architecture. It follows a modular structure 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 and gameplay mode coordination
   • Scene transitions between main/game scenes
   • Gameplay mode selection and launching (match3, clickomania)
   • Navigation flow control
   • References: main.tscn, game.tscn and individual gameplay scenes

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.tscn (Gameplay Container)
├── GameplayContainer (Dynamic content)
├── UI/ScoreDisplay
├── BackButton
└── DebugToggle

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 with modular gameplay system
   • Dynamic loading of gameplay modes into GameplayContainer
   • Global score management and display
   • Back button for navigation to main menu
   • Gameplay mode switching support (Space+Enter debug key)
   • Bridge between UI and individual gameplay implementations

UI Components

scenes/ui/
├── DebugToggle.tscn + DebugToggle.gd    # Now available on all major scenes
├── DebugMenu.tscn + DebugMenu.gd        # Match-3 debug controls
├── MainMenu.tscn + MainMenu.gd
└── SettingsMenu.tscn + SettingsMenu.gd

Modular Gameplay System

The game now uses a modular gameplay architecture where different game modes can be dynamically loaded into the main game scene.

Gameplay Architecture

• Main Game Scene (scenes/game/game.gd) - Container and coordinator
• Gameplay Directory (scenes/game/gameplays/) - Individual gameplay implementations
• Dynamic Loading - Gameplay scenes loaded at runtime based on mode selection
• Signal-based Communication - Gameplays communicate with main scene via signals

Current Gameplay Modes

Match-3 Mode (scenes/game/gameplays/match3_gameplay.tscn)

1. Match3 Controller (scenes/game/gameplays/match3_gameplay.gd)

   • Grid management (8x8 default)
   • Match detection algorithms
   • Tile dropping and refilling
   • Gem pool management (3-8 gem types)
   • Debug UI integration
   • Score reporting via score_changed signal

2. Tile System (scenes/game/gameplays/tile.gd + Tile.tscn)

   • Individual tile behavior
   • Gem type management
   • Visual representation
   • Group membership for coordination

Clickomania Mode (scenes/game/gameplays/clickomania_gameplay.tscn)

• Planned implementation for clickomania-style gameplay
• Will integrate with same scoring and UI systems as match-3

Debug System

• Global debug state via DebugManager with proper initialization
• Debug toggle available on all major scenes (MainMenu, SettingsMenu, PressAnyKeyScreen, Game)
• Match-3 specific debug UI panel with gem count controls and difficulty presets
• Gem count controls (+/- buttons) with difficulty presets (Easy: 3, Normal: 5, Hard: 8)
• Board reroll functionality for testing
• F12 toggle support across all scenes
• Debug prints reduced in production code

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]--> All scenes with DebugToggle
GameplayModes --[score_changed]--> Game Scene
Game Scene --[score updates]--> UI/ScoreDisplay

Scene References

GameManager --> main.tscn, game.tscn
GameManager --> scenes/game/gameplays/*.tscn (via GAMEPLAY_SCENES constant)
Main --> MainMenu.tscn, SettingsMenu.tscn
Game --> GameplayContainer (dynamic loading of gameplay scenes)
Game --> scenes/game/gameplays/match3_gameplay.tscn, clickomania_gameplay.tscn

Asset Dependencies

AudioManager --> assets/audio/music/
SettingsManager --> localization/languages.json
AudioManager --> data/default_bus_layout.tres

Development Notes

Current Implementation Status

• Modular gameplay system with dynamic loading architecture
• Match-3 system with 8x8 grid and configurable gem pools
• Global scoring system integrated across gameplay modes
• Debug UI system with F12 toggle functionality across all major scenes
• Scene transition system via GameManager with gameplay mode support
• Internationalization support for English/Russian

Architecture Patterns

1. Autoload Pattern - Global managers as singletons
2. Signal-Based Communication - Loose coupling between components
3. Modular Gameplay Architecture - Dynamic loading of gameplay modes
4. Scene Composition - Modular scene loading and management
5. Data-Driven Configuration - JSON for settings and translations
6. Component Architecture - Reusable UI and game components
7. Centralized Scoring System - Global score management across gameplay modes

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