feat: Add CompatibleSaveGameCodec for legacy W3DS support and enhance SaveGamePersistence with existence check

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

packages/wolf_3d_dart/lib/src/engine/save/save_game_codec.dart

@@ -578,6 +578,21 @@ class OriginalLayoutEnvelopeSaveGameCodec extends SaveGameCodec {
   }
 }
 
+/// Writes classic-envelope saves while remaining able to read legacy W3DS
+/// saves created by earlier engine builds.
+class CompatibleSaveGameCodec extends OriginalLayoutEnvelopeSaveGameCodec {
+  final SaveGameCodec _legacyCodec = SaveGameCodec();
+
+  @override
+  SaveGameFile decode(Uint8List bytes) {
+    try {
+      return super.decode(bytes);
+    } on FormatException {
+      return _legacyCodec.decode(bytes);
+    }
+  }
+}
+
 class _BinaryWriter {
   final BytesBuilder _builder = BytesBuilder(copy: false);
 

packages/wolf_3d_dart/lib/src/engine/save/save_game_persistence.dart

@@ -9,6 +9,12 @@ abstract class SaveGamePersistence {
   /// Loads raw bytes for [slot] and [version], or `null` when no save exists.
   Future<Uint8List?> load({required int slot, required GameVersion version});
 
+  /// Returns whether a non-empty save exists for [slot] and [version].
+  Future<bool> exists({required int slot, required GameVersion version}) async {
+    final Uint8List? bytes = await load(slot: slot, version: version);
+    return bytes != null && bytes.isNotEmpty;
+  }
+
   /// Persists [bytes] for [slot] and [version].
   Future<void> save({
     required int slot,

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

@@ -50,7 +50,7 @@ class WolfEngine {
          'Provide either data or a non-empty availableGames list.',
        ),
        _availableGames = availableGames ?? <WolfensteinData>[data!],
-       saveGameCodec = saveGameCodec ?? SaveGameCodec(),
+       saveGameCodec = saveGameCodec ?? CompatibleSaveGameCodec(),
        audio = engineAudio ?? CliSilentAudio(),
        doorManager = DoorManager(
          onPlaySound: (effect) => engineAudio?.playSoundEffect(effect),
@@ -498,18 +498,10 @@ class WolfEngine {
       return;
     }
 
-    bool hasSave = false;
-    for (final game in _availableGames) {
-      final Uint8List? bytes = await saveGamePersistence!.load(
-        slot: defaultSaveSlot,
-        version: game.version,
-      );
-      if (bytes != null && bytes.isNotEmpty) {
-        hasSave = true;
-        break;
-      }
-    }
-
+    final bool hasSave = await saveGamePersistence!.exists(
+      slot: defaultSaveSlot,
+      version: data.version,
+    );
     _setLoadGameAvailability(hasSave);
   }
 
@@ -921,6 +913,9 @@ class WolfEngine {
       _currentEpisodeIndex = 0;
       onEpisodeSelected?.call(null);
       menuManager.clearEpisodeSelection();
+      if (saveGamePersistence != null) {
+        unawaited(_refreshLoadGameAvailability());
+      }
       menuManager.beginIntroSplash(
         includeRetailWarning: data.version == GameVersion.retail,
       );

packages/wolf_3d_dart/test/engine/level_state_and_pause_menu_test.dart

@@ -402,6 +402,48 @@ void main() {
       expect(quitCalls, 0);
       expect(exitCalls, 1);
     });
+
+    test('load availability is scoped to active game version', () async {
+      final persistence = _InMemorySaveGamePersistence(
+        saves: {
+          _InMemorySaveGamePersistence.key(
+            slot: 0,
+            version: GameVersion.shareware,
+          ): Uint8List.fromList(const <int>[
+            1,
+          ]),
+        },
+      );
+
+      final retailEngine = WolfEngine(
+        data: _buildTestData(gameVersion: GameVersion.retail),
+        difficulty: null,
+        startingEpisode: 0,
+        frameBuffer: FrameBuffer(64, 64),
+        input: _TestInput(),
+        engineAudio: _SilentAudio(),
+        saveGamePersistence: persistence,
+        onGameWon: () {},
+      );
+      retailEngine.init();
+      await Future<void>.delayed(Duration.zero);
+
+      final sharewareEngine = WolfEngine(
+        data: _buildTestData(gameVersion: GameVersion.shareware),
+        difficulty: null,
+        startingEpisode: 0,
+        frameBuffer: FrameBuffer(64, 64),
+        input: _TestInput(),
+        engineAudio: _SilentAudio(),
+        saveGamePersistence: persistence,
+        onGameWon: () {},
+      );
+      sharewareEngine.init();
+      await Future<void>.delayed(Duration.zero);
+
+      expect(retailEngine.hasLoadableSave, isFalse);
+      expect(sharewareEngine.hasLoadableSave, isTrue);
+    });
   });
 }
 
@@ -410,6 +452,7 @@ WolfEngine _buildMultiGameEngine({
   required Difficulty? difficulty,
   void Function()? onMenuExit,
   void Function()? onQuit,
+  SaveGamePersistence? saveGamePersistence,
 }) {
   final WolfensteinData retail = _buildTestData(
     gameVersion: GameVersion.retail,
@@ -425,6 +468,7 @@ WolfEngine _buildMultiGameEngine({
     frameBuffer: FrameBuffer(64, 64),
     input: input,
     engineAudio: _SilentAudio(),
+    saveGamePersistence: saveGamePersistence,
     onGameWon: () {},
     onMenuExit: onMenuExit,
     onQuit: onQuit,
@@ -585,10 +629,43 @@ class _SilentAudio implements EngineAudio {
   void dispose() {}
 }
 
+class _InMemorySaveGamePersistence implements SaveGamePersistence {
+  _InMemorySaveGamePersistence({Map<String, Uint8List>? saves})
+    : _saves = saves ?? <String, Uint8List>{};
+
+  final Map<String, Uint8List> _saves;
+
+  static String key({required int slot, required GameVersion version}) =>
+      '${version.name}:$slot';
+
+  @override
+  Future<Uint8List?> load({
+    required int slot,
+    required GameVersion version,
+  }) async {
+    return _saves[key(slot: slot, version: version)];
+  }
+
+  @override
+  Future<bool> exists({required int slot, required GameVersion version}) async {
+    final Uint8List? bytes = _saves[key(slot: slot, version: version)];
+    return bytes != null && bytes.isNotEmpty;
+  }
+
+  @override
+  Future<void> save({
+    required int slot,
+    required GameVersion version,
+    required Uint8List bytes,
+  }) async {
+    _saves[key(slot: slot, version: version)] = Uint8List.fromList(bytes);
+  }
+}
+
 void _dismissIntroSplash(WolfEngine engine, _TestInput input) {
   int safety = 0;
   while (engine.menuManager.activeMenu == WolfMenuScreen.introSplash &&
-      safety < 160) {
+      safety < 600) {
     input.isInteracting = safety.isEven;
     engine.tick(const Duration(milliseconds: 16));
     safety++;

packages/wolf_3d_dart/test/engine/save_game_codec_test.dart

@@ -109,10 +109,10 @@ void main() {
     expect(decoded.createdAtMs, 999);
     expect(decoded.gameVersion, engine.data.version);
     expect(
-      decoded.snapshot.activeEpisodeIndex,
-      file.snapshot.activeEpisodeIndex,
+      decoded.snapshot.currentEpisodeIndex,
+      file.snapshot.currentEpisodeIndex,
     );
-    expect(decoded.snapshot.activeLevelIndex, file.snapshot.activeLevelIndex);
+    expect(decoded.snapshot.currentLevelIndex, file.snapshot.currentLevelIndex);
   });
 
   test('OriginalLayoutEnvelopeSaveGameCodec rejects invalid checksum', () {
@@ -140,6 +140,30 @@ void main() {
       throwsA(isA<FormatException>()),
     );
   });
+
+  test('CompatibleSaveGameCodec decodes legacy W3DS saves', () {
+    final WolfEngine engine = _buildEngine();
+    engine.init();
+
+    final SaveGameCodec legacyCodec = SaveGameCodec();
+    final SaveGameFile file = SaveGameFile(
+      slot: 1,
+      gameVersion: engine.data.version,
+      dataVersionName: engine.data.dataVersion.name,
+      description: 'Legacy Save',
+      createdAtMs: 777,
+      snapshot: engine.captureSaveState(),
+      checksum: 0,
+    );
+    final Uint8List legacyBytes = legacyCodec.encode(file);
+
+    final CompatibleSaveGameCodec compatibleCodec = CompatibleSaveGameCodec();
+    final SaveGameFile decoded = compatibleCodec.decode(legacyBytes);
+
+    expect(decoded.slot, 1);
+    expect(decoded.description, 'Legacy Save');
+    expect(decoded.createdAtMs, 777);
+  });
 }
 
 class _TestInput extends Wolf3dInput {