# CLAUDE.md

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

## Project Overview

Coffee Crisis Arcade Edition is a 2-player cooperative arcade shooter built with C++20 and SDL3. Players defend coffee against giant balloons. The game targets Windows, Linux, macOS (Intel/Apple Silicon), Raspberry Pi, and Anbernic handhelds.

## Build Commands

The project uses both CMake and a top-level Makefile. The Makefile is the primary build interface.

### CMake (generates compile_commands.json for IDE/linter support)
```bash
cmake -B build -DCMAKE_BUILD_TYPE=Debug   # configure
cmake --build build                        # build
```

### Makefile (direct compilation, platform-specific targets)
```bash
make linux                # build for Linux
make linux_debug          # debug build with -DDEBUG -DVERBOSE
make linux_release        # release tar.gz with resources.pack
make windows              # build for Windows (cross-compile or native)
make windows_debug        # Windows debug build
make macos                # build for macOS (arm64)
make raspi                # build for Raspberry Pi
make anbernic             # build for Anbernic (no shaders, arcade mode)
make no_audio             # build without audio system
```

### Tools & Resources
```bash
make pack_tool            # compile resource packer
make resources.pack       # pack data/ into resources.pack (required for release builds)
make spirv                # compile GLSL shaders to SPIR-V headers
```

### Code Quality
```bash
make format               # run clang-format on all sources (or: cmake --build build --target format)
make format-check         # check formatting without modifying
make tidy                 # run clang-tidy static analysis (cmake --build build --target tidy)
make tidy-fix             # run clang-tidy with auto-fix
```

## Architecture

### Singletons (core systems)
- **Director** (`source/director.hpp`) — Application state machine, orchestrates scene transitions (Logo → Intro → Title → Game → Credits/HiScore → Title)
- **Screen** (`source/screen.hpp`) — Window management, SDL3 GPU rendering pipeline, post-processing effects
- **Resource** (`source/resource.hpp`) — Asset loading/caching with PRELOAD and LAZY_LOAD modes, reads from `resources.pack`
- **Audio** (`source/audio.hpp`) — Music and SFX management
- **Input** (`source/input.hpp`) — Keyboard and gamepad input handling

### Scenes (source/sections/)
Each scene is a self-contained class with update/render lifecycle. Scene flow is managed by Director.

### Entity Managers
- `BalloonManager` / `BulletManager` — Object pool-based entity management
- `Player` — Two-player support (player 1: keyboard, player 2: gamepad)

### Rendering Pipeline
- SDL3 GPU API (Vulkan/Metal/D3D12 backends)
- SPIR-V shaders compiled offline from GLSL (`data/shaders/`) via `glslc`
- Compiled shader headers embedded in `source/rendering/sdl3gpu/postfx_*_spv.h`
- macOS uses Metal (no SPIR-V compilation needed)

### Configuration
- Game parameters: `config/param_320x240.txt`, `config/param_320x256.txt`
- Asset manifest: `config/assets.txt`
- Balloon formations: `config/formations.txt`
- Level definitions: `config/stages.txt`
- Gamepad mappings: `config/gamecontrollerdb.txt`

### External Libraries (header-only/vendored in source/external/)
- nlohmann/json, fkyaml (YAML), stb_image, stb_vorbis, jail_audio

## Code Style

Enforced via `.clang-format` (Google-based) and `.clang-tidy`:

- **Naming conventions**: Classes/structs `CamelCase`, methods/functions `camelBack`, variables/params `snake_case`, private/protected members `snake_case_` (trailing underscore), constants/constexpr `UPPER_CASE`, namespaces `CamelCase`, enum values `UPPER_CASE`
- 4-space indentation, no column limit, braces attach to statement
- clang-tidy treats all warnings as errors

## Conditional Compilation Defines

| Define | Purpose |
|--------|---------|
| `WINDOWS_BUILD` / `LINUX_BUILD` / `MACOS_BUILD` | Platform selection |
| `DEBUG` / `VERBOSE` | Debug output |
| `RELEASE_BUILD` | Release-specific code paths |
| `RECORDING` | Demo recording mode |
| `NO_SHADERS` | Disable shader pipeline (Anbernic) |
| `NO_AUDIO` | Build without audio |
| `ARCADE` | Arcade-specific mode |
| `MACOS_BUNDLE` | macOS .app bundle paths |
| `ANBERNIC` | Anbernic handheld build |

## Language

Code comments are in Spanish/Catalan. Game UI supports multiple languages via JSON files in `data/lang/`.