From 86bdfb8f73ce2652f71e63234121ac47ba6305fc Mon Sep 17 00:00:00 2001 From: Sergio Valor Date: Fri, 29 May 2026 13:29:24 +0200 Subject: [PATCH] afig guia d'arquitectura del projecte --- docs/ARQUITECTURA.md | 542 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 542 insertions(+) create mode 100644 docs/ARQUITECTURA.md diff --git a/docs/ARQUITECTURA.md b/docs/ARQUITECTURA.md new file mode 100644 index 0000000..9033661 --- /dev/null +++ b/docs/ARQUITECTURA.md @@ -0,0 +1,542 @@ +# Arquitectura de **Coffee Crisis** + +> 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, o donde el código contradice a la documentación previa, lo +> digo explícitamente en lugar de inventarlo. +> +> **Coffee Crisis** es un arcade en C++20 + SDL3: el jugador defiende la UPV de +> globos de café rebotantes a lo largo de 10 fases. Soporta 1–2 jugadores, +> teclado y mando, y varios idiomas. Es el **predecesor** de *Coffee Crisis +> Arcade Edition*; al final del documento ([§15](#15-diferencias-frente-a-la-arcade-edition)) +> hay un resumen de las diferencias entre ambos. 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](#7-entidades) +8. [Modo demo y attract mode](#8-modo-demo-y-attract-mode) +9. [Recursos](#9-recursos) +10. [Audio](#10-audio) +11. [Configuración y constantes](#11-configuración-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) +15. [Diferencias frente a la Arcade Edition](#15-diferencias-frente-a-la-arcade-edition) + +--- + +## 1. Visión general + +El árbol `source/` separa **motor** y **juego**: + +- **`source/core/`** — motor genérico: `system` (`director`, `delta_time`, + `demo`), `rendering` (+ `sdl3gpu`, sprites), `input`, `resources`, `audio`, + `locale`. +- **`source/game/`** — el juego concreto: `game.*` (el hub de gameplay), + `entities/` (player, balloon, bullet, item), `scenes/` (logo, intro, title, + instructions), `ui/` (menu), `options.*` y `defaults.hpp`. +- **`source/utils/`** — `utils.*` (helpers, `struct Section`, `Color`, + dificultad…) y `defines.hpp` (macros de build). +- **`source/external/`** — vendorizado: `stb_image`, `stb_vorbis` (y headers + YAML/JSON). + +~51 ficheros C++ y ~16.000 líneas. **Nota sobre cabeceras**: los módulos +antiguos usan extensión **`.h`** (p.ej. `director.h`, `game.h`, `screen.h`); los +módulos nuevos usan **`.hpp`** (p.ej. `demo.hpp`, `options.hpp`, +`delta_time.hpp`). Es un proyecto en migración, y eso se nota en varias capas. + +**Ideas-fuerza que conviene interiorizar:** + +1. El flujo se controla con un **`struct Section { name, subsection }`** que el + `Director` lee cada frame (§3). +2. El render dibuja con **texturas GPU** (`SDL_Renderer`) sobre un **canvas + virtual de 256×192**, con post-procesado opcional vía un backend SDL3 GPU + (§4). +3. El gameplay es **monolítico**: casi todo vive en la clase `Game`, con + vectores de **punteros crudos** y `new`/`delete` manual (§6, §7). +4. **Sí hay modo demo** (*attract mode*): **reproducción de input grabado**, no + IA, orquestada desde la pantalla de título (§8). +5. El proyecto está **migrando de frame-based a time-based** y de `config.txt` + a YAML; conviven ambos mundos (§2, §11). + +```mermaid +graph TD + SDL[SDL3 callbacks · main.cpp] --> DIR[Director] + DIR -->|struct Section| ST{handleSectionTransition} + ST --> SEC["Logo / Intro / Title / Game"] + SEC --> TITLE[Title] -.attract.-> NESTED["Game anidado en demo + Instructions"] + SEC --> GAME["Game (monolítico)"] + GAME --> ENT["Player* / Balloon* / Bullet* / Item* (punteros crudos)"] + GAME --> DEMOSYS["Demo (playback grabado)"] -.-> ENT + GAME -->|SDL_RenderTexture| CANVAS["game_canvas_ 256×192"] + CANVAS --> SCREEN[Screen] --> SB["ShaderBackend PostFX/CrtPi"] --> WIN[Ventana] + RES["Asset / Resource"] -.-> 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 → new Director(argc, argv); +SDL_AppIterate→ Director::iterate(); // un frame +SDL_AppEvent → Director::handleEvent(event); +SDL_AppQuit → delete Director; +``` + +### 2.2. El `Director` + +`source/core/system/director.h` / `.cpp`. Inicializa SDL, ventana y renderer, +crea la carpeta de sistema, monta input/audio/recursos, y mantiene **un +`unique_ptr` por sección** (`logo_`, `intro_`, `title_`, `game_`) de los que +**solo uno está vivo** (`director.h:55`). Guarda un puntero a la +`struct Section* section_` que comparte con la sección activa. + +`Director::iterate()` cada frame: comprueba salida (doble ESC vía +`GlobalInputs::wantsQuit()`), actualiza la visibilidad del cursor, llama a +`handleSectionTransition()` y despacha `iterate()` a la sección activa +(`director.cpp`, `switch (active_section_)`). + +### 2.3. Gestión del tiempo (en migración) + +El reloj central es `source/core/system/delta_time.*`: `DeltaTime::tick()` +devuelve el delta en segundos consumido al inicio de cada frame de la sección +(`game.cpp`, `Game::iterate`). El proyecto **está migrando de frame-based a +time-based**: en `game.h` se ven contadores duplicados, el viejo frame-based +(`Uint16 death_counter_`) y el nuevo time-based (`float death_counter_s_`), +documentados como tales (`game.h:347`). El playback de la demo también es +time-based: `index = elapsed_s * 60` (`demo.hpp:11`). + +--- + +## 3. Secciones y flujo de la aplicación + +### 3.1. `struct Section` + +`source/utils/utils.h:58` define un POD minimalista: + +```cpp +struct Section { + Uint8 name; // SECTION_PROG_* (LOGO/INTRO/TITLE/GAME/QUIT) + Uint8 subsection; // SUBSECTION_* (p.ej. GAME_PLAY_1P, GAME_PAUSE, TITLE_INSTRUCTIONS…) +}; +``` + +Los valores son **constantes `constexpr int` en `source/game/defaults.hpp`** +(`SECTION_PROG_LOGO = 0`, …, `SECTION_PROG_QUIT = 4`; `SUBSECTION_GAME_PLAY_1P`, +`SUBSECTION_GAME_PAUSE`, `SUBSECTION_GAME_GAMEOVER`, `SUBSECTION_TITLE_INSTRUCTIONS`, +etc.; `defaults.hpp:90`). Cualquier parte del código cambia el flujo asignando +`section_->name = ...` / `section_->subsection = ...`. + +### 3.2. Transición de secciones + +`Director::handleSectionTransition()` (`director.cpp`): + +- Traduce `section_->name` a un `enum class ActiveSection` (`director.h:24`). +- Si coincide con la activa, no hace nada. +- Si cambió: libera las cuatro secciones (`reset()`) y construye la nueva. Para + `GAME` decide el nº de jugadores según `section_->subsection` + (`SUBSECTION_GAME_PLAY_1P` → 1, si no → 2) y crea + `Game(NUM_PLAYERS, 0, renderer_, /*demo=*/false, section_)`. + +Cada sección recibe el `renderer_` y el `Section*`, y expone `iterate()` (y, en +`Game`, `handleEvent()`). + +```mermaid +graph LR + LOGO --> INTRO --> TITLE + TITLE -->|jugar| GAME --> TITLE + TITLE -->|attract / manual| INSTR["Instructions (dentro de Title)"] + TITLE -->|attract| DEMOG["Game anidado en demo (dentro de Title)"] + TITLE --> QUIT +``` + +> **Matiz importante**: `Instructions` y la **demo** no son secciones del +> `Director`. Viven **dentro de `Title`**, que ejecuta un *attract loop* (ver +> §8). El `Director` solo conoce Logo/Intro/Title/Game/Quit. + +--- + +## 4. Renderizado: de la lógica al píxel + +Los sprites son **texturas GPU** dibujadas por `SDL_Renderer` sobre un canvas +virtual; el post-procesado va por un backend SDL3 GPU. + +### 4.1. El canvas virtual 256×192 + +`Screen` (`core/rendering/screen.h`) crea `game_canvas_`, una `SDL_Texture` de +**256×192** (`GAMECANVAS_WIDTH/HEIGHT` en `defaults.hpp:64`) con +`SDL_TEXTUREACCESS_TARGET` (`screen.cpp:106`). Toda la geometría del juego se +deriva de esa resolución y de un `BLOCK` base (áreas de juego en +`defaults.hpp`). + +`Screen::start()` (`screen.cpp:166`) fija el render-target a `game_canvas_`; +a partir de ahí, la sección activa dibuja sus sprites sobre él. + +### 4.2. Texturas y jerarquía de sprites + +- `core/rendering/texture.h` — `Texture` envuelve un `SDL_Texture*` cargado de + PNG; método `render(...)` con clip/zoom/flip. +- `core/rendering/sprite.h` y derivados: + - `Sprite` — dibuja desde un *spritesheet*. + - `AnimatedSprite` — animación por fotogramas, definida en ficheros **`.ani`**. + - `MovingSprite` — añade posición/velocidad (p.ej. las nubes del fondo). + - `SmartSprite` — sprite autónomo (popups de puntuación, el café que salta al + recibir un golpe). +- Texto: `core/rendering/text.h` + `writer.h` (fuentes bitmap). +- Transiciones: `core/rendering/fade.h`. Notificaciones: + `core/rendering/notifications.*`. + +### 4.3. Post-procesado y presentación + +El path de presentación (`screen.cpp:185`) decide cómo llega el canvas a la +ventana: + +- **Con backend GPU acelerado**: lee los píxeles de `game_canvas_` con + `SDL_RenderReadPixels` a un `pixel_buffer_` (ARGB8888; + `screen.h:162`), los sube al backend (`shader_backend_->uploadPixels(...)`) y + este renderiza con el shader activo a la ventana. +- **Sin backend / desactivado** (fallback): `SDL_RenderTexture` del + `game_canvas_` a la ventana y `SDL_RenderPresent` (`screen.cpp:233`). + +El backend vive en `core/rendering/sdl3gpu/` (interfaz abstracta en +`shader_backend.hpp`). Dos shaders: **PostFX** (viñeta, scanlines, chroma, +gamma, máscara, curvatura, *bleeding*, flicker) y **CrtPi** (scanlines continuas +con bloom). Los GLSL de `data/shaders/` se compilan a SPIR-V (`spv/*_spv.h`) vía +`glslc`; en macOS se usan shaders **Metal (MSL)** inline (`sdl3gpu/msl/`). El +build `NO_SHADERS` (Emscripten) fuerza la ruta clásica. + +```mermaid +graph TD + OBJ["fondo, globos, jugador, balas, items…"] -->|SDL_RenderTexture| CANVAS["game_canvas_ 256×192 (render target)"] + CANVAS -->|RenderReadPixels → uploadPixels| SHADER["ShaderBackend (PostFX / CrtPi)"] + SHADER --> WIN[Ventana] + CANVAS -.fallback sin GPU.-> WIN +``` + +### 4.4. Modos de escalado y efectos + +La presentación a la ventana respeta `Options::video.presentation_mode` +(`INTEGER_SCALE`, `LETTERBOX`, `STRETCHED`, `OVERSCAN`; `options.hpp:24`). El +`Game` añade efectos como *flash*, *shake* y un *death shake* intenso +(`game.h:100`, `DeathShake`). + +--- + +## 5. Entrada + +### 5.1. `Input` + +`source/core/input/input.h` — abstracción de teclado y mando bajo un enum de +acciones (`Input::Action`). El jugador se mueve con flechas y dispara +izquierda/centro/derecha; el `Input::Device` selecciona teclado o mando por +jugador (`Game::player_one_control_`, `game.h:379`). + +### 5.2. Hotkeys globales y salida + +`source/core/input/global_inputs.*` gestiona las teclas de sistema (ventana, +vídeo, post-FX, idioma, FPS overlay…) y la **salida en dos pasos**: la primera +pulsación de ESC arma una confirmación y la segunda activa `wantsQuit()`, que el +`Director` traduce a `SECTION_PROG_QUIT` (`director.cpp`). El cursor del ratón +se autooculta (`core/input/mouse.*`). + +Las hotkeys de shaders documentadas: **F4** activa/desactiva post-procesado, +**F5** alterna PostFX↔CrtPi, **F6** siguiente preset (ver `CLAUDE.md`). + +### 5.3. Cómo llega la entrada al jugador + +Dentro de `Game`, `checkGameInput()` → `processLiveInput()` → +`processPlayerLiveInput(player, i)` consulta `Input` y llama a +`player->setInput(Input::Action)` y a `createBullet(...)` al disparar +(`game.h:228`). En modo demo, esa misma vía la alimenta `processDemoInput()` +con datos grabados (§8). + +--- + +## 6. Lógica del juego: la clase `Game` + +`source/game/game.{h,cpp}` es **el hub de gameplay y, con diferencia, la clase +más grande** del proyecto: ~400 líneas solo de declaración. A diferencia de la +Arcade Edition, **no delega en managers**: las formaciones, fases, globos, +balas e ítems se gestionan directamente aquí. + +### 6.1. El frame y sus sub-bucles + +`Game::iterate()` (`game.cpp`) consume el delta con `DeltaTime::tick()` y +despacha según `section_->subsection`: + +```cpp +switch (section_->subsection) { + case SUBSECTION_GAME_PAUSE: iteratePaused(dt); break; + case SUBSECTION_GAME_GAMEOVER: iterateGameOver(dt); break; + case SUBSECTION_GAME_PLAY_1P: + case SUBSECTION_GAME_PLAY_2P: iteratePlaying(dt); break; +} +``` + +Es decir, **pausa y game-over son sub-estados** del propio `Game` (no secciones +del Director), cada uno con su `update`/`render`. En modo demo, entrar en pausa +o game-over rebota directamente a `Title` (`game.cpp`, `Game::iterate`). + +### 6.2. Lo que gestiona `Game` + +Todo dentro de la misma clase (`game.h`): + +- **Fases (`Stage stage_[10]`)**: cada fase tiene un *pool* de formaciones + enemigas (`EnemyPool`/`EnemyFormation`/`EnemyInit`, structs internos), poder + para completarla y umbrales de amenaza. `initEnemyFormations*` precalcula las + formaciones (lineales, simétricas, hexágonos…). +- **Nivel de amenaza** (`menace_current_`/`menace_threshold_`): si la amenaza + cae bajo el umbral, se despliega otra formación (`updateMenace`, + `evaluateAndSetMenace`). +- **Ítems y power-ups**: disco/gaviota/pacmar (puntos), café (toque extra), + máquina de café (power-up), reloj (**detener el tiempo**, + `enableTimeStopItem`), *power ball*. Probabilidades en `Helper` + (`game.h:128`). +- **Colisiones**: jugador↔globo, jugador↔ítem, bala↔globo (`checkPlayer…`, + `checkBulletBalloonCollision`). +- **Muerte del jugador**: secuencia con *death shake* y fases + (`DeathSequence`/`DeathPhase`, `game.h:113`). +- **Marcador, hi-score, fades, fondo** (nubes con parallax via `MovingSprite`), + menús de pausa y game-over (`Menu`), audio (`Ja::Sound*`/`Ja::Music*`). + +### 6.3. Gestión de memoria + +Las entidades viven como **vectores de punteros crudos** +(`std::vector`, ``, ``, ``, +``; `game.h:264`), creados con `new` y liberados con métodos +`freeBalloons()`, `freeBullets()`, `freeItems()`, `deleteAllVectorObjects()`. +Es un estilo más antiguo que el de la Arcade Edition (smart pointers). + +--- + +## 7. Entidades + +`source/game/entities/`: + +- **`Player`** (`player.h`) — movimiento, disparo (tres direcciones), + animaciones, power-up, invulnerabilidad, vidas/score. Puede usar teclado o + mando. +- **`Balloon`** (`balloon.h`) — enemigo básico que rebota; al explotar puede + generar globos hijos. Tiene varios contadores de estado. +- **`Bullet`** (`bullet.h`) — proyectil con `Kind` (UP/LEFT/RIGHT) y estado de + power-up. +- **`Item`** (`item.h`) — power-ups y objetos de puntos que caen, con `Id` por + tipo. + +No hay clase base de entidad común ni managers: el ciclo de vida lo lleva +`Game` directamente sobre los vectores (§6.3). Los efectos visuales tipo +"popup de puntuación" o "café arrojado" se modelan como `SmartSprite` +(`core/rendering/smartsprite.h`). + +--- + +## 8. Modo demo y attract mode + +> **El modo demo SÍ existe, y NO es IA**: es **reproducción de input +> pregrabado**, igual concepto que en la Arcade Edition. + +### 8.1. Formato + +`source/core/system/demo.hpp`: cada fotograma es un `DemoKeys` con seis banderas +(`left`, `right`, `no_input`, `fire`, `fire_left`, `fire_right`). Una demo es un +`vector` de `TOTAL_DEMO_DATA = 2000` fotogramas "a 60 Hz de +referencia" (`demo.hpp:9`). Hay tres ficheros: `data/demo/demo{1,2,3}.bin`. El +playback es **time-based**: `index = elapsed_s * 60`. + +### 8.2. Reproducción + +Cuando un `Game` corre en modo demo, `processDemoInput()` (`game.cpp`) lee el +fotograma actual del set seleccionado y lo inyecta por la **misma vía que un +humano** sobre `players_[0]`: + +```cpp +const DemoKeys &keys = dd.at(demo_.index % dd.size()); +if (keys.left == 1) players_[0]->setInput(Input::Action::LEFT); +if (keys.fire == 1 && players_[0]->canFire()) { + players_[0]->setInput(Input::Action::FIRE_CENTER); + createBullet(...); players_[0]->setFireCooldown(10); +} +// … (right, no_input, fire_left, fire_right) +``` + +No hay toma de decisiones: repite las pulsaciones grabadas. Al agotar el +playback (`index >= TOTAL_DEMO_DATA`) vuelve a `Title`. + +### 8.3. Attract mode (dentro de `Title`) + +El bucle de atracción vive en `source/game/scenes/title.cpp`: el Title arma un +*timeout* (`demo_remaining_s_`) y, al agotarse, lanza un **`Game` anidado en +modo demo** (`runDemoGame()`, `demo_game_`, `demo_game_active_`; +`title.cpp:323`). Title tiquea ese `demo_game_->iterate()` directamente y, al +terminar la demo, encadena las **instrucciones** +(`demo_then_instructions_` → `runInstructions(Instructions::Mode::AUTO)`, +`title.cpp:334`) antes de volver al título. Así el Title alterna +atracción → demo → instrucciones de forma autónoma. + +> Es una diferencia notable con la Arcade Edition, donde la demo es una sección +> `GAME_DEMO` propia del Director. Aquí el `Director` ni se entera: todo el +> attract está encapsulado en `Title`. + +--- + +## 9. Recursos + +- **`Asset`** (`core/resources/asset.h`) — índice de ficheros de recurso + (`add`/`get` por nombre). +- **`Resource`** (`core/resources/resource.h`) — carga y caché de los recursos + (texturas, sonidos, música, fuentes, animaciones). +- **Pack**: `resource_pack.*` + `resource_loader.*` + `resource_helper.*` + sirven desde **`resources.pack`**, con *fallback* al filesystem en desarrollo. +- **Formatos**: PNG (spritesheets) + ficheros **`.ani`** (definición de + animaciones); OGG (audio, vía `stb_vorbis`); fuentes bitmap en `data/font/`. + Los shaders GLSL de `data/shaders/` **no** van al pack (se embeben en el + binario como cabeceras SPIR-V). + +--- + +## 10. Audio + +`source/core/audio/` — `Audio` (`audio.hpp`) + `audio_adapter` sobre +**`jail_audio`** (`jail_audio.hpp`), wrapper de audio SDL3 *first-party* (no +librería externa) que usa `stb_vorbis` para OGG y mezcla por canales (API +`JA_*`). `Game` mantiene punteros `Ja::Sound*` para cada efecto (explosión, +disparo, colisión, reloj, etc.) y un `Ja::Music* game_music_`. + +--- + +## 11. Configuración y constantes + +- **`Options`** (`source/game/options.hpp`) — opciones persistentes en el + namespace `Options::` (`window`, `video` con `gpu`/`shader`, `audio`, + `loading`, `settings`, `gameplay`, `inputs`), más presets `PostFXPreset` y + `CrtPiPreset`. + + > ⚠️ **El `CLAUDE.md` está desactualizado en este punto**: dice que la config + > vive en `config.txt` con "migración a YAML pendiente". El código real + > (`options.hpp:16`) ya **persiste en `config.yaml` vía fkyaml**, con presets + > de shaders en `postfx.yaml`/`crtpi.yaml`. El código manda. + +- **`defaults.hpp`** (`source/game/`) — constantes de gameplay y layout: tamaño + de canvas (256×192), `BLOCK`, áreas de juego, colores, y las constantes + `SECTION_PROG_*` / `SUBSECTION_*` del flujo (§3). +- **`utils/defines.hpp`** — macros de build. + +### Builds condicionales + +Aparecen sobre todo en `Director`/`Screen`: `__EMSCRIPTEN__` (web: no se puede +salir, reinicia al logo; `NO_SHADERS` forzado), `DEBUG`, y la selección de +plataforma para shaders (SPIR-V vs Metal). `make release` empaqueta `.tar.gz` / +`.dmg` / `.zip` según el SO. + +--- + +## 12. Localización + +`source/core/locale/lang.*` — `Lang` carga las cadenas desde `data/lang/` +(es_ES, ba_BA/euskera, en_UK). El idioma se elige en `Options::settings.language`. + +--- + +## 13. Convenciones y patrones recurrentes + +- **Cabeceras mixtas `.h` / `.hpp`**: `.h` en lo antiguo, `.hpp` en lo nuevo — + pista fiable de qué módulos se han reescrito. +- **Punteros crudos + `new`/`delete`** en el gameplay (`Game`), frente a smart + pointers en el resto (secciones, `Screen`). Migración a medias. +- **Migración frame-based → time-based**: contadores duplicados + (`x_counter_` + `x_counter_s_`) conviviendo; el reloj es `DeltaTime::tick()`. +- **Flujo por `struct Section` + constantes `SECTION_PROG_*`** (no enums + tipados ni objetos de transición). +- **Sub-estados dentro de la sección** (pausa/game-over como `subsection` de + `Game`), no como secciones del `Director`. +- **Attract mode encapsulado en `Title`** (demo + instrucciones). +- **`Game` monolítico**: la lógica no está repartida en managers; todo cuelga + de la clase `Game` y de structs internos (`Stage`, `EnemyFormation`, …). +- **Comentarios** en español/valenciano; muchos `#include` con comentario + "// for X" (estilo IWYU). +- **El `CLAUDE.md` puede ir por detrás del código** (caso config.txt→YAML): ante + duda, manda el código. + +--- + +## 14. Guía de navegación: "si quieres tocar X, mira Y" + +| Quiero… | Empieza por… | +|---|---| +| Entender el arranque | `source/core/system/director.cpp` | +| Cambiar el flujo de pantallas | `struct Section` (`utils/utils.h`) + constantes en `game/defaults.hpp` + `handleSectionTransition` | +| Añadir/editar una pantalla | `source/game/scenes/` (Logo/Intro/Title/Instructions) | +| Gestión del tiempo | `source/core/system/delta_time.*` | +| Cómo se dibuja todo | `Screen::start`/render (`core/rendering/screen.cpp`) | +| Canvas / resolución / áreas | `source/game/defaults.hpp` (256×192, BLOCK) | +| Sprites / animaciones `.ani` | `core/rendering/sprite.h` + `animatedsprite.h` + `texture.h` | +| Shaders / CRT / post-FX | `core/rendering/sdl3gpu/` + `data/shaders/` + `Options` | +| Modos de escalado / efectos | `Screen` + `Options::video.presentation_mode` | +| Controles / mandos | `core/input/input.h` | +| Hotkeys / salida en dos pasos | `core/input/global_inputs.cpp` | +| **Toda la lógica de partida** | `source/game/game.cpp` (`iteratePlaying/Paused/GameOver`) | +| Fases / formaciones / amenaza | `Game::initEnemyFormations*`, `Stage stage_[10]`, `updateMenace` | +| Globos / balas / ítems | `game/entities/{balloon,bullet,item}.*` (gestionados en `Game`) | +| El jugador | `game/entities/player.*` | +| Ítems y power-ups | `Game::dropItem/createItem`, `Helper` (`game.h`) | +| **Modo demo / attract** | `core/system/demo.*`, `Game::processDemoInput`, `scenes/title.cpp` (`runDemoGame`) | +| Cargar un recurso | `core/resources/asset.h` + `resource.h` | +| Audio | `core/audio/audio.hpp` + `jail_audio.hpp` | +| Opciones del usuario | `game/options.hpp` (+ `config.yaml`) | +| Valores por defecto / constantes | `game/defaults.hpp`, `utils/defines.hpp` | +| Idiomas | `core/locale/lang.*` + `data/lang/` | +| Empaquetar datos | `tools/` + `make pack` | + +--- + +## 15. Diferencias frente a la Arcade Edition + +`coffee_crisis` es el **predecesor** de `coffee_crisis_arcade_edition`. Ambos +comparten ADN (SDL3, `jail_audio`, demo por input grabado, backend SDL3 GPU con +PostFX/CrtPi, capas core/game), pero el código diverge de forma sistemática. +Resumen de lo observado leyendo ambos repos: + +| Dimensión | **Coffee Crisis (este)** | **Arcade Edition** | +|---|---|---| +| Tamaño | ~51 ficheros, ~16k LOC | ~150 ficheros, ~32k LOC | +| Cabeceras | mixto `.h` (antiguo) / `.hpp` | todo `.hpp` | +| Flujo | `struct Section{name,subsection}` + `enum ActiveSection`; **4 secciones** (Logo/Intro/Title/Game) | variable global `Section::name` con **muchas más** (Preload, HiScore, Credits, GameDemo, Instructions…) | +| Arranque | directo | **no bloqueante** con sección `PRELOAD` + `Resource::loadStep(50ms)` | +| Gameplay | **`Game` monolítico**; formaciones/fases como structs internos | **managers** (`BalloonManager`, `BulletManager`, `StageManager` con `IStageInfo`) | +| Memoria de entidades | **punteros crudos** + `new`/`delete` | `shared_ptr`/`unique_ptr` + listas | +| Pausa / game-over | **sub-estados** dentro de `Game` (`subsection`) | FSM de estados de `Game` + managers dedicados | +| Demo / attract | **encapsulado en `Title`** (Game anidado en demo + instrucciones) | sección `GAME_DEMO` propia del Director + attract Title↔Logo/Demo | +| Canvas | **256×192** fijo (`defaults.hpp`) | parametrizable (`param_320x*.txt`) | +| Render | un único `game_canvas_` → readback → shader / fallback | dos render-targets (`canvas_` zona de juego → `game_canvas_`) → shader / fallback | +| Sprites | `Sprite/AnimatedSprite/MovingSprite/SmartSprite` | añade `PathSprite`, `CardSprite` | +| Reinicio en caliente | (no observado a nivel de `relaunch()`) | `Director::relaunch()` vía `execv` | +| Plataformas | Linux/macOS/Windows/Emscripten | + Raspberry Pi, Anbernic | +| Estado del código | **en migración**: frame→time-based, `config.txt`→YAML | más consolidado (YAML, time-based) | + +En una frase: la Arcade Edition es esta misma idea **refactorizada y ampliada** +— se troceó el `Game` monolítico en managers, se pasó a smart pointers, se +añadieron secciones y plataformas, y se consolidó la migración a time-based y +YAML que aquí todavía está a medias. + +--- + +*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.*