148 lines
5.7 KiB
Markdown
148 lines
5.7 KiB
Markdown
# Skelly
|
|
|
|
Godot 4.4 mobile game project with multiple gameplay modes. Features modular gameplay system with match-3 puzzle (implemented) and planned clickomania mode.
|
|
|
|
**Tech Stack**: Godot 4.4, GDScript
|
|
**Target Platform**: Mobile (Android/iOS)
|
|
**Architecture**: See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed system design
|
|
|
|
## Quick Start
|
|
|
|
### Running the Project
|
|
|
|
1. **Open in Godot Editor**: Import `project.godot`
|
|
2. **Run**: Press `F5` or click the "Play" button
|
|
3. **Debug UI**: Press `F12` in-game to toggle debug panels
|
|
|
|
### Development Commands
|
|
|
|
```bash
|
|
# Generate code maps for LLM development
|
|
python tools/generate_code_map.py
|
|
|
|
# Run tests
|
|
godot --headless --script tests/TestLogging.gd
|
|
|
|
# Development workflow helper
|
|
python tools/run_development.py --codemap # Generate code maps
|
|
python tools/run_development.py --test # Run tests
|
|
```
|
|
|
|
See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for complete development workflows and commands.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
skelly/
|
|
├── src/autoloads/ # Global manager singletons (GameManager, SaveManager, etc.)
|
|
├── scenes/
|
|
│ ├── game/gameplays/ # Gameplay mode implementations (Match3, Clickomania)
|
|
│ ├── ui/components/ # Reusable UI components (ValueStepper, etc.)
|
|
│ └── ui/ # Menu scenes (MainMenu, SettingsMenu)
|
|
├── assets/ # Audio, sprites, fonts (kebab-case naming)
|
|
├── data/ # Godot resource files (.tres)
|
|
├── docs/ # Documentation (architecture, coding standards, testing)
|
|
├── tests/ # Test scripts for system validation
|
|
├── tools/ # Development tools (code map generator, etc.)
|
|
└── localization/ # Translation files (English, Russian)
|
|
```
|
|
|
|
See [docs/MAP.md](docs/MAP.md) for complete file organization details.
|
|
|
|
## Documentation
|
|
|
|
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System design, autoloads, architectural patterns
|
|
- **[docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md)** - Coding standards, naming conventions, best practices
|
|
- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development workflows and commands
|
|
- **[docs/TESTING.md](docs/TESTING.md)** - Testing procedures and protocols
|
|
- **[docs/UI_COMPONENTS.md](docs/UI_COMPONENTS.md)** - UI component API reference
|
|
- **[docs/MAP.md](docs/MAP.md)** - Complete project structure
|
|
|
|
## Features
|
|
|
|
- **Modular Gameplay System**: Easy to add new game modes
|
|
- **Match-3 Puzzle**: Fully implemented with keyboard/gamepad support
|
|
- **Settings Management**: Volume, language, difficulty with input validation
|
|
- **Save System**: Secure save/load with tamper detection and auto-repair
|
|
- **Debug System**: F12 toggle for debug panels on all major scenes
|
|
- **Localization**: Multi-language support (English, Russian)
|
|
- **Audio System**: Music and SFX with bus-based volume control
|
|
|
|
## Contributing
|
|
|
|
### Before Making Changes
|
|
|
|
1. Read [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md) for coding standards
|
|
2. Review [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for system design
|
|
3. Check [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for workflows
|
|
4. Follow the [quality checklist](docs/CODE_OF_CONDUCT.md#code-quality-checklist)
|
|
|
|
### Core Development Rules
|
|
|
|
- **Scene transitions**: Use `GameManager.start_game_with_mode()` - never call `get_tree().change_scene_to_file()` directly
|
|
- **Logging**: Use `DebugManager.log_*()` functions with categories - never use plain `print()` or `push_error()`
|
|
- **Memory management**: Always use `queue_free()` instead of `free()`
|
|
- **Input validation**: Validate all user inputs with type/bounds/null checking
|
|
- **TDD methodology**: Write tests for new functionality
|
|
|
|
See [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md) for complete standards.
|
|
|
|
### Asset Management
|
|
|
|
- **Document every asset** in `assets/sources.yaml` before committing
|
|
- Include source URL, license, attribution, modifications, and usage
|
|
- Verify license compatibility (CC BY, CC0, Public Domain, etc.)
|
|
- Commit asset files and sources.yaml together
|
|
|
|
See [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md#asset-management) for detailed workflow.
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Manual testing
|
|
# F5 in Godot Editor - Run project
|
|
# F12 in-game - Toggle debug UI
|
|
|
|
# Automated testing
|
|
godot --headless --script tests/TestLogging.gd
|
|
godot --headless --script tests/test_checksum_issue.gd
|
|
```
|
|
|
|
See [docs/TESTING.md](docs/TESTING.md) for complete testing procedures.
|
|
|
|
## Development Highlights
|
|
|
|
### Autoload System
|
|
|
|
Global singleton services providing core functionality:
|
|
- **GameManager**: Scene transitions with race condition protection
|
|
- **SaveManager**: Secure save/load with tamper detection
|
|
- **SettingsManager**: Settings persistence with input validation
|
|
- **DebugManager**: Unified logging and debug UI
|
|
- **AudioManager**: Music and SFX playback
|
|
- **LocalizationManager**: Language switching
|
|
|
|
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#autoload-system) for details.
|
|
|
|
### Code Quality Standards
|
|
|
|
- **Memory Safety**: `queue_free()` pattern for safe node cleanup
|
|
- **Error Handling**: Comprehensive error handling with fallbacks
|
|
- **Race Condition Protection**: State flags for async operations
|
|
- **Instance-Based Architecture**: No global static state
|
|
- **Input Validation**: Complete validation coverage
|
|
|
|
See [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md#code-quality-checklist) for complete quality standards.
|
|
|
|
## Resources
|
|
|
|
- [Godot GDScript Style Guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html)
|
|
- [Godot Best Practices](https://docs.godotengine.org/en/stable/tutorials/best_practices/index.html)
|
|
- Project documentation in `docs/` directory
|
|
|
|
## License
|
|
|
|
GPLv3.0
|
|
|
|
See [LICENSE](LICENSE) file for more information
|