nett00n/skelly
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
550b2ac2201955f54744af798b1ef21b46c4e032
skelly/docs/CLAUDE.md

9.6 KiB
Raw Blame History

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
Reference in New Issue View Git Blame Copy Permalink