105 lines
5.6 KiB
Markdown
105 lines
5.6 KiB
Markdown
# 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 compile_shaders # Compila shaders GLSL → headers SPIR-V (requereix glslc)
|
||
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
|
||
│ │ ├── shader_backend.hpp (interfície abstracta de post-procesado)
|
||
│ │ └── sdl3gpu/ (pipeline SDL3 GPU)
|
||
│ │ ├── sdl3gpu_shader.* (implementació del backend GPU)
|
||
│ │ └── spv/ (headers SPIR-V generats — protegits amb dummies `.clang-*`)
|
||
│ ├── 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.
|
||
|
||
### GPU / shaders (post-procesado)
|
||
|
||
Pipeline SDL3 GPU portat de `coffee_crisis_arcade_edition`. El canvas 256×192 es pot passar per un backend GPU que aplica PostFX (vinyeta, scanlines, chroma, gamma, mask, curvatura, bleeding, flicker) o CrtPi (scanlines continues amb bloom). Fallback transparent al `SDL_Renderer` clàssic si la GPU falla o si es desactiva.
|
||
|
||
- **Interfície**: `core/rendering/shader_backend.hpp` (`Rendering::ShaderBackend`).
|
||
- **Implementació**: `core/rendering/sdl3gpu/sdl3gpu_shader.*` + shaders GLSL a `data/shaders/` compilats a `spv/*_spv.h` via `glslc` (o precompilats si no hi ha `glslc`).
|
||
- **Emscripten**: compile-time `NO_SHADERS` → sempre ruta clàssica.
|
||
- **macOS**: shaders Metal (MSL) inline dins `sdl3gpu_shader.cpp`; no SPIR-V.
|
||
- **Opcions persistents** a `config.txt` (migració a YAML pendent):
|
||
- `videoGpuAcceleration` (bool)
|
||
- `videoGpuPreferredDriver` (string, buit = auto)
|
||
- `videoShaderEnabled` (bool)
|
||
- `videoShaderType` (0=POSTFX, 1=CRTPI)
|
||
- **Hotkeys** (provisionals fins que hi hagi menú d'opcions): `F9` toggle GPU · `F10` toggle shader · `F11` alterna POSTFX ↔ CRTPI.
|
||
- **API** a `Screen`: `setGpuAcceleration`/`toggleGpuAcceleration`/`isGpuAccelerated`, `setShaderEnabled`/`toggleShaderEnabled`/`isShaderEnabled`, `setActiveShader`/`toggleActiveShader`/`getActiveShader`.
|
||
|
||
Presets PostFX/CrtPi i cicle de presets encara **no** estan implementats — arribaran amb la migració a YAML. Per ara, valors per defecte hardcoded.
|
||
|
||
## 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
|
||
- `data/shaders/` — fonts GLSL per al post-procesado SDL3 GPU (no van al pack; s'empotren al binari via headers SPIR-V)
|
||
|
||
## Language
|
||
|
||
Code comments and variable names are primarily in Spanish/Catalan-Valencian. README is in Catalan-Valencian.
|