skelly/docs/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

"Skelly" is a Godot 4.4 mobile game project featuring multiple gameplay modes within a unified game framework. The project currently supports match-3 puzzle gameplay with planned support for clickomania gameplay. It includes a modular gameplay system, menu system, settings management, audio handling, localization support, and a comprehensive debug system.

For detailed project architecture, see docs/MAP.md

Development Commands

Running the Project

• Open project in Godot Editor: Import project.godot
• Run project: Press F5 in Godot Editor or use "Play" button
• Debug: Use Godot's built-in debugger and remote inspector
• Debug UI: Press F12 in-game or use debug button to toggle debug panels

Testing & Development

• Debug mode can be toggled with F12 key or debug button UI (available on all major scenes)
• Match-3 debug controls include gem count adjustment and board reroll
• Difficulty presets: Easy (3 gems), Normal (5 gems), Hard (8 gems)
• Gameplay mode switching: Space+Enter in game scene switches between match-3 and clickomania modes
• Match-3 Gem Movement Testing:
  • Keyboard: Arrow keys or WASD to navigate, Enter to select/confirm
  • Gamepad: D-pad to navigate, A button to select/confirm
  • Visual feedback: Selected tiles glow brighter with scale and color effects
  • Invalid swaps automatically revert after animation
  • State machine: WAITING → SELECTING → SWAPPING → PROCESSING
• Test scripts located in tests/ directory for system validation
• Use test_logging.gd to validate the logging system functionality

Audio Configuration

• Music: Located in assets/audio/music/ directory with loop configuration in AudioManager
• Sound effects: UI clicks and game audio managed through audio bus system
• Audio buses: "Music" and "SFX" buses configured in data/default_bus_layout.tres

Localization

• Translations stored in localization/ as .translation files
• Currently supports English and Russian
• New translations: Add to project.godot internationalization section

Asset Management

• CRITICAL: Every asset must be documented in assets/sources.yaml before committing
• Include source, license, attribution, modifications, and usage information
• Verify license compatibility with project requirements
• Commit asset files and sources.yaml together in the same commit

Key Development Guidelines

Code Quality & Safety Standards

• Memory Management: Always use queue_free() instead of free() for node cleanup
• Input Validation: Validate all user inputs with bounds checking and type validation
• Error Handling: Implement comprehensive error handling with fallback mechanisms
• Race Condition Prevention: Use state flags to prevent concurrent operations
• No Global State: Avoid static variables; use instance-based architecture for testability

Scene Management

• ALWAYS use GameManager for scene transitions - never call get_tree().change_scene_to_file() directly
• Scene paths are defined as constants in GameManager
• Error handling is built into GameManager for failed scene loads with proper validation
• Use GameManager.start_game_with_mode(mode) to launch specific gameplay modes
• Supported gameplay modes: "match3", "clickomania" (validated with whitelist)
• GameManager prevents concurrent scene changes with is_changing_scene protection

Autoload Usage

• Use autoloads for global state management only
• Prefer signals over direct access for loose coupling
• Don't access autoloads from deeply nested components
• SettingsManager: Features comprehensive input validation and error recovery
• GameManager: Protected against race conditions with state management

Debug System Integration

• Connect to DebugManager.debug_ui_toggled signal for debug UI visibility
• Use F12 key for global debug toggle
• Remove debug prints before committing unless permanently useful

Logging System Usage

• CRITICAL: ALL print() and push_error() statements have been migrated to DebugManager
• ALWAYS use DebugManager logging functions instead of print(), push_error(), etc.
• Use appropriate log levels: INFO for general messages, WARN for issues, ERROR for failures
• Include meaningful categories to organize log output: "GameManager", "Match3", "Settings", "Game", "MainMenu", "PressAnyKey", "Clickomania", "DebugMenu"
• Leverage structured logging for better debugging and production monitoring
• Use DebugManager.set_log_level() to control verbosity during development and testing
• The logging system provides unified output across all game systems

Important File References

Documentation Structure

• docs/MAP.md - Complete project architecture and structure
• docs/CODE_OF_CONDUCT.md - Coding standards and best practices
• docs/TESTING.md - Testing guidelines and conventions
• This file - Claude Code specific development guidelines

Key Scripts to Understand

• src/autoloads/GameManager.gd - Scene transition patterns with race condition protection
• src/autoloads/SettingsManager.gd - Settings management with comprehensive error handling
• src/autoloads/DebugManager.gd - Debug system integration
• scenes/game/game.gd - Main game scene with modular gameplay system
• scenes/game/gameplays/match3_gameplay.gd - Memory-safe Match-3 implementation with input validation
• scenes/game/gameplays/tile.gd - Instance-based tile behavior without global state
• scenes/ui/DebugMenuBase.gd - Unified debug menu base class (eliminates code duplication)
• scenes/ui/SettingsMenu.gd - Settings UI with input validation
• scenes/game/gameplays/ - Individual gameplay mode implementations
• project.godot - Input actions and autoload definitions
  • Gem movement actions: select_gem, move_up/down/left/right

Development Workflow

Before Making Changes

1. Check docs/MAP.md for architecture understanding
2. Review docs/CODE_OF_CONDUCT.md for coding standards
3. Understand existing patterns before implementing new features
4. If adding assets, prepare assets/sources.yaml documentation

Testing Changes

• Run project with F5 in Godot Editor
• Test debug UI with F12 toggle
• Verify scene transitions work correctly
• Check mobile compatibility if UI changes made
• Use relevant test scripts from tests/ directory to validate system functionality
• Run test_logging.gd after making changes to the logging system

Common Implementation Patterns

• Scene transitions: Use GameManager.start_game_with_mode() with built-in validation
• Debug integration: Connect to DebugManager signals and initialize debug state
• Logging: Use DebugManager.log_*() functions with appropriate levels and categories
• Gameplay modes: Implement in scenes/game/gameplays/ directory following modular pattern
• Scoring system: Connect score_changed signal from gameplay to main game scene
• Settings: Use SettingsManager with automatic input validation and error recovery
• Audio: Use AudioManager for music and sound effects
• Localization: Use LocalizationManager for language switching
• UI Components: Extend DebugMenuBase for debug menus to avoid code duplication
• Memory Management: Use queue_free() and await frame completion for safe cleanup
• Input Validation: Always validate user inputs with type checking and bounds validation

Logging Best Practices

# ✅ Good logging practices
DebugManager.log_info("Scene transition completed", "GameManager")
DebugManager.log_warn("Settings file not found, using defaults", "Settings")
DebugManager.log_error("Failed to load audio resource: " + audio_path, "AudioManager")

# ❌ Avoid these patterns
print("debug")  # Use structured logging instead
push_error("error")  # Use DebugManager.log_error() with category

Asset Management Workflow

# ✅ Required assets/sources.yaml entry format
audio:
  music:
    "background_music.ogg":
      source: "https://freesound.org/people/artist/sounds/123456/"
      license: "CC BY 4.0"
      attribution: "Background Music by Artist Name"
      modifications: "Converted to OGG, adjusted volume"
      usage: "Main menu and gameplay background music"

# ✅ Proper commit workflow
# 1. Add asset to appropriate assets/ subdirectory
# 2. Update assets/sources.yaml with complete metadata
# 3. git add both files together
# 4. Commit with descriptive message including attribution