Refactor menu rendering and state management

- Introduced _AsciiMenuTypography and _AsciiMenuRowFont enums to manage typography settings for menu rendering.
- Updated AsciiRenderer to utilize new typography settings for main menu and game select screens.
- Enhanced SixelRenderer and SoftwareRenderer to support new menu rendering logic, including sidebars for options labels.
- Added disabled text color handling in WolfMenuPalette for better visual feedback on menu entries.
- Implemented a new method _drawSelectableMenuRows to streamline the drawing of menu rows based on selection state.
- Created a comprehensive test suite for level state carry-over and pause menu functionality, ensuring player state is preserved across levels and menus.
- Adjusted footer rendering to account for layout changes and improved visual consistency across different renderers.

Signed-off-by: Hans Kokx <hans.d.kokx@gmail.com>

packages/wolf_3d_dart/lib/src/engine/wolf_3d_engine_base.dart

@@ -150,6 +150,8 @@ class WolfEngine {
   final Map<int, ({int x, int y})> _lastPatrolTileByEnemy = {};
 
   int _currentEpisodeIndex = 0;
+  bool _isMenuOverlayVisible = false;
+  bool _hasActiveSession = false;
 
   bool _isPlayerMovingFast = false;
   int _currentLevelIndex = 0;
@@ -177,6 +179,7 @@ class WolfEngine {
       initialGameIndex: _currentGameIndex,
       initialEpisodeIndex: _currentEpisodeIndex,
       initialDifficulty: difficulty,
+      hasResumableGame: false,
     );
 
     if (_availableGames.length == 1) {
@@ -185,12 +188,19 @@ class WolfEngine {
     }
 
     if (difficulty != null) {
-      _loadLevel();
+      _loadLevel(preservePlayerState: false);
+      _hasActiveSession = true;
     }
 
     isInitialized = true;
   }
 
+  /// Whether a menu overlay is currently blocking gameplay updates.
+  bool get isMenuOpen => difficulty == null || _isMenuOverlayVisible;
+
+  /// Whether the current gameplay session can be resumed from the main menu.
+  bool get canResumeGame => _hasActiveSession;
+
   /// Replaces the shared framebuffer when dimensions change.
   void setFrameBuffer(int width, int height) {
     if (width <= 0 || height <= 0) {
@@ -225,7 +235,13 @@ class WolfEngine {
     input.update();
     final currentInput = input.currentInput;
 
-    if (difficulty == null) {
+    if (difficulty != null && !_isMenuOverlayVisible && currentInput.isBack) {
+      _openPauseMenu();
+      menuManager.absorbInputState(currentInput);
+      return;
+    }
+
+    if (isMenuOpen) {
       menuManager.tickTransition(delta.inMilliseconds);
       _tickMenu(currentInput);
       return;
@@ -275,6 +291,9 @@ class WolfEngine {
     }
 
     switch (menuManager.activeMenu) {
+      case WolfMenuScreen.mainMenu:
+        _tickMainMenu(input);
+        break;
       case WolfMenuScreen.gameSelect:
         _tickGameSelectionMenu(input);
         break;
@@ -287,6 +306,46 @@ class WolfEngine {
     }
   }
 
+  void _tickMainMenu(EngineInput input) {
+    final menuResult = menuManager.updateMainMenu(input);
+
+    if (menuResult.goBack) {
+      if (_isMenuOverlayVisible && _hasActiveSession) {
+        _resumeGame();
+      } else if (menuManager.canGoBackToGameSelection) {
+        menuManager.startTransition(WolfMenuScreen.gameSelect);
+      } else {
+        _exitTopLevelMenu();
+      }
+      return;
+    }
+
+    switch (menuResult.selected) {
+      case WolfMenuMainAction.newGame:
+        _beginNewGameMenuFlow();
+        break;
+      case WolfMenuMainAction.endGame:
+        _endCurrentGame();
+        break;
+      case WolfMenuMainAction.backToGame:
+        _resumeGame();
+        break;
+      case WolfMenuMainAction.backToDemo:
+      case WolfMenuMainAction.quit:
+        _exitTopLevelMenu();
+        break;
+      case WolfMenuMainAction.sound:
+      case WolfMenuMainAction.control:
+      case WolfMenuMainAction.loadGame:
+      case WolfMenuMainAction.saveGame:
+      case WolfMenuMainAction.changeView:
+      case WolfMenuMainAction.readThis:
+      case WolfMenuMainAction.viewScores:
+      case null:
+        break;
+    }
+  }
+
   void _tickGameSelectionMenu(EngineInput input) {
     final menuResult = menuManager.updateGameSelection(
       input,
@@ -294,7 +353,7 @@ class WolfEngine {
     );
 
     if (menuResult.goBack) {
-      _exitTopLevelMenu();
+      menuManager.startTransition(WolfMenuScreen.mainMenu);
       return;
     }
 
@@ -305,7 +364,7 @@ class WolfEngine {
       _currentEpisodeIndex = 0;
       onEpisodeSelected?.call(null);
       menuManager.clearEpisodeSelection();
-      menuManager.startTransition(WolfMenuScreen.episodeSelect);
+      menuManager.startTransition(WolfMenuScreen.mainMenu);
     }
   }
 
@@ -318,11 +377,7 @@ class WolfEngine {
     if (menuResult.goBack) {
       onEpisodeSelected?.call(null);
       menuManager.clearEpisodeSelection();
-      if (_availableGames.length > 1) {
-        menuManager.startTransition(WolfMenuScreen.gameSelect);
-      } else {
-        _exitTopLevelMenu();
-      }
+      menuManager.startTransition(WolfMenuScreen.mainMenu);
       return;
     }
 
@@ -341,13 +396,47 @@ class WolfEngine {
     }
 
     if (menuResult.selected != null) {
-      difficulty = menuResult.selected;
-      _currentLevelIndex = 0;
-      _returnLevelIndex = null;
-      _loadLevel();
+      _startNewGameSession(menuResult.selected!);
     }
   }
 
+  void _beginNewGameMenuFlow() {
+    onEpisodeSelected?.call(null);
+    menuManager.clearEpisodeSelection();
+    menuManager.startTransition(WolfMenuScreen.episodeSelect);
+  }
+
+  void _openPauseMenu() {
+    if (!_hasActiveSession) {
+      return;
+    }
+    _isMenuOverlayVisible = true;
+    menuManager.showMainMenu(hasResumableGame: true);
+  }
+
+  void _resumeGame() {
+    _isMenuOverlayVisible = false;
+    menuManager.absorbInputState(input.currentInput);
+  }
+
+  void _startNewGameSession(Difficulty selectedDifficulty) {
+    difficulty = selectedDifficulty;
+    _currentLevelIndex = 0;
+    _returnLevelIndex = null;
+    _isMenuOverlayVisible = false;
+    _loadLevel(preservePlayerState: false);
+    _hasActiveSession = true;
+  }
+
+  void _endCurrentGame() {
+    difficulty = null;
+    _isMenuOverlayVisible = false;
+    _hasActiveSession = false;
+    _returnLevelIndex = null;
+    onEpisodeSelected?.call(null);
+    menuManager.showMainMenu(hasResumableGame: false);
+  }
+
   void _exitTopLevelMenu() {
     if (onMenuExit != null) {
       onMenuExit!.call();
@@ -357,7 +446,7 @@ class WolfEngine {
   }
 
   /// Wipes the current world state and builds a new floor from map data.
-  void _loadLevel() {
+  void _loadLevel({required bool preservePlayerState}) {
     entities.clear();
     _lastPatrolTileByEnemy.clear();
 
@@ -374,17 +463,26 @@ class WolfEngine {
     audio.playLevelMusic(activeLevel);
 
     // Spawn Player and Entities from the Object Grid
+    bool playerSpawned = false;
     for (int y = 0; y < 64; y++) {
       for (int x = 0; x < 64; x++) {
         int objId = _objectLevel[y][x];
 
         // Map IDs 19-22 are Reserved for Player Starts
         if (objId >= MapObject.playerNorth && objId <= MapObject.playerWest) {
-          player = Player(
-            x: x + 0.5,
-            y: y + 0.5,
-            angle: MapObject.getAngle(objId),
-          );
+          playerSpawned = true;
+          if (preservePlayerState) {
+            player
+              ..x = x + 0.5
+              ..y = y + 0.5
+              ..angle = MapObject.getAngle(objId);
+          } else {
+            player = Player(
+              x: x + 0.5,
+              y: y + 0.5,
+              angle: MapObject.getAngle(objId),
+            );
+          }
         } else {
           Entity? newEntity = EntityRegistry.spawn(
             objId,
@@ -399,6 +497,10 @@ class WolfEngine {
       }
     }
 
+    if (!playerSpawned && !preservePlayerState) {
+      player = Player(x: 1.5, y: 1.5, angle: 0.0);
+    }
+
     // Sanitize the level grid to ensure only valid walls/doors remain
     for (int y = 0; y < 64; y++) {
       for (int x = 0; x < 64; x++) {
@@ -419,6 +521,9 @@ class WolfEngine {
   void _onLevelCompleted({bool isSecretExit = false}) {
     audio.playSoundEffect(WolfSound.levelDone);
     audio.stopMusic();
+    player
+      ..hasGoldKey = false
+      ..hasSilverKey = false;
     final currentEpisode = data.episodes[_currentEpisodeIndex];
 
     if (isSecretExit) {
@@ -439,7 +544,7 @@ class WolfEngine {
         _currentLevelIndex > 9) {
       onGameWon();
     } else {
-      _loadLevel();
+      _loadLevel(preservePlayerState: true);
     }
   }