# 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 SDL2. 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: `libsdl2-dev` and `g++` (Linux) or `clang++` (macOS).

```bash
# Linux
make linux           # Release build → ./coffee_crisis
make linux_debug     # Debug build (defines DEBUG and PAUSE) → ./coffee_crisis_debug

# macOS
make macos           # Release build with clang++
make macos_debug     # Debug build

# Windows (MinGW)
make windows         # Release build → coffee_crisis.exe
make windows_debug   # Debug build

# Release packaging
make linux_release   # Builds and creates .tar.gz
make macos_release   # Builds Intel + Apple Silicon .dmg files
make windows_release # Builds and creates .zip
```

There is also a CMakeLists.txt available as an alternative build system.

There are no tests or linter configured.

## Architecture

All source code is in `source/`. The game uses a section-based architecture controlled by the **Director** class:

- **Director** (`director.h/cpp`): Top-level controller. Initializes SDL, manages the window/renderer, and runs sections in sequence: Logo → Intro → Title → Game → Quit. Owns all shared objects (Screen, Input, Lang, Asset).
- **Game** (`game.h/cpp`): Core gameplay logic. Manages players, balloons (enemies), bullets, items, stages, menace level, and collision detection. Contains its own update/render loop plus sub-loops for pause and game over screens.
- **Screen** (`screen.h/cpp`): Rendering abstraction. Manages a virtual canvas (256×192) that gets scaled to the actual window. Handles fullscreen/windowed modes, border rendering, and fade effects.
- **Input** (`input.h/cpp`): Abstracts keyboard and gamepad input.
- **Asset** (`asset.h/cpp`): Resource file index. Files are registered with `add()` and retrieved by name with `get()`. All paths are relative to the executable.
- **Lang** (`lang.h/cpp`): i18n system loading text strings from files in `data/lang/`.

### Sprite hierarchy

- **Sprite** → base class for drawing from a PNG spritesheet
- **AnimatedSprite** → extends Sprite with frame-based animation (loaded from `.ani` files)
- **MovingSprite** → sprite with movement
- **SmartSprite** → sprite with autonomous behavior (score popups, thrown items)

### Game entities

- **Player** (`player.h/cpp`): Player character state and rendering
- **Balloon** (`balloon.h/cpp`): Enemy entities with multiple types and split-on-pop behavior
- **Bullet** (`bullet.h/cpp`): Projectiles fired by the player (left/center/right)
- **Item** (`item.h/cpp`): Collectible items (points, clock, coffee, power-ups)

### Audio

**jail_audio** (`jail_audio.h/cpp`): Custom audio library wrapping SDL2 audio. Uses stb_vorbis for OGG decoding. Provides `JA_*` functions for music and sound effects with channel-based mixing.

### Key constants

Defined in `const.h`: block size (8px), virtual canvas (256×192), play area bounds, section/subsection IDs, and color definitions.

## 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/config/` — gamecontroller DB, demo recording data
- `data/menu/` — menu definition files

## Language

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