# CLAUDE.md

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

## Project Overview

"Los pollos hermanos" (pollo) is a C++20 game using SDL3 and OpenGL. Cross-platform support for Windows, macOS, and Linux.

## Build Commands

### Using CMake (recommended for development)
```bash
cmake -B build && cmake --build build
```

### Using Makefile (platform-specific)
```bash
# Development builds
make macos          # macOS
make linux          # Linux
make windows        # Windows

# Debug builds (with symbols, starts at GAME scene)
make macos_debug
make linux_debug
make windows_debug

# Release builds (creates distributable packages)
make macos_release   # Creates .dmg files for Intel and Apple Silicon
make linux_release   # Creates .tar.gz
make windows_release # Creates .zip
```

### Static Analysis Targets (via CMake)
```bash
cmake --build build --target tidy        # Run clang-tidy
cmake --build build --target tidy-fix    # Run clang-tidy with auto-fix
cmake --build build --target format      # Run clang-format
cmake --build build --target format-check # Check formatting
```

## Linting Commands

### clang-tidy
```bash
tools/linter/run_clang-tidy.sh [--fix] [files...]  # Specific files or all
tools/linter/run_clang-tidy.sh source/game/entities/player.cpp
```

### cppcheck
```bash
tools/linter/run_cppcheck.sh -w [--path <path>]  # warning, style, performance (daily use)
tools/linter/run_cppcheck.sh -a [--path <path>]  # all checks (exhaustive)
tools/linter/run_cppcheck.sh -u                   # unused functions
# Results saved to tools/linter/cppcheck-result-*.txt
```

## Architecture

### Core Engine (`source/core/`)
- **audio/**: Audio system with `jail_audio.hpp` (external, excluded from linting)
- **input/**: Input handling (keyboard, mouse, gamepad) via `Input`, `Mouse`, `GlobalInputs`
- **rendering/**: SDL3/OpenGL rendering system - `Screen`, `Surface` hierarchy, `Texture`, `Text`, shaders
- **resources/**: Resource pack system - `ResourcePack` for asset bundling, `ResourceCache`, `ResourceLoader`
- **system/**: `Director` (main loop), `GlobalEvents`, `Debug` (debug-only builds)

### Game Logic (`source/game/`)
- **scenes/**: Scene classes (`Logo`, `Title`, `Game`) - each scene manages its own lifecycle
- **scene_manager.hpp**: Scene flow control with `SceneManager` namespace
- **entities/**: Game objects (`Player`, `Enemy`, `Item`)
- **gameplay/**: Game systems - `Room`, `RoomLoader`, `CollisionMap`, `TilemapRenderer`, managers
- **ui/**: UI components (`Notifier`)
- **defaults.hpp**: Game constants (excluded from magic-numbers linting)
- **options.hpp**: Configuration

### Scene Flow
`Director` runs the main loop and delegates to scenes based on `SceneManager::current`:
- Debug builds start at `Scene::GAME`
- Release builds start at `Scene::LOGO` -> `Scene::TITLE` -> `Scene::GAME`

## Code Style

### Naming Conventions (enforced via `.clang-tidy`)
- Variables: `snake_case`
- Private/protected members: `snake_case_` (trailing underscore)
- Classes/Structs/Enums: `CamelCase`
- Enum values: `UPPER_CASE`
- Methods/Functions: `camelBack`
- Namespaces: `CamelCase`
- Constants: `UPPER_CASE`

### Headers
- Use `#pragma once` (not include guards)
- Initialize all struct members with default values
- Prefer `std::array` over C-style arrays
- Order: public section first, then private

## Slash Commands

- `/refactor-class` - Refactors a C++ class applying style best practices, runs linters, compiles
- `/lint-clang-tidy` - Runs clang-tidy analysis with intelligent false positive filtering
- `/lint-cppcheck` - Runs cppcheck analysis with categorized results

## Build Prerequisites

- SDL3 (framework included in `release/frameworks/` for macOS)
- OpenGL
- C++20 compiler (clang++ on macOS, g++ on Linux/Windows)
- CMake 3.10+

## Git Hooks

Pre-commit hooks are stored in `tools/hooks/` and must be configured after cloning:

```bash
make setup_hooks
```

This configures git to use `tools/hooks/` as the hooks directory. The pre-commit hook runs `clang-format` to verify code formatting before each commit.