384 lines
12 KiB
Markdown
384 lines
12 KiB
Markdown
# Development Guide
|
|
|
|
Development workflows, commands, and procedures for the Skelly project.
|
|
|
|
**Quick Links**:
|
|
- **Architecture**: [ARCHITECTURE.md](ARCHITECTURE.md) - Understand system design before developing
|
|
- **Coding Standards**: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Follow coding conventions
|
|
- **Testing**: [TESTING.md](TESTING.md) - Testing procedures and protocols
|
|
|
|
## Development Commands
|
|
|
|
### Running the Project
|
|
|
|
```bash
|
|
# Open project in Godot Editor
|
|
# Import project.godot
|
|
|
|
# Run project
|
|
# Press F5 in Godot Editor or use "Play" button
|
|
|
|
# Toggle debug UI in-game
|
|
# Press F12 key or use debug button
|
|
```
|
|
|
|
### Code Maps Generation
|
|
|
|
Generate machine-readable code intelligence and visual documentation for development:
|
|
|
|
```bash
|
|
# Generate everything (default behavior - maps + diagrams + docs + metrics)
|
|
python tools/generate_code_map.py
|
|
|
|
# Generate specific outputs
|
|
python tools/generate_code_map.py --diagrams # Visual diagrams only
|
|
python tools/generate_code_map.py --docs # Markdown documentation only
|
|
python tools/generate_code_map.py --metrics # Metrics dashboard only
|
|
|
|
# Generate all explicitly (same as no arguments)
|
|
python tools/generate_code_map.py --all
|
|
|
|
# Via development workflow tool
|
|
python tools/run_development.py --codemap
|
|
|
|
# Custom output (single JSON file)
|
|
python tools/generate_code_map.py --output custom_map.json
|
|
|
|
# Skip PNG rendering (Mermaid source only)
|
|
python tools/generate_code_map.py --diagrams --no-render
|
|
```
|
|
|
|
**Generated Files** (Git-ignored):
|
|
|
|
**JSON Maps** (`.llm/` directory):
|
|
- `code_map_api.json` - Function signatures, parameters, return types
|
|
- `code_map_architecture.json` - Autoloads, design patterns, structure
|
|
- `code_map_flows.json` - Signal chains, scene transitions
|
|
- `code_map_security.json` - Input validation, error handling
|
|
- `code_map_assets.json` - Asset dependencies, licensing
|
|
- `code_map_metadata.json` - Statistics, quality metrics
|
|
|
|
**Diagrams** (`.llm/diagrams/` directory):
|
|
- `architecture.png` - Autoload system dependencies
|
|
- `signal_flows.png` - Signal connections between components
|
|
- `scene_hierarchy.png` - Scene tree structure
|
|
- `dependency_graph.png` - Module dependencies
|
|
- `*.mmd` - Mermaid source files
|
|
|
|
**Documentation** (`docs/generated/` directory):
|
|
- `AUTOLOADS_API.md` - Complete autoload API reference with diagrams
|
|
- `SIGNALS_CATALOG.md` - Signal catalog with flow diagrams
|
|
- `FUNCTION_INDEX.md` - Searchable function reference
|
|
- `SCENE_REFERENCE.md` - Scene hierarchy with diagrams
|
|
- `TODO_LIST.md` - Extracted TODO/FIXME comments
|
|
- `METRICS.md` - Project metrics dashboard with charts
|
|
|
|
**When to Regenerate**:
|
|
- Before LLM-assisted development sessions (fresh context)
|
|
- After adding new files or major refactoring (update structure)
|
|
- After changing autoloads or core architecture (capture changes)
|
|
- When onboarding new developers (comprehensive docs)
|
|
- To track project metrics and code complexity
|
|
|
|
### Testing Commands
|
|
|
|
```bash
|
|
# Run specific test
|
|
godot --headless --script tests/TestLogging.gd
|
|
|
|
# Run all save system tests
|
|
godot --headless --script tests/test_checksum_issue.gd
|
|
godot --headless --script tests/TestMigrationCompatibility.gd
|
|
godot --headless --script tests/test_save_system_integration.gd
|
|
|
|
# Development workflow tool
|
|
python tools/run_development.py --test
|
|
```
|
|
|
|
See [TESTING.md](TESTING.md) for complete testing procedures.
|
|
|
|
## Development Workflows
|
|
|
|
### Adding a New Feature
|
|
|
|
1. **Generate code maps** for LLM context:
|
|
```bash
|
|
python tools/generate_code_map.py
|
|
```
|
|
|
|
2. **Review architecture** to understand system design:
|
|
- Read [ARCHITECTURE.md](ARCHITECTURE.md) for relevant system
|
|
- Understand autoload responsibilities
|
|
- Review existing patterns
|
|
|
|
3. **Follow coding standards**:
|
|
- Use [naming conventions](CODE_OF_CONDUCT.md#naming-convention-quick-reference)
|
|
- Follow [core patterns](CODE_OF_CONDUCT.md#project-specific-guidelines)
|
|
- Implement [input validation](CODE_OF_CONDUCT.md#input-validation-standards)
|
|
- Use [proper memory management](CODE_OF_CONDUCT.md#memory-management-standards)
|
|
|
|
4. **Write tests** for new functionality:
|
|
- Create test file in `tests/` directory
|
|
- Follow [test structure guidelines](TESTING.md#adding-new-tests)
|
|
- Run tests to verify functionality
|
|
|
|
5. **Check quality checklist** before committing:
|
|
- Review [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md#code-quality-checklist)
|
|
- Verify all checkboxes are satisfied
|
|
- Run tests one more time
|
|
|
|
### Debugging Issues
|
|
|
|
1. **Toggle debug UI** with F12 in-game:
|
|
- View system state in debug panels
|
|
- Check current values and configurations
|
|
- Use debug controls for testing
|
|
|
|
2. **Check logs** using structured logging:
|
|
```gdscript
|
|
DebugManager.log_debug("Detailed debug info", "MyComponent")
|
|
DebugManager.log_info("Important event occurred", "MyComponent")
|
|
DebugManager.log_warn("Unexpected situation", "MyComponent")
|
|
DebugManager.log_error("Something failed", "MyComponent")
|
|
```
|
|
|
|
3. **Verify state** in debug panels:
|
|
- Match-3: Check gem pool, grid state, match detection
|
|
- Settings: Verify volume, language, difficulty values
|
|
- Save: Check save data integrity
|
|
|
|
4. **Run relevant test scripts**:
|
|
```bash
|
|
# Test specific system
|
|
godot --headless --script tests/TestMatch3Gameplay.gd
|
|
godot --headless --script tests/TestSettingsManager.gd
|
|
```
|
|
|
|
5. **Use Godot debugger**:
|
|
- Set breakpoints in code
|
|
- Inspect variables during execution
|
|
- Step through code execution
|
|
- Use remote inspector for live debugging
|
|
|
|
### Modifying Core Systems
|
|
|
|
1. **Understand current design**:
|
|
- Read [ARCHITECTURE.md](ARCHITECTURE.md) for system architecture
|
|
- Review autoload responsibilities
|
|
- Understand signal flows and dependencies
|
|
|
|
2. **Run existing tests first**:
|
|
```bash
|
|
# Save system testing
|
|
godot --headless --script tests/test_checksum_issue.gd
|
|
godot --headless --script tests/TestMigrationCompatibility.gd
|
|
|
|
# Settings testing
|
|
godot --headless --script tests/TestSettingsManager.gd
|
|
|
|
# Game manager testing
|
|
godot --headless --script tests/TestGameManager.gd
|
|
```
|
|
|
|
3. **Make changes following standards**:
|
|
- Follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) patterns
|
|
- Maintain backward compatibility where possible
|
|
- Add input validation and error handling
|
|
- Use proper memory management
|
|
|
|
4. **Run tests again** to verify no regressions:
|
|
```bash
|
|
# Run all relevant test suites
|
|
python tools/run_development.py --test
|
|
```
|
|
|
|
5. **Update documentation** if architecture changes:
|
|
- Update [ARCHITECTURE.md](ARCHITECTURE.md) if design patterns change
|
|
- Update [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) if new patterns emerge
|
|
- Update [TESTING.md](TESTING.md) if new test protocols needed
|
|
|
|
## Testing Changes
|
|
|
|
### Manual Testing
|
|
|
|
```bash
|
|
# Run project with F5 in Godot Editor
|
|
# Test the following:
|
|
|
|
# Basic functionality
|
|
# - F12 toggle for debug UI
|
|
# - Scene transitions work correctly
|
|
# - Settings persist across restarts
|
|
# - Audio plays correctly
|
|
|
|
# Gameplay testing
|
|
# - Match-3: Gem swapping, match detection, scoring
|
|
# - Input: Keyboard (WASD/Arrows + Enter) and gamepad (D-pad + A)
|
|
# - Visual feedback: Selection highlights, animations
|
|
|
|
# Mobile compatibility (if UI changes made)
|
|
# - Touch input works
|
|
# - UI scales correctly on different resolutions
|
|
# - Performance is acceptable
|
|
```
|
|
|
|
### Automated Testing
|
|
|
|
```bash
|
|
# Logging system
|
|
godot --headless --script tests/TestLogging.gd
|
|
|
|
# Save system (after SaveManager changes)
|
|
godot --headless --script tests/test_checksum_issue.gd
|
|
godot --headless --script tests/TestMigrationCompatibility.gd
|
|
godot --headless --script tests/test_save_system_integration.gd
|
|
|
|
# Settings system
|
|
godot --headless --script tests/TestSettingsManager.gd
|
|
|
|
# Game manager
|
|
godot --headless --script tests/TestGameManager.gd
|
|
|
|
# Gameplay
|
|
godot --headless --script tests/TestMatch3Gameplay.gd
|
|
```
|
|
|
|
See [TESTING.md](TESTING.md) for complete testing protocols.
|
|
|
|
## Troubleshooting
|
|
|
|
### When Stuck
|
|
|
|
1. **Check system design**: Read [ARCHITECTURE.md](ARCHITECTURE.md) for understanding
|
|
2. **Review coding patterns**: Check [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for examples
|
|
3. **Use debug system**: Press F12 to inspect current state
|
|
4. **Search existing code**: Look for similar patterns in the codebase
|
|
5. **Test understanding**: Create small experiments to verify assumptions
|
|
|
|
### Common Issues
|
|
|
|
#### Scene Loading Fails
|
|
**Problem**: Scene transitions not working or crashes during scene change
|
|
|
|
**Solution**:
|
|
- Check if using `GameManager.start_game_with_mode()` (correct)
|
|
- Never use `get_tree().change_scene_to_file()` directly
|
|
- Verify scene paths are correct constants in GameManager
|
|
- Check for race conditions (multiple rapid scene changes)
|
|
|
|
**Example**:
|
|
```gdscript
|
|
# ✅ Correct
|
|
GameManager.start_game_with_mode("match3")
|
|
|
|
# ❌ Wrong
|
|
get_tree().change_scene_to_file("res://scenes/game/Game.tscn")
|
|
```
|
|
|
|
#### Logs Not Appearing
|
|
**Problem**: Debug messages not showing in console
|
|
|
|
**Solution**:
|
|
- Use `DebugManager.log_*()` functions instead of `print()`
|
|
- Include category for log organization
|
|
- Check log level filtering (TRACE/DEBUG require debug mode)
|
|
- Verify DebugManager is configured as autoload
|
|
|
|
**Example**:
|
|
```gdscript
|
|
# ✅ Correct
|
|
DebugManager.log_info("Scene loaded", "GameManager")
|
|
DebugManager.log_error("Failed to load resource", "AssetLoader")
|
|
|
|
# ❌ Wrong
|
|
print("Scene loaded") # Use structured logging
|
|
push_error("Failed") # Missing context and category
|
|
```
|
|
|
|
#### Memory Crashes
|
|
**Problem**: Crashes related to freed nodes or memory access
|
|
|
|
**Solution**:
|
|
- Always use `queue_free()` instead of `free()`
|
|
- Wait for frame completion after queueing nodes
|
|
- Clear references before cleanup
|
|
- Check for access to freed objects
|
|
|
|
**Example**:
|
|
```gdscript
|
|
# ✅ Correct
|
|
for child in children_to_remove:
|
|
child.queue_free()
|
|
await get_tree().process_frame # Wait for cleanup
|
|
|
|
# ❌ Wrong
|
|
for child in children_to_remove:
|
|
child.free() # Immediate deletion causes crashes
|
|
```
|
|
|
|
#### Tests Failing
|
|
**Problem**: Test scripts fail or hang
|
|
|
|
**Solution**:
|
|
- Run tests in sequence (avoid parallel execution)
|
|
- Check autoload configuration in project.godot
|
|
- Remove existing save files before testing SaveManager
|
|
- Verify test file permissions
|
|
- Check test timeout (should complete within seconds)
|
|
|
|
#### Input Not Working
|
|
**Problem**: Keyboard/gamepad input not responding
|
|
|
|
**Solution**:
|
|
- Verify input actions defined in project.godot
|
|
- Check input map configuration
|
|
- Ensure scene has input focus
|
|
- Test with both keyboard and gamepad
|
|
- Check for input event consumption by UI elements
|
|
|
|
## Best Practices
|
|
|
|
### Before Committing
|
|
|
|
1. **Run all relevant tests**:
|
|
```bash
|
|
python tools/run_development.py --test
|
|
```
|
|
|
|
2. **Check quality checklist**: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md#code-quality-checklist)
|
|
|
|
3. **Verify no regressions**: Test existing functionality
|
|
|
|
4. **Update documentation**: If patterns or architecture changed
|
|
|
|
5. **Review changes**: Use `git diff` to review all modifications
|
|
|
|
### Code Review
|
|
|
|
- Focus on code clarity and maintainability
|
|
- Check adherence to project patterns
|
|
- Verify input validation and error handling
|
|
- Ensure memory management is safe
|
|
- Test the changes yourself before approving
|
|
|
|
### Performance Considerations
|
|
|
|
- Profile critical code paths
|
|
- Use object pooling for frequently created nodes
|
|
- Optimize expensive calculations
|
|
- Cache node references with `@onready`
|
|
- Avoid searching nodes repeatedly in `_process()`
|
|
|
|
## Additional 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)
|
|
- [Godot Debugger](https://docs.godotengine.org/en/stable/tutorials/scripting/debug/overview_of_debugging_tools.html)
|
|
|
|
## Related Documentation
|
|
|
|
- [ARCHITECTURE.md](ARCHITECTURE.md) - System design and patterns
|
|
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Coding standards
|
|
- [TESTING.md](TESTING.md) - Testing procedures
|
|
- [UI_COMPONENTS.md](UI_COMPONENTS.md) - Component API reference
|