Escape opens a pause menu

Resume, sound, CRT, abandon the run, quit -- drawn over whatever is on screen,
with the game dimmed but still visible underneath, because that is what you
paused to look at.

It is a flag rather than a state. A state would have thrown away the combat,
the map or the shop underneath, and the point of pausing mid-fight is that the
fight is still there afterwards. That also makes it the easiest possible place
to leave an update path running by accident, so the test compares every
bullet's position across 120 paused frames rather than just checking that the
menu opened.

On a pad, Start is no longer a second confirm button: it opens and closes the
pause menu the way Start does everywhere else. The title screen has nothing to
pause, so there it stays a confirm.

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

Author: softpython2884

README.md

@@ -43,7 +43,7 @@ de riposter. La carte, elle, est un vrai choix — un atelier de réparation n'e
 proposé que dans 54 % des secteurs, sur une seule branche, jamais avant le boss.
 Zoom toujours entier, arène de taille fixe quelle que soit la résolution, et
 20 effets sonores synthétisés au démarrage (aucun fichier audio) —
-[à écouter](docs/nova-sound-demo.wav). Le tir étant automatique, `M` fait le
+[à écouter](docs/nova-sound-demo.wav). `Échap` met en pause. Le tir étant automatique, `M` fait le
 tour de trois réglages — tout, canon coupé, silence — parce que vouloir se
 passer du canon n'est pas vouloir se passer du son. Tout est dans
 [pc/README.md](pc/README.md).

pc/README.md

@@ -49,8 +49,8 @@ construit sur Windows.
 | `--no-crt` | Coupe les scanlines |
 | `--no-sound` | Démarre en muet |
 
-En jeu : `F11` plein écran · `F1` filtre CRT · `M` son (3 crans) ·
-`+`/`-` taille · la fenêtre est redimensionnable à la souris.
+En jeu : `Échap` pause · `F11` plein écran · `F1` filtre CRT · `M` son
+(3 crans) · `+`/`-` taille · la fenêtre est redimensionnable à la souris.
 
 ## Résolutions
 
@@ -177,6 +177,24 @@ plutôt que de planter.
 | Tirer | automatique | automatique |
 | Bombe | `Espace` ou `Maj` | partagée |
 | Menus | flèches + `Entrée` | |
+| Pause | `Échap`, ou `Start` à la manette | |
+
+### La pause
+
+`Échap` ouvre un menu par-dessus ce qui est à l'écran : reprendre, le son, le
+filtre CRT, abandonner la partie, quitter. Le combat reste **visible sous le
+voile**, parce qu'on met en pause justement pour le regarder.
+
+C'est un drapeau, pas un état de la machine à états. Un état aurait jeté le
+combat, la carte ou la boutique en dessous, et tout l'intérêt de mettre en
+pause au milieu d'un combat est que le combat soit encore là au retour. En
+revanche c'est aussi la façon la plus facile de laisser tourner une boucle de
+mise à jour par mégarde, alors le test compare les positions de chaque
+projectile avant et après cent vingt images de pause.
+
+À la manette, `Start` n'est plus un second bouton de validation : il ouvre et
+ferme la pause, comme partout ailleurs — sauf sur l'écran-titre, où il n'y a
+rien à mettre en pause et où il valide.
 
 ### Manette
 

pc/nova/game.py

@@ -54,6 +54,8 @@ def __init__(self, scale=3, fullscreen=False, crt=True, sound=True):
         self.difficulty = 1
         self.players = 1
         self.toast = None
+        self.paused = False
+        self.pause_menu = None
         self.enter_title()
         self.audio.music(0, 0)
 
@@ -127,6 +129,75 @@ def enter_title(self):
              "Leave the void alone."],
             [data.CYAN, data.VIOLET, data.ORANGE, data.GREY])
 
