merge docs/arquitectura: guia d'arquitectura del projecte

2026-05-29 13:39:03 +02:00
parent e47bc5188a ff3c3fe2ff
commit 73e21e9dc0
1 changed files with 553 additions and 0 deletions
@@ -0,0 +1,553 @@
+# Arquitectura de **JailDoctor's Dilemma**
+
+> 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 el código
+> contradice a la documentación previa (`CLAUDE.md`), lo señalo: **manda el
+> código**.
+>
+> **JailDoctor's Dilemma** es un *puzzle-platformer* 2D retro en C++20 + SDL3:
+> 60+ habitaciones interconectadas, ítems coleccionables, enemigos y logros.
+> Resolución de juego **256×192**. 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. [Escenas y flujo de la aplicación](#3-escenas-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 escena `Game`](#6-lógica-del-juego-la-escena-game)
+7. [Habitaciones y colisión](#7-habitaciones-y-colisión)
+8. [Entidades](#8-entidades)
+9. [Logros, estadísticas y marcador](#9-logros-estadísticas-y-marcador)
+10. [Editor de mapas (Debug)](#10-editor-de-mapas-debug)
+11. [Consola y notificaciones](#11-consola-y-notificaciones)
+12. [Modo demo](#12-modo-demo)
+13. [Recursos](#13-recursos)
+14. [Audio, localización y configuración](#14-audio-localización-y-configuración)
+15. [Convenciones y patrones recurrentes](#15-convenciones-y-patrones-recurrentes)
+16. [Guía de navegación: "si quieres tocar X, mira Y"](#16-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` (`director`, `debug`,
+  `global_events`), `rendering` (+ `sprite`, `sdl3gpu`), `input`, `resources`,
+  `audio`, `locale`.
+- **`source/game/`** — el juego concreto: `scenes/`, `gameplay/`, `entities/`,
+  `editor/`, `ui/`, `options.*`, `scene_manager.hpp`, `defaults.hpp`.
+- **`source/utils/`** — `delta_timer`, `easing_functions`, `utils`, `defines`.
+- **`source/external/`** — vendorizado: `fkyaml`, `stb_image`, `stb_vorbis`.
+
+Es el proyecto más grande de su familia: **138 ficheros C++, ~54.000 líneas**.
+
+**Ideas-fuerza que conviene interiorizar:**
+
+1. **Render paletizado por CPU**: `Surface` de 8 bits indexados + paleta, igual
+   filosofía que un motor retro clásico; la GPU solo escala y aplica post-FX
+   (§4).
+2. **Flujo por `SceneManager::current`** (variable global) + un único
+   `active_scene_` que el `Director` conmuta (§3).
+3. **El mundo son habitaciones** de 256×128 px en tiles de 8 px, con colisión
+   por superficies (suelos, paredes, rampas, cintas) y transición entre salas
+   contiguas (§7).
+4. Trae **editor de mapas** y **consola de comandos** integrados (solo Debug)
+   (§10, §11), un **sistema de logros** persistente (§9), y un **modo demo**
+   que es un *tour de habitaciones* (§12).
+
+```mermaid
+graph TD
+    SDL[SDL3 callbacks · main.cpp] --> DIR[Director]
+    DIR -->|SceneManager::current| SW{switchToActiveScene}
+    SW --> SCN["BootLoader / Logo / Title / Game / Demo / Ending…"]
+    SCN --> GAME["Game (Mode GAME/DEMO)"]
+    GAME --> ROOM[Room + colisión] & RL[room_loader]
+    GAME --> PLAYER[Player] & EM[enemy_manager] & IM[item_manager]
+    GAME --> CHV[Cheevos] & STT[Stats] & SCB[Scoreboard]
+    GAME -->|blit paletizado| SURF["Surface (8-bit indexed)"]
+    SURF -->|toARGBBuffer / copyToTexture| SCREEN[Screen]
+    SCREEN --> GPU["ShaderBackend PostFX/CrtPi"] --> WIN[Ventana]
+    SCREEN -.fallback.-> WIN
+    RES["Resource::Cache / List"] -.-> GAME & SCN
+    EDIT["MapEditor (Debug)"] -.-> GAME
+    CON[Console] -.-> GAME
+```
+
+---
+
+## 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.
+
+```cpp
+SDL_AppInit   → new Director();
+SDL_AppIterate→ Director::iterate();          // un frame
+SDL_AppEvent  → Director::handleEvent(event);
+SDL_AppQuit   → delete Director;
+```
+
+> ⚠️ **Discrepancia con el `CLAUDE.md`**: este describe un `Director::run()` con
+> un bucle `while (SceneManager::current != QUIT)`. **El código actual no es
+> así**: usa la API de callbacks de SDL3. El `Director` real
+> (`core/system/director.hpp`) expone `iterate()` y `handleEvent()`, no `run()`.
+
+### 2.2. El `Director`
+
+`source/core/system/director.{hpp,cpp}`. Mantiene **un solo
+`std::unique_ptr<Scene> active_scene_`** y un enum `current_scene_`. No guarda un
+puntero por escena (a diferencia de los proyectos hermanos): construye la escena
+bajo demanda en `switchToActiveScene()` (`director.cpp`).
+
+El constructor inicializa los subsistemas en orden: `Resource::List` (registro
+de assets desde `config/assets.yaml`), `Options`, `Audio`, `Screen`, `Input`,
+`Resource::Cache` (con `beginLoad()`), y arranca en la escena `BOOT_LOADER`.
+
+### 2.3. Arranque NO bloqueante
+
+`Resource::Cache` no se carga de golpe. El constructor deja la escena en
+`BOOT_LOADER` (una barra de progreso) y cada frame `Director::iterate()` llama a
+`Resource::Cache::get()->loadStep(50 /*ms*/)` (`director.cpp`): carga assets
+hasta agotar un presupuesto de 50 ms por frame, manteniendo ventana y eventos
+vivos. Cuando termina, `finishBoot()` inicializa lo que depende de los recursos
+(`Notifier`, `RenderInfo`, `Console`, `Cheevos`, `Locale`, en Debug `Debug` y
+`MapEditor`) y fija la escena destino (`LOGO` en release; en Debug, la que diga
+`debug.yaml` vía `Debug::getInitialScene()`).
+
+### 2.4. Gestión del tiempo
+
+**Time-based**: la escena `Game` posee un `DeltaTimer delta_timer_`
+(`utils/delta_timer.hpp`) y toda la física/animación consume `delta_time` en
+segundos. Las constantes de tiempo se documentan como "N frames a 66.67 fps →
+segundos" (p.ej. `BLACK_SCREEN_DURATION = 0.30F`, `game.hpp:46`).
+
+---
+
+## 3. Escenas y flujo de la aplicación
+
+### 3.1. La base `Scene` y el `SceneManager`
+
+`source/game/scenes/scene.hpp` es minimalista:
+
+```cpp
+class Scene {
+   public:
+    virtual void iterate() = 0;                       // un frame (update + render)
+    virtual void handleEvent(const SDL_Event&) = 0;   // un evento
+};
+```
+
+`source/game/scene_manager.hpp` define el flujo con **variables globales
+`inline`** en el namespace `SceneManager`:
+
+```cpp
+enum class Scene { BOOT_LOADER, LOGO, LOADING_SCREEN, TITLE, CREDITS,
+                   GAME, DEMO, GAME_OVER, ENDING, ENDING2, RESTART_CURRENT, QUIT };
+inline Scene current = Scene::BOOT_LOADER;
+inline Options options = Options::LOGO_TO_LOADING_SCREEN;
+inline Scene scene_before_restart = Scene::LOGO;
+```
+
+Cualquier escena solicita una transición asignando `SceneManager::current`.
+
+### 3.2. La conmutación
+
+`Director::switchToActiveScene()` (`director.cpp`):
+
+- `RESTART_CURRENT` es especial: restaura `scene_before_restart` (relanza la
+  escena que estaba activa).
+- `active_scene_.reset()` destruye la anterior (su destructor puede parar la
+  música, etc.).
+- Un `switch` construye la concreta: `BootLoader`, `Logo`, `LoadingScreen`,
+  `Title`, `Credits`, `Game(Mode::DEMO)`, `Game(Mode::GAME)`, `GameOver`,
+  `Ending`, `Ending2`.
+
+Nótese que **DEMO y GAME son la misma clase `Game`**, parametrizada por
+`Game::Mode` (§12).
+
+```mermaid
+graph LR
+    BOOT[BOOT_LOADER] --> LOGO --> LOADING[LOADING_SCREEN] --> TITLE
+    TITLE -->|jugar| GAME --> ENDING --> ENDING2 --> CREDITS
+    TITLE -->|attract| DEMO --> TITLE
+    GAME --> GAME_OVER --> TITLE
+    TITLE --> QUIT
+```
+
+---
+
+## 4. Renderizado: de la lógica al píxel
+
+El render es **paletizado por CPU**: se dibuja sobre superficies de 8 bits
+indexados y solo al final se sube a la GPU.
+
+### 4.1. `Surface`: 8 bits indexados + paleta
+
+`source/core/rendering/surface.hpp`. Una `Surface` guarda los píxeles como
+**índices `Uint8`** (`SurfaceData`) más una **`Palette` de 256 colores ARGB** y
+una **`SubPalette`** (remapeo de índices, identidad por defecto vía `std::iota`).
+
+Operaciones clave:
+- `render(...)` / `renderWithColorReplace(src, dst)` — blit con color
+  transparente y reemplazo de índice (para recolorear sprites/glifos).
+- `renderWithVerticalFade(...)` — disolución por hash 2D (cantos).
+- `fadePalette()` / `fadeSubPalette()` — fundidos manipulando la paleta.
+- `copyToTexture(...)` y **`toARGBBuffer(buffer)`** — vuelcan la surface a una
+  `SDL_Texture` o a un buffer ARGB externo.
+
+Sobre `Surface` se construyen los sprites (`core/rendering/sprite/`):
+`Sprite` → `AnimatedSprite` (frames `.yaml`) → `MovingSprite` (posición/velocidad)
+y `DissolveSprite` (transición). Texto: `text.*`. Efectos: `pixel_reveal.*`.
+Paletas: `palette_manager.*` (el juego permite **cambiar de paleta en caliente**;
+ver §5).
+
+### 4.2. `Screen` y la composición
+
+`source/core/rendering/screen.{hpp,cpp}`. Hay dos superficies/texturas:
+- **`game_surface_` / `game_texture_`** — el canvas de juego 256×192
+  (`SDL_TEXTUREACCESS_STREAMING`, ARGB8888; `screen.cpp:125`).
+- **`border_surface_` / `border_texture_`** — el borde/overscan alrededor del
+  canvas.
+
+El path de presentación (`Screen::render`, `screen.cpp:197`):
+- **Con backend GPU acelerado**: vuelca las superficies a buffers ARGB
+  (`toARGBBuffer`) y los sube al `shader_backend_` (`uploadPixels`), que renderiza
+  con el shader activo.
+- **Sin backend** (fallback): `copyToTexture` + `SDL_RenderTexture` de
+  `game_texture_` y `border_texture_` a la ventana.
+
+El backend vive en `core/rendering/sdl3gpu/` (interfaz `shader_backend.hpp`). Dos
+shaders: **PostFX** y **CrtPi** (scanlines, curvatura, máscara, etc.), GLSL en
+`data/shaders/` compilados a SPIR-V (`spv/*_spv.h`), o Metal (MSL) en macOS
+(`sdl3gpu/msl/`). En Emscripten (`NO_SHADERS`) se fuerza la ruta clásica.
+
+```mermaid
+graph TD
+    OBJ["room, player, enemies, items, HUD…"] -->|blit índices| GS["game_surface_ (256×192, 8-bit)"]
+    BORDER["borde / overscan"] --> BS[border_surface_]
+    GS -->|toARGBBuffer / copyToTexture| SCREEN[Screen]
+    BS --> SCREEN
+    SCREEN -->|uploadPixels| SHADER["ShaderBackend (PostFX / CrtPi)"]
+    SHADER --> WIN[Ventana]
+    SCREEN -.fallback SDL_Renderer.-> WIN
+```
+
+---
+
+## 5. Entrada
+
+### 5.1. `Input`
+
+`source/core/input/input.{hpp,cpp}` + `input_types.*` — abstracción de teclado y
+mando bajo un enum `InputAction`. Las vinculaciones se aplican desde `Options`
+(`Input::applyKeyboardBindingsFromOptions()` /
+`applyGamepadBindingsFromOptions()`, `director.cpp`). `mouse.*` gestiona el ratón
+(usado sobre todo por el editor).
+
+### 5.2. Hotkeys globales
+
+`source/core/input/global_inputs.{hpp,cpp}` traduce eventos a acciones de sistema
+(`global_inputs.cpp`):
+- **Ventana/vídeo**: fullscreen, zoom ±, integer scale, vsync, info.
+- **Shaders**: toggle; con **Ctrl** → siguiente shader, con **Shift** →
+  siguiente preset.
+- **Paletas**: siguiente / anterior (`NEXT_PALETTE`/`PREVIOUS_PALETTE`), y orden
+  de paleta — una seña de identidad de este juego (paleta intercambiable).
+- **Borde** (overscan) toggle, **consola** toggle, **EXIT**.
+- En `GAME`, EXIT vuelve a `TITLE`; el `QUIT` global sale del programa.
+
+Cuando la **consola está activa**, `EXIT`/`ACCEPT` se redirigen a ella en vez de
+a la escena (`global_inputs.cpp:231`).
+
+---
+
+## 6. Lógica del juego: la escena `Game`
+
+`source/game/scenes/game.{hpp,cpp}` es la escena de gameplay. Hereda de `Scene` y
+coordina habitación, jugador, enemigos, ítems, marcador, estadísticas y logros.
+
+### 6.1. FSM de la escena
+
+`Game::State` (`game.hpp:28`): `PLAYING → BLACK_SCREEN → GAME_OVER →
+FADE_TO_ENDING → POST_FADE_ENDING`. Cada estado tiene su `updateX`/`renderX`;
+`transitionToState()` cambia de estado y resetea los timers. El modo
+(`Game::Mode::GAME` o `DEMO`) condiciona el comportamiento.
+
+### 6.2. El frame
+
+`Game::iterate()` calcula el delta con el `DeltaTimer`, llama a `update()`
+(input + lógica + colisiones + cambio de sala) y a `render()`. El render del
+estado `PLAYING` va directo a las superficies; los fades de fin de juego usan un
+`game_backbuffer_surface_`.
+
+### 6.3. Qué gestiona
+
+- **Habitación activa** (`std::shared_ptr<Room> room_`) y cambio de sala al tocar
+  un borde (`changeRoom`, `checkPlayerIsOnBorder`; §7).
+- **Jugador** (`Player`), con muerte (`killPlayer`, `BLACK_SCREEN`), y la "Jail"
+  que restaura vidas con el tiempo (`checkRestoringJail`, `JAIL_RESTORE_INTERVAL`).
+- **Colisiones**: jugador↔enemigos (`checkPlayerAndEnemies`) y jugador↔ítems
+  (`checkPlayerAndItems`).
+- **Progresión**: `RoomTracker` (salas visitadas), `Stats`, `Scoreboard`, fin de
+  juego (`checkEndGame`) y secuencias de **ending** (fades a `ENDING`/`ENDING2`).
+- **Logros**: `checkSomeCheevos`, `checkEndGameCheevos` (§9).
+
+---
+
+## 7. Habitaciones y colisión
+
+`source/game/gameplay/room.{hpp,cpp}` modela cada sala. Geometría: tiles de
+**8 px**, mapa de **32×16** tiles (256×128 px). Los tipos de tile
+(`Room::Tile`) son `EMPTY, WALL, PASSABLE, SLOPE_L, SLOPE_R, KILL, ANIMATED`
+(`room.hpp:32`).
+
+### 7.1. Datos de sala
+
+`Room::Data` (`room.hpp:42`) se carga de YAML (vía `RoomLoader`,
+`Room::loadYAML`). Contiene número/nombre, colores (fondo, borde, ítems),
+**salas contiguas** (`upper_room`, `lower_room`, `left_room`, `right_room` →
+navegación tipo *metroidvania*), tileset, el `tile_map` embebido, y las listas
+de enemigos e ítems.
+
+### 7.2. Colisión por superficies
+
+La colisión no es AABB simple contra tiles, sino consultas de **superficies**:
+`checkRightSurfaces`, `checkLeftSurfaces`, `checkTopSurfaces`,
+`checkBottomSurfaces`, `checkAutoSurfaces` (cintas), más rampas
+(`checkLeftSlopes`/`checkRightSlopes`, `getSlopeHeight`, `getSlopeAtPoint`) y
+cintas transportadoras (`checkConveyorBelts`, `conveyor_belt_direction_`). El
+jugador aporta puntos de colisión finos (8 `collider_points_` + `under_left_foot_`
+/ `under_right_foot_`; `player.hpp:147`). Los tiles `KILL` matan al jugador.
+
+Subobjetos de `Room`: `CollisionMap` (datos de colisión), `TilemapRenderer`
+(dibujo del tilemap), `EnemyManager` e `ItemManager` (ciclo de vida de enemigos
+e ítems de la sala). `RoomTracker` (`gameplay/room_tracker.*`) registra las salas
+visitadas.
+
+---
+
+## 8. Entidades
+
+`source/game/entities/`:
+
+- **`Player`** (`player.hpp`) — física *time-based* con `JUMP_VELOCITY = -80`,
+  `GRAVITY_FORCE = 155.6` px/s² (`player.hpp:42`). FSM de estados (IDLE/WALKING/
+  JUMPING/…), colisión por 8 puntos + "pies", controladores de sonido de salto y
+  caída (`JumpSoundController`/`FallSoundController`), y un `SpawnData` para
+  reaparecer (también usado al cambiar de sala conservando velocidad).
+- **`Enemy`** (`enemy.hpp`) — enemigos con datos (`Enemy::Data`), colisión AABB,
+  gestionados por `EnemyManager` (`gameplay/enemy_manager.*`).
+- **`Item`** (`item.hpp`) — coleccionables (`Item::Data`), gestionados por
+  `ItemManager` (`gameplay/item_manager.*`) y rastreados por `ItemTracker`.
+
+No hay una clase base de entidad común con polimorfismo profundo: cada tipo tiene
+su `update`/`render`/colisión y su *manager* dedicado dentro de la `Room`.
+
+---
+
+## 9. Logros, estadísticas y marcador
+
+- **`Cheevos`** (`source/game/gameplay/cheevos.{hpp,cpp}`) — singleton del sistema
+  de logros. `unlock(id)`, `setUnobtainable(id)`, `getTotalUnlockedAchievements()`;
+  estado **persistido en `cheevos.bin`** (`loadFromFile`/`saveToFile`). La escena
+  `Game` llama a `checkSomeCheevos`/`checkEndGameCheevos`, y el `Notifier` muestra
+  el logro en pantalla (§11).
+- **`Stats`** (`gameplay/stats.*`) — diccionario de estadísticas de partida
+  (`initStats`).
+- **`Scoreboard`** (`gameplay/scoreboard.*`) — datos y dibujo del marcador
+  (`Scoreboard::Data` se comparte por `shared_ptr` con la sala y el editor).
+- **`ItemTracker`** / **`RoomTracker`** — progreso de ítems recogidos y salas
+  visitadas.
+
+---
+
+## 10. Editor de mapas (Debug)
+
+`source/game/editor/` — **solo se compila en `_DEBUG`** (todo el header de
+`MapEditor` está bajo `#ifdef _DEBUG`, `map_editor.hpp:3`). Es un editor de
+habitaciones *in-game* completo, integrado con la escena `Game` y con la consola.
+
+### 10.1. `MapEditor` (singleton)
+
+`map_editor.hpp`. Se entra con `enter(room, player, room_path, scoreboard_data)`
+sobre la sala viva. Funcionalidades:
+- **Pintado de tiles** con *brush* (`brush_tile_`, `ERASER_BRUSH`, `painting_`),
+  preview bajo el cursor y rejilla opcional (`renderGrid`, `settings_.grid`).
+- **Drag & drop** de jugador, enemigos (posición inicial y *bounds* de patrulla)
+  e ítems (`DragTarget`, `DragState`, `handleMouseDown/Up`, `updateDrag`), con
+  *snap* a rejilla.
+- **Edición de propiedades** de enemigos, ítems y de la sala
+  (`setEnemyProperty`, `setItemProperty`, `setRoomProperty`, colores, color de
+  fondo…), invocables tanto por teclas como por **comandos de consola**.
+- **Gestión de salas**: crear (`createNewRoom(direction)`), borrar (`deleteRoom`),
+  con conexión a las salas contiguas.
+- **Persistencia**: `autosave()` + `room_saver.*` escribe el YAML de la sala;
+  `revert()` restaura desde el backup del nodo YAML (`yaml_backup_`).
+
+### 10.2. Subcomponentes del editor
+
+- **`TilePicker`** (`tile_picker.*`) — selector visual de tiles del tileset
+  (`openTilePicker`).
+- **`MiniMap`** (`mini_map.*`) — minimapa de salas con conexiones, colores
+  configurables (`setMiniMapBg`/`setMiniMapConn`).
+- **`EditorStatusBar`** (`editor_statusbar.*`) — barra de estado con info de
+  edición (`updateStatusBarInfo`).
+- **`RoomSaver`** (`room_saver.*`) — serialización de la sala a YAML preservando
+  campos no editados.
+
+El editor guarda/restaura estado del juego al entrar/salir (invencibilidad,
+overlay de info) para no contaminar la partida.
+
+---
+
+## 11. Consola y notificaciones
+
+### 11.1. `Console`
+
+`source/game/ui/console.{hpp,cpp}` — consola de comandos *in-game* (singleton),
+con estética de terminal verde sobre `Surface` propia. Características
+(`console.hpp`):
+- Panel animado (`Status` HIDDEN/RISING/ACTIVE/VANISHING), efecto *typewriter*,
+  cursor parpadeante.
+- **Historial** navegable (flechas), **autocompletado por TAB** (`tab_matches_`),
+  *word-wrap* por ancho en píxeles.
+- **`CommandRegistry`** (`console_commands.{hpp,cpp}`): metadatos (desde YAML) +
+  *handlers* C++. Los comandos cubren depuración del juego y **pilotan el editor
+  de mapas** (`setEnemyProperty`, `addItem`, `setRoomProperty`, etc.).
+- **Scopes** (`setScope`/`getScope`): filtran qué comandos y autocompletados
+  están disponibles según el contexto (p.ej. dentro del editor).
+- `on_toggle` notifica a la escena cuando se abre/cierra (para pausar input de
+  juego).
+
+### 11.2. `Notifier`
+
+`source/game/ui/notifier.{hpp,cpp}` — cola de notificaciones en pantalla (logros
+desbloqueados, cambios de opción…). Se inicializa en `finishBoot()` y el `Screen`
+las pinta como overlay (`renderNotifications`). El overlay de FPS/driver es
+`core/rendering/render_info.*` (toggle por hotkey).
+
+---
+
+## 12. Modo demo
+
+> **El modo demo de este juego NO es reproducción de input grabado.** Es un
+> **tour automático de habitaciones** (escaparate de niveles).
+
+La escena `Game` construida con `Game::Mode::DEMO` recorre una **lista curada de
+salas** y va cambiando cada `DEMO_ROOM_DURATION = 6.0F` segundos
+(`game.hpp:48`):
+
+```cpp
+// game.cpp — demoInit()
+demo_ = DemoData(0.0F, 0, {"04.yaml","54.yaml","20.yaml","09.yaml",
+                           "05.yaml","11.yaml","31.yaml","44.yaml"});
+// demoCheckRoomChange(): acumula delta_time y, al llegar a 6s,
+// avanza demo_.room_index y changeRoom(...). Al agotar la lista, vuelve.
+```
+
+No hay ficheros `.bin` ni `DemoKeys`: la demo simplemente pasea por las
+habitaciones para la pantalla de atracción. La salida de la demo devuelve a la
+escena de título.
+
+---
+
+## 13. Recursos
+
+- **`Resource::List`** (`core/resources/resource_list.*`) — registro de rutas de
+  asset cargado de **`config/assets.yaml`**, con consulta `get(filename)` O(1).
+- **`Resource::Cache`** (`core/resources/resource_cache.*`) — caché de surfaces,
+  música, sonidos y datos de animación (`getSurface`, `getMusic`,
+  `getAnimationData`). Carga **incremental** vía `beginLoad()` + `loadStep(ms)`
+  (§2.3), con una FSM interna de etapas (`LoadStage`).
+- **Pack y fallback**: `resource_pack.*` + `resource_loader.*` + `resource_helper.*`
+  sirven desde **`resources.pack`** (release) o el filesystem (desarrollo).
+- **Formatos**: GIF (gráficos + paletas, `core/rendering/gif.*`); `.yaml` para
+  animaciones y para las salas (`data/room/`); `.pal` para paletas
+  (`data/palette/`); OGG/WAV para audio; GLSL para shaders.
+
+---
+
+## 14. Audio, localización y configuración
+
+- **Audio**: `core/audio/audio.*` (singleton, música y SFX) + `audio_adapter.*`
+  sobre **`jail_audio`** (`jail_audio.hpp`), wrapper SDL3 *first-party* con
+  `stb_vorbis` para OGG.
+- **Localización**: `core/locale/locale.*` carga las cadenas de `data/locale/`.
+  En release el locale vive dentro del pack (`Locale::initFromContent`);
+  `Options::language` selecciona el idioma.
+- **Configuración**: `source/game/options.{hpp,cpp}` mantiene las opciones
+  (ventana, vídeo+shaders, audio, idioma, controles, presets PostFX/CrtPi) y las
+  persiste; `source/game/defaults.hpp` reúne las constantes de gameplay y layout
+  (canvas 256×192, tamaños de tile, colores de paleta). En Debug, `debug.yaml`
+  (`core/system/debug.*`) fija la escena inicial.
+- **Builds condicionales**: `_DEBUG` (editor, consola, overlay), `RELEASE_BUILD`,
+  `__EMSCRIPTEN__` (locale/paths especiales, `NO_SHADERS`), y la selección de
+  shaders por plataforma (SPIR-V vs Metal).
+
+---
+
+## 15. Convenciones y patrones recurrentes
+
+- **Singletons con `init()`/`destroy()`/`get()`**: `Screen`, `Input`, `Audio`,
+  `Resource::Cache`, `Resource::List`, `Cheevos`, `Console`, `Notifier`,
+  `RenderInfo`, `MapEditor`, `Debug`. Se crean/destruyen en orden explícito desde
+  el `Director` (no por destructores estáticos).
+- **Render paletizado por CPU** (`Surface` de 8 bits + `Palette`/`SubPalette`),
+  con recoloreado por reemplazo de índice y paletas intercambiables en caliente.
+- **Flujo por variable global** (`SceneManager::current`) + un único
+  `active_scene_`.
+- **Time-based**: todo consume `delta_time` (`DeltaTimer`); las constantes citan
+  su equivalencia en frames a 66.67 fps.
+- **`#ifdef _DEBUG`** envuelve editor, consola de propiedades, overlays y atajos
+  de depuración — ausentes en release.
+- **Comentarios** en español/valenciano; muchos `#include` con comentario
+  "// Para X" (estilo IWYU).
+- **El `CLAUDE.md` puede ir por detrás del código** (caso `Director::run()` vs
+  callbacks). Ante duda, **manda el código**.
+
+---
+
+## 16. Guía de navegación: "si quieres tocar X, mira Y"
+
+| Quiero… | Empieza por… |
+|---|---|
+| Entender el arranque | `core/system/director.cpp` (ctor, `iterate`, `finishBoot`) |
+| Cambiar el flujo de pantallas | `game/scene_manager.hpp` + `Director::switchToActiveScene` |
+| Añadir/editar una pantalla | `game/scenes/` (hereda de `Scene`) + un `case` en `switchToActiveScene` |
+| La barra de carga / arranque | `Resource::Cache::beginLoad/loadStep` + `scenes/boot_loader.*` |
+| Cómo se dibuja todo | `core/rendering/surface.*` + `Screen::render` (`screen.cpp`) |
+| Sprites / animaciones | `core/rendering/sprite/` + `data/**/*.yaml` (animaciones) |
+| Paletas / recoloreado | `core/rendering/palette_manager.*` + `Surface` |
+| Shaders / CRT | `core/rendering/sdl3gpu/` + `data/shaders/` |
+| Controles / hotkeys | `core/input/input.*` + `global_inputs.cpp` |
+| **Lógica de partida** | `game/scenes/game.cpp` (`updatePlaying`, FSM `State`) |
+| Habitaciones / colisión | `game/gameplay/room.*` (`check*Surfaces`, slopes, cintas) |
+| Cargar una sala | `game/gameplay/room_loader.*` + `data/room/*.yaml` |
+| El jugador (física) | `game/entities/player.*` (`JUMP_VELOCITY`, `GRAVITY_FORCE`, colisión por puntos) |
+| Enemigos / ítems | `game/entities/{enemy,item}.*` + `gameplay/{enemy,item}_manager.*` |
+| Logros | `game/gameplay/cheevos.*` (+ `cheevos.bin`) |
+| Marcador / estadísticas | `game/gameplay/{scoreboard,stats,item_tracker,room_tracker}.*` |
+| **Editor de mapas** | `game/editor/map_editor.*` (+ `tile_picker`, `mini_map`, `room_saver`) |
+| **Consola / comandos** | `game/ui/console.*` + `console_commands.*` |
+| Notificaciones / FPS | `game/ui/notifier.*` + `core/rendering/render_info.*` |
+| Modo demo (tour) | `Game::demoInit/demoCheckRoomChange` (`game.cpp`) |
+| Cargar un recurso | `core/resources/resource_cache.*` + `resource_list.*` + `config/assets.yaml` |
+| Audio | `core/audio/audio.*` + `jail_audio.hpp` |
+| Idiomas | `core/locale/locale.*` + `data/locale/` |
+| Opciones / constantes | `game/options.*`, `game/defaults.hpp` |
+| Escena inicial en Debug | `core/system/debug.*` + `debug.yaml` |
+
+---
+
+*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.*