# 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