+    # Pause is a flag rather than a state.
+    #
+    # Every other screen is a state, but pause is the one thing that has to
+    # happen *on top of* whatever is already there: a state would throw away
+    # the combat, the map or the shop underneath, and the whole point of
+    # pausing mid-fight is that the fight is still there when you come back.
+    def toggle_pause(self):
+        if self.state in (TITLE, GAMEOVER):
+            return                      # nothing to come back to
+        self.paused = not self.paused
+        if self.paused:
+            self.build_pause_menu()
+            self.audio.play("menu_ok", 0.6)
+        else:
+            self.audio.play("menu_move")
+
+    def build_pause_menu(self):
+        crt = "ON" if self.crt_on else "OFF"
+        self.pause_menu = ui.Menu(
+            ["RESUME", "SOUND   " + self.audio.mode_name, "CRT     " + crt,
+             "ABANDON RUN", "QUIT"],
+            ["Back to it.",
+             "M does this too, mid-fight.",
+             "Scanlines. F1 does this too.",
+             "Give up this run and go back to the title.",
+             "Close the game."],
+            [data.CYAN, data.WHITE, data.WHITE, data.ORANGE, data.GREY])
+
+    def pause_key(self, e):
+        before = self.pause_menu.index
+        choice = self.pause_menu.key(e)
+        if self.pause_menu.index != before:
+            self.audio.play("menu_move")
+        if choice is None:
+            return
+        if choice == 0:
+            self.toggle_pause()
+        elif choice == 1:
+            self.toast = [self.audio.cycle_mute(), 1.6]
+            if not self.audio.muted:
+                self.audio.music(self.run.sector if self.run else 0,
+                                 self.run.seed if self.run else 0)
+            self.build_pause_menu()
+        elif choice == 2:
+            self.crt_on = not self.crt_on
+            self.build_pause_menu()
+        elif choice == 3:
+            self.paused = False
+            self.run = None
+            self.combat = None
+            self.audio.play("menu_no")
+            self.enter_title()
+            self.audio.music(0, 0)
+        elif choice == 4:
+            self.running = False
+
+    def draw_pause(self, c):
+        """Dim what is underneath, then the panel. The game stays visible on
+        purpose: you paused to look at it."""
+        w, h = c.get_size()
+        veil = pygame.Surface((w, h), pygame.SRCALPHA)
+        veil.fill((0, 0, 0, 170))
+        c.blit(veil, (0, 0))
+        ui.text(c, self.art, "PAUSED", w // 2, data.TOP + 18, data.CYAN,
+                centre=True, big=True)
+        self.pause_menu.draw(c, self.art, data.TOP + 54, self.t)
+        ui.text(c, self.art, "ESC or START to resume", w // 2, h - 16,
+                data.DARK, centre=True)
+
     def start_run(self, players):
         self.players = players
         self.run = Run(players, self.difficulty)
@@ -339,6 +410,14 @@ def handle_event(self, e):
             return
         if e.type != pygame.KEYDOWN:
             return
+        if e.key == pygame.K_ESCAPE:
+            self.toggle_pause()
+            return
+        if self.paused:
+            # Nothing else gets a look in: F11 and the rest would otherwise
+            # fire straight through the panel.
+            self.pause_key(e)
+            return
         if e.key == pygame.K_F11 or (e.key == pygame.K_RETURN and
                                      (e.mod & pygame.KMOD_ALT)):
             self.toggle_fullscreen()
@@ -440,12 +519,28 @@ def pad_menu(self):
         """Turn pad presses into the key events the menus already understand,
         so there is exactly one place that knows what a menu does."""
         for edge in self.pads.menu_edges():
-            key = {"up": pygame.K_UP, "down": pygame.K_DOWN,
-                   "confirm": pygame.K_RETURN, "back": pygame.K_BACKSPACE}[edge]
+            if edge == "start":
+                # Pause, except on the title where there is nothing to pause;
+                # there it is the confirm button people expect it to be.
+                key = (pygame.K_RETURN if self.state in (TITLE, GAMEOVER)
+                       else pygame.K_ESCAPE)
+            else:
+                key = {"up": pygame.K_UP, "down": pygame.K_DOWN,
+                       "confirm": pygame.K_RETURN,
+                       "back": pygame.K_BACKSPACE}[edge]
             self.handle_event(pygame.event.Event(pygame.KEYDOWN, key=key, mod=0))
 
     def update(self, dt):
         self.t += dt
