merge docs/arquitectura: guia d'arquitectura del projecte

2026-05-29 13:30:21 +02:00
parent 7a4b340ee4 86bdfb8f73
commit 88b295bc13
1 changed files with 542 additions and 0 deletions
@@ -0,0 +1,542 @@
+# 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.*