refactor(scenes): flux centralitzat amb SceneId+ExitRequest; TitleScene attract → LOGO amb fade-to-black

source/game/scenes/scene_flow.hpp

@@ -0,0 +1,63 @@
+#pragma once
+
+#include <cstdint>
+#include <variant>
+
+#include "game/debug_config.hpp"
+
+// Sistema centralitzat de transicions entre escenes. Cada escena, en lloc
+// de construir directament la següent, declara una `ExitRequest` amb un
+// identificador i els paràmetres que la nova escena necessite per
+// arrencar; `Director::buildScene` és l'únic punt que sap com instanciar
+// cada tipus i té tots els recursos a mà.
+//
+// Afegir una escena nova:
+//   1. Una entrada al `enum SceneId`.
+//   2. Si necessita paràmetres, un struct `*Params` i afegir-lo al variant.
+//   3. Un cas a `Director::buildScene` que el construïsca.
+//
+// Una escena només pot demanar transicionar a un altre `SceneId` que
+// haja estat enregistrat al variant — el compilador ja descarta noms
+// erronis.
+enum class SceneId : std::uint8_t {
+    LOGO,
+    TITLE,
+    INTRO,
+    GAME,
+};
+
+// Estructures de paràmetres per escena. Buides quan la nova escena no
+// rep cap dada de l'anterior; en cas contrari, només els camps que
+// fluixen pel canal de transició (els recursos, defaults i config
+// interna els resol Director quan construeix).
+struct LogoParams {};
+struct TitleParams {};
+struct IntroParams {
+    DebugConfig::StartingPlayers starting_players{DebugConfig::StartingPlayers::BOTH};
+};
+struct GameParams {
+    DebugConfig::StartingPlayers starting_players{DebugConfig::StartingPlayers::BOTH};
+};
+
+using SceneParams = std::variant<LogoParams, TitleParams, IntroParams, GameParams>;
+
+struct ExitRequest {
+    SceneId next;
+    SceneParams params;
+};
+
+// Helper per a logs / debug. Implementat inline per evitar un .cpp per a
+// una funció de tres línies.
+[[nodiscard]] inline auto toString(SceneId id) -> const char* {
+    switch (id) {
+        case SceneId::LOGO:
+            return "LOGO";
+        case SceneId::TITLE:
+            return "TITLE";
+        case SceneId::INTRO:
+            return "INTRO";
+        case SceneId::GAME:
+            return "GAME";
+    }
+    return "?";
+}