merge docs/arquitectura: guia d'arquitectura del projecte

2026-05-29 13:22:02 +02:00
parent 02bc4de6d5 753fff5f59
commit 998bc6f1fa
1 changed files with 642 additions and 0 deletions
@@ -0,0 +1,642 @@
+# 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.*