475 lines
22 KiB
Markdown
475 lines
22 KiB
Markdown
# Arquitectura de **Aventures en Egipte (AEE)**
|
||
|
||
> Guía de orientación para un desarrollador nuevo en el proyecto.
|
||
>
|
||
> Cada afirmación está anclada a código real: se cita el fichero (y, cuando
|
||
> ayuda, la función o el número de línea) que la respalda. Donde no he
|
||
> encontrado algo, lo digo explícitamente en lugar de inventarlo.
|
||
>
|
||
> **Aventures en Egipte** es un juego de aventura/plataformas retro (el
|
||
> protagonista "Sam" explora pirámides esquivando momias y recogiendo
|
||
> tesoros), escrito en C++ + SDL3. Resolución de juego **320×200**. El rasgo
|
||
> que más condiciona el código es que está **en plena migración** desde un
|
||
> motor legacy propio ("Jail") hacia C++ moderno (ver
|
||
> [§3](#3-el-motor-legacy-jail)). Los comentarios del código están en
|
||
> valenciano/español; este documento está en castellano.
|
||
>
|
||
> Existe además un `docs/scenes-migration-plan.md` (histórico) sobre la
|
||
> migración del sistema de escenas; aquí se documenta el **estado actual** del
|
||
> código, no el plan.
|
||
|
||
---
|
||
|
||
## Índice
|
||
|
||
1. [Visión general](#1-visión-general)
|
||
2. [Punto de entrada y bucle principal](#2-punto-de-entrada-y-bucle-principal)
|
||
3. [El motor legacy "Jail"](#3-el-motor-legacy-jail)
|
||
4. [Escenas y máquina de estados](#4-escenas-y-máquina-de-estados)
|
||
5. [Renderizado: de la lógica al píxel](#5-renderizado-de-la-lógica-al-píxel)
|
||
6. [Entrada](#6-entrada)
|
||
7. [Gameplay: `ModuleGame` y entidades](#7-gameplay-modulegame-y-entidades)
|
||
8. [Sistema de escenas cinemáticas](#8-sistema-de-escenas-cinemáticas)
|
||
9. [Recursos](#9-recursos)
|
||
10. [Audio y localización](#10-audio-y-localización)
|
||
11. [Configuración y persistencia](#11-configuración-y-persistencia)
|
||
12. [Modo demo / IA](#12-modo-demo--ia)
|
||
13. [Convenciones y patrones recurrentes](#13-convenciones-y-patrones-recurrentes)
|
||
14. [Guía de navegación: "si quieres tocar X, mira Y"](#14-guía-de-navegación-si-quieres-tocar-x-mira-y)
|
||
|
||
---
|
||
|
||
## 1. Visión general
|
||
|
||
El árbol `source/` separa **motor** y **juego**, pero con una particularidad:
|
||
el motor tiene **dos generaciones** conviviendo (legacy "Jail" + capas nuevas).
|
||
|
||
- **`source/core/jail/`** — el **motor legacy "Jail"** (APIs C planas): `Jg`
|
||
(jgame), `Jd8` (jdraw8), `Ji` (jinput), `Jf` (jfile). En modernización (§3).
|
||
- **`source/core/`** (resto) — capas **nuevas**: `rendering` (`Screen`,
|
||
`Overlay`, `Text`, `Menu`, `sdl3gpu`), `input`, `system` (`Director`),
|
||
`resources`, `audio`, `locale`.
|
||
- **`source/game/`** — el juego: gameplay legacy en la raíz (`modulegame`,
|
||
`prota`, `momia`, `engendro`, `bola`, `mapa`, `marcador`, `info`, `sprite`) y
|
||
el sistema de **escenas** nuevo en `scenes/`.
|
||
- **`source/utils/`** — `easing`, `utils`.
|
||
- **`source/external/`** — vendorizado (stb, fkyaml).
|
||
|
||
~117 ficheros C++, ~40.000 líneas.
|
||
|
||
**El `CLAUDE.md` define una frontera explícita "Original vs New Code"** (§79):
|
||
`core/jail/` y `game/*.cpp` son *legacy en modernización* (modificar con
|
||
cuidado, preservando comportamiento); `core/rendering`, `core/input`,
|
||
`utils/`, `options/defines/defaults` son *código nuevo*. Interiorizar esa
|
||
frontera es lo primero para no romper invariantes del juego original.
|
||
|
||
**Ideas-fuerza:**
|
||
|
||
1. Un solo hilo, **tick-based**, vía callbacks de SDL3 (§2).
|
||
2. El render es **software paletizado 8-bit** (`Jd8`, 320×200) que al final se
|
||
convierte a ARGB y pasa por shaders GPU (§5).
|
||
3. El flujo de pantallas es una **máquina de estados** apoyada en
|
||
`Info::ctx.num_piramide`, con un `SceneRegistry` que va sustituyendo
|
||
cinemáticas legacy por escenas nuevas (§4).
|
||
|
||
```mermaid
|
||
graph TD
|
||
SDL[SDL3 callbacks · main.cpp] --> DIR[Director]
|
||
DIR -->|game_state_ + Info::ctx| DISP{createNextScene}
|
||
DISP -->|==0| MG["ModuleGame (gameplay)"]
|
||
DISP -->|==1| REG["SceneRegistry::tryCreate(num_piramide)"]
|
||
REG --> CINE["intro / banner / slides / mort / secreta / credits…"]
|
||
MG --> MAPA[Mapa] & PROTA[Prota] & MOMIA[Momia] & BOLA[Bola] & MARC[Marcador]
|
||
DIR --> INP["KeyConfig / GlobalInputs / Gamepad / KeyRemap / Mouse"]
|
||
MG -->|dibuja índices| JD8["Jd8 (8-bit 320×200)"]
|
||
CINE --> JD8
|
||
JD8 -->|JD8_Flip → ARGB| SCREEN[Screen]
|
||
OVL[Overlay] --> SCREEN
|
||
SCREEN --> GPU["sdl3gpu PostFX / CrtPi / upscale"] --> WIN[Ventana]
|
||
RES["Resource::Cache / List"] -.-> MG & CINE
|
||
```
|
||
|
||
---
|
||
|
||
## 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 (clave
|
||
para el port a Emscripten). `SDL_AppInit` monta todo y `SDL_AppIterate` llama a
|
||
`Director::iterate()`.
|
||
|
||
El arranque en `SDL_AppInit` inicializa, en orden: carpeta de config (`Jf`),
|
||
sistema de recursos (`resources.pack` + fallback en Debug/WASM), `Options`,
|
||
`KeyConfig`, `Locale`, presets de shaders, y luego el **motor**: `Jg::init`,
|
||
`Screen::init`, `Jd8::init`, `Audio::init`, `Overlay::init`, `Menu::init`,
|
||
`Resource::List`/`Cache` (con `beginLoad()`), y `Director::init` + `setup()`.
|
||
|
||
### 2.2. El `Director`
|
||
|
||
`source/core/system/director.{hpp,cpp}`. Es el **orquestador singleton, único
|
||
hilo del runtime** (sin fibers, mutex ni condition variables; el comentario de
|
||
`director.hpp:11` lo subraya). Posee el estado de escena como miembros:
|
||
`current_scene_` (`std::unique_ptr<Scenes::Scene>`), `game_state_`,
|
||
`last_tick_ms_`, y dos buffers de frame `[320*200]` (`game_frame_`,
|
||
`presentation_buffer_`).
|
||
|
||
Cada `iterate()` (modelo documentado en `CLAUDE.md:161`):
|
||
|
||
```
|
||
Gamepad/KeyRemap/GlobalInputs/Mouse::update
|
||
JA_Update() ← bombeo de audio
|
||
if (!paused_) {
|
||
if (scene && (scene->done() || JG_Quitting())) game_state_ = scene->nextState(); scene.reset();
|
||
if (!scene) scene = createNextScene(); scene->onEnter(); ← ModuleGame o SceneRegistry
|
||
JI_Update()
|
||
scene->tick(now - last_tick_ms_)
|
||
JD8_Flip() ← índices → ARGB
|
||
memcpy → game_frame
|
||
}
|
||
memcpy game_frame → presentation_buffer
|
||
Overlay::render(presentation_buffer)
|
||
Screen::present(presentation_buffer)
|
||
SDL_Delay(frame_target - elapsed) ← cap de FPS
|
||
```
|
||
|
||
### 2.3. Tiempo, pausa y salida
|
||
|
||
Las escenas reciben `delta_ms` real (time-based). El gameplay (`ModuleGame`)
|
||
gatea su `Update()` a 10 ms fijos vía `Jg::shouldUpdate()` (ticker del motor
|
||
legacy, ya sin *yield*). La **pausa** (F11) simplemente salta el bloque de
|
||
`tick()`: el overlay y el present siguen, re-presentando el último frame
|
||
congelado. La **salida** se solicita con `requestQuit()` (doble ESC o
|
||
`SDL_QUIT`) y `requestRestart()` hace un reinicio suave (para audio, resetea
|
||
`Info::ctx`, vuelve a la intro).
|
||
|
||
---
|
||
|
||
## 3. El motor legacy "Jail"
|
||
|
||
`source/core/jail/` es el sustrato heredado, **APIs C planas con prefijo por
|
||
subsistema** (sin clases), que se está convirtiendo progresivamente a C++
|
||
idiomático manteniendo los nombres externos estables para no romper los
|
||
*call sites* (`CLAUDE.md:92`). Es el rasgo más distintivo del proyecto.
|
||
|
||
| Subsistema | Fichero | Qué hace |
|
||
|---|---|---|
|
||
| **`Jg`** (jgame) | `jail/jgame.*` | *Timing*: init/finalize, fixed-timestep (`Jg::shouldUpdate()` a 10 ms), flag de salida (`JG_Quitting`). |
|
||
| **`Jd8`** (jdraw8) | `jail/jdraw8.*` | **Renderer software 8-bit paletizado**, buffer de pantalla 320×200 (`Jd8::Surface = Uint8*`), blits con *color key*, fades no bloqueantes (máquina de estados), `flip()` (paleta→ARGB) → `Screen::present`. |
|
||
| **`Ji`** (jinput) | `jail/jinput.*` | Sondeo de teclado, *debounce*, códigos *cheat*. Filtra las teclas de GUI del juego y llama a `GlobalInputs`/`Mouse` cada update. |
|
||
| **`Jf`** (jfile) | `jail/jfile.*` | I/O de ficheros: carpeta `data/` o pack; carpeta de config en `~/.config/jailgames/aee/`. |
|
||
|
||
### `Jd8` en detalle (el corazón del render)
|
||
|
||
`jail/jdraw8.hpp`. API representativa:
|
||
- `using Surface = Uint8*` (búfer de índices de paleta), `using Palette = Color*`.
|
||
- `loadSurface`/`newSurface`/`freeSurface`, `loadPalette`/`setScreenPalette`.
|
||
- Blits: `blit`, `blitCK` (con *color key*/transparencia), `blitCKCut`,
|
||
`blitCKScroll`, `blitToSurface`/`blitCKToSurface` (blit entre surfaces).
|
||
- `fillRect`/`fillSquare`/`putPixel`/`getPixel`.
|
||
- **Fade no bloqueante** (`fadeStart*` + `fadeTickStep` que devuelve `true` al
|
||
acabar): sustituye los `JD8_FadeOut` bloqueantes del código original.
|
||
- `flip()` convierte el buffer indexado + paleta a ARGB y delega en
|
||
`Screen::present`; `getFramebuffer()` devuelve el `Uint32*` resultante.
|
||
|
||
> Mentalidad clave: **todo el dibujo del juego ocurre sobre índices de 8 bits**
|
||
> en un buffer 320×200; el color real y los shaders entran solo al final.
|
||
|
||
---
|
||
|
||
## 4. Escenas y máquina de estados
|
||
|
||
### 4.1. La base `Scene`
|
||
|
||
`source/game/scenes/scene.hpp` (`namespace Scenes`):
|
||
|
||
```cpp
|
||
class Scene {
|
||
public:
|
||
virtual void onEnter() {} // una vez, antes del primer tick
|
||
virtual void tick(int delta_ms) = 0; // no bloquea, NO llama a Jd8::flip
|
||
virtual auto done() const -> bool = 0;
|
||
virtual auto nextState() const -> int { return 1; } // 1=siguiente, 0=gameplay, -1=salir
|
||
};
|
||
```
|
||
|
||
El `Director` hace avanzar la escena hasta que `done()` es cierto, consulta
|
||
`nextState()` y construye la siguiente.
|
||
|
||
### 4.2. El despachador: `game_state_` + `Info::ctx`
|
||
|
||
`Director::createNextScene()` decide la siguiente escena:
|
||
- `game_state_ == 0` → `new ModuleGame` (gameplay puro, §7).
|
||
- `game_state_ == 1` → `SceneRegistry::tryCreate(Info::ctx.num_piramide)`
|
||
(`game/scenes/scene_registry.hpp`): un mapa `int → factory` que devuelve la
|
||
escena registrada para ese estado, o `nullptr` para caer al **path legacy**.
|
||
Replica el viejo `ModuleSequence::Go`, incluido el *redirect* heredado
|
||
`num_piramide == 6 && diners < 200 → 7` (`CLAUDE.md:104`).
|
||
- `game_state_ == -1` → salir.
|
||
|
||
### 4.3. `Info::ctx`: el estado del juego
|
||
|
||
`source/game/info.hpp` — `Info::GameContext ctx` (singleton inline) es la fuente
|
||
de verdad del estado:
|
||
|
||
```cpp
|
||
struct GameContext {
|
||
int num_piramide, num_habitacio, diners, diamants, vida, momies, engendros;
|
||
bool nou_personatge, pepe_activat;
|
||
void reset();
|
||
};
|
||
```
|
||
|
||
`num_piramide` es la pieza central: hace de **selector tanto de cinemáticas como
|
||
de nivel jugable**. El `SceneRegistry` va migrando cada estado de cinemática a
|
||
una `Scene` nueva; lo que no esté registrado cae a legacy. Por eso el registro
|
||
"crece" a medida que avanza la modernización.
|
||
|
||
```mermaid
|
||
graph LR
|
||
SC[Scene activa] -->|done()| NS{nextState}
|
||
NS -->|0| MG[ModuleGame]
|
||
NS -->|1| REG["SceneRegistry(num_piramide)"]
|
||
NS -->|-1| QUIT[salir]
|
||
MG -->|muta Info::ctx| REG
|
||
REG --> SC
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Renderizado: de la lógica al píxel
|
||
|
||
El pipeline tiene dos mitades: **software paletizado** (`Jd8`) y **GPU**
|
||
(`Screen` + shaders).
|
||
|
||
### 5.1. Software: dibujar índices
|
||
|
||
Escenas y `ModuleGame` dibujan sobre el buffer `screen` de `Jd8` (índices 8-bit,
|
||
320×200) con blits y *color key*. `JD8_Flip()` aplica la paleta y produce un
|
||
buffer ARGB (formato **ABGR8888**: `0xFF000000 + R + (G<<8) + (B<<16)`;
|
||
`CLAUDE.md:220`).
|
||
|
||
### 5.2. `Overlay`: sobre el buffer ARGB
|
||
|
||
`source/core/rendering/overlay.*` pinta **directamente sobre el buffer ARGB**
|
||
antes de presentar: notificaciones (slide-in), info de render animada (4
|
||
segmentos), indicador de **PAUSA** y la lógica de **doble-ESC para salir**.
|
||
|
||
### 5.3. `Screen`: a la ventana (GPU o fallback)
|
||
|
||
`source/core/rendering/screen.*` (singleton). Doble camino
|
||
(`Screen::present`, `CLAUDE.md:204`):
|
||
- **GPU con shaders** (primario, `sdl3gpu/`): sube los píxeles a una textura
|
||
de escena 320×200; opcionalmente *upscale*/**supersampling** (3×/6×/9× con
|
||
*downscale* Lanczos) y **estiramiento 4:3** fusionado en el *upscale*; luego
|
||
el shader **PostFX** o **CRT-Pi** (con presets) a la *swapchain* con
|
||
*letterboxing*.
|
||
- **GPU sin shaders**: subida limpia a la *swapchain*.
|
||
- **Fallback**: `SDL_UpdateTexture` + `SDL_RenderPresent` (`SDL_Renderer`).
|
||
|
||
`Screen` gestiona ventana, fullscreen, zoom, 4:3, *integer scaling*, VSync, FPS.
|
||
Apoyos de UI: `Text` (fuentes bitmap `.fnt`+`.gif` sobre el buffer ARGB, con
|
||
*clipping* 2D) y `Menu` (menú flotante de opciones con navegación por páginas,
|
||
animaciones y captura de teclas para *remapping*).
|
||
|
||
---
|
||
|
||
## 6. Entrada
|
||
|
||
Toda la entrada de UI/sistema converge en **`KeyConfig`** como fuente única de
|
||
verdad de las teclas (`source/core/input/key_config.*`): carga
|
||
`data/input/keys.yaml` (F1–F10 GlobalInputs + F11 pausa + F12 menú) y aplica
|
||
*overrides* del usuario; expone `scancode("id")`, `isGuiKey(sc)` (para que el
|
||
`Director` no propague teclas de UI al juego), y persiste solo lo que difiere
|
||
del default.
|
||
|
||
- **`GlobalInputs`** (`global_inputs.*`) — mapea las F-keys a acciones de
|
||
presentación (zoom, fullscreen, shaders, 4:3, supersampling, filtro, render
|
||
info, pausa, menú). Tabla completa en `CLAUDE.md:139`.
|
||
- **`Gamepad`** (`gamepad.*`) — primer mando con *hot-plug* y notificación;
|
||
D-pad/stick → flechas virtuales; botones frontales → Enter sintético;
|
||
SELECT → menú, START → pausa. Carga `gamecontrollerdb.txt`.
|
||
- **`KeyRemap`** (`key_remap.*`) — cada frame copia `Options::keys_game.*` al
|
||
estado virtual de scancodes estándar (UP/DOWN/LEFT/RIGHT). Permite remapear el
|
||
movimiento **sin tocar el código legacy** de `prota.cpp`/`mapa.cpp`.
|
||
- **`Mouse`** (`mouse.*`) — auto-oculta el cursor tras 3 s de inactividad.
|
||
|
||
> Reparto deliberado: las teclas de **UI/sistema** viven en `KeyConfig`
|
||
> (`keys.yaml`); las de **movimiento del jugador** en `Options::keys_game`
|
||
> (`config.yaml`, sección `controls:`).
|
||
|
||
---
|
||
|
||
## 7. Gameplay: `ModuleGame` y entidades
|
||
|
||
`source/game/modulegame.{hpp,cpp}` es la **escena de gameplay puro**
|
||
(`game_state_ == 0`). Hereda de `Scenes::Scene` y sustituye el viejo `Go()`
|
||
bloqueante por un `tick()`. Tres fases internas (`Phase`):
|
||
`FADING_IN → PLAYING → FADING_OUT → DONE` (`modulegame.hpp:46`), con un
|
||
`PaletteFade` para los fundidos no bloqueantes.
|
||
|
||
Coordina las entidades del nivel, todas con una `Jd8::Surface gfx_` compartida:
|
||
- **`Mapa`** (`game/mapa.*`) — la sala/pirámide: tiles con contenido
|
||
(`CONTE_RES`/`CONTE_TRESOR`/`CONTE_FARAO`…), colisión y dibujo del escenario.
|
||
- **`Prota`** (`game/prota.*`) — el protagonista "Sam" (hereda de `Sprite`),
|
||
movimiento y colisión.
|
||
- **`Momia`** (`game/momia.*`) — enemigo que persigue al `Prota` (recibe
|
||
`Prota*`); variante `dimoni` (demonio).
|
||
- **`Bola`** (`game/bola.*`) — bola/roca que interactúa con el `Prota`.
|
||
- **`Engendro`** (`game/engendro.*`) — entidad generada (su `update()` devuelve
|
||
`bool`); `Info::ctx.engendros` lleva la cuenta.
|
||
- **`Marcador`** (`game/marcador.*`) — el marcador (vidas, dinero, diamantes),
|
||
lee del `Prota`/`Info::ctx`.
|
||
|
||
`ModuleGame::tick()` hace `draw()` (a `screen`, sin `flip` — lo hace el
|
||
`Director`) y `update()` (gateado por `Jg::shouldUpdate`). Cuando la partida
|
||
acaba (`final_ != 0`: muerte o cambio de sala), `applyFinalTransitions()` muta
|
||
`Info::ctx` y `nextState()` devuelve el estado siguiente.
|
||
|
||
Todas las entidades de gameplay derivan de **`Sprite`** (`game/sprite.*`),
|
||
clase base con `draw()`/`update()` sobre `Jd8`.
|
||
|
||
---
|
||
|
||
## 8. Sistema de escenas cinemáticas
|
||
|
||
Las pantallas no jugables (`game_state_ == 1`) son `Scene`s registradas en el
|
||
`SceneRegistry`. Las concretas viven en `source/game/scenes/`: `boot_loader`
|
||
(carga incremental, §9), `banner`, `intro`, `intro_new_logo`, `intro_sprites`,
|
||
`slides`, `menu` (`menu_scene`), `mort` (secuencia de muerte), `secreta`
|
||
(pantalla secreta) y `credits`.
|
||
|
||
Sobre ellas hay un **conjunto de utilidades de animación** reutilizables —el
|
||
andamiaje "cinematográfico" del juego—:
|
||
- **`Timeline`** (`scenes/timeline.*`) — secuenciación temporal de eventos.
|
||
- **`FrameAnimator`** (`scenes/frame_animator.*`) — animación por fotogramas.
|
||
- **`SpriteMover`** (`scenes/sprite_mover.*`) — movimiento interpolado de
|
||
sprites (con `easing`).
|
||
- **`PaletteFade`** (`scenes/palette_fade.*`) — fundidos por paleta no
|
||
bloqueantes (también usado por `ModuleGame`).
|
||
- **`SurfaceHandle`** (`scenes/surface_handle.*`) — propiedad RAII de una
|
||
`Jd8::Surface` (las escenas poseen sus assets y los liberan en el destructor).
|
||
- **`scene_utils`** — helpers compartidos.
|
||
|
||
---
|
||
|
||
## 9. Recursos
|
||
|
||
- **`Resource::List`** (`core/resources/resource_list.*`) — registro de rutas de
|
||
asset desde **`data/config/assets.yaml`**, con consulta O(1).
|
||
- **`Resource::Cache`** (`core/resources/resource_cache.*`) — caché de assets con
|
||
**carga incremental**: `beginLoad()` (en `SDL_AppInit`) + la escena
|
||
`BootLoaderScene` que el `Director` arranca automáticamente mientras
|
||
`Resource::Cache::isLoadDone()` sea falso (una barra de progreso con la
|
||
ventana viva).
|
||
- **Pack y fallback**: `resource_pack.*` + `resource_helper.*` sirven desde
|
||
**`resources.pack`** (formato propio "AEE1", `CLAUDE.md:237`); en release
|
||
nativo es estricto (solo pack), en Debug/WASM hay *fallback* a `data/`.
|
||
- **Formatos**: GIF/paletas para gráficos (vía `Jd8`), fuentes `.fnt`+`.gif`,
|
||
OGG/WAV para audio, GLSL para shaders.
|
||
|
||
---
|
||
|
||
## 10. Audio y localización
|
||
|
||
- **Audio**: `core/audio/audio.*` (singleton, aplica `Options::audio`) sobre
|
||
**`jail_audio`** (`Ja`, `jail/jail_audio.hpp` / `core/audio/jail_audio.hpp`),
|
||
mezcla propia con streams SDL3 (OGG vía `stb_vorbis`, WAV). `JA_Update()` se
|
||
bombea cada frame desde el `Director`; pausa/resume con F11.
|
||
- **Localización**: `core/locale/locale.*` — mapa plano clave→cadena cargado de
|
||
YAML (`data/locale/ca.yaml`, valenciano por defecto). Claves con notación de
|
||
puntos (`menu.items.zoom`); si falta una clave, devuelve la propia clave
|
||
(fallback visible para depurar).
|
||
|
||
---
|
||
|
||
## 11. Configuración y persistencia
|
||
|
||
- **`Options`** (`source/game/options.*`) — namespace con globals `inline` y
|
||
carga/guardado YAML. Structs: `KeysGame` (movimiento), `Video`, `RenderInfo`,
|
||
`Audio`, `Window`, `Game`, `PostFXPreset`, `CrtPiPreset`.
|
||
- **`defines.hpp`** — constantes del juego: `Texts::WINDOW_TITLE`/`VERSION`,
|
||
`GameScreen::WIDTH=320`/`HEIGHT=200`/`BUFFER_SIZE=64000`.
|
||
- **`defaults.hpp`** — valores por defecto (`Defaults::KeysGame`, `Video`,
|
||
`Audio`, `Window`, `Game`).
|
||
- **`KeyConfig`** — teclas de UI (§6).
|
||
|
||
Ficheros persistentes en `~/.config/jailgames/aee/` (`CLAUDE.md:224`):
|
||
`config.yaml` (vídeo/audio/ventana/render_info/controles), `keys.yaml`
|
||
(overrides de UI), `postfx.yaml` (6 presets), `crtpi.yaml` (4 presets), y en
|
||
Debug `debug.yaml` (estado inicial de gameplay para pruebas).
|
||
|
||
**Builds condicionales**: `NDEBUG` (release: pack estricto, sin `debug.yaml`),
|
||
`__EMSCRIPTEN__` (WASM: fuerza ventana/zoom/4:3, mantiene fallback de assets,
|
||
sin persistencia MEMFS).
|
||
|
||
---
|
||
|
||
## 12. Modo demo / IA
|
||
|
||
**No he encontrado un modo demo, *attract mode* ni IA de demostración en este
|
||
proyecto.** Lo he buscado explícitamente: la única aparición de "replay" es un
|
||
comentario en `jail_audio.hpp` sobre re-reproducción de pistas de audio, sin
|
||
relación con un modo demo.
|
||
|
||
A diferencia de los proyectos hermanos `coffee_crisis` (playback de input
|
||
grabado) o `jaildoctors_dilemma` (tour de habitaciones), aquí el flujo de
|
||
atracción —si lo hubiera— se construiría sobre el `SceneRegistry` y las escenas
|
||
cinemáticas (§8), pero **hoy no existe** tal cosa implementada.
|
||
|
||
---
|
||
|
||
## 13. Convenciones y patrones recurrentes
|
||
|
||
- **Frontera legacy/nuevo** (`CLAUDE.md:79`): lo más importante. `core/jail/` y
|
||
`game/*.cpp` son legacy en modernización (preservar comportamiento); el resto
|
||
es código nuevo. Los assets de `data/gfx`/`data/music` son **intocables**.
|
||
- **Namespaces legacy abreviados** `Jg`/`Jd8`/`Ji`/`Jf`/`Ja` (APIs C planas),
|
||
con nombres externos estables durante la transición.
|
||
- **Single-thread, tick-based**: sin fibers/mutex; las escenas no bloquean ni
|
||
llaman a `Jd8::flip` (lo hace el `Director`).
|
||
- **Render paletizado 8-bit** sobre buffer 320×200; color y shaders solo al
|
||
final (`JD8_Flip` → `Screen`).
|
||
- **Singletons con `init()`/`destroy()`/`get()`** (`Screen`, `Audio`,
|
||
`Director`, `Menu`, `Overlay`, `Resource::*`, `Jd8`/`Jg` como módulos),
|
||
creados/destruidos en orden explícito en `SDL_AppInit`/`SDL_AppQuit`.
|
||
- **Máquina de estados por `Info::ctx.num_piramide`** + `SceneRegistry` que
|
||
migra cinemáticas legacy a `Scene`s nuevas de forma incremental.
|
||
- **Fades y timing no bloqueantes**: lo que antes eran bucles bloqueantes
|
||
(`JD8_FadeOut`) ahora son máquinas de estados que avanzan un paso por tick.
|
||
- **Comentarios** en valenciano/español; muchos `#include` con comentario de
|
||
justificación (estilo IWYU).
|
||
|
||
---
|
||
|
||
## 14. Guía de navegación: "si quieres tocar X, mira Y"
|
||
|
||
| Quiero… | Empieza por… |
|
||
|---|---|
|
||
| Entender el arranque | `source/main.cpp` (`SDL_AppInit`) + `core/system/director.cpp` |
|
||
| El bucle / orden del frame | `Director::iterate()` (`director.cpp`) |
|
||
| Tocar el motor de dibujo | `core/jail/jdraw8.*` (`Jd8`) |
|
||
| Timing / fixed-timestep | `core/jail/jgame.*` (`Jg::shouldUpdate`) |
|
||
| Añadir/editar una pantalla | `game/scenes/` (hereda de `Scenes::Scene`) + `SceneRegistry::registerScene` |
|
||
| Cómo se decide la siguiente pantalla | `Director::createNextScene` + `Info::ctx.num_piramide` + `scene_registry.*` |
|
||
| El estado del juego | `game/info.hpp` (`Info::ctx`) |
|
||
| **Gameplay** | `game/modulegame.*` (fases) + entidades `prota/momia/bola/engendro/mapa/marcador` |
|
||
| Animaciones de cinemáticas | `game/scenes/{timeline,frame_animator,sprite_mover,palette_fade,surface_handle}.*` |
|
||
| Composición final / shaders | `core/rendering/screen.*` + `sdl3gpu/` + presets `postfx.yaml`/`crtpi.yaml` |
|
||
| Overlays (notificaciones/PAUSA/info) | `core/rendering/overlay.*` |
|
||
| Texto / menú | `core/rendering/text.*`, `core/rendering/menu.*` |
|
||
| Teclas de UI / F1–F12 | `core/input/key_config.*` + `global_inputs.*` + `data/input/keys.yaml` |
|
||
| Remapear movimiento | `core/input/key_remap.*` + `Options::keys_game` |
|
||
| Mando | `core/input/gamepad.*` |
|
||
| Cargar recursos / barra de carga | `core/resources/resource_cache.*` + `resource_list.*` + `scenes/boot_loader_scene.*` |
|
||
| Audio | `core/audio/audio.*` + `jail_audio.hpp` (`Ja`) |
|
||
| Idiomas | `core/locale/locale.*` + `data/locale/` |
|
||
| Opciones / constantes | `game/options.*`, `game/defines.hpp`, `game/defaults.hpp` |
|
||
| Carpetas y pack | `core/jail/jfile.*` (`Jf`) + `core/resources/resource_pack.*` |
|
||
|
||
---
|
||
|
||
*Documento generado a partir de la lectura directa del código en el commit
|
||
actual de la rama `main`. Si algo aquí no cuadra con el código, el código
|
||
manda: actualiza este documento.*
|