feat: Refactor game persistence and rendering management for CLI and Flutter hosts

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

apps/wolf_3d_cli/bin/main.dart

@@ -7,11 +7,11 @@ library;
 import 'dart:io';
 
 import 'package:args/args.dart';
-import 'package:wolf_3d_cli/cli_game_loop.dart';
 import 'package:wolf_3d_dart/wolf_3d_audio.dart';
 import 'package:wolf_3d_dart/wolf_3d_data.dart';
 import 'package:wolf_3d_dart/wolf_3d_data_types.dart';
 import 'package:wolf_3d_dart/wolf_3d_engine.dart';
+import 'package:wolf_3d_dart/wolf_3d_host.dart';
 import 'package:wolf_3d_dart/wolf_3d_input.dart';
 
 /// Restores terminal state before exiting the process with [code].

apps/wolf_3d_cli/lib/cli_game_loop.dart

@@ -1,241 +0,0 @@
-/// Terminal game loop that ties engine ticks, raw input, and CLI rendering together.
-library;
-
-import 'dart:async';
-import 'dart:io';
-
-import 'package:wolf_3d_dart/wolf_3d_engine.dart';
-import 'package:wolf_3d_dart/wolf_3d_input.dart';
-import 'package:wolf_3d_dart/wolf_3d_renderer.dart';
-
-/// Runs the Wolf3D engine inside a terminal using CLI-specific renderers.
-///
-/// The loop owns raw-stdin handling, renderer switching, terminal size checks,
-/// and frame pacing. It expects [engine.input] to be a [CliInput] instance so
-/// raw key bytes can be queued directly into the engine input adapter.
-class CliGameLoop {
-  CliGameLoop({
-    required this.engine,
-    required this.onExit,
-    this.persistence,
-    this.initialSettings,
-  }) : input = engine.input is CliInput
-           ? engine.input as CliInput
-           : throw ArgumentError.value(
-               engine.input,
-               'engine.input',
-               'CliGameLoop requires a CliInput instance.',
-             ),
-
-       primaryRenderer = SixelRenderer(),
-       secondaryRenderer = AsciiRenderer(
-         mode: AsciiRendererMode.terminalAnsi,
-       ) {
-    _renderer = primaryRenderer;
-  }
-
-  final WolfEngine engine;
-  final CliRendererBackend primaryRenderer;
-  final CliRendererBackend secondaryRenderer;
-  final CliInput input;
-  final void Function(int code) onExit;
-  final RendererSettingsPersistence? persistence;
-  final WolfRendererSettings? initialSettings;
-
-  final Stopwatch _stopwatch = Stopwatch();
-  final Stream<List<int>> _stdinStream = stdin.asBroadcastStream();
-  late CliRendererBackend _renderer;
-  StreamSubscription<List<int>>? _stdinSubscription;
-  Timer? _timer;
-  bool _isRunning = false;
-  bool _isSixelAvailable = false;
-  Duration _lastTick = Duration.zero;
-
-  /// Starts terminal probing, enters raw input mode, and begins the frame timer.
-  Future<void> start() async {
-    if (_isRunning) {
-      return;
-    }
-
-    if (primaryRenderer is SixelRenderer) {
-      final sixel = primaryRenderer as SixelRenderer;
-      sixel.isSixelSupported = await SixelRenderer.checkTerminalSixelSupport(
-        inputStream: _stdinStream,
-      );
-      _isSixelAvailable = sixel.isSixelSupported;
-    } else {
-      _isSixelAvailable = false;
-    }
-
-    final Set<WolfRendererMode> supportedModes = <WolfRendererMode>{
-      WolfRendererMode.ascii,
-      if (_isSixelAvailable) WolfRendererMode.sixel,
-    };
-    engine.setRendererCapabilities(
-      WolfRendererCapabilities(
-        supportedModes: supportedModes,
-        supportsAsciiThemes: true,
-        supportsFpsCounter: true,
-      ),
-    );
-
-    if (initialSettings != null) {
-      engine.updateRendererSettings(initialSettings!);
-    } else if (_isSixelAvailable) {
-      engine.updateRendererSettings(
-        engine.rendererSettings.copyWith(mode: WolfRendererMode.sixel),
-      );
-    }
-
-    _syncRendererFromEngine();
-
-    if (stdin.hasTerminal) {
-      try {
-        stdin.echoMode = false;
-        stdin.lineMode = false;
-      } catch (_) {
-        // Keep running without raw mode when stdin is not mutable.
-      }
-    }
-
-    // Disable Sixel scrolling mode so frames overwrite in-place.
-    stdout.write('\x1b[?80l\x1b[?25l\x1b[2J');
-
-    _stdinSubscription = _stdinStream.listen(_handleInput);
-    _stopwatch.start();
-    _timer = Timer.periodic(const Duration(milliseconds: 33), _tick);
-    _isRunning = true;
-  }
-
-  /// Stops the timer, unsubscribes from stdin, and restores terminal settings.
-  void stop() {
-    if (!_isRunning) {
-      return;
-    }
-
-    _timer?.cancel();
-    _timer = null;
-    _stdinSubscription?.cancel();
-    _stdinSubscription = null;
-
-    if (_stopwatch.isRunning) {
-      _stopwatch.stop();
-    }
-
-    if (stdin.hasTerminal) {
-      try {
-        stdin.echoMode = true;
-        stdin.lineMode = true;
-      } catch (_) {
-        // Ignore cleanup failures if stdin is no longer a mutable TTY.
-      }
-    }
-
-    if (stdout.hasTerminal) {
-      // Restore scrolling Sixel mode and cursor visibility.
-      stdout.write('\x1b[0m\x1b[?80h\x1b[?25h');
-    }
-
-    _isRunning = false;
-  }
-
-  void _handleInput(List<int> bytes) {
-    // Keep q and Ctrl+C as hard exits; ESC is now menu-back input.
-    if (bytes.contains(113) || bytes.contains(3)) {
-      stop();
-      onExit(0);
-      return;
-    }
-
-    if (input.matchesRendererToggleShortcut(bytes)) {
-      engine.cycleRendererMode();
-      _syncRendererFromEngine();
-      unawaited(persistence?.save(engine.rendererSettings));
-      stdout.write('\x1b[2J\x1b[H');
-      return;
-    }
-
-    if (input.matchesAsciiThemeCycleShortcut(bytes)) {
-      engine.cycleAsciiTheme();
-      _syncRendererFromEngine();
-      unawaited(persistence?.save(engine.rendererSettings));
-      return;
-    }
-
-    if (input.matchesFpsToggleShortcut(bytes)) {
-      engine.toggleFpsCounter();
-      _syncRendererFromEngine();
-      unawaited(persistence?.save(engine.rendererSettings));
-      return;
-    }
-
-    input.handleKey(bytes);
-  }
-
-  void _syncRendererFromEngine() {
-    final CliRendererBackend previousRenderer = _renderer;
-    final WolfRendererMode mode = engine.rendererSettings.mode;
-    if (mode == WolfRendererMode.sixel && _isSixelAvailable) {
-      _renderer = primaryRenderer;
-    } else {
-      _renderer = secondaryRenderer;
-    }
-
-    final AsciiTheme theme =
-        engine.rendererSettings.asciiThemeId ==
-            WolfRendererSettings.asciiThemeQuadrant
-        ? AsciiThemes.quadrant
-        : AsciiThemes.blocks;
-    if (primaryRenderer is AsciiRenderer) {
-      (primaryRenderer as AsciiRenderer).activeTheme = theme;
-    }
-    if (secondaryRenderer is AsciiRenderer) {
-      (secondaryRenderer as AsciiRenderer).activeTheme = theme;
-    }
-
-    engine.showFpsCounter = engine.rendererSettings.fpsCounterEnabled;
-
-    if (!identical(previousRenderer, _renderer) && stdout.hasTerminal) {
-      // Clear stale frame content when switching backend output modes.
-      stdout.write('\x1b[2J\x1b[H');
-    }
-  }
-
-  void _tick(Timer timer) {
-    if (!_isRunning) {
-      return;
-    }
-
-    // Apply renderer changes made via in-game menus or settings updates.
-    _syncRendererFromEngine();
-
-    if (stdout.hasTerminal) {
-      final int cols = stdout.terminalColumns;
-      final int rows = stdout.terminalLines;
-      if (!_renderer.prepareTerminalFrame(
-        engine,
-        columns: cols,
-        rows: rows,
-      )) {
-        // Size warnings are rendered instead of running the simulation so the
-        // game does not keep advancing while the user resizes the terminal.
-        stdout.write('\x1b[2J\x1b[H');
-        stdout.write(
-          _renderer.buildTerminalSizeWarning(columns: cols, rows: rows),
-        );
-
-        _lastTick = _stopwatch.elapsed;
-        return;
-      }
-    }
-
-    final Duration currentTick = _stopwatch.elapsed;
-    final Duration elapsed = currentTick - _lastTick;
-    _lastTick = currentTick;
-
-    stdout.write('\x1b[H');
-
-    engine.tick(elapsed);
-    stdout.write(_renderer.render(engine));
-  }
-}

