141 lines
6.4 KiB
Markdown
141 lines
6.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
"Skelly" is a Godot 4.4 mobile game project featuring multiple gameplay modes within a unified game framework. The project currently supports match-3 puzzle gameplay with planned support for clickomania gameplay. It includes a modular gameplay system, menu system, settings management, audio handling, localization support, and a comprehensive debug system.
|
|
|
|
**For detailed project architecture, see `docs/MAP.md`**
|
|
|
|
## Development Commands
|
|
|
|
### Running the Project
|
|
- Open project in Godot Editor: Import `project.godot`
|
|
- Run project: Press F5 in Godot Editor or use "Play" button
|
|
- Debug: Use Godot's built-in debugger and remote inspector
|
|
- Debug UI: Press F12 in-game or use debug button to toggle debug panels
|
|
|
|
### Testing & Development
|
|
- Debug mode can be toggled with F12 key or debug button UI (available on all major scenes)
|
|
- Match-3 debug controls include gem count adjustment and board reroll
|
|
- Difficulty presets: Easy (3 gems), Normal (5 gems), Hard (8 gems)
|
|
- Gameplay mode switching: Space+Enter in game scene switches between match-3 and clickomania modes
|
|
- Test scripts located in `tests/` directory for system validation
|
|
- Use `test_logging.gd` to validate the logging system functionality
|
|
|
|
### Audio Configuration
|
|
- Music: Located in `assets/audio/music/` directory with loop configuration in AudioManager
|
|
- Sound effects: UI clicks and game audio managed through audio bus system
|
|
- Audio buses: "Music" and "SFX" buses configured in `data/default_bus_layout.tres`
|
|
|
|
### Localization
|
|
- Translations stored in `localization/` as `.translation` files
|
|
- Currently supports English and Russian
|
|
- New translations: Add to `project.godot` internationalization section
|
|
|
|
### Asset Management
|
|
- **CRITICAL**: Every asset must be documented in `assets/sources.yaml` before committing
|
|
- Include source, license, attribution, modifications, and usage information
|
|
- Verify license compatibility with project requirements
|
|
- Commit asset files and sources.yaml together in the same commit
|
|
|
|
## Key Development Guidelines
|
|
|
|
### Scene Management
|
|
- **ALWAYS** use `GameManager` for scene transitions - never call `get_tree().change_scene_to_file()` directly
|
|
- Scene paths are defined as constants in GameManager
|
|
- Error handling is built into GameManager for failed scene loads
|
|
- Use `GameManager.start_game_with_mode(mode)` to launch specific gameplay modes
|
|
- Supported gameplay modes: "match3", "clickomania"
|
|
|
|
### Autoload Usage
|
|
- Use autoloads for global state management only
|
|
- Prefer signals over direct access for loose coupling
|
|
- Don't access autoloads from deeply nested components
|
|
|
|
### Debug System Integration
|
|
- Connect to `DebugManager.debug_ui_toggled` signal for debug UI visibility
|
|
- Use F12 key for global debug toggle
|
|
- Remove debug prints before committing unless permanently useful
|
|
|
|
### Logging System Usage
|
|
- **ALWAYS** use `DebugManager` logging functions instead of `print()`, `push_error()`, etc.
|
|
- Use appropriate log levels: INFO for general messages, WARN for issues, ERROR for failures
|
|
- Include meaningful categories to organize log output: `"GameManager"`, `"Match3"`, `"Settings"`
|
|
- Leverage structured logging for better debugging and production monitoring
|
|
- Use `DebugManager.set_log_level()` to control verbosity during development and testing
|
|
|
|
## Important File References
|
|
|
|
### Documentation Structure
|
|
- **`docs/MAP.md`** - Complete project architecture and structure
|
|
- **`docs/CODE_OF_CONDUCT.md`** - Coding standards and best practices
|
|
- **`docs/TESTING.md`** - Testing guidelines and conventions
|
|
- **This file** - Claude Code specific development guidelines
|
|
|
|
### Key Scripts to Understand
|
|
- `src/autoloads/GameManager.gd` - Scene transition patterns and gameplay mode management
|
|
- `src/autoloads/DebugManager.gd` - Debug system integration
|
|
- `scenes/game/game.gd` - Main game scene with modular gameplay system
|
|
- `scenes/game/gameplays/match3_gameplay.gd` - Match-3 implementation reference
|
|
- `scenes/game/gameplays/` - Individual gameplay mode implementations
|
|
- `project.godot` - Input actions and autoload definitions
|
|
|
|
## Development Workflow
|
|
|
|
### Before Making Changes
|
|
1. Check `docs/MAP.md` for architecture understanding
|
|
2. Review `docs/CODE_OF_CONDUCT.md` for coding standards
|
|
3. Understand existing patterns before implementing new features
|
|
4. If adding assets, prepare `assets/sources.yaml` documentation
|
|
|
|
### Testing Changes
|
|
- Run project with F5 in Godot Editor
|
|
- Test debug UI with F12 toggle
|
|
- Verify scene transitions work correctly
|
|
- Check mobile compatibility if UI changes made
|
|
- Use relevant test scripts from `tests/` directory to validate system functionality
|
|
- Run `test_logging.gd` after making changes to the logging system
|
|
|
|
### Common Implementation Patterns
|
|
- Scene transitions: Use `GameManager.start_game_with_mode()` and related methods
|
|
- Debug integration: Connect to `DebugManager` signals and initialize debug state
|
|
- Logging: Use `DebugManager.log_*()` functions with appropriate levels and categories
|
|
- Gameplay modes: Implement in `scenes/game/gameplays/` directory following modular pattern
|
|
- Scoring system: Connect `score_changed` signal from gameplay to main game scene
|
|
- Settings: Use `SettingsManager` for persistent configuration
|
|
- Audio: Use `AudioManager` for music and sound effects
|
|
- Localization: Use `LocalizationManager` for language switching
|
|
|
|
### Logging Best Practices
|
|
```gdscript
|
|
# ✅ Good logging practices
|
|
DebugManager.log_info("Scene transition completed", "GameManager")
|
|
DebugManager.log_warn("Settings file not found, using defaults", "Settings")
|
|
DebugManager.log_error("Failed to load audio resource: " + audio_path, "AudioManager")
|
|
|
|
# ❌ Avoid these patterns
|
|
print("debug") # Use structured logging instead
|
|
push_error("error") # Use DebugManager.log_error() with category
|
|
```
|
|
|
|
### Asset Management Workflow
|
|
```yaml
|
|
# ✅ Required assets/sources.yaml entry format
|
|
audio:
|
|
music:
|
|
"background_music.ogg":
|
|
source: "https://freesound.org/people/artist/sounds/123456/"
|
|
license: "CC BY 4.0"
|
|
attribution: "Background Music by Artist Name"
|
|
modifications: "Converted to OGG, adjusted volume"
|
|
usage: "Main menu and gameplay background music"
|
|
|
|
# ✅ Proper commit workflow
|
|
# 1. Add asset to appropriate assets/ subdirectory
|
|
# 2. Update assets/sources.yaml with complete metadata
|
|
# 3. git add both files together
|
|
# 4. Commit with descriptive message including attribution
|
|
```
|