# 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 (delegates to CMake)
```bash
make                      # build Release via cmake
make debug                # build Debug via cmake
make release              # create release package (auto-detects OS)
make linux_release        # release tar.gz with resources.pack
make windows_release      # release zip for Windows
make macos_release        # release dmg for macOS (Intel + Apple Silicon)
make raspi_release        # release tar.gz for Raspberry Pi
```

### 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

### Source layout
The `source/` tree is organised in the same style as the sibling projects `projecte_2026` and `jaildoctors_dilemma`:

```
source/
├── core/           # engine: audio, input, locale, rendering (+ sdl3gpu, sprite), resources, system
├── game/           # gameplay: entities, gameplay, scenes, ui, options
├── utils/          # color, param, utils
├── external/       # vendored third-party headers (json, fkyaml, stb_*)
└── main.cpp
```

`#include` paths are absolute relative to `source/` (e.g. `#include "core/audio/audio.hpp"`, `#include "game/scenes/logo.hpp"`). The CMake build adds a single `-I${CMAKE_SOURCE_DIR}/source`.

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

### Scenes (source/game/scenes/)
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 (`source/game/gameplay/`)
- `Player` — Two-player support (player 1: keyboard, player 2: gamepad) (`source/game/entities/`)

### 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/core/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` lives in `source/core/audio/` and `gif.{hpp,cpp}` in `source/core/rendering/` — these are first-party, not third-party.

## 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/`.
