# 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