Merge branch 'docs/arquitectura': document d'arquitectura per a nous companys

2026-05-29 11:56:23 +02:00
parent a9b662840b 582bd0ee30
commit 0f986cbf80
1 changed files with 838 additions and 0 deletions
@@ -0,0 +1,838 @@
+# Arquitectura de Orni Attack
+
+> Documento de orientación para alguien que llega nuevo al proyecto. Cada
+> afirmación está anclada a código real (fichero/clase/función con su ruta).
+> Cuando algo no se ha podido verificar o no existe, se indica explícitamente.
+> El objetivo no es vender una arquitectura ideal, sino describir lo que **este**
+> proyecto hace, incluso donde es poco convencional.
+
+## Índice
+
+1. [Visión general](#1-visión-general)
+2. [Punto de entrada y el Director](#2-punto-de-entrada-y-el-director)
+3. [Bucle principal](#3-bucle-principal)
+4. [Sistema de escenas](#4-sistema-de-escenas)
+5. [Renderizado: de la lógica al píxel](#5-renderizado-de-la-lógica-al-píxel)
+6. [Entrada](#6-entrada)
+7. [Audio](#7-audio)
+8. [Recursos](#8-recursos)
+9. [Comunicación entre módulos](#9-comunicación-entre-módulos)
+10. [Lógica del juego](#10-lógica-del-juego)
+11. [IA del modo demo (attract)](#11-ia-del-modo-demo-attract)
+12. [Efectos visuales](#12-efectos-visuales)
+13. [Configuración, constantes y convenciones](#13-configuración-constantes-y-convenciones)
+14. [Guía de navegación](#14-guía-de-navegación)
+
+---
+
+## 1. Visión general
+
+Orni Attack es un arcade vectorial (estética CRT de líneas con bloom) construido
+sobre **SDL3**, usando la **GPU API de SDL3** (`SDL_gpu`) para el render — **no**
+`SDL_Renderer`. El código está partido en dos grandes mundos:
+
+- **`source/core/`** — el "motor": ventana, GPU, audio, input, recursos, i18n,
+  overlays de sistema. No conoce nada del juego concreto. Por ejemplo,
+  [audio.hpp](source/core/audio/audio.hpp) recibe un struct de configuración y no
+  lee YAML, e [input.hpp](source/core/input/input.hpp) no incluye nada de `game/`.
+- **`source/game/`** — la lógica concreta de Orni Attack: escenas, entidades
+  (naves, enemigos, balas), sistemas (colisiones, IA), stages/oleadas y efectos.
+
+El punto de indirección entre ambos mundos para el render es
+[render_context.hpp](source/core/rendering/render_context.hpp): el juego habla con
+un `Rendering::Renderer*` opaco que es un alias de `GPU::GpuFrameRenderer`. Esto
+permite cambiar de backend sin tocar las firmas del juego.
+
+```mermaid
+graph TD
+    subgraph entry["Punto de entrada"]
+        MAIN["main.cpp<br/>SDL_MAIN_USE_CALLBACKS"]
+    end
+    MAIN -->|posee| DIR["Director<br/>(es el programa)"]
+
+    subgraph core["source/core (motor)"]
+        SDLM["SDLManager<br/>ventana + GPU"]
+        GE["GlobalEvents<br/>F1-F7/F12/ESC/hotplug"]
+        INPUT["Input (singleton)"]
+        AUDIO["Audio (singleton)"]
+        RES["Resource::Loader / Pack"]
+        LOC["Locale (i18n)"]
+        OVL["Notifier · ServiceMenu<br/>DebugOverlay · DefineInputs"]
+    end
+
+    subgraph game["source/game (juego)"]
+        SCN["Scenes<br/>Logo · Title · Game"]
+        ENT["Entities<br/>Ship · Enemy · Bullet"]
+        SYS["Systems<br/>Collision · EnemyAi · DemoPilot"]
+        STG["StageManager / WaveRunner"]
+        FX["Effects<br/>debris · firework · score · trail"]
+    end
+
+    DIR --> SDLM
+    DIR --> GE
+    DIR --> OVL
+    DIR --> SCN
+    SCN --> ENT
+    SCN --> SYS
+    SCN --> STG
+    SCN --> FX
+    GE --> INPUT
+    SCN -.usa.-> AUDIO
+    SCN -.usa.-> RES
+    OVL -.usa.-> LOC
+```
+
+**Patrón dominante de comunicación:** singletons globales (`Input::get()`,
+`Audio::get()`, `Locale::get()`, `Notifier`, `ServiceMenu`) más paso por
+referencia de un `Rendering::Renderer*` y un `SceneContext&`. **No hay** un bus de
+eventos genérico ni un ECS — las entidades viven en `std::array` de tamaño fijo
+dentro de `GameScene` y los sistemas operan sobre un struct `Context` de punteros
+(ver [§10](#10-lógica-del-juego)).
+
+**Rasgo de diseño destacable:** gran parte de la lógica es *data-driven*. Los
+enemigos, balas y el jugador se describen en **YAML declarativo**
+(`data/entities/*/*.yaml`: physics/ai/animation/events), los stages en
+`data/stages/stages.yaml` (oleadas), y las figuras vectoriales en ficheros `.shp`.
+
+---
+
+## 2. Punto de entrada y el Director
+
+El `main` real está en [main.cpp](source/main.cpp) y usa el modo de callbacks de
+SDL3 (`#define SDL_MAIN_USE_CALLBACKS 1`). En lugar de un bucle `while` clásico,
+SDL llama a cuatro funciones, y todas son pura fontanería que delega en un
+`Director`:
+
+```cpp
+// main.cpp
+auto SDL_AppInit(void** appstate, int argc, char* argv[]) -> SDL_AppResult {
+    System::Relaunch::setArgv(argc, argv);
+    auto director = std::make_unique<Director>(argc, argv);
+    *appstate = director.release();      // SDL guarda el puntero
+    return SDL_APP_CONTINUE;
+}
+auto SDL_AppEvent(void* s, SDL_Event* e) { return ((Director*)s)->handleEvent(*e); }
+auto SDL_AppIterate(void* s)             { return ((Director*)s)->iterate(); }
+void SDL_AppQuit(void* s, ...)           { /* reabsorbe y destruye el Director */ }
+```
+
+La filosofía está escrita en el propio comentario de cabecera de
+[director.hpp](source/core/system/director.hpp):
+
+> *El Director és EL programa: posseeix la configuració, els subsistemes i
+> l'estat.*
+
+Como con `SDL_MAIN_USE_CALLBACKS` no hay un `scope` que envuelva todo el bucle,
+el estado que antes vivía en un `run()` ahora es **miembro** del Director:
+`sdl_` (SDLManager), `context_` (SceneContext), `debug_overlay_` y
+`current_scene_` (todos `std::unique_ptr`, ver
+[director.hpp:45-48](source/core/system/director.hpp#L45-L48)).
+
+### Orden de arranque (constructor)
+
+El constructor [Director::Director](source/core/system/director.cpp#L46) ejecuta el
+bootstrap completo, en este orden:
+
+1. `ConfigYaml::init()` — valores por defecto de configuración.
+2. Parseo de argumentos (`--console`, `--reset-config`) en
+   [checkProgramArguments](source/core/system/director.cpp#L241).
+3. `Utils::initializePathSystem()` + sistema de recursos
+   ([§8](#8-recursos)): en *release* el `resources.pack` es obligatorio; en *dev*
+   hay fallback a `data/`.
+4. Crea la carpeta de sistema (`~/.config/jailgames/<NAME>` en Linux) y carga/crea
+   `config.yaml` ([createSystemFolder](source/core/system/director.cpp#L260)).
+5. Carga el `locale` ([§7](#7-audio) usa lo mismo: i18n).
+6. `Input::init()` con el `gamecontrollerdb.txt` (autoasigna mandos a P1/P2 la
+   primera vez).
+7. Crea `SDLManager` (ventana + GPU), oculta el cursor, inicializa `Audio`.
+8. **Precarga bloqueante** de todos los recursos (música, sonidos, shapes) para
+   evitar tirones de I/O en las transiciones
+   ([director.cpp:187-195](source/core/system/director.cpp#L187-L195)).
+9. Crea el `SceneContext` y fija la escena inicial: `TITLE` en `_DEBUG`, `LOGO`
+   en el resto ([director.cpp:200-205](source/core/system/director.cpp#L200-L205)).
+10. Inicializa los overlays de sistema: `DebugOverlay`, `Notifier`, `ServiceMenu`,
+    `DefineInputs`.
+
+El destructor [Director::~Director](source/core/system/director.cpp#L218) guarda
+la config y destruye los subsistemas **en orden inverso** a la construcción (el
+`Notifier` referencia el renderer, así que debe morir antes que `sdl_`).
+
+---
+
+## 3. Bucle principal
+
+Cada frame, SDL llama a `SDL_AppIterate`, que delega en
+[Director::iterate()](source/core/system/director.cpp#L383). Su estructura es:
+
+```mermaid
+sequenceDiagram
+    participant SDL
+    participant Dir as Director::iterate()
+    participant Scene
+    participant SDLM as SDLManager
+    participant GPU as GpuFrameRenderer
+
+    SDL->>Dir: iterate()
+    Note over Dir: si wants_quit_ → SDL_APP_SUCCESS
+    Dir->>Dir: si !scene o scene.isFinished() → advanceScene()
+    Dir->>Dir: delta_time = (now - last) capeado a 50 ms
+    Dir->>Dir: Input::update()
+    Dir->>Scene: update(dt)
+    Dir->>Dir: overlays.update(dt) + Audio::update()
+    Dir->>SDLM: clear() (= GPU.beginFrame)
+    alt swapchain no disponible
+        SDLM-->>Dir: false → saltar draw+present
+    end
+    Dir->>SDLM: updateRenderingContext()
+    Dir->>Scene: draw()
+    Dir->>Dir: overlays.draw() (capas)
+    Dir->>SDLM: present() (= GPU.endFrame → bloom + postfx)
+```
+
+Puntos concretos a tener en cuenta:
+
+- **Pivot de escena**: si no hay escena o la actual reporta `isFinished()`, se
+  llama a [advanceScene()](source/core/system/director.cpp#L338), que destruye la
+  actual y construye la siguiente con
+  [buildScene()](source/core/system/director.cpp#L323) según
+  `context_->nextScene()`.
+- **Delta time**: se mide con `SDL_GetTicks()` y se **capea a 50 ms** para evitar
+  saltos grandes tras un stall ([director.cpp:397-400](source/core/system/director.cpp#L397-L400)).
+- **Orden de update**: `Input::update()` → `current_scene_->update(dt)` →
+  `debug_overlay_` → `Notifier` → `ServiceMenu` → `DefineInputs` → `Audio::update()`.
+- **Render por capas** (de abajo arriba, entre `clear` y `present`):
+  escena → `debug_overlay_` → `Notifier` (toasts) → `ServiceMenu` → `DefineInputs`
+  (modal de rebinding). Si el overlay de rebinding está activo, el menú de servicio
+  no se pinta ([director.cpp:432-439](source/core/system/director.cpp#L432-L439)).
+- **Salto de frame**: si `sdl_->clear()` devuelve `false` (swapchain no disponible,
+  p. ej. ventana minimizada), se omiten `draw` y `present` ese frame.
+
+El bucle de eventos vive aparte, en
+[Director::handleEvent()](source/core/system/director.cpp#L354), que enruta cada
+`SDL_Event` por la cadena: **ventana → GlobalEvents → F11 (debug overlay) →
+escena** (ver [§9](#9-comunicación-entre-módulos)).
+
+---
+
+## 4. Sistema de escenas
+
+La interfaz base es [scene.hpp](source/core/system/scene.hpp). Como dice su
+cabecera, *el frame loop vive en el Director, no en cada escena*. Cada escena
+implementa cuatro métodos puros:
+
+```cpp
+virtual void handleEvent(const SDL_Event&) = 0;   // eventos no-globales
+virtual void update(float delta_time) = 0;        // lógica
+virtual void draw() = 0;                           // pintado (entre clear y present)
+virtual auto isFinished() const -> bool = 0;       // ¿transición pendiente?
+```
+
+Una escena pide transición vía `context_.setNextScene(...)`; en el siguiente frame
+`isFinished()` devuelve `true` y el Director la destruye para construir la
+siguiente.
+
+### SceneContext
+
+[scene_context.hpp](source/core/system/scene_context.hpp) es el "buzón" de
+transición que el Director posee y va pasando a cada escena por referencia. Tiene:
+
+- `SceneType` (enum): `LOGO`, `TITLE`, `GAME`, `EXIT`.
+- `Option` (p. ej. `JUMP_TO_TITLE_MAIN`) consumible con `consumeOption()`.
+- `MatchConfig` (jugadores activos, modo NORMAL/DEMO) para pasar a `GAME`.
+- El **índice del escenario de demo** (`demoScenarioIndex()` / `advanceDemoScenario()`),
+  que persiste entre escenas para que cada entrada al attract mode muestre el
+  siguiente escenario curado (ver [§11](#11-ia-del-modo-demo-attract)).
+
+Existe además una variable global `SceneManager::actual` que el Director mantiene
+sincronizada con la escena en curso (compatibilidad hacia atrás).
+
+### Las tres escenas (FSM jerárquica)
+
+```mermaid
+stateDiagram-v2
+    [*] --> LOGO
+    LOGO --> TITLE
+    TITLE --> GAME : START (1P/2P)
+    TITLE --> GAME : idle timeout (DEMO)
+    GAME --> TITLE : game over / fin demo (input)
+    GAME --> LOGO : fin demo (timeout/muerte)
+    TITLE --> [*] : EXIT
+```
+
+Cada escena tiene además su **propia** máquina de estados interna:
+
+- **[LogoScene](source/game/scenes/logo_scene.hpp)** — `AnimationState`:
+  `PRE_ANIMATION → ANIMATION → POST_ANIMATION → EXPLOSION → POST_EXPLOSION`. Anima
+  el logo JAILGAMES y lo hace explotar en fragmentos (debris).
+- **[TitleScene](source/game/scenes/title_scene.hpp)** — `TitleState`:
+  `STARFIELD_FADE_IN → STARFIELD → MAIN → PLAYER_JOIN_PHASE → BLACK_SCREEN →
+  DEMO_DIVE → DEMO_CURTAIN`. Naves 3D flotantes (vía
+  [ShipAnimator](source/game/title/ship_animator.hpp)), selección 1P/2P, y un
+  `idle_timer_` en el estado `MAIN` que dispara el attract mode por inactividad.
+- **[GameScene](source/game/scenes/game_scene.hpp)** — es el núcleo del juego y se
+  detalla en [§10](#10-lógica-del-juego).
+
+---
+
+## 5. Renderizado: de la lógica al píxel
+
+Este es el subsistema más denso. La idea central: **toda la geometría son líneas**
+(la estética es vectorial). El juego acumula líneas en CPU durante `draw()`, y al
+final del frame se envían a la GPU en un único batch, se rasterizan a una textura
+*offscreen*, y un par de pases de post-procesado (bloom + flicker/fondo) componen
+la imagen final sobre la swapchain.
+
+### 5.1 Capas del subsistema
+
+| Fichero | Rol |
+|---|---|
+| [sdl_manager.hpp/.cpp](source/core/rendering/sdl_manager.hpp) | Crea la ventana SDL, posee el `GpuFrameRenderer`, gestiona zoom/fullscreen/letterbox. Expone `clear()` / `present()` / `getRenderer()`. |
+| [gpu/gpu_frame_renderer.hpp/.cpp](source/core/rendering/gpu/gpu_frame_renderer.hpp) | Orquestador del frame GPU: `beginFrame` → `pushLine`/`pushRect` → `endFrame` (`flushBatch` + `bloomPass` + `compositePass`). |
+| [gpu/gpu_device](source/core/rendering/gpu/gpu_device.hpp) | Wrapper del `SDL_GPUDevice` (claim de ventana, formato de swapchain). |
+| [gpu/gpu_line_pipeline](source/core/rendering/gpu/gpu_line_pipeline.hpp) | Pipeline de líneas: dibuja cada línea como un quad (2 triángulos) con antialias geométrico. |
+| [gpu/gpu_bloom_pipeline](source/core/rendering/gpu/gpu_bloom_pipeline.hpp) | Blur gaussiano separable (pase H + pase V) sobre dos texturas ping-pong. |
+| [gpu/gpu_postfx_pipeline](source/core/rendering/gpu/gpu_postfx_pipeline.hpp) | Composite final: mezcla escena + bloom + flicker + fondo pulsante. |
+| [line_renderer.hpp/.cpp](source/core/rendering/line_renderer.hpp) | API que usa el juego: `Rendering::linea(...)` y `lineaGlow(...)`. |
+| [shape_renderer.hpp/.cpp](source/core/rendering/shape_renderer.hpp) | `renderShape(...)`: dibuja una `Shape` aplicando transformación y, opcionalmente, glow multipase. |
+
+### 5.2 Una `Shape` y cómo se carga
+
+Una "shape" es una figura vectorial: un conjunto de **polilíneas** y **líneas**
+([shape.hpp](source/core/graphics/shape.hpp)). Los ficheros viven en `data/shapes/`
+con extensión `.shp` y un formato de texto tipo clave:valor. Ejemplo real
+([data/shapes/ship/arrow.shp](data/shapes/ship/arrow.shp)):
+
+```
+name: arrow
+scale: 1.0
+center: 0, 0
+polyline: 0,-12  8.49,8.49  0,4  -8.49,8.49  0,-12
+```
+
+> Nota: el formato real usa directivas `name:`, `scale:`, `center:`,
+> `polyline:` y `line:` (Y negativo = arriba). No es la sintaxis
+> `POLYLINE: (x,y)` que podría suponerse de otros motores.
+
+La carga la centraliza [shape_loader.hpp](source/core/graphics/shape_loader.hpp)
+(`Graphics::ShapeLoader::load(filename)`), con caché de `std::shared_ptr<Shape>`.
+Todas las shapes se precargan en el boot del Director.
+
+### 5.3 El flujo de un frame de render
+
+```mermaid
+graph TD
+    A["Scene::draw()<br/>(acumula en CPU)"] --> B["Rendering::linea / renderShape"]
+    B --> C["GpuFrameRenderer::pushLine()<br/>extruye quad → vertices_ / indices_"]
+    C -.repetido N veces.-> C
+    A --> D["SDLManager::present()<br/>= GpuFrameRenderer::endFrame()"]
+    D --> E["flushBatch()<br/>sube VBO/IBO, dibuja sobre OFFSCREEN"]
+    E --> F["bloomPass()<br/>H: high-pass+blur → bloom_a<br/>V: blur → bloom_b"]
+    F --> G["compositePass()<br/>offscreen + bloom_b + flicker + fondo<br/>→ swapchain (letterbox)"]
+    G --> H["SubmitGPUCommandBuffer + present"]
+```
+
+Paso a paso, con anclas reales:
+
+1. **Emisión (juego).** Durante `current_scene_->draw()`, el juego llama a
+   [Rendering::linea()](source/core/rendering/line_renderer.hpp#L33) (y
+   `renderShape`, `VectorText`, `Playfield`, etc.). Las coordenadas son **lógicas
+   (1280×720)**. El color por defecto si `alpha==0` es el verde fósforo CRT
+   `DEFAULT_LINE_COLOR = {100,255,100,255}`.
+2. **Acumulación (CPU).** `linea()` pre-multiplica el brillo y llama a
+   [GpuFrameRenderer::pushLine()](source/core/rendering/gpu/gpu_frame_renderer.hpp#L88),
+   que **extruye** la línea en un quad (4 vértices, 6 índices) y lo acumula en
+   `vertices_` / `indices_`. Si el antialias está activo, añade ~0.5 px de padding y
+   marca `edge_dist` para el fade del fragment shader.
+3. **Flush (GPU).** En `endFrame()`, `flushBatch()` sube el batch a un VBO/IBO,
+   abre un render pass sobre el `offscreen_texture_` (R8G8B8A8, tamaño físico
+   configurable, independiente del lógico) y dibuja con el `line_pipeline_`. El
+   vertex shader transforma píxeles lógicos → NDC; el fragment shader aplica
+   `smoothstep` sobre `edge_dist` para el suavizado.
+4. **Bloom.** `bloomPass()` hace un blur separable: pase H (high-pass por
+   luminancia + blur horizontal → `bloom_texture_a_`) y pase V (blur vertical →
+   `bloom_texture_b_`). Parámetros en `PostFxParams`
+   ([gpu_frame_renderer.hpp:33-51](source/core/rendering/gpu/gpu_frame_renderer.hpp#L33-L51)).
+5. **Composite.** `compositePass()` dibuja un triángulo *fullscreen* sobre la
+   swapchain, muestreando offscreen + bloom, aplicando flicker temporal y un fondo
+   verde pulsante. Aquí se aplica el **letterbox** vía el viewport físico
+   (`setViewport`).
+
+El interruptor maestro de post-proceso es **F6** (`setPostFxEnabled`): cuando está
+OFF, la escena offscreen sale tal cual (passthrough), útil para A/B testing.
+
+### 5.4 Texto, 3D y elementos de escena
+
+- **[VectorText](source/core/graphics/vector_text.hpp)** — renderiza texto donde
+  cada carácter es una `Shape` precargada.
+- **[Camera3D](source/core/graphics/camera3d.hpp)** + **[Wireframe3D](source/core/graphics/wireframe3d.hpp)**
+  — proyección perspectiva en CPU de mallas 3D (vértices + aristas) a líneas 2D.
+  Lo usan el starfield 3D y las naves del título.
+- **[Starfield](source/core/graphics/starfield.hpp)** (campo de estrellas 3D que
+  vienen hacia la cámara) y **[StarfieldParallax](source/core/graphics/starfield_parallax.hpp)**
+  (capas 2D de fondo con parallax).
+- **[Playfield](source/core/graphics/playfield.hpp)** — rejilla de fondo con
+  animación de construcción y *ripples* (ondas) que reaccionan a la nave y a las
+  explosiones.
+- **[Border](source/core/graphics/border.hpp)** — marco de 4 lados que se desplaza
+  al recibir impactos.
+- **[Curtain](source/core/graphics/curtain.hpp)** — cortinilla negra para
+  transiciones; se pinta siempre la última.
+
+### 5.5 Shaders: fuentes, compilación y selección
+
+Las fuentes GLSL viven en [shaders/](shaders/): `line.vert.glsl`, `line.frag.glsl`,
+`postfx.vert.glsl`, `postfx.frag.glsl`, `bloom.frag.glsl`. **No se cargan de disco en
+runtime**: se embeben como arrays/strings en el binario.
+
+**Pipeline de compilación (SPIR-V, Linux/Windows).** Lo orquesta
+[CMakeLists.txt:139-187](CMakeLists.txt#L139). La lógica clave:
+
+- Para cada `.glsl` hay un header destino en
+  [gpu/spv/](source/core/rendering/gpu/spv/) (p. ej. `line_vert_spv.h`).
+- CMake busca `glslc` (`find_program(GLSLC_EXE ...)`). Hay **tres caminos**:
+  1. `glslc` presente → un `add_custom_command` regenera los headers SPV cuando
+     cambian los `.glsl`, vía el target `shaders` del que depende el ejecutable.
+  2. `glslc` ausente pero **los headers ya están commiteados** → se usan tal cual
+     (los `.spv.h` están versionados en el repo).
+  3. `glslc` ausente **y** faltan headers → `FATAL_ERROR` pidiendo instalar
+     `shaderc`/`vulkan-sdk`.
+- La conversión binario→header la hace el script
+  [tools/shaders/compile_spirv.cmake](tools/shaders/compile_spirv.cmake): invoca
+  `glslc -O -fshader-stage=<vert|frag>` para producir el `.spv`, lee el binario como
+  hex (`file(READ ... HEX)`) y escribe un header con
+  `static const uint8_t LINE_VERT_SPV[] = { 0x.., ... };` y su `_SIZE`. Es
+  multiplataforma puro CMake (no necesita `bash` ni `xxd`).
+
+**MSL (macOS).** Los headers Metal en [gpu/msl/](source/core/rendering/gpu/msl/)
+(`line_vert.msl.h`, etc.) están **escritos a mano** (no los genera CMake), como
+strings literales C++.
+
+**Selección SPV vs MSL: es _compile-time_, no runtime.** La hace
+[shader_factory.hpp](source/core/rendering/gpu/shader_factory.hpp) con `#ifdef __APPLE__`:
+en Apple expone `createShaderMSL(...)` (`SDL_GPU_SHADERFORMAT_MSL`), y en el resto
+`createShaderSPIRV(...)` (`SDL_GPU_SHADERFORMAT_SPIRV`). Cada pipeline llama al helper
+disponible con el header embebido correspondiente. (Es decir: no es `GpuDevice` quien
+elige el backend de shader, sino el preprocesador al compilar.)
+
+---
+
+## 6. Entrada
+
+El subsistema de input ([core/input/](source/core/input/)) es un **singleton**
+(`Input::init()` / `Input::get()` / `Input::destroy()`) que unifica teclado,
+gamepads y ratón.
+
+- **Acciones**: enum `InputAction` (`LEFT`, `RIGHT`, `THRUST`, `SHOOT`, `START`,
+  `MENU`, ...) en [input_types.hpp](source/core/input/input_types.hpp).
+- **Bindings por jugador**: hay bindings separados de teclado y de gamepad para P1
+  y P2, que se cargan de la config con `applyPlayer1Bindings()` /
+  `applyPlayer2Bindings()` (llamados desde el constructor del Director).
+- **Captura por frame**: `Input::update()` lee `SDL_GetKeyboardState()` y los ejes
+  y botones del gamepad, y hace *edge-detection* para distinguir `just_pressed` de
+  `is_held`. La consulta es `checkAction(...)` / `checkActionPlayer1/2(...)`.
+- **Hotplug**: `Input::handleEvent()` procesa `SDL_EVENT_GAMEPAD_ADDED/REMOVED`
+  (`addGamepad` / `removeGamepad`) y notifica con un toast vía `Notifier`.
+- **Ratón**: [mouse.hpp](source/core/input/mouse.hpp) auto-oculta el cursor.
+- **Rebinding en runtime**: [define_inputs.hpp](source/core/input/define_inputs.hpp)
+  es un modal singleton que captura una secuencia de acciones, persiste en config y
+  reaplica bindings sin reiniciar.
+
+El enrutado de input ocurre en dos sitios: los eventos **globales** pasan por
+`GlobalEvents::handle()` (que primero deja a `Input` procesar el hotplug), y la
+lógica de juego consulta directamente `Input::get()->checkAction...` durante
+`update()` (p. ej. [Ship::processInput](source/game/entities/ship.hpp)).
+
+---
+
+## 7. Audio
+
+[core/audio/](source/core/audio/) es otro singleton (`Audio::init/get/destroy`)
+con un motor de bajo nivel propio:
+
+- **[Audio](source/core/audio/audio.hpp)** — capa lógica: `playMusic()`,
+  `playSound()`, volúmenes por grupo (`GAME`, `INTERFACE`), `playSoundWithEcho/Reverb`.
+- **[jail_audio.hpp](source/core/audio/jail_audio.hpp)** (`Ja::Engine`) — motor
+  sobre SDL3 audio: streaming de **OGG** (vía `stb_vorbis`) para música, **WAV**
+  descomprimido para efectos, mezcla en N canales.
+- **[audio_adapter.hpp](source/core/audio/audio_adapter.hpp)** —
+  `AudioResource::getMusic/getSound`: caché *lazy* que carga bytes vía
+  `Resource::Helper` y los decodifica una sola vez.
+- **[audio_effects.hpp](source/core/audio/audio_effects.hpp)** — DSP de echo y
+  reverb; presets en `data/config/sounds.yaml`
+  ([sound_effects_config.hpp](source/core/audio/sound_effects_config.hpp)).
+
+El Director precarga toda la música y todos los sonidos en el boot, y llama a
+`Audio::update()` una vez por frame.
+
+---
+
+## 8. Recursos
+
+[core/resources/](source/core/resources/) abstrae de dónde salen los bytes:
+
+- **[resource_pack](source/core/resources/resource_pack.hpp)** (`Resource::Pack`)
+  — lee un fichero empaquetado con cabecera *magic* `"ORNI"` y entradas con CRC32
+  para validación de integridad.
+- **[resource_loader](source/core/resources/resource_loader.hpp)**
+  (`Resource::Loader`, singleton Meyers) — `loadResource()`, `resourceExists()`,
+  `listResources(prefix)`, `validatePack()`.
+- **[resource_helper](source/core/resources/resource_helper.hpp)** — wrappers de
+  conveniencia (`initializeResourceSystem`, `listResources`, `loadFile`).
+
+**Estrategia dual** (decidida en el constructor del Director,
+[director.cpp:64-93](source/core/system/director.cpp#L64-L93)):
+
+- **Release** (`RELEASE_BUILD`): `resources.pack` es **obligatorio** y se valida su
+  integridad; si falla, el juego aborta. No hay fallback (ver memoria de proyecto
+  *"No fallback a SDL_Renderer"* — aquí es la política equivalente para recursos).
+- **Dev**: intenta el pack; si no está, hace **fallback al directorio `data/`** del
+  filesystem, escaneándolo según prefijo (`music/`, `sounds/`, `shapes/`).
+
+El formato de datos de juego:
+
+- **Entidades** (`data/entities/<nombre>/<nombre>.yaml`) — YAML declarativo con
+  `shape`, `physics`, `ai`, `animation`, `wounded`, `spawn`, `colors`, `score`,
+  `events`. Ejemplo: [data/entities/square/square.yaml](data/entities/square/square.yaml).
+- **Stages** (`data/stages/stages.yaml`) — oleadas (`waves`) con `spawn`,
+  `spawn_interval`, `next` y multiplicadores de dificultad por stage.
+- **Shapes** (`data/shapes/**/*.shp`) — figuras vectoriales (ver [§5.2](#52-una-shape-y-cómo-se-carga)).
+
+El parser YAML usado es [fkyaml](source/external/fkyaml_node.hpp) (cabecera única),
+envuelto por [config_yaml](source/game/config_yaml.hpp).
+
+---
+
+## 9. Comunicación entre módulos
+
+No hay un sistema de mensajería desacoplado. La comunicación es:
+
+1. **Eventos SDL → cadena del Director.** Por cada `SDL_Event`,
+   [Director::handleEvent](source/core/system/director.cpp#L354) intenta, en orden:
+   `SDLManager::handleWindowEvent` → `GlobalEvents::handle` → F11 (debug overlay) →
+   `current_scene_->handleEvent`.
+
+2. **GlobalEvents** ([global_events.cpp](source/core/system/global_events.cpp)) es
+   el orquestador de la entrada global. Su `handle()` hace, en orden:
+   `Input::get()->handleEvent` (hotplug) → `consumeIfDefineActive` (si el modal de
+   rebinding está activo, **engulle todo**) → `SDL_EVENT_QUIT` → ratón → botón MENU
+   del mando → reenvío al `ServiceMenu` si está abierto → teclas de función:
+
+   | Tecla | Acción |
+   |---|---|
+   | F1 / F2 | reducir / aumentar tamaño de ventana |
+   | F3 | fullscreen |
+   | F4 | VSync |
+   | F5 | antialias geométrico |
+   | F6 | post-procesado (bloom/flicker/fondo) |
+   | F7 | idioma ca ↔ en (hot-swap de `Locale`) |
+   | F11 | debug overlay (gestionado en el Director, no en GlobalEvents) |
+   | F12 | menú de servicio |
+   | ESC | doble pulsación para salir (la 1ª muestra un toast de confirmación) |
+
+3. **Singletons compartidos.** `Input`, `Audio`, `Locale`, `Notifier`,
+   `ServiceMenu`, `DefineInputs` se acceden globalmente vía `::get()`. Muchos
+   comprueban `nullptr` para degradar con elegancia (p. ej. el hotplug notifica
+   solo si `Notifier::get() != nullptr`).
+
+4. **Paso por referencia.** Las escenas reciben `SDLManager&` y `SceneContext&`; el
+   render se propaga como `Rendering::Renderer*`. Los sistemas de juego reciben un
+   struct `Context` con punteros a los pools (ver [§10](#10-lógica-del-juego)).
+
+**Overlays de sistema** (todos singletons, todos por encima de la escena):
+
+- **[Notifier](source/core/system/notifier.hpp)** — toasts deslizantes centrados
+  (`notifyInfo/Warn/Exit`), con máquina de animación HIDDEN/ENTERING/HOLDING/EXITING.
+- **[ServiceMenu](source/core/system/service_menu.hpp)** — menú de configuración
+  (F12) con pila de páginas (vídeo, audio, controles, sistema...).
+- **[DebugOverlay](source/core/system/debug_overlay.hpp)** — HUD de FPS/VSync (F11).
+- **[Relaunch](source/core/system/relaunch.hpp)** — reinicio en caliente vía
+  `execv` (lo solicita el ServiceMenu, lo ejecuta `SDL_AppQuit`).
+
+**Lo que NO existe** (verificado): no hay event bus genérico, ni cola de mensajes
+desacoplada, ni un FSM genérico reutilizable fuera de las máquinas de estado
+concretas de cada escena/sistema, ni un ECS.
+
+---
+
+## 10. Lógica del juego
+
+Toda la partida vive en [GameScene](source/game/scenes/game_scene.hpp). Es la clase
+más grande del juego y actúa como orquestador. Posee:
+
+- El mundo físico [Physics::PhysicsWorld](source/core/physics/physics_world.hpp)
+  (integración cinemática + colisiones físicas).
+- Pools de tamaño **fijo**: `std::array<Ship, 2>`,
+  `std::array<Enemy, MAX_ORNIS>` (15), `std::array<Bullet, MAX_BULLETS_TOTAL>` (6:
+  P1=[0,1,2], P2=[3,4,5]).
+- Estado de partida: vidas, score y *death timers* por jugador, máquina de
+  game over (`GameOverState`: `NONE/CONTINUE/GAME_OVER`), continues usados.
+- El stage system, los efectos visuales, y los `DemoPilot` (uno por nave).
+
+### 10.1 Orquestación por frame
+
+[GameScene::update()](source/game/scenes/game_scene.cpp) es un orquestador delgado;
+cada paso es una función privada (descompuesto para reducir complejidad cognitiva):
+
+```cpp
+void GameScene::update(float dt) {
+    if (ServiceMenu abierto) return;          // pausa global (draw sí sigue)
+    stepPhysics(dt);
+    if (mode == DEMO) { if (stepDemo(dt)) return; }
+    else if (game_over_state_ == NONE) { stepShootingInput(); stepMidGameJoin(); }
+    if (stepContinueScreen(dt)) return;
+    if (stepGameOver(dt)) return;
+    stepDeathSequence(dt);
+    stepStageStateMachine(dt);
+}
+```
+
+El corazón del gameplay es
+[stepStageStateMachine](source/game/scenes/game_scene.hpp#L166), que despacha según
+el estado del stage; en `PLAYING`,
+[runStagePlaying](source/game/scenes/game_scene.hpp#L169) ejecuta: WaveRunner
+(spawns) → IA de cada enemigo → control de naves
+([updateShipsControl](source/game/scenes/game_scene.cpp), que en demo usa
+`applyMovement` con el control del pilot y fuera de demo usa `processInput`) →
+detección de colisiones ([runCollisionDetections](source/game/scenes/game_scene.hpp#L176)).
+
+`draw()` despacha de forma análoga según `GameOverState` y el estado del stage, y
+siempre pinta la cortinilla al final.
+
+### 10.2 Entidades
+
+Las tres heredan de `Entities::Entity` ([entity.hpp](source/core/entities/entity.hpp)):
+
+- **[Ship](source/game/entities/ship.hpp)** — nave del jugador. `processInput()`
+  (humano) y `applyMovement()` (usado por la IA demo). Estados: activa,
+  invulnerable (parpadeo tras spawn), herida (`hurt`). Al morir genera debris con
+  la inercia heredada.
+- **[Enemy](source/game/entities/enemy.hpp)** — 5 tipos (`EnemyType`: `PENTAGON`,
+  `SQUARE`, `PINWHEEL`, `STAR`, `ORB`). Toda su config (físicas, IA, animación,
+  eventos) viene del **YAML** vía [EnemyRegistry](source/game/entities/enemy_registry.hpp).
+  Tiene salud (la mayoría HP=1; `ORB` HP=10) y estado *wounded* (parpadeo).
+- **[Bullet](source/game/entities/bullet.hpp)** — con `owner_id` (0=P1, 1=P2,
+  ≥16=enemigo) y `prev_position` para colisión *swept* (la bala que cruza un enemigo
+  entre dos frames). Config en [BulletRegistry](source/game/entities/bullet_registry.hpp).
+
+### 10.3 IA de enemigos: declarativa
+
+Los enemigos **no** tienen comportamiento hardcoded. El YAML describe:
+
+- Una **primitiva de movimiento** (`MovementType` en
+  [enemy_ai.hpp](source/game/entities/enemy_ai.hpp)): `ZIGZAG`, `TRACKING`,
+  `RECTILINEAR_PROXIMITY`, `WANDER`, `CHASE`, `FLEE`.
+- **Acciones de tick** periódicas (p. ej. `SHOOT`).
+- **Eventos** (`on_hit`, `on_no_health`, `on_hurt_end`, `on_destroy`) con acciones
+  (`APPLY_IMPULSE`, `DECREASE_HEALTH`, `CREATE_DEBRIS`, `ADD_SCORE`, `FLASH`,
+  `FIRE_BULLET`, `DESTROY`, ...).
+
+Dos sistemas los ejecutan:
+
+- **[EnemyAiSystem](source/game/systems/enemy_ai_system.hpp)** — `move()` aplica la
+  primitiva de movimiento; `tick()` añade las acciones periódicas. Helper
+  `findNearestShipPosition()` para las primitivas que buscan al jugador.
+- **[EnemyEventDispatcher](source/game/systems/enemy_event_dispatcher.hpp)** —
+  ejecuta las acciones declarativas cuando se dispara un evento.
+
+### 10.4 Colisiones
+
+[CollisionSystem](source/game/systems/collision_system.hpp) recibe un struct
+`Context` (punteros a ships/enemies/bullets, managers de efectos, timers, scores,
+vidas y un callback `on_player_hit`) que GameScene construye en
+[buildCollisionContext](source/game/scenes/game_scene.hpp#L174). Detecta:
+bala↔enemigo, nave↔enemigo, bala↔jugador (fuego amigo / autodisparo), bala
+enemiga↔nave, y balas fuera del área. Reglas observadas: el primer impacto deja al
+enemigo *wounded*; el segundo lo destruye y suma score. La nave entra en `hurt` al
+primer toque y muere al segundo durante ese estado.
+
+### 10.5 Stages y oleadas
+
+- **[StageManager](source/game/stage_system/stage_manager.hpp)** — FSM del stage
+  (`EstatStage`): `INIT_HUD` (anima el HUD, 3 s) → `LEVEL_START` ("ENEMY INCOMING",
+  3 s, arranca `game.ogg`) → `PLAYING` → `LEVEL_COMPLETED` ("GOOD JOB COMMANDER!",
+  3 s) → siguiente stage. `initDemo(stage_id)` arranca directamente en `PLAYING`
+  para el attract mode.
+- **[WaveRunner](source/game/stage_system/wave_runner.hpp)** — emite los enemigos de
+  cada oleada según `spawn_interval` y avanza cuando se cumple `next` (`all_dead`,
+  `timeout`, o ambos).
+- **[StageConfig](source/game/stage_system/stage_config.hpp)** /
+  [StageLoader](source/game/stage_system/stage_loader.hpp) — modelo y carga del
+  YAML de stages.
+
+### 10.6 Dos capas de colisión: física vs gameplay
+
+Conviene no confundirlas, porque conviven:
+
+**1. Física** — [PhysicsWorld](source/core/physics/physics_world.hpp) /
+[physics_world.cpp](source/core/physics/physics_world.cpp). Es un mundo 2D
+minimalista de arcade. Cada frame, `update(dt)` hace tres pasos:
+
+1. **Integración** semi-implícita de Euler con damping exponencial
+   (`v += (F·invMass)·dt; v *= exp(-damping·dt); x += v·dt`) sobre cada
+   [RigidBody](source/core/physics/rigid_body.hpp) no estático. Un cuerpo con
+   `mass=0` (`inverse_mass=0`) es estático (masa infinita).
+2. **Rebote contra los bordes** del `PLAYAREA` (`resolveBoundsCollisions`): reposiciona
+   el cuerpo dentro del rect y refleja la componente normal de la velocidad por su
+   `restitution`. Antes de reflejar, invoca un `BoundsHitCallback` opcional con la
+   velocidad de impacto entrante (lo usa GameScene para los efectos de borde).
+3. **Colisiones cuerpo-cuerpo** (`resolveBodyCollisions`): broadphase trivial
+   **O(n²)** (suficiente para ~23 cuerpos), círculo-círculo, con corrección posicional
+   de penetración + **impulso elástico** `j = -(1+e)(v_rel·n) / (1/mₐ + 1/m_b)`
+   (referencia Box2D / Chris Hecker, en `resolveBodyPair`). Los cuerpos con `radius=0`
+   (las balas, cinemáticas puras) **no** participan aquí.
+
+Los `RigidBody` los poseen las entidades; el mundo solo guarda punteros no-owning
+(`addBody`/`removeBody`).
+
+**2. Gameplay** — [collision_system.cpp](source/game/systems/collision_system.cpp)
+(ver [§10.4](#104-colisiones)), que decide *qué pasa* (daño, score, muerte). Usa los
+helpers de [collision.hpp](source/core/physics/collision.hpp): `checkCollision`
+(círculo-círculo discreto, distancia al cuadrado sin `sqrt`) y `checkCollisionSwept`
+(segment-círculo, para que una bala rápida no atraviese un enemigo entre frames —
+*anti-tunneling*). Estos checks usan el `collision_radius` de la **entidad**
+(con amplificador opcional de hitbox), no el `radius` del body.
+
+En resumen: la **física** mueve y rebota los cuerpos; el **gameplay** detecta los
+contactos relevantes para las reglas. Una bala no rebota físicamente (radius 0) pero sí
+provoca daño vía el check *swept*.
+
+---
+
+## 11. IA del modo demo (attract)
+
+El attract mode es una partida que se juega sola para atraer al jugador. Se activa
+desde [TitleScene](source/game/scenes/title_scene.hpp) cuando el `idle_timer_` en el
+estado `MAIN` supera el umbral de inactividad, y desde
+[GameScene](source/game/scenes/game_scene.hpp) cuando `match_config_.mode == DEMO`.
+
+La IA vive en [DemoPilot](source/game/systems/demo_pilot.hpp) /
+[demo_pilot.cpp](source/game/systems/demo_pilot.cpp). Su diseño es explícito en la
+cabecera: busca **parecer humano, no ser óptimo**. Características clave:
+
+- **Solo lectura**: `DemoPilot::compute(ship, enemies, bullets, play_area, dt)`
+  devuelve un `Control{left,right,thrust,shoot}`. No lee `Input` ni muta entidades;
+  GameScene aplica el resultado vía `Ship::applyMovement` + `fireBullet`.
+- **Escenarios curados**: hay 4 (`SCENARIOS` en
+  [demo_pilot.hpp:36-42](source/game/systems/demo_pilot.hpp#L36-L42)): stages
+  `{5,8,6,10}` con 1 o 2 naves IA. El `SceneContext` recuerda el índice y rota al
+  siguiente en cada entrada al demo.
+
+**Lógica de decisión por prioridad** (verificado en `demo_pilot.cpp`, con sus
+constantes):
+
+1. **Esquiva de bala** — si una bala enemiga entrante está dentro de
+   `DODGE_SCAN_RADIUS = 190 px` y viene hacia la nave (`DODGE_HEADING_MIN = 0.25`),
+   maniobra perpendicular a la bala con sesgo al centro (`WALL_BIAS = 0.6`); no
+   dispara mientras esquiva.
+2. **Sin enemigos** — deriva tranquila (giro lento).
+3. **Peligro cercano** — si el objetivo está a menos de `DANGER_RADIUS = 95 px`, se
+   aleja con sesgo al centro.
+4. **Combate** — apuntado con *lead* (`LEAD_TIME = 0.30 s`) más un error humano
+   (`AIM_JITTER_MAX = 0.10 rad`); dispara si el error es menor que
+   `FIRE_TOLERANCE = 0.18 rad` y el cooldown (`FIRE_COOLDOWN = 0.32 s`) lo permite;
+   se acerca si está más lejos que `APPROACH_RADIUS = 250 px`.
+
+Temporización "humana": reevalúa el objetivo cada `RETARGET_INTERVAL = 0.15 s` y usa
+una zona muerta de rotación (`ROTATE_DEADZONE = 0.05 rad`) para no oscilar. La demo
+se rompe con cualquier input (vuelve a TITLE) o por timeout/muerte (vuelve a LOGO),
+gestionado en [stepDemo](source/game/scenes/game_scene.hpp#L157).
+
+---
+
+## 12. Efectos visuales
+
+Viven en [game/effects/](source/game/effects/) y son managers con pools:
+
+- **[DebrisManager](source/game/effects/debris_manager.hpp)** — rompe una shape en
+  fragmentos que vuelan radialmente, heredando inercia del cuerpo y, opcionalmente,
+  el impulso de la bala que causó la muerte. Notifica al `Border` (bump) y al
+  `Playfield` (ripple). Lo usan muerte de nave/enemigo, balas fuera de área y las
+  explosiones del logo.
+- **[FireworkManager](source/game/effects/firework_manager.hpp)** — bursts de fuegos
+  artificiales.
+- **[FloatingScoreManager](source/game/effects/floating_score_manager.hpp)** —
+  números de puntuación flotantes ("+150").
+- **[TrailManager](source/game/effects/trail_manager.hpp)** — estela tras las naves.
+
+---
+
+## 13. Configuración, constantes y convenciones
+
+**Configuración:**
+
+- **[EngineConfig](source/core/config/engine_config.hpp)** — struct POD con
+  ventana, rendering, audio, bindings de jugadores, locale, console. Es la config
+  persistente (`config.yaml`), gestionada por
+  [config_yaml](source/game/config_yaml.hpp) (`ConfigYaml::engine_config`,
+  `loadFromFile`/`saveToFile`).
+- **[PostFxConfig](source/core/config/postfx_config.hpp)** — carga los `PostFxParams`
+  (bloom/flicker/fondo) desde YAML.
+- **[GameConfig::MatchConfig](source/core/system/game_config.hpp)** — config no
+  persistente de la partida (jugadores activos, modo NORMAL/DEMO).
+
+**Constantes y tipos:**
+
+- **[core/types.hpp](source/core/types.hpp)** — `Vec2` / `Vec3` (agregados con
+  operadores y helpers como `length()`, `normalized()`, `dot()`, `cross()`).
+- **[core/defaults/](source/core/defaults/)** — un fichero por dominio
+  (`window.hpp`, `rendering.hpp`, `audio.hpp`, `entities.hpp`, `notifier.hpp`...)
+  con todas las constantes por defecto. `game/constants.hpp` reexporta varias como
+  alias (`MAX_ORNIS`, `MAX_BULLETS`, `PI`) y añade helpers de área de juego.
+
+**Convenciones de código** (de `.clang-tidy`, confirmadas en memoria de proyecto):
+
+- Métodos en `camelBack`, tipos en `CamelCase`, constantes en `UPPER_CASE`.
+- Comentarios mayormente en **catalán** (algunos en castellano); el código y los
+  identificadores mezclan catalán/castellano/inglés.
+- Patrón recurrente: **singletons** con `init/get/destroy` y comprobación de
+  `nullptr` para degradación elegante.
+- Patrón recurrente: descomposición de funciones grandes (`update`/`draw`) en
+  sub-pasos privados (`stepX`/`runX`/`drawXState`) para mantener baja la complejidad
+  cognitiva.
+- Análisis estático (cppcheck/clang-tidy) corre vía git hooks
+  ([.githooks/](.githooks/)); la política es **arreglar la causa**, no suprimir el
+  diagnóstico.
+
+---
+
+## 14. Guía de navegación
+
+| Si quieres tocar… | Mira… |
+|---|---|
+| El arranque, orden de init, o el bucle de frame | [director.cpp](source/core/system/director.cpp) (`Director::iterate` / `handleEvent`) |
+| Las callbacks de SDL | [main.cpp](source/main.cpp) |
+| Añadir/cambiar una escena o una transición | [scene.hpp](source/core/system/scene.hpp), [scene_context.hpp](source/core/system/scene_context.hpp), `Director::buildScene` |
+| Cómo se dibuja una línea / el frame de render | [line_renderer.cpp](source/core/rendering/line_renderer.cpp) → [gpu_frame_renderer.cpp](source/core/rendering/gpu/gpu_frame_renderer.cpp) |
+| Bloom / flicker / fondo (post-proceso) | [gpu_postfx_pipeline](source/core/rendering/gpu/gpu_postfx_pipeline.hpp), [gpu_bloom_pipeline](source/core/rendering/gpu/gpu_bloom_pipeline.hpp), shaders en [shaders/](shaders/) |
+| Crear/editar una figura vectorial | `data/shapes/**/*.shp` + [shape_loader.hpp](source/core/graphics/shape_loader.hpp) |
+| El texto en pantalla | [vector_text.hpp](source/core/graphics/vector_text.hpp) |
+| Eventos globales (teclas F, ESC, hotplug) | [global_events.cpp](source/core/system/global_events.cpp) |
+| Controles, bindings, rebinding | [input.cpp](source/core/input/input.cpp), [define_inputs.cpp](source/core/input/define_inputs.cpp) |
+| Reproducir música/efectos | [audio.hpp](source/core/audio/audio.hpp), [audio_adapter.hpp](source/core/audio/audio_adapter.hpp) |
+| Cómo se cargan los recursos / el pack | [resource_loader.cpp](source/core/resources/resource_loader.cpp), [resource_pack.cpp](source/core/resources/resource_pack.cpp) |
+| Reglas de la partida, vidas, game over | [game_scene.cpp](source/game/scenes/game_scene.cpp) |
+| Comportamiento de un enemigo | su YAML en `data/entities/<tipo>/` + [enemy_ai_system.cpp](source/game/systems/enemy_ai_system.cpp) |
+| Definir oleadas / dificultad de un nivel | [data/stages/stages.yaml](data/stages/stages.yaml) + [stage_manager.cpp](source/game/stage_system/stage_manager.cpp) |
+| Colisiones | [collision_system.cpp](source/game/systems/collision_system.cpp) |
+| La IA del modo demo | [demo_pilot.cpp](source/game/systems/demo_pilot.cpp) |
+| Explosiones / partículas | [debris_manager.cpp](source/game/effects/debris_manager.cpp) |
+| El menú de servicio (F12) | [service_menu.cpp](source/core/system/service_menu.cpp) |
+| Textos traducibles | `data/locale/*.yaml` + [locale.cpp](source/core/locale/locale.cpp) |
+| Constantes por defecto | [core/defaults/](source/core/defaults/) |
+
+---
+
+### Notas de honestidad sobre la cobertura
+
+- Todas las secciones se verificaron leyendo directamente los ficheros y firmas
+  citados, incluyendo el **pipeline de compilación de shaders**
+  ([§5.5](#55-shaders-fuentes-compilación-y-selección): `CMakeLists.txt` +
+  `tools/shaders/compile_spirv.cmake` + `shader_factory.hpp`) y el interior de la
+  **física** ([§10.6](#106-dos-capas-de-colisión-física-vs-gameplay):
+  `physics_world.cpp` + `collision.hpp` + `rigid_body.hpp`).
+- Lo que **no** se ha trazado a fondo y queda como lectura directa del código si hace
+  falta: los detalles finos de animación de cada overlay (curvas de easing del
+  `Notifier`/`ServiceMenu`) y la coreografía interna completa de `LogoScene` y
+  `TitleScene` (más allá de sus estados). Son descriptivos, no estructurales.
+</content>
+</invoke>