apps/wolf_3d_cli/lib/cli_renderer_settings_persistence.dart

@@ -1,58 +0,0 @@
-/// CLI host adapter for persisting renderer settings to a local file.
-library;
-
-import 'dart:io';
-
-import 'package:wolf_3d_dart/wolf_3d_engine.dart';
-
-/// Persists [WolfRendererSettings] as JSON to a local file.
-///
-/// The default path is `~/.wolf3d_cli_settings.json`.
-/// An alternative [filePath] can be supplied at construction time.
-class CliRendererSettingsPersistence extends RendererSettingsPersistence
-    with JsonRendererSettingsPersistence {
-  CliRendererSettingsPersistence({String? filePath})
-    : _filePath = filePath ?? '${_platformConfigDir()}/settings.json';
-
-  final String _filePath;
-
-  @override
-  Future<String?> readRaw() async {
-    try {
-      final File f = File(_filePath);
-      if (!f.existsSync()) {
-        return null;
-      }
-      return await f.readAsString();
-    } catch (_) {
-      return null;
-    }
-  }
-
-  @override
-  Future<void> writeRaw(String json) async {
-    try {
-      await File(_filePath).writeAsString(json, flush: true);
-    } catch (_) {
-      // Best-effort; never crash the loop on a write failure.
-    }
-  }
-}
-
-String _platformConfigDir() {
-  if (Platform.isLinux) {
-    final String xdg = Platform.environment['XDG_CONFIG_HOME'] ?? '';
-    final String home = Platform.environment['HOME'] ?? '.';
-    return xdg.isNotEmpty ? '$xdg/wolf3d' : '$home/.config/wolf3d';
-  }
-  if (Platform.isMacOS) {
-    final String home = Platform.environment['HOME'] ?? '.';
-    return '$home/Library/Application Support/wolf3d';
-  }
-  if (Platform.isWindows) {
-    final String appData = Platform.environment['APPDATA'] ?? '.';
-    return '$appData/wolf3d';
-  }
-  final String home = Platform.environment['HOME'] ?? '.';
-  return '$home/.config/wolf3d';
-}

