skelly/docs/CLAUDE.md

CLAUDE.md

Guidance for Claude Code (claude.ai/code) when working with this repository.

Project Overview

"Skelly" is a Godot 4.4 mobile game project with multiple gameplay modes. Supports match-3 puzzle gameplay with planned clickomania gameplay. Includes modular gameplay system, menu system, settings management, audio handling, localization support, and 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 TestLogging.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

• Document every asset in assets/sources.yaml before committing
• Include source, license, attribution, modifications, and usage information
• Verify license compatibility
• Commit asset files and sources.yaml together

Key Development Guidelines

Code Quality & Safety Standards

• Memory Management: Use queue_free() instead of free()
• Input Validation: Validate user inputs with bounds checking and type validation
• Error Handling: Implement 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

• Use GameManager for all scene transitions - never call get_tree().change_scene_to_file() directly
• Scene paths defined as constants in GameManager
• Error handling built into GameManager for failed scene loads
• Use GameManager.start_game_with_mode(mode) to launch specific gameplay modes
• Supported 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
• SaveManager: Save system with tamper detection, race condition protection, and permissive validation
• SettingsManager: Features input validation, NaN/Infinity checks, and security hardening
• GameManager: Protected against race conditions with state management

Save System Security & Data Integrity

• SaveManager implements security standards for data protection
• Tamper Detection: Deterministic checksums detect save file modification or corruption
• Race Condition Protection: Save operation locking prevents concurrent conflicts
• Permissive Validation: Auto-repair system fixes corrupted data instead of rejecting saves
• Type Safety: NaN/Infinity/bounds checking for numeric values
• Memory Protection: File size limits prevent memory exhaustion attacks
• Version Migration: Backward-compatible system handles save format upgrades
• Error Recovery: Multi-layered backup and fallback systems ensure no data loss
• Security Logging: All save operations logged for monitoring and debugging

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

• All print() and push_error() statements migrated to DebugManager
• Use DebugManager logging functions instead of print(), push_error(), etc.
• Use log levels: INFO for general messages, WARN for issues, ERROR for failures
• Include categories to organize log output: "GameManager", "Match3", "Settings", "DebugMenu"
• Use structured logging for better debugging and production monitoring
• Use DebugManager.set_log_level() to control verbosity during development and testing
• Logging system provides unified output across all game systems

Important File References

Documentation Structure

• docs/MAP.md - Complete project architecture and structure
• docs/UI_COMPONENTS.md - Custom UI components
• 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/SaveManager.gd - Save system with security features
• src/autoloads/SettingsManager.gd - Settings management with input validation and security
• src/autoloads/DebugManager.gd - Debug system integration
• scenes/game/game.gd - Main game scene with modular gameplay system
• scenes/game/gameplays/Match3Gameplay.gd - 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
• scenes/ui/SettingsMenu.gd - Settings UI with input validation
• scenes/game/gameplays/ - Individual gameplay mode implementations
• project.godot - Input actions and autoload definitions

Development Workflow

Before Making Changes

1. Check docs/MAP.md for architecture
2. Review docs/CODE_OF_CONDUCT.md for coding standards
3. Review naming conventions: See Naming Convention Quick Reference for all file and code naming standards
4. Understand existing patterns before implementing features
5. If adding assets, prepare assets/sources.yaml documentation following asset naming conventions

Testing Changes

• Run project with F5 in Godot Editor
• Test debug UI with F12 toggle
• Verify scene transitions work
• Check mobile compatibility if UI changes made
• Use test scripts from tests/ directory to validate functionality
• Run TestLogging.gd after logging system changes
• Save system testing: Run save/load test suites after SaveManager changes
• Checksum validation: Test test_checksum_issue.gd to verify deterministic checksums
• Migration compatibility: Run TestMigrationCompatibility.gd for version upgrades

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
• Save/Load operations: Use SaveManager with security and validation
• Settings: Use SettingsManager with input validation, NaN/Infinity checks, and security hardening
• 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
• Value Selection: Use ValueStepper component for discrete option selection (language, resolution, difficulty)
• Memory Management: Use queue_free() and await frame completion for safe cleanup
• Input Validation: Validate user inputs with type checking and bounds validation

Logging Best Practices

# Good logging
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
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