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 that features a match-3 puzzle game within a broader game framework. The project includes a menu system, settings management, audio handling, and localization support.

Project Structure

Core Architecture

• Autoloaded Singletons: The project uses four global singletons (autoloads) defined in project.godot:
  • SettingsManager - Handles game settings and configuration
  • AudioManager - Manages music and sound effects with volume controls
  • GameManager - Handles scene transitions and game state
  • LocalizationManager - Manages multi-language support (English/Russian)

Directory Structure

• scripts/ - Global singleton scripts and utility classes
• scenes/ - Game scenes including main game and match-3 components
  • match3/ - Specialized match-3 game implementation
• ui/ - User interface scenes (MainMenu, SettingsMenu, PressAnyKeyScreen)
• audio/ - Music and sound effect files
• resources/ - Game assets (textures, sprites, animations)
• localization/ - Translation files for internationalization

Scene Management Flow

1. Main entry point: scenes/main.tscn with press-any-key screen
2. Menu navigation: MainMenu → SettingsMenu (with back navigation)
3. Game flow: MainMenu → Game scene → Match3 game integration
4. All scene transitions handled through GameManager singleton

Match-3 Game System

• Located in scenes/match3/
• Grid-based (8x8) tile matching system
• Implements match detection, tile dropping, and grid refilling
• Uses tile instances with position-based grid management
• Automatic cascade matching after tile drops

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

Audio Configuration

• Music: Located in audio/ 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 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 Components

AudioManager (scripts/AudioManager.gd)

• Handles background music with looping
• Manages UI sound effects (click sounds)
• Volume control integration with SettingsManager
• Automatic audio bus configuration

Match3 Game (scenes/match3/match3.gd)

• 8x8 grid system with 5 tile types
• Match detection in horizontal and vertical directions
• Tile dropping physics with position-based movement
• Recursive match clearing and grid refilling

Scene Navigation

• All scene changes go through GameManager for consistency
• Scene paths defined as constants in GameManager
• Error handling for failed scene loads

Input System

• Custom input actions defined in project.godot:
  • ui_pause - Space key or gamepad button
  • any_key - Multiple inputs for menu progression
  • ui_menu_toggle - Escape key or gamepad button

Asset Attribution

Asset sources documented in sources.yaml including:

• Music from Clement Panchout
• Sound effects from Freesound
• Sprites and textures from various itch.io creators