+        if self.paused:
+            # The cursor still pulses and the toast still fades: a frozen menu
+            # looks like a crash. Nothing else advances.
+            if self.toast is not None:
+                self.toast[1] -= dt
+                if self.toast[1] <= 0:
+                    self.toast = None
+            self.pad_menu()
+            return
         self.flash.update(dt)
         if self.toast is not None:
             self.toast[1] -= dt
@@ -486,6 +581,9 @@ def draw(self):
             elif self.state == GAMEOVER:
                 self.draw_gameover(c)
 
+        if self.paused:
+            self.draw_pause(c)
+            ox = oy = 0
         if self.toast is not None:
             self.draw_toast(c)
 

pc/nova/gamepad.py

@@ -120,10 +120,15 @@ def menu_edges(self):
                 out.append("up")
             elif dy > 0:
                 out.append("down")
-        if (confirm and not prev[2]) or (start and not prev[4]):
+        if confirm and not prev[2]:
             out.append("confirm")
         elif back and not prev[3]:
             out.append("back")
+        if start and not prev[4]:
+            # Start is its own edge now rather than another confirm: it opens
+            # and closes the pause menu, which is what start does everywhere
+            # else, and the game decides what that means on the title screen.
+            out.append("start")
         self.prev[0] = (dx, dy, confirm, back, start)
         return out
 

pc/tests/test_run.py

@@ -163,6 +163,62 @@ def run_once(seed, players=1, difficulty=1):
             "fights": d.fights, "minutes": d.frames * DT / 60.0, "log": d.log}
 
 
+def test_pause():
+    """Escape freezes the fight and gives it back untouched.
+
+    The interesting half is not that the menu opens, it is that nothing moves
+    behind it. Pause is a flag over the existing screen rather than a state of
+    its own, which is what keeps the combat alive underneath -- and also what
+    makes it easy to leave one update path running by accident.
+    """
+    from nova.game import COMBAT, TITLE
+    g = Game(scale=1, crt=False, sound=False)
+    g.start_run(1)
+    g.run.seed = 3
+    g.run.rng = random.Random(3)
+    g.map = None
+    g.new_sector()
+    while g.state != COMBAT:                    # walk into the first fight
+        if g.state == MAP:
+            press(g, pygame.K_RETURN)
+        else:
+            press(g, pygame.K_RETURN)
+    for _ in range(240):                        # let the fight get going
+        g.update(DT)
+
+    press(g, pygame.K_ESCAPE)
+    assert g.paused, "escape did not pause"
+    before = (g.combat.time, len(g.combat.enemies), len(g.combat.shots),
+              g.run.hull, [(round(s.x, 3), round(s.y, 3))
+                           for s in g.combat.shots])
+    for _ in range(120):
+        g.update(DT)
+        g.draw()                                # drawing must be safe too
+    after = (g.combat.time, len(g.combat.enemies), len(g.combat.shots),
+             g.run.hull, [(round(s.x, 3), round(s.y, 3))
+                          for s in g.combat.shots])
+    assert before == after, "the fight moved while paused"
+
+    press(g, pygame.K_ESCAPE)
+    assert not g.paused, "escape did not resume"
+    for _ in range(60):
+        g.update(DT)
+    assert g.combat is None or g.combat.time > before[0], "the fight did not resume"
+
+    # abandoning goes back to the title, and the title cannot be paused
+    if g.state == COMBAT:
+        press(g, pygame.K_ESCAPE)
+        for _ in range(3):
+            press(g, pygame.K_DOWN)
+        press(g, pygame.K_RETURN)
+        assert g.state == TITLE, "abandon did not return to the title"
+        assert not g.paused
+    press(g, pygame.K_ESCAPE)
+    assert not g.paused, "the title screen must not pause"
+    print("  pause: freezes the fight, resumes it, abandons cleanly")
+    return True
+
+
 def test_boss_entrance():
     """A boss must not be damageable while it is holding fire.
 
@@ -257,6 +313,7 @@ def main():
 
     print()
     print("=== edge cases ===")
+    test_pause()
     test_boss_entrance()
     test_maxed_trader()
     print("  fully-upgraded ship: trader and salvage both handled")