237 lines
8.6 KiB
Markdown
237 lines
8.6 KiB
Markdown
# 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. |