skelly/docs/DEVELOPMENT.md

Development Guide

Development workflows, commands, and procedures for the Skelly project.

Quick Links:

• Architecture: ARCHITECTURE.md - Understand system design before developing
• Coding Standards: CODE_OF_CONDUCT.md - Follow coding conventions
• Testing: TESTING.md - Testing procedures and protocols

Development Commands

Running the Project

# 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:

# 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

# 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 for complete testing procedures.

Development Workflows

Adding a New Feature

1. Generate code maps for LLM context:

   python tools/generate_code_map.py
   

2. Review architecture to understand system design:

   • Read ARCHITECTURE.md for relevant system
   • Understand autoload responsibilities
   • Review existing patterns

3. Follow coding standards:

   • Use naming conventions
   • Follow core patterns
   • Implement input validation
   • Use proper memory management

4. Write tests for new functionality:

   • Create test file in tests/ directory
   • Follow test structure guidelines
   • Run tests to verify functionality

5. Check quality checklist before committing:

   • Review CODE_OF_CONDUCT.md
   • 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:

   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:

   # 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 for system architecture
   • Review autoload responsibilities
   • Understand signal flows and dependencies

2. Run existing tests first:

   # 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 patterns
   • Maintain backward compatibility where possible
   • Add input validation and error handling
   • Use proper memory management

4. Run tests again to verify no regressions:

   # Run all relevant test suites
   python tools/run_development.py --test
   

5. Update documentation if architecture changes:

   • Update ARCHITECTURE.md if design patterns change
   • Update CODE_OF_CONDUCT.md if new patterns emerge
   • Update TESTING.md if new test protocols needed

Testing Changes

Manual Testing

# 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

# 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 for complete testing protocols.

Troubleshooting

When Stuck

1. Check system design: Read ARCHITECTURE.md for understanding
2. Review coding patterns: Check 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:

# ✅ 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:

# ✅ 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:

# ✅ 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:

   python tools/run_development.py --test
   

2. Check quality checklist: CODE_OF_CONDUCT.md

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
• Godot Best Practices
• Godot Debugger

Related Documentation

• ARCHITECTURE.md - System design and patterns
• CODE_OF_CONDUCT.md - Coding standards
• TESTING.md - Testing procedures
• UI_COMPONENTS.md - Component API reference