# CLAUDE.md

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

## Project Overview

Coffee Crisis is a C++20 arcade game built with SDL3. The player controls a character defending the UPV (university) from bouncing coffee-ball enemies across 10 stages. Supports 1-2 players, keyboard and gamepad input, and multiple languages (Spanish, Basque, English).

## Build Commands

Dependencies: `libsdl3-dev` and `g++` (Linux) or `clang++` (macOS). Build system is CMake (driven by `Makefile` wrappers).

```bash
make              # Release build
make debug        # Debug build (defines DEBUG and PAUSE)
make release      # Empaqueta .tar.gz / .dmg / .zip segons SO
make pack         # Regenera resources.pack
make controllerdb # Descarga gamecontrollerdb.txt
make format       # clang-format -i
make tidy         # clang-tidy
make cppcheck     # cppcheck
```

## Architecture

Source layout (alineat amb la resta de projectes germans):

```
source/
├── main.cpp
├── core/
│   ├── audio/       jail_audio.hpp
│   ├── input/       input.*, mouse.*
│   ├── locale/      lang.*
│   ├── rendering/   screen, fade, text, writer, texture, sprite + animated/moving/smart
│   ├── resources/   asset, resource, resource_pack, resource_loader, resource_helper
│   └── system/      director
├── game/
│   ├── defaults.hpp (constants de gameplay: block size, canvas, áreas, colors)
│   ├── game.*       (hub de gameplay)
│   ├── entities/    player, balloon, bullet, item
│   ├── scenes/      logo, intro, title, instructions
│   └── ui/          menu
├── utils/
│   ├── defines.hpp  (macros de build)
│   └── utils.*      (helpers, enum de dificultat, circle_t, ...)
└── external/        (stb_image, stb_vorbis — protegits amb dummies `.clang-*`)
```

Flux general controlat per la classe **Director** (`core/system/director.h`): inicialitza SDL, finestra/renderer i executa seccions en seqüència **Logo → Intro → Title → Game → Quit**. Les classes principals:

- **Game** (`game/game.h`): gameplay nuclear. Gestiona jugadors, balloons, bullets, items, stages, nivell d'amenaça i col·lisions. Té el seu bucle d'update/render i sub-bucles per pausa i game-over.
- **Screen** (`core/rendering/screen.h`): abstracció de render. Canvas virtual 256×192 escalat a la finestra. Fullscreen/windowed, borders, fades.
- **Input** (`core/input/input.h`): abstracció de teclat i gamepad.
- **Asset** (`core/resources/asset.h`): índex de fitxers de recurs (`add`/`get` per nom).
- **Lang** (`core/locale/lang.h`): i18n, carrega strings des de `data/lang/`.

### Sprite hierarchy (`core/rendering/`)

- **Sprite** → base per dibuixar des d'un spritesheet PNG
- **AnimatedSprite** → afegeix animació per frames (arxius `.ani`)
- **MovingSprite** → sprite amb posició/velocitat
- **SmartSprite** → sprite autònom (score popups, objectes llençats)

### Audio

**jail_audio** (`core/audio/jail_audio.hpp`): wrapper audio SDL3 first-party. Usa stb_vorbis per OGG. API `JA_*` per música i efectes amb mesclat per canals.

## Data Directory

- `data/gfx/` — PNG spritesheets and `.ani` animation definition files
- `data/font/` — bitmap font files
- `data/music/` and `data/sound/` — audio assets
- `data/lang/` — language files (es_ES, ba_BA, en_UK)
- `data/demo/` — demo recording data (gamecontrollerdb.txt vive en la raíz del proyecto, fuera del pack)
- `data/menu/` — menu definition files

## Language

Code comments and variable names are primarily in Spanish/Catalan-Valencian. README is in Catalan-Valencian.