# Arquitectura de **Coffee Crisis Arcade Edition**

> Guía de orientación para un desarrollador nuevo en el proyecto.
>
> Cada afirmación está anclada a código real: se cita el fichero (y, cuando
> ayuda, la función o el número de línea) que la respalda. Donde no he
> encontrado algo, lo digo explícitamente en lugar de inventarlo.
>
> **Coffee Crisis Arcade Edition** es un *shooter* arcade cooperativo de 2
> jugadores escrito en **C++20 sobre SDL3**: los jugadores defienden el café
> de globos gigantes. Apunta a Windows, Linux, macOS (Intel/Apple Silicon),
> Raspberry Pi, Anbernic y web (Emscripten). Los comentarios del código están
> en español/valenciano; este documento está en castellano.

---

## Índice

1. [Visión general](#1-visión-general)
2. [Punto de entrada y bucle principal](#2-punto-de-entrada-y-bucle-principal)
3. [Secciones y flujo de la aplicación](#3-secciones-y-flujo-de-la-aplicación)
4. [Renderizado: de la lógica al píxel](#4-renderizado-de-la-lógica-al-píxel)
5. [Entrada](#5-entrada)
6. [Lógica del juego: la clase `Game`](#6-lógica-del-juego-la-clase-game)
7. [Entidades y managers de gameplay](#7-entidades-y-managers-de-gameplay)
8. [Modo demo y attract mode](#8-modo-demo-y-attract-mode)
9. [Recursos](#9-recursos)
10. [Audio](#10-audio)
11. [Configuración, parámetros y constantes](#11-configuración-parámetros-y-constantes)
12. [Localización](#12-localización)
13. [Convenciones y patrones recurrentes](#13-convenciones-y-patrones-recurrentes)
14. [Guía de navegación: "si quieres tocar X, mira Y"](#14-guía-de-navegación-si-quieres-tocar-x-mira-y)

---

## 1. Visión general

El árbol `source/` separa **motor** y **juego**:

- **`source/core/`** — motor genérico: `system` (arranque, secciones, demo,
  eventos globales), `rendering` (+ `sdl3gpu`, `sprite`), `input`, `resources`,
  `audio`, `locale`.
- **`source/game/`** — el juego concreto: `scenes` (las secciones), `gameplay`
  (managers), `entities` (jugador, globos, balas, ítems…), `ui`, y `options`.
- **`source/utils/`** — `color`, `param`, `utils`, `defines`.
- **`source/external/`** — vendorizado: `nlohmann/json`, `fkyaml`, `stb_image`,
  `stb_vorbis`.

Los `#include` son **absolutos respecto a `source/`** (p.ej.
`#include "core/audio/audio.hpp"`); CMake añade un único `-I.../source`
(ver `CLAUDE.md`). ~150 ficheros C++, ~32.000 líneas.

**Cuatro ideas-fuerza que conviene interiorizar:**

1. **El flujo de la aplicación se conduce con una variable global**
   (`Section::name`), no con objetos de transición. El `Director` reacciona a
   sus cambios (§3).
2. **El render usa texturas GPU vía `SDL_Renderer`** dibujadas sobre una
   *render-target texture*, con post-procesado opcional vía un backend SDL3
   GPU. No es un blitter de software (§4).
3. **El gameplay se organiza con managers/pools** (`BalloonManager`,
   `BulletManager`, `StageManager`) coordinados por una clase `Game` muy grande
   (§6, §7).
4. **Sí hay modo demo** (*attract mode*): es **reproducción de input grabado**,
   no IA (§8).

```mermaid
graph TD
    SDL[SDL3 callbacks · main.cpp] --> DIR[Director]
    DIR -->|lee Section::name| ST{handleSectionTransition}
    ST --> SEC["Section activa (Logo/Intro/Title/Game/…)"]
    DIR --> GE[GlobalEvents] --> INP[Input] & SVC[ServiceMenu]
    SEC --> GAME[Game]
    GAME --> BM[BalloonManager] & BLM[BulletManager] & STG[StageManager]
    GAME --> PL[Players] -->|Input::Action| INP
    GAME --> DEMO["Demo (playback de input grabado)"] -.->|setInput| PL
    GAME -->|SDL_RenderTexture| CV["game_canvas_ (render target)"]
    CV -->|RenderReadPixels → uploadPixels| SB[ShaderBackend SDL3 GPU] --> WIN[Ventana]
    RES["Resource / Asset"] -.-> GAME & SEC
```

---

## 2. Punto de entrada y bucle principal

### 2.1. SDL conduce el bucle (callbacks)

`source/main.cpp` define `SDL_MAIN_USE_CALLBACKS`: no hay `while` propio. SDL
llama a cuatro funciones, todas delegando en el `Director`:

```cpp
SDL_AppInit   → *appstate = new Director(argc, argv);   // main.cpp:15
SDL_AppIterate→ Director::iterate();                     // un frame
SDL_AppEvent  → Director::handleEvent(event);            // un evento
SDL_AppQuit   → delete Director;
```

### 2.2. El `Director`

`source/core/system/director.{hpp,cpp}` es el orquestador. Mantiene **un
`unique_ptr` por cada sección** (`preload_`, `logo_`, `intro_`, `title_`,
`game_`, …) de los que **solo uno está vivo** a la vez (`director.hpp:60`).

**Constructor (`director.cpp:82`)**: fija la semilla aleatoria, crea la carpeta
de sistema (`jailgames/coffee_crisis_arcade_edition`), decide la sección
inicial según el build (`RECORDING` → GAME; `_DEBUG` → lee `debug.yaml`; Release
→ LOGO) y llama a `init()`.

**`init()` (`director.cpp:131`)** inicializa en orden: `Asset` (índice de
ficheros), sistema de recursos (`resources.pack`, con/ sin *fallback* a disco
según build), `Input`, `Options` (config.yaml, controllers.json, presets de
shaders), parámetros y *scores*, `Lang`, `Screen`, `Audio` y `Resource`.

### 2.3. Arranque NO bloqueante (PRELOAD incremental)

Un detalle importante: si el modo de carga es `PRELOAD`, **no se cargan todos
los recursos de golpe**. `init()` redirige el arranque a la sección `PRELOAD`
guardando el destino real en `Section::post_preload` (`director.cpp:191`):

```cpp
Section::post_preload = Section::name;   // destino real
Section::name = Section::Name::PRELOAD;  // mientras tanto, barra de progreso
Resource::get()->beginLoad();
```

Cada frame, `Director::iterate()` (`director.cpp:489`) llama a
`Resource::loadStep(50 /*ms*/)`: carga recursos hasta agotar un presupuesto de
50 ms por frame, manteniendo la ventana y el bucle vivos. Cuando termina,
`finishBoot()` inicializa lo que depende de los recursos (`ServiceMenu`,
`Notifier`, singletons de `Screen`) y salta a `post_preload`.

### 2.4. Orden del frame y gestión del tiempo

`Director::iterate()` (`director.cpp:489`):

```mermaid
sequenceDiagram
    participant SDL
    participant Dir as Director::iterate
    participant Sec as Section activa
    SDL->>Dir: SDL_AppIterate
    alt boot_loading_
        Dir->>Dir: Resource::loadStep(50ms) → finishBoot() al terminar
    end
    Dir->>Dir: handleSectionTransition() (destruye/crea sección)
    Dir->>Sec: iterate()  (la sección hace su propio update+render)
```

El tiempo es **time-based**: cada sección calcula su propio `delta_time`. En
`Game` es `calculateDeltaTime()` (`game.hpp:210`), usado en todos los `update`.
Los eventos llegan por separado vía `Director::handleEvent` →
`GlobalEvents::handle` + reenvío a la sección activa (`director.cpp:539`).

### 2.5. Reinicio en caliente

Igual que su proyecto hermano, soporta reinicio real vía `execv`
(`Director::relaunch()`, `director.cpp:254`): la sección `RESET` (p.ej. tras
F10 o cambio de idioma) reemplaza el proceso por sí mismo; si no se puede
(Emscripten, `argv` inválido), cae a un `reset()` interno que recarga recursos y
vuelve a `LOGO`.

---

## 3. Secciones y flujo de la aplicación

### 3.1. Variables globales de estado

`source/core/system/section.hpp` define el estado del flujo como **variables
globales `inline`** en el namespace `Section`:

```cpp
inline Name name = Name::RESET;            // sección a la que ir
inline Name post_preload = Name::LOGO;     // destino tras PRELOAD
inline Options options = Options::NONE;    // 1P/2P/BOTH, timeouts, etc.
inline AttractMode attract_mode = AttractMode::TITLE_TO_DEMO;
```

`Name` enumera: `RESET, PRELOAD, LOGO, INTRO, TITLE, GAME, HI_SCORE_TABLE,
GAME_DEMO, INSTRUCTIONS, CREDITS, QUIT`. Cualquier parte del código cambia el
flujo simplemente asignando `Section::name = ...`.

### 3.2. La transición de secciones

`Director::handleSectionTransition()` (`director.cpp:390`) se ejecuta cada
frame:

- Si `Section::name == RESET`: intenta `relaunch()`; si vuelve, hace el reset
  interno.
- Si `Section::name == last_built_section_name_`: no hace nada (ya está viva).
- Si cambió: `resetActiveSection()` (libera todos los `unique_ptr`) y un
  `switch` construye la nueva sección. Para `GAME` traduce `Section::options`
  a `Player::Id` (1P/2P/BOTH); para `GAME_DEMO` construye `Game(..., DEMO_ON)`
  con jugador aleatorio (`director.cpp:448`).

Cada sección (`source/game/scenes/`) es autónoma y expone `iterate()` +
`handleEvent()`. `Director::iterate` despacha al puntero vivo con una cadena de
`if/else if` (`director.cpp:517`).

```mermaid
graph LR
    RESET --> PRELOAD --> LOGO --> INTRO --> TITLE
    TITLE -->|jugar| GAME --> HI_SCORE_TABLE --> TITLE
    TITLE -->|timeout / attract| GAME_DEMO --> TITLE
    TITLE -->|attract alterno| LOGO
    TITLE --> INSTRUCTIONS & CREDITS
```

### 3.3. Attract mode

El *attract mode* alterna entre mostrar la demo y volver al logo. En
`title.cpp:51` el Title, al construirse, mira `Section::attract_mode` y fija su
`next_section_` (a `GAME_DEMO` o `LOGO`), **invirtiendo el modo** para la
próxima vez. Cuando el Title agota su *timeout* sin input, salta a esa sección
(ver §8).

---

## 4. Renderizado: de la lógica al píxel

A diferencia de un blitter de software, aquí **los sprites son texturas GPU**
compuestas por `SDL_Renderer`, y el post-procesado se hace en un backend SDL3
GPU.

### 4.1. `Texture` y la jerarquía de sprites

- `source/core/rendering/texture.hpp` — `Texture` envuelve un `SDL_Texture*`,
  con `loadFromFile`, `createBlank`, `setAsRenderTarget` y un `render(x, y,
  clip, zoom, angle, …)`. Es la unidad de dibujo.
- `source/core/rendering/sprite/` — jerarquía sobre `Sprite`
  (`sprite.hpp:13`), que guarda **varias texturas** (`textures_`), un
  `sprite_clip_` y posición/zoom:
  - `AnimatedSprite` — animación por fotogramas (clip que avanza).
  - `MovingSprite` — con velocidad.
  - `PathSprite` — sigue rutas precalculadas (`Path`).
  - `SmartSprite` — sprite con lógica propia (p.ej. el café que salta al ser
    golpeado).
  - `CardSprite` — variante para "cartas"/paneles.

El `Player`, por ejemplo, compone un `AnimatedSprite player_sprite_` y un
`power_sprite_` para el aura (`player.hpp:250`).

### 4.2. Dos render-targets

Hay **dos texturas de destino** encadenadas:

1. **`Game::canvas_`** — textura de la *zona de juego*. `Game::fillCanvas()`
   (`game.cpp`) fija el render-target a `canvas_` y dibuja, **en este orden**:
   `background → smart_sprites → items → balloons → tabe → players → bullets →
   path_sprites`. Ese orden es el z-order del playfield.

2. **`Screen::game_canvas_`** — textura de *pantalla completa* (ARGB8888 a la
   resolución de juego; `screen.cpp:92`, `SDL_TEXTUREACCESS_TARGET`).
   `Game::render()` hace `screen_->start()` (que pone el target en
   `game_canvas_`), copia `canvas_` sobre él, y encima dibuja **scoreboard** y
   los **fades** de entrada/salida; finalmente `screen_->render()`.

### 4.3. Post-procesado y presentación

`Screen::renderPresent()` (`screen.cpp:156`) decide cómo llega a la ventana:

- **Con backend GPU acelerado**: lee los píxeles de `game_canvas_` con
  `SDL_RenderReadPixels` a un `pixel_buffer_` CPU, los sube al backend
  (`shader_backend_->uploadPixels(...)`) y este los renderiza con el shader
  activo (`shader_backend_->render()`).
- **Sin backend** (fallback): vuelca `game_canvas_` directamente a la ventana
  con `SDL_RenderTexture`.

El backend vive en `source/core/rendering/sdl3gpu/` (SDL3 GPU API; shaders
SPIR-V compilados offline desde GLSL en `data/shaders/`, embebidos en cabeceras
`spv/`/`msl/`). Hay dos shaders seleccionables, **PostFX** y **CrtPi**, con
presets en `postfx.yaml`/`crtpi.yaml` (`screen.cpp:382`). El build `NO_SHADERS`
(Anbernic) desactiva todo el pipeline de shaders.

```mermaid
graph TD
    OBJ["background, balloons, players, bullets…"] -->|SDL_RenderTexture| CANVAS["Game::canvas_ (zona de juego)"]
    CANVAS -->|copiar| GC["Screen::game_canvas_ (pantalla)"]
    SB2[scoreboard] --> GC
    FADE[fades de entrada/salida] --> GC
    GC -->|RenderReadPixels → uploadPixels| SHADER["ShaderBackend (PostFX/CrtPi)"]
    SHADER --> WIN[Ventana]
    GC -.fallback sin GPU.-> WIN
```

### 4.4. Efectos de pantalla

`Screen` integra efectos globales sobre la presentación: **shake**
(`ShakeEffect`, desplaza el rect), **flash** (`FlashEffect`, tinte temporal) y
**attenuate** (atenuación) — todos definidos como structs internos en
`screen.hpp:108`–`205`. Las transiciones entre estados usan
`source/core/rendering/fade.*` (cuadrícula de cuadros).

---

## 5. Entrada

### 5.1. `Input` singleton

`source/core/input/input.hpp`. Centraliza teclado y mandos bajo un enum de
**acciones** (`Input::Action`, alias de `InputAction`). El mapeo por defecto
vive en structs:

- **`Keyboard`** (`input.hpp:54`): flechas = mover; **Q/W/E** = disparar
  izquierda/centro/derecha; Enter = START; F12 = SERVICE; P = PAUSE; ESC = EXIT;
  **F1–F11** = ventana/vídeo/audio/idioma/reset/info.
- **`Gamepad`** (`input.hpp:99`): cruceta = mover; WEST/NORTH/EAST = disparar;
  START/ BACK = start/service. Cada mando es un `shared_ptr<Gamepad>` con su
  propio `bindings`, nombre y *path*.

La consulta principal es `checkAction(action, repeat, check_keyboard, gamepad)`
(`input.hpp:168`). Hay además detección de ejes y triggers como botones, y
gestión de configuraciones de mando persistidas (`gamepad_config_manager`,
`controllers.json`).

### 5.2. Eventos globales y hotkeys

- `source/core/system/global_events.cpp` — `GlobalEvents::handle(event)` trata
  lo común a cualquier sección: `SDL_EVENT_QUIT`, *resize*, render target reset,
  hot-plug de mandos (con notificación tras `markStartupComplete`), el toggle
  del menú de servicio y el ratón.
- `source/core/input/global_inputs.cpp` — hotkeys de sistema, despachadas con
  un mapa acción→lambda (`global_inputs.cpp:187`): fullscreen, zoom ±, audio,
  autofire, idioma (CHANGE_LANG → `Section::RESET`, reinicia), VSync, integer
  scale, info; más PostFX/shader/preset. **F10/RESET** pone `Section::name =
  RESET` (reinicio) y **ESC/EXIT** pone `QUIT`.

### 5.3. Cómo llega la entrada a un jugador

Dentro de `Game`, `checkInput()` → `handlePlayersInput()` →
`handleNormalPlayerInput(player)` consulta `Input` y traduce a
`player->setInput(Input::Action)` y disparos (`handleFireInput`). El `Player`
sabe si usa teclado o un mando concreto (`uses_keyboard_`, `gamepad_`;
`player.hpp:217`). En modo demo, esta misma vía se alimenta de datos grabados
(§8).

---

## 6. Lógica del juego: la clase `Game`

`source/game/scenes/game.{hpp,cpp}` es la sección de gameplay y la clase más
grande del proyecto. Coordina jugadores, globos, balas, ítems, fases,
puntuación y efectos.

### 6.1. FSM de la partida

`Game::State` (`game.hpp:75`): `FADE_IN → ENTERING_PLAYER →
SHOWING_GET_READY_MESSAGE → PLAYING → COMPLETED / GAME_OVER`. `checkState()`
(`game.cpp`) detecta fin de juego (`stage_manager_->isGameCompleted()`) o game
over (`allPlayersAreGameOver()`); `setState()` hace la transición.

### 6.2. El frame de `Game`

```cpp
void Game::iterate() {                 // game.cpp
    const float DELTA_TIME = calculateDeltaTime();
    checkInput();
    update(DELTA_TIME);
    render();
}
void Game::update(float dt) {
    screen_->update(dt);
    Audio::update();
    updateDemo(dt);                    // no-op si no es demo
    updateGameStates(dt);             // dispatch por State
    fillCanvas();                      // dibuja la zona de juego en canvas_
}
```

`updateGameStates` despacha a un `updateGameState<Estado>` por cada valor de la
FSM (`game.hpp:218`).

### 6.3. Sistemas que orquesta

`Game` posee (vía `unique_ptr`) los managers y objetos del nivel
(`game.hpp:136`):

- **`StageManager`** — progresión por "poder": cada fase necesita
  `power_to_complete`; el juego se completa al acumular el poder total. También
  define umbrales de **amenaza** (`menace`) por fase. Implementa `IStageInfo`
  (`stage.hpp:51`), interfaz mínima que se inyecta a jugador y globos.
- **`BalloonManager`** — despliega formaciones (`deployRandomFormation`),
  globos hijos al explotar uno, *power balls*, ajusta velocidad
  (`Balloon::GAME_TEMPO`) y calcula la amenaza en pantalla (§7).
- **`BulletManager`** — pool de balas; las colisiones se resuelven con
  **callbacks** que registra `Game` (`setBalloonCollisionCallback`,
  `setTabeCollisionCallback`, `setOutOfBoundsCallback`; `bullet_manager.hpp:49`),
  manteniendo la lógica de juego dentro de `Game`.
- **`Background`**, **`Fade` ×2**, **`Tabe`** (enemigo especial volador),
  **`Scoreboard`**, **`PauseManager`**.
- Listas de `Item` (power-ups y puntos), `SmartSprite` y `PathSprite`.

### 6.4. Mecánicas destacadas

- **Ítems / power-ups** (`game.hpp:268`): café (toque extra),
  máquina de café (power-up), *power ball*, reloj (= **detener el tiempo**,
  `enableTimeStopItem`), e ítems de puntos. La probabilidad de soltar ítem la
  decide `dropItem()` con *odds* configurables (`Helper`, `game.hpp:100`).
- **Sistema de amenaza** (`updateMenace`/`setMenace`): si la amenaza cae por
  debajo de un umbral, se generan más globos.
- **Multijugador**: `players_` es un `vector<shared_ptr<Player>>` (1 o 2). Un
  `players_draw_list_` separado mantiene el z-order de dibujo
  (`buildPlayerDrawList`, `sendPlayerToBack`/`bringPlayerToFront`;
  `game.hpp:338`).
- **Récords**: al perder con buena puntuación, el jugador entra en
  `ENTERING_NAME` (`enter_name.*`, `manage_hiscore_table.*`).

---

## 7. Entidades y managers de gameplay

`source/game/entities/`:

- **`Player`** (`player.hpp`) — la entidad más compleja. Hereda de
  `AnimatedSprite`. Tiene **tres ejes de estado** independientes:
  `walking_state_`, `firing_state_` y `playing_state_` (`player.hpp:266`). El
  disparo usa un **sistema de dos líneas**: una funcional (cooldown, `canFire`)
  y otra visual (animaciones `NORMAL→AIMING→RECOILING→THREAT_POSE`,
  `player.hpp:296`). Soporta power-up, invulnerabilidad con parpadeo, *continue*
  y entrada de nombre. Puede controlarse por teclado o por un `Gamepad`
  concreto.
- **`Balloon`** (`balloon.hpp`) — el enemigo básico; al explotar puede crear
  globos hijos. `Balloon::GAME_TEMPO` define velocidades por progreso.
- **`Bullet`** (`bullet.hpp`) — proyectil con tipo (UP/LEFT/RIGHT) y color
  (según power-up del jugador).
- **`Item`** — power-ups y objetos de puntos que caen.
- **`Explosions`** — efectos de explosión (lo posee `BalloonManager`).
- **`Tabe`** — enemigo/objeto especial volador con su propia lógica de impacto.

`source/game/gameplay/` contiene los **managers y sistemas** (no entidades en
sí): `BalloonManager`, `BulletManager`, `StageManager`, `Difficulty`,
`Scoreboard`, `balloon_formations` (lee `formations.txt`), `cooldown`,
`enter_name`, `manage_hiscore_table`, `game_logo`.

El patrón general aquí **no es un `EntityManager` polimórfico único** (como en
el proyecto hermano), sino **managers especializados por tipo** + listas
homogéneas en `Game`, con **callbacks** para cruzar responsabilidades sin
acoplar (caso de `BulletManager`).

---

## 8. Modo demo y attract mode

> **A diferencia de muchos juegos, aquí el modo demo SÍ existe — pero NO es
> IA.** Es **reproducción de input pregrabado**.

### 8.1. Formato de los datos

`source/core/system/demo.hpp`: cada fotograma de demo es un `DemoKeys` con seis
banderas (`left`, `right`, `no_input`, `fire`, `fire_left`, `fire_right`). Una
demo es un `vector<DemoKeys>` de `TOTAL_DEMO_DATA = 2000` fotogramas. Hay tres
ficheros: `data/demo/demo{1,2,3}.bin`, leídos por `loadDemoDataFromFile`
(`demo.cpp:11`).

### 8.2. Reproducción

Cuando `Game` se construye con `DEMO_ON` (sección `GAME_DEMO`), `initDemo()`
(`game.cpp`) carga todas las demos del `Asset` y **asigna una a cada jugador de
forma aleatoria** (`shuffle`), elige una fase de inicio al azar, da cafés
aleatorios, pone los marcadores en modo `DEMO` y silencia los globos. Luego cada
frame, `demoHandlePlayerInput()` lee el fotograma actual y lo inyecta por la
**misma vía de input que un humano**:

```cpp
// game.cpp — demoHandlePlayerInput
const auto& demo_data = demo_data_vec.at(demo_.index % demo_data_vec.size());
if (demo_data.left == 1)       player->setInput(Input::Action::LEFT);
else if (demo_data.right == 1) player->setInput(Input::Action::RIGHT);
...
if (demo_data.fire == 1)       handleFireInput(player, Bullet::Type::UP);
```

No hay toma de decisiones: el jugador "demo" repite exactamente las pulsaciones
grabadas. `demoHandlePassInput()` permite **salir** con cualquier botón,
volviendo a `TITLE` y dejando armado el siguiente attract (`TITLE_TO_DEMO`).

### 8.3. Attract mode

El Title alterna `TITLE_TO_DEMO` ↔ `TITLE_TO_LOGO` (`title.cpp:51`): tras su
*timeout*, una vez lanza la demo y la siguiente vuelve al logo, en bucle de
atracción típico de recreativa.

### 8.4. Grabación y autoplay

- **`#ifdef RECORDING`** (`demo.cpp:43`, `game.hpp:349`): build especial que
  arranca directamente en GAME y **graba** las pulsaciones a un `.bin` con
  `saveDemoFile`. Así se generan las demos.
- **`autoplay`** (debug): en `_DEBUG`, `debug_config.autoplay` permite alimentar
  datos de demo a los jugadores en una partida normal (`game.hpp:354`,
  `initDemo`).

---

## 9. Recursos

### 9.1. `Resource` (singleton)

`source/core/resources/resource.hpp`. Cachea por nombre texturas, música,
sonidos, ficheros de texto/fuentes, animaciones y **datos de demo**
(`getDemoData`). Dos modos (`LoadingMode`):

- **`PRELOAD`** — carga incremental al arranque con `beginLoad()` +
  `loadStep(budget_ms)` + `renderProgress()` (la sección Preload pinta la
  barra). Es el modo por defecto.
- **`LAZY_LOAD`** — carga bajo demanda (seleccionable vía `debug.yaml`).

### 9.2. `Asset` y el pack

`source/core/resources/asset.*` mantiene el **índice de ficheros** a partir del
manifiesto `data/config/assets.txt` (`director.cpp:296`) y valida que no falte
ninguno (`Asset::check()`). La lectura física pasa por
`ResourceHelper::loadFile`, que sirve desde **`resources.pack`** y hace
*fallback* al filesystem en builds de desarrollo (en Release nativo es estricto:
solo el pack; `director.cpp:143`). `resource_pack.*` y `resource_loader.*`
implementan el formato del pack y la carga.

Formatos: imágenes vía `stb_image` + `gif` propio; audio `.ogg` vía
`stb_vorbis`; texto/JSON vía `nlohmann/json`; configs vía `fkyaml`.

---

## 10. Audio

`source/core/audio/audio.hpp` — `Audio` singleton sobre `jail_audio`
(primer-party, no librería externa) y `audio_adapter`. API: `playMusic(name,
loop, crossfade_ms)`, `playSound(name, Group)`, control de volumen por **grupos**
(`Group::GAME`, `INTERFACE`, …), `pause/resume/stop`, *crossfade* y *fade out*
(`audio.hpp:49`). `Audio::update()` se llama cada frame desde las secciones
(p.ej. `Game::update`). El build `NO_AUDIO` compila sin audio.

---

## 11. Configuración, parámetros y constantes

El proyecto tiene **tres capas de configuración** que conviene no confundir:

1. **`Options`** (`source/game/options.hpp`) — opciones persistentes del
   usuario, agrupadas en structs (`Window`, `Video`, `Audio`, `Settings`,
   `Gamepad`, `Keyboard`) más presets de shaders (`PostFXPreset`,
   `CrtPiPreset`). Se guardan en `config.yaml` / `controllers.json` /
   `postfx.yaml` / `crtpi.yaml`. Incluye `params_preset` ∈ {`classic`,
   `arcade`, `red`} (`options.hpp:339`).
2. **`param` / `Param`** (`source/utils/param.hpp`) — parámetros de *gameplay y
   layout* (dimensiones del juego, `play_area`, ajustes de globos, scoreboard,
   título, fades, jugador, Tabe…). Se cargan de ficheros de texto
   `param_320x240.txt` / `param_320x256.txt` / `classic.txt` con
   `loadParamsFromFile` (`director.cpp:275`). El objeto global `param` lo leen
   casi todos los subsistemas.
3. **Otros datos de juego**: `stages.txt` (fases, lo lee `StageManager`),
   `formations.txt` (formaciones de globos), `assets.txt` (manifiesto).

Los **valores de fallback compilados** viven en
`source/core/system/defaults.hpp` (y `source/utils/defines.hpp` para constantes
base). En Debug, `debug.yaml` controla sección inicial, opciones, fase, modo de
carga, `autoplay` e `invincibility` (`director.cpp:318`).

### Builds condicionales (multiplataforma)

El juego se adapta por *defines* (ver `CLAUDE.md`): `WINDOWS_BUILD` /
`LINUX_BUILD` / `MACOS_BUILD`, `RELEASE_BUILD`, `MACOS_BUNDLE`, `ANBERNIC`
(handheld), `__EMSCRIPTEN__` (web), `NO_SHADERS`, `NO_AUDIO`, `RECORDING`,
`ARCADE`, `DEBUG`/`VERBOSE`. Aparecen sobre todo en `Director::init` y `Screen`.

---

## 12. Localización

`source/core/locale/lang.*` — `Lang` carga el idioma desde **JSON** en
`data/lang/`. `Lang::setLanguage(Options::settings.language)` se llama en
`init()` y en cada `reset()`. Cambiar idioma en caliente (F9 / `CHANGE_LANG`)
fuerza un `Section::RESET` (reinicio del proceso) para recargarlo todo
(`global_inputs.cpp`).

---

## 13. Convenciones y patrones recurrentes

- **Naming** (de `.clang-format`/`.clang-tidy`, resumido en `CLAUDE.md`):
  clases `CamelCase`, métodos `camelBack`, variables/params `snake_case`,
  miembros privados `snake_case_` (guion bajo final), constantes `UPPER_CASE`,
  namespaces `CamelCase`, valores de enum `UPPER_CASE`. clang-tidy trata los
  warnings como errores.
- **Singletons con init/destroy manual**: `Screen`, `Resource`, `Audio`,
  `Input`, `Asset`, `ServiceMenu`, `Notifier`, `Lang`. Se crean/destruyen en
  orden explícito en `Director::init` / `shutdownSubsystems` (`director.cpp:227`)
  — no se confía en destructores estáticos.
- **Estado de flujo por variable global** (`Section::name`): patrón central; no
  hay objetos de transición tipados.
- **Time-based en todo**: cada sistema recibe `delta_time`; las constantes de
  tiempo se documentan como "N frames a 60fps → segundos" (p.ej.
  `game.hpp:85`).
- **Callbacks para desacoplar**: `BulletManager` y `StageManager` reciben
  `std::function` desde `Game` para no conocer la lógica de colisión/puntuación.
- **Interfaz mínima `IStageInfo`** (`stage_interface.hpp`): se inyecta a
  jugador y globos para que consulten amenaza/poder sin ver todo el
  `StageManager`.
- **Managers por tipo + listas homogéneas** en `Game`, en vez de un contenedor
  de entidades polimórfico.
- **Comentarios** en español/valenciano; muchos `#include` llevan comentario
  "// Para X" indicando qué símbolo justifican (estilo IWYU).
- **Multiplataforma por `#ifdef`** (ver §11). Conviene leerlos al tocar
  arranque o render.

---

## 14. Guía de navegación: "si quieres tocar X, mira Y"

| Quiero… | Empieza por… |
|---|---|
| Entender el arranque | `source/core/system/director.cpp` (`init`, `iterate`) |
| Cambiar el flujo de pantallas | `source/core/system/section.hpp` + `handleSectionTransition` |
| Añadir/editar una pantalla | `source/game/scenes/` (crea `iterate()`+`handleEvent()`) y un `case` en `director.cpp` |
| La barra de carga / arranque lento | `Resource::beginLoad/loadStep` + `scenes/preload.*` |
| Cómo se dibuja todo | `Game::fillCanvas` + `Game::render` + `Screen::renderPresent` (`screen.cpp:156`) |
| Sprites / animaciones | `source/core/rendering/sprite/` + `texture.hpp` |
| Shaders / CRT / post-FX | `source/core/rendering/sdl3gpu/` + `data/shaders/` + `Options` presets |
| Efectos (shake/flash/fade) | `screen.hpp` (structs) + `core/rendering/fade.*` |
| Controles / mandos | `source/core/input/input.hpp` (`Keyboard`/`Gamepad`/`checkAction`) |
| Hotkeys F1–F12 / reset | `source/core/input/global_inputs.cpp` |
| Eventos globales / hot-plug | `source/core/system/global_events.cpp` |
| Lógica de partida y estados | `source/game/scenes/game.cpp` (`updateGameState*`) |
| Globos y formaciones | `gameplay/balloon_manager.*` + `entities/balloon.*` + `formations.txt` |
| Balas y colisiones | `gameplay/bullet_manager.*` (callbacks) + `entities/bullet.*` |
| Fases / progresión / dificultad | `gameplay/stage.*` (`StageManager`) + `stages.txt` + `gameplay/difficulty.*` |
| El jugador (movimiento, disparo) | `entities/player.*` (sistema de disparo de dos líneas) |
| Ítems y power-ups | `entities/item.*` + `Game::dropItem/createItem` |
| Récords / entrada de nombre | `gameplay/manage_hiscore_table.*`, `gameplay/enter_name.*` |
| **Modo demo / attract** | `core/system/demo.*`, `Game::initDemo/demoHandle*`, `scenes/title.cpp` |
| Grabar nuevas demos | build con `RECORDING` + `Game::updateRecording` |
| Cargar un recurso | `core/resources/resource.hpp` + `asset.*` + `assets.txt` |
| Audio (música/SFX) | `core/audio/audio.hpp` |
| Opciones del usuario | `game/options.hpp` (+ `config.yaml`) |
| Parámetros de gameplay/layout | `utils/param.hpp` + `param_320x*.txt` |
| Valores por defecto | `core/system/defaults.hpp`, `utils/defines.hpp` |
| Idiomas | `core/locale/lang.*` + `data/lang/` |
| Menú de servicio / notificaciones | `game/ui/service_menu.*`, `game/ui/notifier.*` |
| Empaquetar datos | `tools/` (`pack_resources`) + `make resources.pack` |

---

*Documento generado a partir de la lectura directa del código en el commit
actual de la rama `main`. Si algo aquí no cuadra con el código, el código
manda: actualiza este documento.*