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

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

Key Development Guidelines

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
• Use GameManager.start_game_with_mode(mode) to launch specific gameplay modes
• Supported gameplay modes: "match3", "clickomania"

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

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

Important File References

Documentation Structure

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

Key Scripts to Understand

• src/autoloads/GameManager.gd - Scene transition patterns and gameplay mode management
• src/autoloads/DebugManager.gd - Debug system integration
• scenes/game/game.gd - Main game scene with modular gameplay system
• scenes/game/gameplays/match3_gameplay.gd - Match-3 implementation reference
• 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 understanding
2. Review docs/CODE_OF_CONDUCT.md for coding standards
3. Understand existing patterns before implementing new features

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

Common Implementation Patterns

• Scene transitions: Use GameManager.start_game_with_mode() and related methods
• Debug integration: Connect to DebugManager signals and initialize debug state
• 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 for persistent configuration
• Audio: Use AudioManager for music and sound effects
• Localization: Use LocalizationManager for language switching