codemap generation
Some checks failed
Some checks failed
This commit is contained in:
383
docs/DEVELOPMENT.md
Normal file
383
docs/DEVELOPMENT.md
Normal file
@@ -0,0 +1,383 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user