codemap generation

README.md

@@ -0,0 +1,147 @@
+# 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