Add hold-to-rewind (Backspace) to the single-player emulator

RewindManager keeps a rolling buffer of Gameboy mementos (one every 6
frames, 300 entries - about 30 seconds). Holding Backspace posts
Controller.RewindEvent(true); BasicController then restores one recorded
state per rendered frame and emulates a single frame from it, so the
game plays backwards at 6x speed with live video and audio. Releasing
the key resumes forward play from wherever the rewind stopped. History
is cleared on ROM load, reset and snapshot restore. Save-state slots
already existed in the Game menu; together they complete the
quality-of-life pair.

Verified headless: 4 s of Tetris, 1 s of rewind restores ~32 recorded
states and keeps rendering; controller and swing suites green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01J1wLWscyUGS7CFwc3CjJR8

Author: trekawek

controller/src/main/java/eu/rekawek/coffeegb/controller/BasicController.kt

@@ -31,6 +31,10 @@ class BasicController(
 
   private var isPaused = false
 
+  private var isRewinding = false
+
+  private val rewindManager = RewindManager()
+
   private val patches = mutableListOf<Patch>()
 
   private val thread = Thread {
@@ -44,6 +48,7 @@ class BasicController(
     eventQueue.register<Controller.LoadRomEvent> {
       stop()
       patches.clear()
+      rewindManager.clear()
       val config = Controller.createGameboyConfig(properties, Rom(it.rom))
       session = createSession(config)
       if (it.memento != null) {
@@ -55,6 +60,7 @@ class BasicController(
     eventQueue.register<Controller.SaveSnapshotEvent> { e -> saveSnapshot(e.slot) }
     eventQueue.register<Controller.PauseEmulationEvent> { isPaused = true }
     eventQueue.register<Controller.ResumeEmulationEvent> { isPaused = false }
+    eventQueue.register<Controller.RewindEvent> { isRewinding = it.active }
     eventQueue.register<Controller.ResetEmulationEvent> { reset() }
     eventQueue.register<Controller.StopEmulationEvent> { stop() }
     eventQueue.register<Controller.UpdatedSystemMappingEvent> {
@@ -74,12 +80,21 @@ class BasicController(
   private fun runFrame() {
     eventQueue.dispatch()
 
+    // rewinding restores one recorded state and then emulates a single frame from it,
+    // so the display and audio play backwards at RewindManager.RECORD_INTERVAL speed
+    val rewound = isRewinding && session?.gameboy?.let { rewindManager.rewindOneStep(it) } == true
+
+    var emulated = false
     repeat(TICKS_PER_FRAME) {
-      if (!isPaused) {
+      if (rewound || (!isPaused && !isRewinding)) {
         session?.gameboy?.tick()
+        emulated = true
       }
       timingTicker.run()
     }
+    if (emulated && !rewound) {
+      session?.gameboy?.let { rewindManager.record(it) }
+    }
   }
 
   private fun createSession(config: Gameboy.GameboyConfiguration) =
@@ -109,6 +124,7 @@ class BasicController(
     val session = session ?: return
     val config = session.config
     stop()
+    rewindManager.clear()
     this.session = createSession(config)
     start()
   }
@@ -119,6 +135,7 @@ class BasicController(
 
   private fun loadSnapshot(slot: Int) {
     session?.gameboy?.let { snapshotManager?.loadSnapshot(slot, it) }
+    rewindManager.clear()
   }
 
   override fun snapshotAvailable(slot: Int): Boolean {

controller/src/main/java/eu/rekawek/coffeegb/controller/Controller.kt

@@ -41,6 +41,9 @@ interface Controller : AutoCloseable {
 
   data class GameboyTypeEvent(val gameboyType: GameboyType) : Event
 
+  /** Posted while the rewind key is held; the emulation plays backwards while active. */
+  data class RewindEvent(val active: Boolean) : Event
+
   data class ControllerState(val memento: Memento<Gameboy>, val rom: Rom)
 
   companion object {

controller/src/main/java/eu/rekawek/coffeegb/controller/RewindManager.kt

@@ -0,0 +1,45 @@
+package eu.rekawek.coffeegb.controller
+
+import eu.rekawek.coffeegb.core.Gameboy
+import eu.rekawek.coffeegb.core.memento.Memento
+
+/**
+ * Rolling history of emulation states for the rewind feature. A state is recorded every
+ * [RECORD_INTERVAL] frames and the buffer holds [CAPACITY] entries, giving about
+ * CAPACITY * RECORD_INTERVAL / 60 seconds of history. Rewinding restores one recorded
+ * state per rendered frame, so it plays backwards at RECORD_INTERVAL times the game speed.
+ */
+class RewindManager {
+
+  private val states = ArrayDeque<Memento<Gameboy>>()
+
+  private var frameCounter = 0
+
+  fun record(gameboy: Gameboy) {
+    if (frameCounter++ % RECORD_INTERVAL != 0) {
+      return
+    }
+    if (states.size == CAPACITY) {
+      states.removeFirst()
+    }
+    states.addLast(gameboy.saveToMemento())
+  }
+
+  /** Restores the most recent recorded state; returns false when the history is empty. */
+  fun rewindOneStep(gameboy: Gameboy): Boolean {
+    val state = states.removeLastOrNull() ?: return false
+    gameboy.restoreFromMemento(state)
+    return true
+  }
+
+  fun clear() {
+    states.clear()
+    frameCounter = 0
+  }
+
+  companion object {
+    const val RECORD_INTERVAL = 6
+
+    const val CAPACITY = 300
+  }
+}

swing/src/main/java/eu/rekawek/coffeegb/swing/io/SwingJoypad.java

@@ -1,5 +1,6 @@
 package eu.rekawek.coffeegb.swing.io;
 
+import eu.rekawek.coffeegb.controller.Controller;
 import eu.rekawek.coffeegb.core.joypad.Button;
 import eu.rekawek.coffeegb.core.joypad.ButtonPressEvent;
 import eu.rekawek.coffeegb.core.joypad.ButtonReleaseEvent;
@@ -11,10 +12,14 @@
 
 public class SwingJoypad implements KeyListener {
 
+    private static final int REWIND_KEY = KeyEvent.VK_BACK_SPACE;
+
     private final Map<Integer, Button> mapping;
 
     private final EventBus eventBus;
 
+    private boolean rewindActive;
+
     public SwingJoypad(Map<Integer, Button> mapping, EventBus eventBus) {
         this.mapping = mapping;
         this.eventBus = eventBus;
@@ -26,6 +31,14 @@ public void keyTyped(KeyEvent e) {
 
     @Override
     public void keyPressed(KeyEvent e) {
+        if (e.getKeyCode() == REWIND_KEY) {
+            // holding the key auto-repeats; post only on the state change
+            if (!rewindActive) {
+                rewindActive = true;
+                eventBus.post(new Controller.RewindEvent(true));
+            }
+            return;
+        }
         Button b = getButton(e);
         if (b != null) {
             eventBus.post(new ButtonPressEvent(b));
@@ -34,6 +47,11 @@ public void keyPressed(KeyEvent e) {
 
     @Override
     public void keyReleased(KeyEvent e) {
+        if (e.getKeyCode() == REWIND_KEY) {
+            rewindActive = false;
+            eventBus.post(new Controller.RewindEvent(false));
+            return;
+        }
         Button b = getButton(e);
         if (b != null) {
             eventBus.post(new ButtonReleaseEvent(b));