feat(game-scene): FSM mínima ROOM_INTRO/PLAYING/ROOM_OUTRO sense efectes

source/game/scenes/game_scene.hpp

@@ -38,6 +38,18 @@ class GameScene : public Scene {
 
     [[nodiscard]] static auto defaultConfig() -> Config;
 
+    // Estat de l'escena dins del cicle d'una sala. La màquina és interna a
+    // GameScene: SceneManager segueix tractant GameScene com una sola
+    // escena. ROOM_INTRO i ROOM_OUTRO bloquegen input i render dels
+    // jugadors; l'EntityManager segueix avançant i el HUD/Notifier també.
+    // L'enum es declara públic perquè els helpers de log (stateName) i
+    // tests viuen fora de la classe; el camp `state_` segueix privat.
+    enum class State : std::uint8_t {
+        ROOM_INTRO,  // Entrada de sala: fade in + text d'entrada.
+        PLAYING,     // Joc normal.
+        ROOM_OUTRO,  // Sortida de sala: text de sortida + fade out.
+    };
+
     explicit GameScene(Config config = defaultConfig());
     ~GameScene() override;
 
@@ -45,6 +57,18 @@ class GameScene : public Scene {
     void render() override;
 
    private:
+    // Punt centralitzat per canviar d'estat. Imprimeix la transició i
+    // reinicialitza els acumuladors de la transició de sala. Cap estat
+    // s'ha de canviar fora d'aquí.
+    void setState(State new_state);
+
+    // Avança la transició activa (sub-fases, timings). En aquesta fita
+    // les transicions són instantànies (sense efectes); les sub-fases
+    // amb fades i text arribaran als commits següents. S'executa cada
+    // frame amb delta real (no escalat per la pausa) perquè la
+    // transició viu en temps de UI.
+    void updateRoomTransition(int delta_ms);
+
     // Consumeix events d'aquest frame (F11 del KeyConfig "pause" o botó
     // START del gamepad primari) per disparar les transicions de pausa.
     // No alterna un flag binari: inicia (o inverteix mid-flight) un
@@ -131,6 +155,17 @@ class GameScene : public Scene {
         UiConfig::CurveFn curve{nullptr};  // Corba activa.
     } pause_;
 
+    // Estat actual de la FSM de sala. S'inicialitza a ROOM_INTRO al ctor
+    // perquè cada vegada que entres al joc passes per la presentació de
+    // la sala. La transició a PLAYING l'orquestra `updateRoomTransition`.
+    State state_{State::ROOM_INTRO};
+
+    // Índex de sala que es passa com a paràmetre {n} al text d'intro.
+    // Avui és sempre 1 (no hi ha itinerari de sales encara). Quan
+    // arribi l'itinerari, és el camp que es modificarà al transicionar
+    // de ROOM_OUTRO → ROOM_INTRO per saltar a la pròxima.
+    int room_index_{1};
+
 #ifdef _DEBUG
     // Editor modal del tilemap. Mútuament excloent amb la pausa: si la
     // pausa no està IDLE la tecla de toggle de l'editor s'ignora, i