create gem grid
This commit is contained in:
209
docs/MAP.md
Normal file
209
docs/MAP.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user