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