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 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

# 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 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 for complete file organization details.

Documentation

• docs/ARCHITECTURE.md - System design, autoloads, architectural patterns
• docs/CODE_OF_CONDUCT.md - Coding standards, naming conventions, best practices
• docs/DEVELOPMENT.md - Development workflows and commands
• docs/TESTING.md - Testing procedures and protocols
• docs/UI_COMPONENTS.md - UI component API reference
• 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 for coding standards
2. Review docs/ARCHITECTURE.md for system design
3. Check docs/DEVELOPMENT.md for workflows
4. Follow the 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 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 for detailed workflow.

Testing

# 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 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 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 for complete quality standards.

Resources

• Godot GDScript Style Guide
• Godot Best Practices
• Project documentation in docs/ directory

License

GPLv3.0

See LICENSE file for more information