coffee-crisis/docs/ARQUITECTURA.md

# Arquitectura de **Coffee Crisis**

> 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, o donde el código contradice a la documentación previa, lo
> digo explícitamente en lugar de inventarlo.
>
> **Coffee Crisis** es un arcade en C++20 + SDL3: el jugador defiende la UPV de
> globos de café rebotantes a lo largo de 10 fases. Soporta 1–2 jugadores,
> teclado y mando, y varios idiomas. Es el **predecesor** de *Coffee Crisis
> Arcade Edition*; al final del documento ([§15](#15-diferencias-frente-a-la-arcade-edition))
> hay un resumen de las diferencias entre ambos. 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](#7-entidades)
8. [Modo demo y attract mode](#8-modo-demo-y-attract-mode)
9. [Recursos](#9-recursos)
10. [Audio](#10-audio)
11. [Configuración y constantes](#11-configuración-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)
15. [Diferencias frente a la Arcade Edition](#15-diferencias-frente-a-la-arcade-edition)

---

## 1. Visión general

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

- **`source/core/`** — motor genérico: `system` (`director`, `delta_time`,
  `demo`), `rendering` (+ `sdl3gpu`, sprites), `input`, `resources`, `audio`,
  `locale`.
- **`source/game/`** — el juego concreto: `game.*` (el hub de gameplay),
  `entities/` (player, balloon, bullet, item), `scenes/` (logo, intro, title,
  instructions), `ui/` (menu), `options.*` y `defaults.hpp`.
- **`source/utils/`** — `utils.*` (helpers, `struct Section`, `Color`,
  dificultad…) y `defines.hpp` (macros de build).
- **`source/external/`** — vendorizado: `stb_image`, `stb_vorbis` (y headers
  YAML/JSON).

~51 ficheros C++ y ~16.000 líneas. **Nota sobre cabeceras**: los módulos
antiguos usan extensión **`.h`** (p.ej. `director.h`, `game.h`, `screen.h`); los
módulos nuevos usan **`.hpp`** (p.ej. `demo.hpp`, `options.hpp`,
`delta_time.hpp`). Es un proyecto en migración, y eso se nota en varias capas.

**Ideas-fuerza que conviene interiorizar:**

1. El flujo se controla con un **`struct Section { name, subsection }`** que el
   `Director` lee cada frame (§3).
2. El render dibuja con **texturas GPU** (`SDL_Renderer`) sobre un **canvas
   virtual de 256×192**, con post-procesado opcional vía un backend SDL3 GPU
   (§4).
3. El gameplay es **monolítico**: casi todo vive en la clase `Game`, con
   vectores de **punteros crudos** y `new`/`delete` manual (§6, §7).
4. **Sí hay modo demo** (*attract mode*): **reproducción de input grabado**, no
   IA, orquestada desde la pantalla de título (§8).
5. El proyecto está **migrando de frame-based a time-based** y de `config.txt`
   a YAML; conviven ambos mundos (§2, §11).

```mermaid
graph TD
    SDL[SDL3 callbacks · main.cpp] --> DIR[Director]
    DIR -->|struct Section| ST{handleSectionTransition}
    ST --> SEC["Logo / Intro / Title / Game"]
    SEC --> TITLE[Title] -.attract.-> NESTED["Game anidado en demo + Instructions"]
    SEC --> GAME["Game (monolítico)"]
    GAME --> ENT["Player* / Balloon* / Bullet* / Item* (punteros crudos)"]
    GAME --> DEMOSYS["Demo (playback grabado)"] -.-> ENT
    GAME -->|SDL_RenderTexture| CANVAS["game_canvas_ 256×192"]
    CANVAS --> SCREEN[Screen] --> SB["ShaderBackend PostFX/CrtPi"] --> WIN[Ventana]
    RES["Asset / Resource"] -.-> 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   → new Director(argc, argv);
SDL_AppIterate→ Director::iterate();         // un frame
SDL_AppEvent  → Director::handleEvent(event);
SDL_AppQuit   → delete Director;
```

### 2.2. El `Director`

`source/core/system/director.h` / `.cpp`. Inicializa SDL, ventana y renderer,
crea la carpeta de sistema, monta input/audio/recursos, y mantiene **un
`unique_ptr` por sección** (`logo_`, `intro_`, `title_`, `game_`) de los que
**solo uno está vivo** (`director.h:55`). Guarda un puntero a la
`struct Section* section_` que comparte con la sección activa.

`Director::iterate()` cada frame: comprueba salida (doble ESC vía
`GlobalInputs::wantsQuit()`), actualiza la visibilidad del cursor, llama a
`handleSectionTransition()` y despacha `iterate()` a la sección activa
(`director.cpp`, `switch (active_section_)`).

### 2.3. Gestión del tiempo (en migración)

El reloj central es `source/core/system/delta_time.*`: `DeltaTime::tick()`
devuelve el delta en segundos consumido al inicio de cada frame de la sección
(`game.cpp`, `Game::iterate`). El proyecto **está migrando de frame-based a
time-based**: en `game.h` se ven contadores duplicados, el viejo frame-based
(`Uint16 death_counter_`) y el nuevo time-based (`float death_counter_s_`),
documentados como tales (`game.h:347`). El playback de la demo también es
time-based: `index = elapsed_s * 60` (`demo.hpp:11`).

---

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

### 3.1. `struct Section`

`source/utils/utils.h:58` define un POD minimalista:

```cpp
struct Section {
    Uint8 name;        // SECTION_PROG_* (LOGO/INTRO/TITLE/GAME/QUIT)
    Uint8 subsection;  // SUBSECTION_* (p.ej. GAME_PLAY_1P, GAME_PAUSE, TITLE_INSTRUCTIONS…)
};
```

Los valores son **constantes `constexpr int` en `source/game/defaults.hpp`**
(`SECTION_PROG_LOGO = 0`, …, `SECTION_PROG_QUIT = 4`; `SUBSECTION_GAME_PLAY_1P`,
`SUBSECTION_GAME_PAUSE`, `SUBSECTION_GAME_GAMEOVER`, `SUBSECTION_TITLE_INSTRUCTIONS`,
etc.; `defaults.hpp:90`). Cualquier parte del código cambia el flujo asignando
`section_->name = ...` / `section_->subsection = ...`.

### 3.2. Transición de secciones

`Director::handleSectionTransition()` (`director.cpp`):

- Traduce `section_->name` a un `enum class ActiveSection` (`director.h:24`).
- Si coincide con la activa, no hace nada.
- Si cambió: libera las cuatro secciones (`reset()`) y construye la nueva. Para
  `GAME` decide el nº de jugadores según `section_->subsection`
  (`SUBSECTION_GAME_PLAY_1P` → 1, si no → 2) y crea
  `Game(NUM_PLAYERS, 0, renderer_, /*demo=*/false, section_)`.

Cada sección recibe el `renderer_` y el `Section*`, y expone `iterate()` (y, en
`Game`, `handleEvent()`).

```mermaid
graph LR
    LOGO --> INTRO --> TITLE
    TITLE -->|jugar| GAME --> TITLE
    TITLE -->|attract / manual| INSTR["Instructions (dentro de Title)"]
    TITLE -->|attract| DEMOG["Game anidado en demo (dentro de Title)"]
    TITLE --> QUIT
```

> **Matiz importante**: `Instructions` y la **demo** no son secciones del
> `Director`. Viven **dentro de `Title`**, que ejecuta un *attract loop* (ver
> §8). El `Director` solo conoce Logo/Intro/Title/Game/Quit.

---

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

Los sprites son **texturas GPU** dibujadas por `SDL_Renderer` sobre un canvas
virtual; el post-procesado va por un backend SDL3 GPU.

### 4.1. El canvas virtual 256×192

`Screen` (`core/rendering/screen.h`) crea `game_canvas_`, una `SDL_Texture` de
**256×192** (`GAMECANVAS_WIDTH/HEIGHT` en `defaults.hpp:64`) con
`SDL_TEXTUREACCESS_TARGET` (`screen.cpp:106`). Toda la geometría del juego se
deriva de esa resolución y de un `BLOCK` base (áreas de juego en
`defaults.hpp`).

`Screen::start()` (`screen.cpp:166`) fija el render-target a `game_canvas_`;
a partir de ahí, la sección activa dibuja sus sprites sobre él.

### 4.2. Texturas y jerarquía de sprites

- `core/rendering/texture.h` — `Texture` envuelve un `SDL_Texture*` cargado de
  PNG; método `render(...)` con clip/zoom/flip.
- `core/rendering/sprite.h` y derivados:
  - `Sprite` — dibuja desde un *spritesheet*.
  - `AnimatedSprite` — animación por fotogramas, definida en ficheros **`.ani`**.
  - `MovingSprite` — añade posición/velocidad (p.ej. las nubes del fondo).
  - `SmartSprite` — sprite autónomo (popups de puntuación, el café que salta al
    recibir un golpe).
- Texto: `core/rendering/text.h` + `writer.h` (fuentes bitmap).
- Transiciones: `core/rendering/fade.h`. Notificaciones:
  `core/rendering/notifications.*`.

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

El path de presentación (`screen.cpp:185`) decide cómo llega el canvas a la
ventana:

- **Con backend GPU acelerado**: lee los píxeles de `game_canvas_` con
  `SDL_RenderReadPixels` a un `pixel_buffer_` (ARGB8888;
  `screen.h:162`), los sube al backend (`shader_backend_->uploadPixels(...)`) y
  este renderiza con el shader activo a la ventana.
- **Sin backend / desactivado** (fallback): `SDL_RenderTexture` del
  `game_canvas_` a la ventana y `SDL_RenderPresent` (`screen.cpp:233`).

El backend vive en `core/rendering/sdl3gpu/` (interfaz abstracta en
`shader_backend.hpp`). Dos shaders: **PostFX** (viñeta, scanlines, chroma,
gamma, máscara, curvatura, *bleeding*, flicker) y **CrtPi** (scanlines continuas
con bloom). Los GLSL de `data/shaders/` se compilan a SPIR-V (`spv/*_spv.h`) vía
`glslc`; en macOS se usan shaders **Metal (MSL)** inline (`sdl3gpu/msl/`). El
build `NO_SHADERS` (Emscripten) fuerza la ruta clásica.

```mermaid
graph TD
    OBJ["fondo, globos, jugador, balas, items…"] -->|SDL_RenderTexture| CANVAS["game_canvas_ 256×192 (render target)"]
    CANVAS -->|RenderReadPixels → uploadPixels| SHADER["ShaderBackend (PostFX / CrtPi)"]
    SHADER --> WIN[Ventana]
    CANVAS -.fallback sin GPU.-> WIN
```

### 4.4. Modos de escalado y efectos

La presentación a la ventana respeta `Options::video.presentation_mode`
(`INTEGER_SCALE`, `LETTERBOX`, `STRETCHED`, `OVERSCAN`; `options.hpp:24`). El
`Game` añade efectos como *flash*, *shake* y un *death shake* intenso
(`game.h:100`, `DeathShake`).

---

## 5. Entrada

### 5.1. `Input`

`source/core/input/input.h` — abstracción de teclado y mando bajo un enum de
acciones (`Input::Action`). El jugador se mueve con flechas y dispara
izquierda/centro/derecha; el `Input::Device` selecciona teclado o mando por
jugador (`Game::player_one_control_`, `game.h:379`).

### 5.2. Hotkeys globales y salida

`source/core/input/global_inputs.*` gestiona las teclas de sistema (ventana,
vídeo, post-FX, idioma, FPS overlay…) y la **salida en dos pasos**: la primera
pulsación de ESC arma una confirmación y la segunda activa `wantsQuit()`, que el
`Director` traduce a `SECTION_PROG_QUIT` (`director.cpp`). El cursor del ratón
se autooculta (`core/input/mouse.*`).

Las hotkeys de shaders documentadas: **F4** activa/desactiva post-procesado,
**F5** alterna PostFX↔CrtPi, **F6** siguiente preset (ver `CLAUDE.md`).

### 5.3. Cómo llega la entrada al jugador

Dentro de `Game`, `checkGameInput()` → `processLiveInput()` →
`processPlayerLiveInput(player, i)` consulta `Input` y llama a
`player->setInput(Input::Action)` y a `createBullet(...)` al disparar
(`game.h:228`). En modo demo, esa misma vía la alimenta `processDemoInput()`
con datos grabados (§8).

---

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

`source/game/game.{h,cpp}` es **el hub de gameplay y, con diferencia, la clase
más grande** del proyecto: ~400 líneas solo de declaración. A diferencia de la
Arcade Edition, **no delega en managers**: las formaciones, fases, globos,
balas e ítems se gestionan directamente aquí.

### 6.1. El frame y sus sub-bucles

`Game::iterate()` (`game.cpp`) consume el delta con `DeltaTime::tick()` y
despacha según `section_->subsection`:

```cpp
switch (section_->subsection) {
    case SUBSECTION_GAME_PAUSE:    iteratePaused(dt);   break;
    case SUBSECTION_GAME_GAMEOVER: iterateGameOver(dt); break;
    case SUBSECTION_GAME_PLAY_1P:
    case SUBSECTION_GAME_PLAY_2P:  iteratePlaying(dt);  break;
}
```

Es decir, **pausa y game-over son sub-estados** del propio `Game` (no secciones
del Director), cada uno con su `update`/`render`. En modo demo, entrar en pausa
o game-over rebota directamente a `Title` (`game.cpp`, `Game::iterate`).

### 6.2. Lo que gestiona `Game`

Todo dentro de la misma clase (`game.h`):

- **Fases (`Stage stage_[10]`)**: cada fase tiene un *pool* de formaciones
  enemigas (`EnemyPool`/`EnemyFormation`/`EnemyInit`, structs internos), poder
  para completarla y umbrales de amenaza. `initEnemyFormations*` precalcula las
  formaciones (lineales, simétricas, hexágonos…).
- **Nivel de amenaza** (`menace_current_`/`menace_threshold_`): si la amenaza
  cae bajo el umbral, se despliega otra formación (`updateMenace`,
  `evaluateAndSetMenace`).
- **Ítems y power-ups**: disco/gaviota/pacmar (puntos), café (toque extra),
  máquina de café (power-up), reloj (**detener el tiempo**,
  `enableTimeStopItem`), *power ball*. Probabilidades en `Helper`
  (`game.h:128`).
- **Colisiones**: jugador↔globo, jugador↔ítem, bala↔globo (`checkPlayer…`,
  `checkBulletBalloonCollision`).
- **Muerte del jugador**: secuencia con *death shake* y fases
  (`DeathSequence`/`DeathPhase`, `game.h:113`).
- **Marcador, hi-score, fades, fondo** (nubes con parallax via `MovingSprite`),
  menús de pausa y game-over (`Menu`), audio (`Ja::Sound*`/`Ja::Music*`).

### 6.3. Gestión de memoria

Las entidades viven como **vectores de punteros crudos**
(`std::vector<Player*>`, `<Balloon*>`, `<Bullet*>`, `<Item*>`,
`<SmartSprite*>`; `game.h:264`), creados con `new` y liberados con métodos
`freeBalloons()`, `freeBullets()`, `freeItems()`, `deleteAllVectorObjects()`.
Es un estilo más antiguo que el de la Arcade Edition (smart pointers).

---

## 7. Entidades

`source/game/entities/`:

- **`Player`** (`player.h`) — movimiento, disparo (tres direcciones),
  animaciones, power-up, invulnerabilidad, vidas/score. Puede usar teclado o
  mando.
- **`Balloon`** (`balloon.h`) — enemigo básico que rebota; al explotar puede
  generar globos hijos. Tiene varios contadores de estado.
- **`Bullet`** (`bullet.h`) — proyectil con `Kind` (UP/LEFT/RIGHT) y estado de
  power-up.
- **`Item`** (`item.h`) — power-ups y objetos de puntos que caen, con `Id` por
  tipo.

No hay clase base de entidad común ni managers: el ciclo de vida lo lleva
`Game` directamente sobre los vectores (§6.3). Los efectos visuales tipo
"popup de puntuación" o "café arrojado" se modelan como `SmartSprite`
(`core/rendering/smartsprite.h`).

---

## 8. Modo demo y attract mode

> **El modo demo SÍ existe, y NO es IA**: es **reproducción de input
> pregrabado**, igual concepto que en la Arcade Edition.

### 8.1. Formato

`source/core/system/demo.hpp`: cada fotograma 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 "a 60 Hz de
referencia" (`demo.hpp:9`). Hay tres ficheros: `data/demo/demo{1,2,3}.bin`. El
playback es **time-based**: `index = elapsed_s * 60`.

### 8.2. Reproducción

Cuando un `Game` corre en modo demo, `processDemoInput()` (`game.cpp`) lee el
fotograma actual del set seleccionado y lo inyecta por la **misma vía que un
humano** sobre `players_[0]`:

```cpp
const DemoKeys &keys = dd.at(demo_.index % dd.size());
if (keys.left  == 1) players_[0]->setInput(Input::Action::LEFT);
if (keys.fire  == 1 && players_[0]->canFire()) {
    players_[0]->setInput(Input::Action::FIRE_CENTER);
    createBullet(...); players_[0]->setFireCooldown(10);
}
// … (right, no_input, fire_left, fire_right)
```

No hay toma de decisiones: repite las pulsaciones grabadas. Al agotar el
playback (`index >= TOTAL_DEMO_DATA`) vuelve a `Title`.

### 8.3. Attract mode (dentro de `Title`)

El bucle de atracción vive en `source/game/scenes/title.cpp`: el Title arma un
*timeout* (`demo_remaining_s_`) y, al agotarse, lanza un **`Game` anidado en
modo demo** (`runDemoGame()`, `demo_game_`, `demo_game_active_`;
`title.cpp:323`). Title tiquea ese `demo_game_->iterate()` directamente y, al
terminar la demo, encadena las **instrucciones**
(`demo_then_instructions_` → `runInstructions(Instructions::Mode::AUTO)`,
`title.cpp:334`) antes de volver al título. Así el Title alterna
atracción → demo → instrucciones de forma autónoma.

> Es una diferencia notable con la Arcade Edition, donde la demo es una sección
> `GAME_DEMO` propia del Director. Aquí el `Director` ni se entera: todo el
> attract está encapsulado en `Title`.

---

## 9. Recursos

- **`Asset`** (`core/resources/asset.h`) — índice de ficheros de recurso
  (`add`/`get` por nombre).
- **`Resource`** (`core/resources/resource.h`) — carga y caché de los recursos
  (texturas, sonidos, música, fuentes, animaciones).
- **Pack**: `resource_pack.*` + `resource_loader.*` + `resource_helper.*`
  sirven desde **`resources.pack`**, con *fallback* al filesystem en desarrollo.
- **Formatos**: PNG (spritesheets) + ficheros **`.ani`** (definición de
  animaciones); OGG (audio, vía `stb_vorbis`); fuentes bitmap en `data/font/`.
  Los shaders GLSL de `data/shaders/` **no** van al pack (se embeben en el
  binario como cabeceras SPIR-V).

---

## 10. Audio

`source/core/audio/` — `Audio` (`audio.hpp`) + `audio_adapter` sobre
**`jail_audio`** (`jail_audio.hpp`), wrapper de audio SDL3 *first-party* (no
librería externa) que usa `stb_vorbis` para OGG y mezcla por canales (API
`JA_*`). `Game` mantiene punteros `Ja::Sound*` para cada efecto (explosión,
disparo, colisión, reloj, etc.) y un `Ja::Music* game_music_`.

---

## 11. Configuración y constantes

- **`Options`** (`source/game/options.hpp`) — opciones persistentes en el
  namespace `Options::` (`window`, `video` con `gpu`/`shader`, `audio`,
  `loading`, `settings`, `gameplay`, `inputs`), más presets `PostFXPreset` y
  `CrtPiPreset`.

  > ⚠️ **El `CLAUDE.md` está desactualizado en este punto**: dice que la config
  > vive en `config.txt` con "migración a YAML pendiente". El código real
  > (`options.hpp:16`) ya **persiste en `config.yaml` vía fkyaml**, con presets
  > de shaders en `postfx.yaml`/`crtpi.yaml`. El código manda.

- **`defaults.hpp`** (`source/game/`) — constantes de gameplay y layout: tamaño
  de canvas (256×192), `BLOCK`, áreas de juego, colores, y las constantes
  `SECTION_PROG_*` / `SUBSECTION_*` del flujo (§3).
- **`utils/defines.hpp`** — macros de build.

### Builds condicionales

Aparecen sobre todo en `Director`/`Screen`: `__EMSCRIPTEN__` (web: no se puede
salir, reinicia al logo; `NO_SHADERS` forzado), `DEBUG`, y la selección de
plataforma para shaders (SPIR-V vs Metal). `make release` empaqueta `.tar.gz` /
`.dmg` / `.zip` según el SO.

---

## 12. Localización

`source/core/locale/lang.*` — `Lang` carga las cadenas desde `data/lang/`
(es_ES, ba_BA/euskera, en_UK). El idioma se elige en `Options::settings.language`.

---

## 13. Convenciones y patrones recurrentes

- **Cabeceras mixtas `.h` / `.hpp`**: `.h` en lo antiguo, `.hpp` en lo nuevo —
  pista fiable de qué módulos se han reescrito.
- **Punteros crudos + `new`/`delete`** en el gameplay (`Game`), frente a smart
  pointers en el resto (secciones, `Screen`). Migración a medias.
- **Migración frame-based → time-based**: contadores duplicados
  (`x_counter_` + `x_counter_s_`) conviviendo; el reloj es `DeltaTime::tick()`.
- **Flujo por `struct Section` + constantes `SECTION_PROG_*`** (no enums
  tipados ni objetos de transición).
- **Sub-estados dentro de la sección** (pausa/game-over como `subsection` de
  `Game`), no como secciones del `Director`.
- **Attract mode encapsulado en `Title`** (demo + instrucciones).
- **`Game` monolítico**: la lógica no está repartida en managers; todo cuelga
  de la clase `Game` y de structs internos (`Stage`, `EnemyFormation`, …).
- **Comentarios** en español/valenciano; muchos `#include` con comentario
  "// for X" (estilo IWYU).
- **El `CLAUDE.md` puede ir por detrás del código** (caso config.txt→YAML): ante
  duda, manda el código.

---

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

| Quiero… | Empieza por… |
|---|---|
| Entender el arranque | `source/core/system/director.cpp` |
| Cambiar el flujo de pantallas | `struct Section` (`utils/utils.h`) + constantes en `game/defaults.hpp` + `handleSectionTransition` |
| Añadir/editar una pantalla | `source/game/scenes/` (Logo/Intro/Title/Instructions) |
| Gestión del tiempo | `source/core/system/delta_time.*` |
| Cómo se dibuja todo | `Screen::start`/render (`core/rendering/screen.cpp`) |
| Canvas / resolución / áreas | `source/game/defaults.hpp` (256×192, BLOCK) |
| Sprites / animaciones `.ani` | `core/rendering/sprite.h` + `animatedsprite.h` + `texture.h` |
| Shaders / CRT / post-FX | `core/rendering/sdl3gpu/` + `data/shaders/` + `Options` |
| Modos de escalado / efectos | `Screen` + `Options::video.presentation_mode` |
| Controles / mandos | `core/input/input.h` |
| Hotkeys / salida en dos pasos | `core/input/global_inputs.cpp` |
| **Toda la lógica de partida** | `source/game/game.cpp` (`iteratePlaying/Paused/GameOver`) |
| Fases / formaciones / amenaza | `Game::initEnemyFormations*`, `Stage stage_[10]`, `updateMenace` |
| Globos / balas / ítems | `game/entities/{balloon,bullet,item}.*` (gestionados en `Game`) |
| El jugador | `game/entities/player.*` |
| Ítems y power-ups | `Game::dropItem/createItem`, `Helper` (`game.h`) |
| **Modo demo / attract** | `core/system/demo.*`, `Game::processDemoInput`, `scenes/title.cpp` (`runDemoGame`) |
| Cargar un recurso | `core/resources/asset.h` + `resource.h` |
| Audio | `core/audio/audio.hpp` + `jail_audio.hpp` |
| Opciones del usuario | `game/options.hpp` (+ `config.yaml`) |
| Valores por defecto / constantes | `game/defaults.hpp`, `utils/defines.hpp` |
| Idiomas | `core/locale/lang.*` + `data/lang/` |
| Empaquetar datos | `tools/` + `make pack` |

---

## 15. Diferencias frente a la Arcade Edition

`coffee_crisis` es el **predecesor** de `coffee_crisis_arcade_edition`. Ambos
comparten ADN (SDL3, `jail_audio`, demo por input grabado, backend SDL3 GPU con
PostFX/CrtPi, capas core/game), pero el código diverge de forma sistemática.
Resumen de lo observado leyendo ambos repos:

| Dimensión | **Coffee Crisis (este)** | **Arcade Edition** |
|---|---|---|
| Tamaño | ~51 ficheros, ~16k LOC | ~150 ficheros, ~32k LOC |
| Cabeceras | mixto `.h` (antiguo) / `.hpp` | todo `.hpp` |
| Flujo | `struct Section{name,subsection}` + `enum ActiveSection`; **4 secciones** (Logo/Intro/Title/Game) | variable global `Section::name` con **muchas más** (Preload, HiScore, Credits, GameDemo, Instructions…) |
| Arranque | directo | **no bloqueante** con sección `PRELOAD` + `Resource::loadStep(50ms)` |
| Gameplay | **`Game` monolítico**; formaciones/fases como structs internos | **managers** (`BalloonManager`, `BulletManager`, `StageManager` con `IStageInfo`) |
| Memoria de entidades | **punteros crudos** + `new`/`delete` | `shared_ptr`/`unique_ptr` + listas |
| Pausa / game-over | **sub-estados** dentro de `Game` (`subsection`) | FSM de estados de `Game` + managers dedicados |
| Demo / attract | **encapsulado en `Title`** (Game anidado en demo + instrucciones) | sección `GAME_DEMO` propia del Director + attract Title↔Logo/Demo |
| Canvas | **256×192** fijo (`defaults.hpp`) | parametrizable (`param_320x*.txt`) |
| Render | un único `game_canvas_` → readback → shader / fallback | dos render-targets (`canvas_` zona de juego → `game_canvas_`) → shader / fallback |
| Sprites | `Sprite/AnimatedSprite/MovingSprite/SmartSprite` | añade `PathSprite`, `CardSprite` |
| Reinicio en caliente | (no observado a nivel de `relaunch()`) | `Director::relaunch()` vía `execv` |
| Plataformas | Linux/macOS/Windows/Emscripten | + Raspberry Pi, Anbernic |
| Estado del código | **en migración**: frame→time-based, `config.txt`→YAML | más consolidado (YAML, time-based) |

En una frase: la Arcade Edition es esta misma idea **refactorizada y ampliada**
— se troceó el `Game` monolítico en managers, se pasó a smart pointers, se
añadieron secciones y plataformas, y se consolidó la migración a time-based y
YAML que aquí todavía está a medias.

---

*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.*