@@ -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×
> 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×
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×
(`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×
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× ** tiles (256×
(`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× `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.*
JailDesigner