apps/wolf_3d_cli/lib/cli_save_game_persistence.dart

@@ -1,84 +0,0 @@
-library;
-
-import 'dart:io';
-import 'dart:typed_data';
-
-import 'package:wolf_3d_dart/wolf_3d_data_types.dart';
-import 'package:wolf_3d_dart/wolf_3d_engine.dart';
-
-/// CLI host adapter for slot-based game save persistence.
-///
-/// Files are stored under `~/.wolf3d_saves` by default and named
-/// `SAVEGAM{slot}.{ext}` where `{ext}` follows the active game version.
-class CliSaveGamePersistence implements SaveGamePersistence {
-  CliSaveGamePersistence({String? directoryPath})
-    : _directoryPath = directoryPath ?? '${_platformConfigDir()}/saves';
-
-  final String _directoryPath;
-
-  @override
-  Future<Uint8List?> load({
-    required int slot,
-    required GameVersion version,
-  }) async {
-    try {
-      final File file = File(_slotPath(slot, version));
-      if (!file.existsSync()) {
-        return null;
-      }
-      return await file.readAsBytes();
-    } catch (_) {
-      return null;
-    }
-  }
-
-  @override
-  Future<bool> exists({
-    required int slot,
-    required GameVersion version,
-  }) async {
-    try {
-      final File file = File(_slotPath(slot, version));
-      return file.existsSync() && file.lengthSync() > 0;
-    } catch (_) {
-      return false;
-    }
-  }
-
-  @override
-  Future<void> save({
-    required int slot,
-    required GameVersion version,
-    required Uint8List bytes,
-  }) async {
-    final Directory dir = Directory(_directoryPath);
-    if (!dir.existsSync()) {
-      await dir.create(recursive: true);
-    }
-
-    await File(_slotPath(slot, version)).writeAsBytes(bytes, flush: true);
-  }
-
-  String _slotPath(int slot, GameVersion version) {
-    final String normalizedSlot = slot.clamp(0, 9).toString();
-    return '$_directoryPath/SAVEGAM$normalizedSlot.${version.fileExtension}';
-  }
-}
-
-String _platformConfigDir() {
-  if (Platform.isLinux) {
-    final String xdg = Platform.environment['XDG_CONFIG_HOME'] ?? '';
-    final String home = Platform.environment['HOME'] ?? '.';
-    return xdg.isNotEmpty ? '$xdg/wolf3d' : '$home/.config/wolf3d';
-  }
-  if (Platform.isMacOS) {
-    final String home = Platform.environment['HOME'] ?? '.';
-    return '$home/Library/Application Support/wolf3d';
-  }
-  if (Platform.isWindows) {
-    final String appData = Platform.environment['APPDATA'] ?? '.';
-    return '$appData/wolf3d';
-  }
-  final String home = Platform.environment['HOME'] ?? '.';
-  return '$home/.config/wolf3d';
-}