@@ -0,0 +1,642 @@
# Arquitectura de **Coffee Crisis Arcade Edition**
> 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.
>
> **Coffee Crisis Arcade Edition** es un *shooter* arcade cooperativo de 2
> jugadores escrito en **C++20 sobre SDL3**: los jugadores defienden el café
> de globos gigantes. Apunta a Windows, Linux, macOS (Intel/Apple Silicon),
> Raspberry Pi, Anbernic y web (Emscripten). 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. [Secciones y flujo de la aplicación ](#3-secciones-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 clase `Game` ](#6-lógica-del-juego-la-clase-game )
7. [Entidades y managers de gameplay ](#7-entidades-y-managers-de-gameplay )
8. [Modo demo y attract mode ](#8-modo-demo-y-attract-mode )
9. [Recursos ](#9-recursos )
10. [Audio ](#10-audio )
11. [Configuración, parámetros y constantes ](#11-configuración-parámetros-y-constantes )
12. [Localización ](#12-localización )
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 ** :
- **`source/core/` ** — motor genérico: `system` (arranque, secciones, demo,
eventos globales), `rendering` (+ `sdl3gpu` , `sprite` ), `input` , `resources` ,
`audio` , `locale` .
- **`source/game/` ** — el juego concreto: `scenes` (las secciones), `gameplay`
(managers), `entities` (jugador, globos, balas, ítems…), `ui` , y `options` .
- **`source/utils/` ** — `color` , `param` , `utils` , `defines` .
- **`source/external/` ** — vendorizado: `nlohmann/json` , `fkyaml` , `stb_image` ,
`stb_vorbis` .
Los `#include` son **absolutos respecto a `source/` ** (p.ej.
`#include "core/audio/audio.hpp"` ); CMake añade un único `-I.../source`
(ver `CLAUDE.md` ). ~150 ficheros C++, ~32.000 líneas.
**Cuatro ideas-fuerza que conviene interiorizar: **
1. **El flujo de la aplicación se conduce con una variable global **
(`Section::name` ), no con objetos de transición. El `Director` reacciona a
sus cambios (§3).
2. **El render usa texturas GPU vía `SDL_Renderer` ** dibujadas sobre una
* render-target texture * , con post-procesado opcional vía un backend SDL3
GPU. No es un blitter de software (§4).
3. **El gameplay se organiza con managers/pools ** (`BalloonManager` ,
`BulletManager` , `StageManager` ) coordinados por una clase `Game` muy grande
(§6, §7).
4. **Sí hay modo demo ** (*attract mode*): es **reproducción de input grabado ** ,
no IA (§8).
``` mermaid
graph TD
SDL[SDL3 callbacks · main.cpp] --> DIR[Director]
DIR -->|lee Section::name| ST{handleSectionTransition}
ST --> SEC["Section activa (Logo/Intro/Title/Game/…)"]
DIR --> GE[GlobalEvents] --> INP[Input] & SVC[ServiceMenu]
SEC --> GAME[Game]
GAME --> BM[BalloonManager] & BLM[BulletManager] & STG[StageManager]
GAME --> PL[Players] -->|Input::Action| INP
GAME --> DEMO["Demo (playback de input grabado)"] -.->|setInput| PL
GAME -->|SDL_RenderTexture| CV["game_canvas_ (render target)"]
CV -->|RenderReadPixels → uploadPixels| SB[ShaderBackend SDL3 GPU] --> WIN[Ventana]
RES["Resource / Asset"] -.-> GAME & SEC
```
---
## 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. SDL
llama a cuatro funciones, todas delegando en el `Director` :
``` cpp
SDL_AppInit → * appstate = new Director ( argc , argv ) ; // main.cpp:15
SDL_AppIterate → Director : : iterate ( ) ; // un frame
SDL_AppEvent → Director : : handleEvent ( event ) ; // un evento
SDL_AppQuit → delete Director ;
```
### 2.2. El `Director`
`source/core/system/director.{hpp,cpp}` es el orquestador. Mantiene **un
`unique_ptr` por cada sección** (`preload_` , `logo_` , `intro_` , `title_` ,
`game_` , …) de los que **solo uno está vivo ** a la vez (`director.hpp:60` ).
**Constructor (`director.cpp:82`) ** : fija la semilla aleatoria, crea la carpeta
de sistema (`jailgames/coffee_crisis_arcade_edition` ), decide la sección
inicial según el build (`RECORDING` → GAME; `_DEBUG` → lee `debug.yaml` ; Release
→ LOGO) y llama a `init()` .
* * `init()` (`director.cpp:131` )** inicializa en orden: `Asset` (índice de
ficheros), sistema de recursos (`resources.pack` , con/ sin * fallback * a disco
según build), `Input` , `Options` (config.yaml, controllers.json, presets de
shaders), parámetros y * scores * , `Lang` , `Screen` , `Audio` y `Resource` .
### 2.3. Arranque NO bloqueante (PRELOAD incremental)
Un detalle importante: si el modo de carga es `PRELOAD` , **no se cargan todos
los recursos de golpe**. `init()` redirige el arranque a la sección `PRELOAD`
guardando el destino real en `Section::post_preload` (`director.cpp:191` ):
``` cpp
Section : : post_preload = Section : : name ; // destino real
Section : : name = Section : : Name : : PRELOAD ; // mientras tanto, barra de progreso
Resource : : get ( ) - > beginLoad ( ) ;
```
Cada frame, `Director::iterate()` (`director.cpp:489` ) llama a
`Resource::loadStep(50 /*ms*/)` : carga recursos hasta agotar un presupuesto de
50 ms por frame, manteniendo la ventana y el bucle vivos. Cuando termina,
`finishBoot()` inicializa lo que depende de los recursos (`ServiceMenu` ,
`Notifier` , singletons de `Screen` ) y salta a `post_preload` .
### 2.4. Orden del frame y gestión del tiempo
`Director::iterate()` (`director.cpp:489` ):
``` mermaid
sequenceDiagram
participant SDL
participant Dir as Director::iterate
participant Sec as Section activa
SDL->>Dir: SDL_AppIterate
alt boot_loading_
Dir->>Dir: Resource::loadStep(50ms) → finishBoot() al terminar
end
Dir->>Dir: handleSectionTransition() (destruye/crea sección)
Dir->>Sec: iterate() (la sección hace su propio update+render)
```
El tiempo es **time-based ** : cada sección calcula su propio `delta_time` . En
`Game` es `calculateDeltaTime()` (`game.hpp:210` ), usado en todos los `update` .
Los eventos llegan por separado vía `Director::handleEvent` →
`GlobalEvents::handle` + reenvío a la sección activa (`director.cpp:539` ).
### 2.5. Reinicio en caliente
Igual que su proyecto hermano, soporta reinicio real vía `execv`
(`Director::relaunch()` , `director.cpp:254` ): la sección `RESET` (p.ej. tras
F10 o cambio de idioma) reemplaza el proceso por sí mismo; si no se puede
(Emscripten, `argv` inválido), cae a un `reset()` interno que recarga recursos y
vuelve a `LOGO` .
---
## 3. Secciones y flujo de la aplicación
### 3.1. Variables globales de estado
`source/core/system/section.hpp` define el estado del flujo como **variables
globales `inline` ** en el namespace `Section` :
``` cpp
inline Name name = Name : : RESET ; // sección a la que ir
inline Name post_preload = Name : : LOGO ; // destino tras PRELOAD
inline Options options = Options : : NONE ; // 1P/2P/BOTH, timeouts, etc.
inline AttractMode attract_mode = AttractMode : : TITLE_TO_DEMO ;
```
`Name` enumera: `RESET, PRELOAD, LOGO, INTRO, TITLE, GAME, HI_SCORE_TABLE,
GAME_DEMO, INSTRUCTIONS, CREDITS, QUIT` . Cualquier parte del código cambia el
flujo simplemente asignando `Section::name = ...` .
### 3.2. La transición de secciones
`Director::handleSectionTransition()` (`director.cpp:390` ) se ejecuta cada
frame:
- Si `Section::name == RESET` : intenta `relaunch()` ; si vuelve, hace el reset
interno.
- Si `Section::name == last_built_section_name_` : no hace nada (ya está viva).
- Si cambió: `resetActiveSection()` (libera todos los `unique_ptr` ) y un
`switch` construye la nueva sección. Para `GAME` traduce `Section::options`
a `Player::Id` (1P/2P/BOTH); para `GAME_DEMO` construye `Game(..., DEMO_ON)`
con jugador aleatorio (`director.cpp:448` ).
Cada sección (`source/game/scenes/` ) es autónoma y expone `iterate()` +
`handleEvent()` . `Director::iterate` despacha al puntero vivo con una cadena de
`if/else if` (`director.cpp:517` ).
``` mermaid
graph LR
RESET --> PRELOAD --> LOGO --> INTRO --> TITLE
TITLE -->|jugar| GAME --> HI_SCORE_TABLE --> TITLE
TITLE -->|timeout / attract| GAME_DEMO --> TITLE
TITLE -->|attract alterno| LOGO
TITLE --> INSTRUCTIONS & CREDITS
```
### 3.3. Attract mode
El * attract mode * alterna entre mostrar la demo y volver al logo. En
`title.cpp:51` el Title, al construirse, mira `Section::attract_mode` y fija su
`next_section_` (a `GAME_DEMO` o `LOGO` ), **invirtiendo el modo ** para la
próxima vez. Cuando el Title agota su * timeout * sin input, salta a esa sección
(ver §8).
---
## 4. Renderizado: de la lógica al píxel
A diferencia de un blitter de software, aquí **los sprites son texturas GPU **
compuestas por `SDL_Renderer` , y el post-procesado se hace en un backend SDL3
GPU.
### 4.1. `Texture` y la jerarquía de sprites
- `source/core/rendering/texture.hpp` — `Texture` envuelve un `SDL_Texture*` ,
con `loadFromFile` , `createBlank` , `setAsRenderTarget` y un `render(x, y,
clip, zoom, angle, …)` . Es la unidad de dibujo.
- `source/core/rendering/sprite/` — jerarquía sobre `Sprite`
(`sprite.hpp:13` ), que guarda **varias texturas ** (`textures_` ), un
`sprite_clip_` y posición/zoom:
- `AnimatedSprite` — animación por fotogramas (clip que avanza).
- `MovingSprite` — con velocidad.
- `PathSprite` — sigue rutas precalculadas (`Path` ).
- `SmartSprite` — sprite con lógica propia (p.ej. el café que salta al ser
golpeado).
- `CardSprite` — variante para "cartas"/paneles.
El `Player` , por ejemplo, compone un `AnimatedSprite player_sprite_` y un
`power_sprite_` para el aura (`player.hpp:250` ).
### 4.2. Dos render-targets
Hay **dos texturas de destino ** encadenadas:
1. * * `Game::canvas_` ** — textura de la * zona de juego * . `Game::fillCanvas()`
(`game.cpp` ) fija el render-target a `canvas_` y dibuja, **en este orden ** :
`background → smart_sprites → items → balloons → tabe → players → bullets →
path_sprites` . Ese orden es el z-order del playfield.
2. * * `Screen::game_canvas_` ** — textura de * pantalla completa * (ARGB8888 a la
resolución de juego; `screen.cpp:92` , `SDL_TEXTUREACCESS_TARGET` ).
`Game::render()` hace `screen_->start()` (que pone el target en
`game_canvas_` ), copia `canvas_` sobre él, y encima dibuja **scoreboard ** y
los **fades ** de entrada/salida; finalmente `screen_->render()` .
### 4.3. Post-procesado y presentación
`Screen::renderPresent()` (`screen.cpp:156` ) decide cómo llega a la ventana:
- **Con backend GPU acelerado**: lee los píxeles de `game_canvas_` con
`SDL_RenderReadPixels` a un `pixel_buffer_` CPU, los sube al backend
(`shader_backend_->uploadPixels(...)` ) y este los renderiza con el shader
activo (`shader_backend_->render()` ).
- **Sin backend** (fallback): vuelca `game_canvas_` directamente a la ventana
con `SDL_RenderTexture` .
El backend vive en `source/core/rendering/sdl3gpu/` (SDL3 GPU API; shaders
SPIR-V compilados offline desde GLSL en `data/shaders/` , embebidos en cabeceras
`spv/` /`msl/` ). Hay dos shaders seleccionables, **PostFX ** y **CrtPi ** , con
presets en `postfx.yaml` /`crtpi.yaml` (`screen.cpp:382` ). El build `NO_SHADERS`
(Anbernic) desactiva todo el pipeline de shaders.
``` mermaid
graph TD
OBJ["background, balloons, players, bullets…"] -->|SDL_RenderTexture| CANVAS["Game::canvas_ (zona de juego)"]
CANVAS -->|copiar| GC["Screen::game_canvas_ (pantalla)"]
SB2[scoreboard] --> GC
FADE[fades de entrada/salida] --> GC
GC -->|RenderReadPixels → uploadPixels| SHADER["ShaderBackend (PostFX/CrtPi)"]
SHADER --> WIN[Ventana]
GC -.fallback sin GPU.-> WIN
```
### 4.4. Efectos de pantalla
`Screen` integra efectos globales sobre la presentación: **shake **
(`ShakeEffect` , desplaza el rect), **flash ** (`FlashEffect` , tinte temporal) y
**attenuate ** (atenuación) — todos definidos como structs internos en
`screen.hpp:108` – `205` . Las transiciones entre estados usan
`source/core/rendering/fade.*` (cuadrícula de cuadros).
---
## 5. Entrada
### 5.1. `Input` singleton
`source/core/input/input.hpp` . Centraliza teclado y mandos bajo un enum de
**acciones ** (`Input::Action` , alias de `InputAction` ). El mapeo por defecto
vive en structs:
- **`Keyboard` ** (`input.hpp:54` ): flechas = mover; **Q/W/E ** = disparar
izquierda/centro/derecha; Enter = START; F12 = SERVICE; P = PAUSE; ESC = EXIT;
**F1– ** = ventana/vídeo/audio/idioma/reset/info.
- **`Gamepad` ** (`input.hpp:99` ): cruceta = mover; WEST/NORTH/EAST = disparar;
START/ BACK = start/service. Cada mando es un `shared_ptr<Gamepad>` con su
propio `bindings` , nombre y * path * .
La consulta principal es `checkAction(action, repeat, check_keyboard, gamepad)`
(`input.hpp:168` ). Hay además detección de ejes y triggers como botones, y
gestión de configuraciones de mando persistidas (`gamepad_config_manager` ,
`controllers.json` ).
### 5.2. Eventos globales y hotkeys
- `source/core/system/global_events.cpp` — `GlobalEvents::handle(event)` trata
lo común a cualquier sección: `SDL_EVENT_QUIT` , * resize * , render target reset,
hot-plug de mandos (con notificación tras `markStartupComplete` ), el toggle
del menú de servicio y el ratón.
- `source/core/input/global_inputs.cpp` — hotkeys de sistema, despachadas con
un mapa acción→lambda (`global_inputs.cpp:187` ): fullscreen, zoom ±, audio,
autofire, idioma (CHANGE_LANG → `Section::RESET` , reinicia), VSync, integer
scale, info; más PostFX/shader/preset. **F10/RESET ** pone `Section::name =
RESET` (reinicio) y **ESC/EXIT ** pone `QUIT` .
### 5.3. Cómo llega la entrada a un jugador
Dentro de `Game` , `checkInput()` → `handlePlayersInput()` →
`handleNormalPlayerInput(player)` consulta `Input` y traduce a
`player->setInput(Input::Action)` y disparos (`handleFireInput` ). El `Player`
sabe si usa teclado o un mando concreto (`uses_keyboard_` , `gamepad_` ;
`player.hpp:217` ). En modo demo, esta misma vía se alimenta de datos grabados
(§8).
---
## 6. Lógica del juego: la clase `Game`
`source/game/scenes/game.{hpp,cpp}` es la sección de gameplay y la clase más
grande del proyecto. Coordina jugadores, globos, balas, ítems, fases,
puntuación y efectos.
### 6.1. FSM de la partida
`Game::State` (`game.hpp:75` ): `FADE_IN → ENTERING_PLAYER →
SHOWING_GET_READY_MESSAGE → PLAYING → COMPLETED / GAME_OVER` . `checkState()`
(`game.cpp` ) detecta fin de juego (`stage_manager_->isGameCompleted()` ) o game
over (`allPlayersAreGameOver()` ); `setState()` hace la transición.
### 6.2. El frame de `Game`
``` cpp
void Game : : iterate ( ) { // game.cpp
const float DELTA_TIME = calculateDeltaTime ( ) ;
checkInput ( ) ;
update ( DELTA_TIME ) ;
render ( ) ;
}
void Game : : update ( float dt ) {
screen_ - > update ( dt ) ;
Audio : : update ( ) ;
updateDemo ( dt ) ; // no-op si no es demo
updateGameStates ( dt ) ; // dispatch por State
fillCanvas ( ) ; // dibuja la zona de juego en canvas_
}
```
`updateGameStates` despacha a un `updateGameState<Estado>` por cada valor de la
FSM (`game.hpp:218` ).
### 6.3. Sistemas que orquesta
`Game` posee (vía `unique_ptr` ) los managers y objetos del nivel
(`game.hpp:136` ):
- **`StageManager` ** — progresión por "poder": cada fase necesita
`power_to_complete` ; el juego se completa al acumular el poder total. También
define umbrales de **amenaza ** (`menace` ) por fase. Implementa `IStageInfo`
(`stage.hpp:51` ), interfaz mínima que se inyecta a jugador y globos.
- **`BalloonManager` ** — despliega formaciones (`deployRandomFormation` ),
globos hijos al explotar uno, * power balls * , ajusta velocidad
(`Balloon::GAME_TEMPO` ) y calcula la amenaza en pantalla (§7).
- **`BulletManager` ** — pool de balas; las colisiones se resuelven con
**callbacks ** que registra `Game` (`setBalloonCollisionCallback` ,
`setTabeCollisionCallback` , `setOutOfBoundsCallback` ; `bullet_manager.hpp:49` ),
manteniendo la lógica de juego dentro de `Game` .
- **`Background` **, * * `Fade` × * * `Tabe` ** (enemigo especial volador),
* * `Scoreboard` **, * * `PauseManager` **.
- Listas de `Item` (power-ups y puntos), `SmartSprite` y `PathSprite` .
### 6.4. Mecánicas destacadas
- **Ítems / power-ups** (`game.hpp:268` ): café (toque extra),
máquina de café (power-up), * power ball * , reloj (= **detener el tiempo ** ,
`enableTimeStopItem` ), e ítems de puntos. La probabilidad de soltar ítem la
decide `dropItem()` con * odds * configurables (`Helper` , `game.hpp:100` ).
- **Sistema de amenaza** (`updateMenace` /`setMenace` ): si la amenaza cae por
debajo de un umbral, se generan más globos.
- **Multijugador**: `players_` es un `vector<shared_ptr<Player>>` (1 o 2). Un
`players_draw_list_` separado mantiene el z-order de dibujo
(`buildPlayerDrawList` , `sendPlayerToBack` /`bringPlayerToFront` ;
`game.hpp:338` ).
- **Récords**: al perder con buena puntuación, el jugador entra en
`ENTERING_NAME` (`enter_name.*` , `manage_hiscore_table.*` ).
---
## 7. Entidades y managers de gameplay
`source/game/entities/` :
- **`Player` ** (`player.hpp` ) — la entidad más compleja. Hereda de
`AnimatedSprite` . Tiene **tres ejes de estado ** independientes:
`walking_state_` , `firing_state_` y `playing_state_` (`player.hpp:266` ). El
disparo usa un **sistema de dos líneas ** : una funcional (cooldown, `canFire` )
y otra visual (animaciones `NORMAL→AIMING→RECOILING→THREAT_POSE` ,
`player.hpp:296` ). Soporta power-up, invulnerabilidad con parpadeo, * continue *
y entrada de nombre. Puede controlarse por teclado o por un `Gamepad`
concreto.
- **`Balloon` ** (`balloon.hpp` ) — el enemigo básico; al explotar puede crear
globos hijos. `Balloon::GAME_TEMPO` define velocidades por progreso.
- **`Bullet` ** (`bullet.hpp` ) — proyectil con tipo (UP/LEFT/RIGHT) y color
(según power-up del jugador).
- **`Item` ** — power-ups y objetos de puntos que caen.
- **`Explosions` ** — efectos de explosión (lo posee `BalloonManager` ).
- **`Tabe` ** — enemigo/objeto especial volador con su propia lógica de impacto.
`source/game/gameplay/` contiene los **managers y sistemas ** (no entidades en
sí): `BalloonManager` , `BulletManager` , `StageManager` , `Difficulty` ,
`Scoreboard` , `balloon_formations` (lee `formations.txt` ), `cooldown` ,
`enter_name` , `manage_hiscore_table` , `game_logo` .
El patrón general aquí **no es un `EntityManager` polimórfico único ** (como en
el proyecto hermano), sino **managers especializados por tipo ** + listas
homogéneas en `Game` , con **callbacks ** para cruzar responsabilidades sin
acoplar (caso de `BulletManager` ).
---
## 8. Modo demo y attract mode
> **A diferencia de muchos juegos, aquí el modo demo SÍ existe — pero NO es
> IA.** Es **reproducción de input pregrabado**.
### 8.1. Formato de los datos
`source/core/system/demo.hpp` : cada fotograma de demo es un `DemoKeys` con seis
banderas (`left` , `right` , `no_input` , `fire` , `fire_left` , `fire_right` ). Una
demo es un `vector<DemoKeys>` de `TOTAL_DEMO_DATA = 2000` fotogramas. Hay tres
ficheros: `data/demo/demo{1,2,3}.bin` , leídos por `loadDemoDataFromFile`
(`demo.cpp:11` ).
### 8.2. Reproducción
Cuando `Game` se construye con `DEMO_ON` (sección `GAME_DEMO` ), `initDemo()`
(`game.cpp` ) carga todas las demos del `Asset` y **asigna una a cada jugador de
forma aleatoria** (`shuffle` ), elige una fase de inicio al azar, da cafés
aleatorios, pone los marcadores en modo `DEMO` y silencia los globos. Luego cada
frame, `demoHandlePlayerInput()` lee el fotograma actual y lo inyecta por la
**misma vía de input que un humano ** :
``` cpp
// game.cpp — demoHandlePlayerInput
const auto & demo_data = demo_data_vec . at ( demo_ . index % demo_data_vec . size ( ) ) ;
if ( demo_data . left = = 1 ) player - > setInput ( Input : : Action : : LEFT ) ;
else if ( demo_data . right = = 1 ) player - > setInput ( Input : : Action : : RIGHT ) ;
. . .
if ( demo_data . fire = = 1 ) handleFireInput ( player , Bullet : : Type : : UP ) ;
```
No hay toma de decisiones: el jugador "demo" repite exactamente las pulsaciones
grabadas. `demoHandlePassInput()` permite **salir ** con cualquier botón,
volviendo a `TITLE` y dejando armado el siguiente attract (`TITLE_TO_DEMO` ).
### 8.3. Attract mode
El Title alterna `TITLE_TO_DEMO` ↔ `TITLE_TO_LOGO` (`title.cpp:51` ): tras su
* timeout * , una vez lanza la demo y la siguiente vuelve al logo, en bucle de
atracción típico de recreativa.
### 8.4. Grabación y autoplay
- **`#ifdef RECORDING` ** (`demo.cpp:43` , `game.hpp:349` ): build especial que
arranca directamente en GAME y **graba ** las pulsaciones a un `.bin` con
`saveDemoFile` . Así se generan las demos.
- **`autoplay` ** (debug): en `_DEBUG` , `debug_config.autoplay` permite alimentar
datos de demo a los jugadores en una partida normal (`game.hpp:354` ,
`initDemo` ).
---
## 9. Recursos
### 9.1. `Resource` (singleton)
`source/core/resources/resource.hpp` . Cachea por nombre texturas, música,
sonidos, ficheros de texto/fuentes, animaciones y **datos de demo **
(`getDemoData` ). Dos modos (`LoadingMode` ):
- **`PRELOAD` ** — carga incremental al arranque con `beginLoad()` +
`loadStep(budget_ms)` + `renderProgress()` (la sección Preload pinta la
barra). Es el modo por defecto.
- **`LAZY_LOAD` ** — carga bajo demanda (seleccionable vía `debug.yaml` ).
### 9.2. `Asset` y el pack
`source/core/resources/asset.*` mantiene el **índice de ficheros ** a partir del
manifiesto `data/config/assets.txt` (`director.cpp:296` ) y valida que no falte
ninguno (`Asset::check()` ). La lectura física pasa por
`ResourceHelper::loadFile` , que sirve desde * * `resources.pack` ** y hace
* fallback * al filesystem en builds de desarrollo (en Release nativo es estricto:
solo el pack; `director.cpp:143` ). `resource_pack.*` y `resource_loader.*`
implementan el formato del pack y la carga.
Formatos: imágenes vía `stb_image` + `gif` propio; audio `.ogg` vía
`stb_vorbis` ; texto/JSON vía `nlohmann/json` ; configs vía `fkyaml` .
---
## 10. Audio
`source/core/audio/audio.hpp` — `Audio` singleton sobre `jail_audio`
(primer-party, no librería externa) y `audio_adapter` . API: `playMusic(name,
loop, crossfade_ms)` , `playSound(name, Group)` , control de volumen por **grupos **
(`Group::GAME` , `INTERFACE` , …), `pause/resume/stop` , * crossfade * y * fade out *
(`audio.hpp:49` ). `Audio::update()` se llama cada frame desde las secciones
(p.ej. `Game::update` ). El build `NO_AUDIO` compila sin audio.
---
## 11. Configuración, parámetros y constantes
El proyecto tiene **tres capas de configuración ** que conviene no confundir:
1. * * `Options` ** (`source/game/options.hpp` ) — opciones persistentes del
usuario, agrupadas en structs (`Window` , `Video` , `Audio` , `Settings` ,
`Gamepad` , `Keyboard` ) más presets de shaders (`PostFXPreset` ,
`CrtPiPreset` ). Se guardan en `config.yaml` / `controllers.json` /
`postfx.yaml` / `crtpi.yaml` . Incluye `params_preset` ∈ {`classic` ,
`arcade` , `red` } (`options.hpp:339` ).
2. * * `param` / `Param` ** (`source/utils/param.hpp` ) — parámetros de *gameplay y
layout* (dimensiones del juego, `play_area` , ajustes de globos, scoreboard,
título, fades, jugador, Tabe…). Se cargan de ficheros de texto
`param_320x240.txt` / `param_320x256.txt` / `classic.txt` con
`loadParamsFromFile` (`director.cpp:275` ). El objeto global `param` lo leen
casi todos los subsistemas.
3. **Otros datos de juego ** : `stages.txt` (fases, lo lee `StageManager` ),
`formations.txt` (formaciones de globos), `assets.txt` (manifiesto).
Los **valores de fallback compilados ** viven en
`source/core/system/defaults.hpp` (y `source/utils/defines.hpp` para constantes
base). En Debug, `debug.yaml` controla sección inicial, opciones, fase, modo de
carga, `autoplay` e `invincibility` (`director.cpp:318` ).
### Builds condicionales (multiplataforma)
El juego se adapta por * defines * (ver `CLAUDE.md` ): `WINDOWS_BUILD` /
`LINUX_BUILD` / `MACOS_BUILD` , `RELEASE_BUILD` , `MACOS_BUNDLE` , `ANBERNIC`
(handheld), `__EMSCRIPTEN__` (web), `NO_SHADERS` , `NO_AUDIO` , `RECORDING` ,
`ARCADE` , `DEBUG` /`VERBOSE` . Aparecen sobre todo en `Director::init` y `Screen` .
---
## 12. Localización
`source/core/locale/lang.*` — `Lang` carga el idioma desde **JSON ** en
`data/lang/` . `Lang::setLanguage(Options::settings.language)` se llama en
`init()` y en cada `reset()` . Cambiar idioma en caliente (F9 / `CHANGE_LANG` )
fuerza un `Section::RESET` (reinicio del proceso) para recargarlo todo
(`global_inputs.cpp` ).
---
## 13. Convenciones y patrones recurrentes
- **Naming** (de `.clang-format` /`.clang-tidy` , resumido en `CLAUDE.md` ):
clases `CamelCase` , métodos `camelBack` , variables/params `snake_case` ,
miembros privados `snake_case_` (guion bajo final), constantes `UPPER_CASE` ,
namespaces `CamelCase` , valores de enum `UPPER_CASE` . clang-tidy trata los
warnings como errores.
- **Singletons con init/destroy manual**: `Screen` , `Resource` , `Audio` ,
`Input` , `Asset` , `ServiceMenu` , `Notifier` , `Lang` . Se crean/destruyen en
orden explícito en `Director::init` / `shutdownSubsystems` (`director.cpp:227` )
— no se confía en destructores estáticos.
- **Estado de flujo por variable global** (`Section::name` ): patrón central; no
hay objetos de transición tipados.
- **Time-based en todo**: cada sistema recibe `delta_time` ; las constantes de
tiempo se documentan como "N frames a 60fps → segundos" (p.ej.
`game.hpp:85` ).
- **Callbacks para desacoplar**: `BulletManager` y `StageManager` reciben
`std::function` desde `Game` para no conocer la lógica de colisión/puntuación.
- **Interfaz mínima `IStageInfo` ** (`stage_interface.hpp` ): se inyecta a
jugador y globos para que consulten amenaza/poder sin ver todo el
`StageManager` .
- **Managers por tipo + listas homogéneas** en `Game` , en vez de un contenedor
de entidades polimórfico.
- **Comentarios** en español/valenciano; muchos `#include` llevan comentario
"// Para X" indicando qué símbolo justifican (estilo IWYU).
- **Multiplataforma por `#ifdef` ** (ver §11). Conviene leerlos al tocar
arranque o render.
---
## 14. Guía de navegación: "si quieres tocar X, mira Y"
| Quiero… | Empieza por… |
|---|---|
| Entender el arranque | `source/core/system/director.cpp` (`init` , `iterate` ) |
| Cambiar el flujo de pantallas | `source/core/system/section.hpp` + `handleSectionTransition` |
| Añadir/editar una pantalla | `source/game/scenes/` (crea `iterate()` +`handleEvent()` ) y un `case` en `director.cpp` |
| La barra de carga / arranque lento | `Resource::beginLoad/loadStep` + `scenes/preload.*` |
| Cómo se dibuja todo | `Game::fillCanvas` + `Game::render` + `Screen::renderPresent` (`screen.cpp:156` ) |
| Sprites / animaciones | `source/core/rendering/sprite/` + `texture.hpp` |
| Shaders / CRT / post-FX | `source/core/rendering/sdl3gpu/` + `data/shaders/` + `Options` presets |
| Efectos (shake/flash/fade) | `screen.hpp` (structs) + `core/rendering/fade.*` |
| Controles / mandos | `source/core/input/input.hpp` (`Keyboard` /`Gamepad` /`checkAction` ) |
| Hotkeys F1– `source/core/input/global_inputs.cpp` |
| Eventos globales / hot-plug | `source/core/system/global_events.cpp` |
| Lógica de partida y estados | `source/game/scenes/game.cpp` (`updateGameState*` ) |
| Globos y formaciones | `gameplay/balloon_manager.*` + `entities/balloon.*` + `formations.txt` |
| Balas y colisiones | `gameplay/bullet_manager.*` (callbacks) + `entities/bullet.*` |
| Fases / progresión / dificultad | `gameplay/stage.*` (`StageManager` ) + `stages.txt` + `gameplay/difficulty.*` |
| El jugador (movimiento, disparo) | `entities/player.*` (sistema de disparo de dos líneas) |
| Ítems y power-ups | `entities/item.*` + `Game::dropItem/createItem` |
| Récords / entrada de nombre | `gameplay/manage_hiscore_table.*` , `gameplay/enter_name.*` |
| **Modo demo / attract ** | `core/system/demo.*` , `Game::initDemo/demoHandle*` , `scenes/title.cpp` |
| Grabar nuevas demos | build con `RECORDING` + `Game::updateRecording` |
| Cargar un recurso | `core/resources/resource.hpp` + `asset.*` + `assets.txt` |
| Audio (música/SFX) | `core/audio/audio.hpp` |
| Opciones del usuario | `game/options.hpp` (+ `config.yaml` ) |
| Parámetros de gameplay/layout | `utils/param.hpp` + `param_320x*.txt` |
| Valores por defecto | `core/system/defaults.hpp` , `utils/defines.hpp` |
| Idiomas | `core/locale/lang.*` + `data/lang/` |
| Menú de servicio / notificaciones | `game/ui/service_menu.*` , `game/ui/notifier.*` |
| Empaquetar datos | `tools/` (`pack_resources` ) + `make resources.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.*
JailDesigner