afterglow/game.py

Part of Afterglow.

"""Afterglow game root: the full state machine that hosts the flagship demo.

``GameRoot`` is the App root node and the single long-lived host for everything:
the 3D diorama scene, the post-processing environment, the lighting rig, the
game-feel effects layer, per-world music, the HUD, and the menu screens. It runs
a small explicit state machine and swaps the active UI screen by add/remove child
(never a whole-App scene change), so the 3D scene and audio survive transitions:

    TITLE  ->  LEVEL_SELECT  ->  PLAY(room)  ->  RESULTS
                                   ^  |
                          PAUSE / OPTIONS overlays

* TITLE shows a slowly idle-rotating 3D diorama behind the menu for flair.
* LEVEL_SELECT lists worlds/rooms from ``Progress`` (best times, shards, locks).
* PLAY builds the per-room 3D view, reads input via ``controls.read_player_input``,
  steps the sim, forwards events to ``Effects``, and syncs view + camera + HUD.
  Death respawns instantly; a win records progress and advances to the next room
  (or to RESULTS at the end of a world, unlocking the next).
* PAUSE / OPTIONS overlay PLAY without tearing down the room. Options apply live
  (volumes, screenshake, photosensitive-safe, assist toggles) and persist.

Progress loads on boot and saves on every meaningful change and on exit.
"""

from __future__ import annotations

import logging
import math
import os
import sys

from afterglow.assets import audio
from afterglow.progress import Progress
from afterglow.sim.entities import GLOW_FROM_ORB
from afterglow.sim.room import Room
from afterglow.sim.rooms_data import WORLDS
from afterglow.ui import menus
from afterglow.ui.controls import ControlHints, RoomIntro, TouchControls, read_player_input, should_show_touch
from afterglow.ui.hud import HUD
from afterglow.ui.menus import LevelSelect, OptionsMenu, PauseMenu, ResultsScreen, TitleScreen
from afterglow.view.camera import WORLD_SCALE, GameCamera
from afterglow.view.diorama import Diorama
from afterglow.view.effects import Effects
from afterglow.view.environment import per_world_environment
from afterglow.view.lighting import setup_world_lights
from afterglow.view.sprites import EntityView
from afterglow.view.title_backdrop import TitleBackdrop
from simvx.core import (
    AnchorPreset,
    AudioBusLayout,
    AudioPlayer,
    Input,
    JoyButton,
    Key,
    Label,
    Node,
    Node3D,
    Quat,
    Vec3,
)

log = logging.getLogger(__name__)

# Game states.
TITLE = "title"
LEVEL_SELECT = "level_select"
PLAY = "play"
RESULTS = "results"

#: Real-time delay (seconds) between death and instant respawn.
RESPAWN_DELAY = 0.4

#: Real-time pause (seconds) after reaching the exit before advancing / showing
#: results, so the next room / menu does not appear under still-held keys.
WIN_DELAY = 0.9

#: World ids in play order (mirrors WORLDS / progress.WORLD_ORDER).
_WORLD_ORDER = [w["id"] for w in WORLDS]
_WORLD_BY_ID = {w["id"]: w for w in WORLDS}

#: Screenshot/gallery affordance ONLY: when ``AFTERGLOW_COVER=glade:3`` (worldid:roomidx)
#: is set, the game boots straight into that play room instead of the title screen
#: and runs a tiny scripted "walk right" so the no-input gallery thumbnail captures a
#: Wisp-in-room moment rather than the menu. Unset in every normal run; never affects
#: gameplay, input, or progress. The value defaults to a hand-picked glade room.
_COVER_ENV = "AFTERGLOW_COVER"

#: Self-diagnosing console trace. When ``AFTERGLOW_DEBUG`` is set in the
#: environment the game prints a ``[afterglow]`` line on every room entry, death,
#: reset/respawn, win/advance and ``_enter_play`` call, plus a once-per-second
#: fps/dt heartbeat while playing. Captured once at import so the per-frame path
#: is a single bool test (zero work when unset).
_DEBUG = bool(os.environ.get("AFTERGLOW_DEBUG"))


def _dbg(msg: str) -> None:
    """Print one ``[afterglow]`` trace line (no-op unless ``AFTERGLOW_DEBUG`` set)."""
    if _DEBUG:
        print(f"[afterglow] {msg}", flush=True)


#: Assist tuning.
_ASSIST_SLOW_SCALE = 0.6  # time scale when "slow time" assist is on
_EXTENDED_GLOW = 8.0  # glow_timer floor topped up each frame under extended-glow


def _world_room_count(world_id: str) -> int:
    world = _WORLD_BY_ID.get(world_id)
    return len(world["rooms"]) if world else 0


class GameRoot(Node):
    """Full Afterglow game: state machine hosting the 3D scene + menus + audio."""

    # Declared at class scope so the web exporter auto-registers them (it
    # instantiates the root without running ``main()``). Keyboard + gamepad.
    input_actions = {
        "move_left": [Key.LEFT, Key.A, JoyButton.DPAD_LEFT],
        "move_right": [Key.RIGHT, Key.D, JoyButton.DPAD_RIGHT],
        "move_up": [Key.UP, Key.W, JoyButton.DPAD_UP],
        "move_down": [Key.DOWN, Key.S, JoyButton.DPAD_DOWN],
        "jump": [Key.SPACE, JoyButton.A],
        "dash": [Key.LEFT_SHIFT, Key.J, JoyButton.X],
        "pause": [Key.ESCAPE, JoyButton.START],
        # NB: confirm is Enter / gamepad-A only, NOT Space. Space is the jump key;
        # binding it to confirm too let a still-focused menu button re-fire on every
        # in-game jump and restart the room.
        "confirm": [Key.ENTER, JoyButton.A],
        "back": [Key.ESCAPE, JoyButton.B],
        "restart": [Key.R],
    }

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.progress = Progress.load()
        self.state = TITLE

        # 3D scene host (everything 3D lives under this one node).
        self._scene: Node3D | None = None
        self._env = None
        self._diorama: Diorama | None = None
        self._entities: EntityView | None = None
        self._camera: GameCamera | None = None
        self._title_backdrop: TitleBackdrop | None = None
        self._lights = None
        self._effects: Effects | None = None
        self._music: AudioPlayer | None = None
        self._music_world: str | None = None

        # Active room + location.
        self.room: Room | None = None
        self._world_id = _WORLD_ORDER[0]
        self._room_index = 0
        self._respawn_timer = 0.0
        self._win_timer = 0.0
        self._title_spin = 0.0
        self._cover_walk: float | None = None  # screenshot-only scripted walk timer
        self._dbg_was_dead = False  # AFTERGLOW_DEBUG: death-edge detection
        self._dbg_hb = 0.0  # AFTERGLOW_DEBUG: fps heartbeat accumulator

        # Per-world / run tallies for the results screen.
        self._world_time = 0.0
        self._world_deaths = 0
        self._world_shards = 0

        # UI: persistent HUD + touch overlay + the one active menu screen.
        self._hud: HUD | None = None
        self._touch: TouchControls | None = None
        self._intro: RoomIntro | None = None  # fading room-name card on entry
        self._hints: ControlHints | None = None  # first-room control cheat-sheet
        self._loading: Label | None = None  # "Loading" indicator during scene build
        self._build_pending = False  # defer the heavy scene build one frame
        self._screen = None  # current menu overlay (Control) or None during PLAY

        # Assist toggles the OptionsMenu offers but the Progress schema does not
        # persist (infinite dash, extended glow): tracked locally, in-memory only.
        self._assist_extra: dict[str, bool] = {
            "assist_infinite_dash": False,
            "assist_extended_glow": False,
        }

    # -- lifecycle ---------------------------------------------------------

    def on_ready(self) -> None:
        self._scene = self.add_child(Node3D(name="Scene3D"))
        self._effects = Effects(
            reduced_motion=bool(self.progress.get_option("photosensitive_safe")),
            screenshake_enabled=bool(self.progress.get_option("screenshake")),
        )
        self._apply_audio_volumes()
        # Menus are audio-free on their own; hand them a sink so navigating and
        # confirming are audible (and follow the SFX volume slider).
        menus.play_sound = self._play_ui_sfx
        # Re-evaluate the touch overlay on every resize / orientation change so a
        # window shrunk small (or a device rotated to portrait) surfaces or hides
        # the virtual pad mid-room, not just at the next room load.
        self.tree.screen_resized.connect(self._refresh_touch)

        # Gallery/screenshot affordance (see ``_COVER_ENV``): boot straight into a
        # representative play room so the no-input thumbnail shows the game, not a
        # menu. No effect in normal runs (env var unset).
        cover = os.environ.get(_COVER_ENV)
        if cover:
            wid, _, idx = cover.partition(":")
            self._cover_walk = 0.0
            self._enter_play(wid or _WORLD_ORDER[0], int(idx or 0))
            return

        self._cover_walk = None
        self._enter_title()

    def on_update(self, dt: float) -> None:
        if self.state == TITLE:
            self._update_title(dt)
        elif self.state == PLAY:
            self._update_play(dt)
        # LEVEL_SELECT / RESULTS are pure UI: nothing to tick here.

    # ======================================================================
    # 3D scene (built once per room; reused across rooms of the same shape)
    # ======================================================================

    def _build_scene(self, world_id: str, room: Room) -> None:
        """(Re)build the whole 3D view + lighting + effects for ``room``.

        Music is deliberately NOT touched here: the looping per-world bed is owned
        by ``_play_music`` / ``_stop_music`` and must survive a scene rebuild. The
        caller (``_enter_play``) calls ``_play_music(world_id)`` after this, which
        is a no-op when the world is unchanged, so advancing to the next room of
        the SAME world keeps one continuous music player instead of tearing it
        down and spawning a fresh one (the audible per-room music restart).
        """
        scene = self._scene
        scene.clear_children()
        self._title_backdrop = None  # destroyed by clear_children above

        self._env = scene.add_child(per_world_environment(world_id))
        self._diorama = scene.add_child(Diorama())
        self._diorama.build(room)
        self._entities = scene.add_child(EntityView())
        self._entities.build(room)
        self._camera = scene.add_child(GameCamera())
        self._camera.frame_room(room)
        self._lights = setup_world_lights(world_id, room.w, room.h).add_to(scene)

        # clear_children() above destroyed the previous room's pooled emitters and
        # ambient motes; drop the stale references so attach rebuilds them here.
        self._effects.reset()
        self._effects.attach(scene, self._camera, self.app)
        self._effects.set_ambient_centre(Vec3(room.w * 0.5, -room.h * 0.5, 0.0))
        self._sync_lights()

    def _sync_lights(self) -> None:
        if self._lights is None or self.room is None:
            return
        p = self.room.player
        pos = Vec3(p.cx * WORLD_SCALE, -p.cy * WORLD_SCALE, 0.0)
        self._lights.update(pos, glowing=p.glowing)

    def _teardown_scene(self) -> None:
        """Drop the 3D view (used when returning to the title's idle diorama)."""
        if self._scene is not None:
            self._scene.clear_children()
        self._env = self._diorama = self._entities = self._camera = None
        self._title_backdrop = None
        self._lights = None
        self._stop_music()

    # ======================================================================
    # Music
    # ======================================================================

    def _play_music(self, world_id: str) -> None:
        if self._music_world == world_id:
            return
        self._stop_music()
        self._music = AudioPlayer(stream=audio.build_music(world_id), bus=audio.MUSIC_BUS)
        self._music.loop = True
        self._music.autoplay = True
        self.add_child(self._music)
        self._music_world = world_id

    def _stop_music(self) -> None:
        if self._music is not None:
            # Stop the channel NOW: destroy() only removes the node (and fires the
            # AudioPlayer's stop-on-exit) at end of frame, so without this the old
            # bed keeps playing over the newly started one for the rest of the
            # frame, layering two tracks on every world change.
            self._music.stop()
            self._music.destroy()
            self._music = None
        self._music_world = None

    # ======================================================================
    # TITLE
    # ======================================================================

    def _enter_title(self) -> None:
        self.state = TITLE
        self.room = None
        self._hide_play_overlays()
        # A CLEAN, intentional abstract backdrop (NOT a gameplay room): a dark
        # field of soft drifting motes over the environment's gradient sky, so
        # the menu never reads as a confusing blurred level behind it.
        scene = self._scene
        scene.clear_children()
        self._diorama = self._entities = None
        env = scene.add_child(per_world_environment(_WORLD_ORDER[0]))
        env.bloom_intensity = 1.2  # let the motes glow softly against the dark
        env.vignette_intensity = 0.42  # heavier vignette frames it as menu art
        self._title_backdrop = scene.add_child(TitleBackdrop(name="TitleBackdrop"))
        self._title_backdrop.build()
        self._camera = scene.add_child(GameCamera())
        self._frame_title_camera()
        setup_world_lights(_WORLD_ORDER[0]).add_to(scene)
        self._title_spin = 0.0
        self._play_music(_WORLD_ORDER[0])

        # Offer "Continue" only when there is progress to resume (the first
        # unfinished room is past the very first room).
        can_continue = self._first_unfinished() != (_WORLD_ORDER[0], 0)
        screen = TitleScreen(can_continue=can_continue, name="TitleScreen")
        screen.on_play = self._title_play
        screen.on_continue = self._title_continue
        screen.on_levels = self._enter_level_select
        screen.on_options = lambda: self._open_options(return_to=self._enter_title)
        screen.on_quit = self._quit
        self._set_screen(screen)

    def _frame_title_camera(self) -> None:
        """Point the camera at the abstract backdrop (centred on the origin)."""
        cam = self._camera
        if cam is None:
            return
        cam.position = Vec3(0.0, 0.0, 9.0)
        cam.look_at((0.0, 0.0, 0.0))

    def _update_title(self, dt: float) -> None:
        # Drift the decorative motes + a barely-there scene sway for life.
        if self._scene is None:
            return
        if self._title_backdrop is not None:
            self._title_backdrop.update(dt)
        self._title_spin += dt * 0.18
        self._scene.rotation = Quat.from_euler(0.0, math.sin(self._title_spin) * 0.06, 0.0)

    def _title_play(self) -> None:
        # Play always starts a fresh run at the very first room (completion data is
        # kept, so Level Select stars and Continue still work).
        self._enter_play(_WORLD_ORDER[0], 0)

    def _title_continue(self) -> None:
        # Continue resumes at the first not-yet-completed room of the first
        # unlocked world, else the first room.
        wid, idx = self._first_unfinished()
        self._enter_play(wid, idx)

    def _first_unfinished(self) -> tuple[str, int]:
        for wid in _WORLD_ORDER:
            if not self.progress.is_world_unlocked(wid):
                continue
            for i in range(_world_room_count(wid)):
                if not self.progress.is_completed(wid, i):
                    return wid, i
        return _WORLD_ORDER[0], 0

    # ======================================================================
    # LEVEL_SELECT
    # ======================================================================

    def _enter_level_select(self) -> None:
        self.state = LEVEL_SELECT
        self._hide_play_overlays()
        screen = LevelSelect(WORLDS, self.progress, screen_size=self.tree.screen_size, name="LevelSelect")
        screen.on_select = self._enter_play
        screen.on_back = self._enter_title
        self._set_screen(screen)

    # ======================================================================
    # PLAY
    # ======================================================================

    def _enter_play(self, world_id: str, room_index: int) -> None:
        if _DEBUG:
            caller = sys._getframe(1).f_code.co_name
            _dbg(f"_enter_play(world={world_id!r}, room={room_index}) called by {caller}()")
        if world_id not in _WORLD_BY_ID or not (0 <= room_index < _world_room_count(world_id)):
            world_id, room_index = _WORLD_ORDER[0], 0
        new_world = world_id != self._world_id or self.state != PLAY
        # Reset per-world tallies when starting a fresh world from the menu.
        if new_world:
            self._world_time = 0.0
            self._world_deaths = 0
            self._world_shards = 0

        self.state = PLAY
        self._world_id = world_id
        self._room_index = room_index
        self._scene.rotation = Quat()
        self.room = Room(_WORLD_BY_ID[world_id]["rooms"][room_index])
        self._respawn_timer = 0.0
        self._win_timer = 0.0

        # Cover/screenshot mode builds synchronously (no menus, deterministic frame).
        if self._cover_walk is not None:
            self._finish_enter_play()
            return
        # Normal play: defer the heavy diorama build one frame so the "Loading"
        # indicator paints first. The displayed frame stays "Loading" until the
        # build (which blocks the next frame) completes, so there is clear feedback
        # instead of an apparent hang/crash.
        self._set_screen(None)
        self._show_loading(True)
        self._build_pending = True

    def _finish_enter_play(self) -> None:
        """Build the deferred room scene + UI (runs the frame after _enter_play)."""
        self._build_scene(self._world_id, self.room)
        self._play_music(self._world_id)
        self._ensure_hud()
        self._refresh_touch()
        self._show_room_intro(self._world_id, self._room_index)
        self._show_loading(False)
        self._set_screen(None)

        if _DEBUG:
            p = self.room.player
            _dbg(
                f"ENTER ROOM world={self._world_id!r} index={self._room_index} "
                f"name={self.room.name!r} spawn=({p.x:.1f},{p.y:.1f})"
            )
        # Per-frame death/respawn edge detection + fps heartbeat (debug-only).
        self._dbg_was_dead = False
        self._dbg_hb = 0.0

    def _show_loading(self, on: bool) -> None:
        """Show / hide a centred 'Loading' indicator while a room scene builds."""
        if on:
            if self._loading is None:
                lbl = Label(text="Loading…", name="Loading")
                lbl.set_anchor_preset(AnchorPreset.CENTER)
                lbl.alignment = "center"
                self._loading = self.add_child(lbl)
            self._loading.visible = True
        elif self._loading is not None:
            self._loading.visible = False

    def _show_room_intro(self, world_id: str, room_index: int) -> None:
        """Flash the room's name on entry (so resuming Play is never a surprise),
        and on the very first room of a fresh run show the control cheat-sheet.

        Both overlays are persistent children built once and reused; ``cover``
        screenshot mode keeps a clean menu-free look so it skips them.
        """
        if self._cover_walk is not None:
            return
        if self._intro is None:
            self._intro = self.add_child(RoomIntro(name="RoomIntro"))
        world = _WORLD_BY_ID.get(world_id, {})
        subtitle = f"{world.get('name', '')}  ·  Room {room_index + 1}"
        self._intro.show(self.room.name if self.room else "", subtitle.strip(" ·"))

        # Control hints: only the tutorial (glade:0) of a brand-new save, where
        # nothing has been completed yet, so a returning player is never nagged.
        first_room = (world_id, room_index) == (_WORLD_ORDER[0], 0)
        fresh = not self.progress.is_completed(_WORLD_ORDER[0], 0)
        if first_room and fresh:
            if self._hints is None:
                self._hints = self.add_child(ControlHints(name="ControlHints"))
            self._hints.show()
        elif self._hints is not None:
            self._hints.visible = False

    def _update_play(self, dt: float) -> None:
        room = self.room
        if room is None:
            return

        # Deferred room build: the previous frame painted the "Loading" indicator;
        # do the heavy diorama build now (it blocks this frame, but Loading stays
        # on screen until it finishes), then resume normal play next frame.
        if self._build_pending:
            self._build_pending = False
            self._finish_enter_play()
            return

        # Cover-shot affordance: drive the Wisp right (then a brief dash) for a
        # short window so the gallery thumbnail catches it mid-room with a trail.
        if self._cover_walk is not None:
            self._cover_walk += dt
            Input.inject_key(Key.RIGHT, self._cover_walk < 0.95)
            Input.inject_key(Key.LEFT_SHIFT, 0.45 <= self._cover_walk < 0.6)

        # A menu overlay (pause / options) is open over PLAY: freeze the sim and
        # swallow gameplay input so nothing moves, dies, wins, or restarts behind
        # the menu. Resume/restart happen via the menu buttons (which clear the
        # screen); the pause action only re-opens an already-open menu, so gate it.
        if self._screen is not None:
            return

        if Input.is_action_just_pressed("pause"):
            self._open_pause()
            return
        if Input.is_action_just_pressed("restart"):
            self._restart_room()
            return

        assist = bool(self.progress.get_option("assist_mode"))
        invincible = assist and self._assist("assist_invincible")
        sim_dt = dt
        if assist and self._assist("assist_slow_time"):
            sim_dt = dt * _ASSIST_SLOW_SCALE

        if _DEBUG:
            self._dbg_trace_play(room, dt)

        if room.dead and not invincible:
            self._respawn_timer += dt
            if self._respawn_timer >= RESPAWN_DELAY:
                if _DEBUG:
                    _dbg(f"RESPAWN room={room.name!r} (deaths so far={room.deaths})")
                room.reset()
                self._respawn_timer = 0.0
        elif room.won:
            # Brief beat after reaching the exit before advancing / showing the
            # results menu, so it does not pop up under the player's still-held
            # keys the instant they touch the exit.
            self._win_timer += dt
            if self._win_timer >= WIN_DELAY:
                self._win_timer = 0.0
                self._on_room_won()
            return
        else:
            if room.dead and invincible:
                room.reset()  # assist: shrug off the death immediately
            inp = read_player_input(self.tree)
            room.step(sim_dt, inp)
            self._apply_assist_post_step(assist)

        # Drive the view + feel from the post-step state.
        self._effects.play_events(room.drain_events(), WORLD_SCALE)
        self._entities.sync(room, dt)
        self._camera.update(dt, room)
        self._sync_lights()
        if self._hud is not None:
            self._hud.update(room, self.progress, world_id=self._world_id, room_index=self._room_index, dt=dt)
        if self._intro is not None:
            self._intro.update(dt)
        if self._hints is not None:
            self._hints.update(dt)

    def _dbg_trace_play(self, room: Room, dt: float) -> None:
        """Debug-only: log the first frame ``room.dead`` flips True (with WHY) and
        a once-per-second fps/dt heartbeat. Cheap; only called when _DEBUG is set."""
        if room.dead and not self._dbg_was_dead:
            p = room.player
            below = p.y > room.h * room.tile_size + room.tile_size
            hazard = room._hazard_overlap(p)
            why = "hazard tile overlap" if hazard else ("fell below room / out of bounds" if below else "unknown")
            _dbg(f"DEATH room={room.name!r} player=({p.x:.1f},{p.y:.1f}) why={why}")
        self._dbg_was_dead = room.dead

        self._dbg_hb += dt
        if self._dbg_hb >= 1.0:
            fps = 1.0 / dt if dt > 0 else 0.0
            _dbg(f"PLAY room={room.name!r} fps={fps:.1f} dt={dt * 1000:.1f}ms time={room.time:.1f}s")
            self._dbg_hb = 0.0

    def _assist(self, key: str) -> bool:
        """Read an assist toggle, falling back to the schema-absent local dict."""
        try:
            return bool(self.progress.get_option(key))
        except KeyError:
            return self._assist_extra.get(key, False)

    def _apply_assist_post_step(self, assist: bool) -> None:
        if not assist or self.room is None:
            return
        p = self.room.player
        if self._assist("assist_infinite_dash"):
            p.refill_dash()
        if self._assist("assist_extended_glow") and p.glow_timer > 0.0:
            p.glow_timer = max(p.glow_timer, _EXTENDED_GLOW)

    def _restart_room(self) -> None:
        if self.room is not None:
            if _DEBUG:
                _dbg(f"RESTART room={self.room.name!r} (manual restart)")
            self.room.reset()
            self._respawn_timer = 0.0
            self._dbg_was_dead = False

    def _on_room_won(self) -> None:
        room = self.room
        # Cover/screenshot mode is a throwaway scripted run: never record results
        # or save, so it can't pollute the player's real progress (and thus skip
        # them past the tutorial room). Just hold the won room for the thumbnail.
        if self._cover_walk is not None:
            return
        self.progress.record_room_result(
            self._world_id,
            self._room_index,
            room.time,
            room.shard_collected,
            died_count=room.deaths,
            world_room_count=_world_room_count(self._world_id),
        )
        self.progress.save()

        self._world_time += room.time
        self._world_deaths += room.deaths
        if room.shard_collected:
            self._world_shards += 1

        last = self._room_index >= _world_room_count(self._world_id) - 1
        if _DEBUG:
            _dbg(
                f"WIN room={room.name!r} time={room.time:.2f}s shard={room.shard_collected} "
                f"deaths={room.deaths} -> {'RESULTS (world complete)' if last else 'advance to next room'}"
            )
        if last:
            self._enter_results()
        else:
            self._enter_play(self._world_id, self._room_index + 1)

    # ======================================================================
    # RESULTS
    # ======================================================================

    def _enter_results(self) -> None:
        self.state = RESULTS
        self._hide_play_overlays()
        self._teardown_scene_to_idle()

        wid = self._world_id
        widx = _WORLD_ORDER.index(wid) if wid in _WORLD_ORDER else 0
        final = widx >= len(_WORLD_ORDER) - 1

        screen = ResultsScreen(name="ResultsScreen")
        screen.set_summary(
            title="GAME COMPLETE" if final else f"{_WORLD_BY_ID[wid]['name'].upper()} COMPLETE",
            total_time=self._world_time,
            deaths=self._world_deaths,
            shards=self._world_shards,
            shards_total=_world_room_count(wid),
            final=final,
        )
        next_world = None if final else _WORLD_ORDER[widx + 1]
        screen.on_continue = self._enter_title if final else (lambda w=next_world: self._enter_play(w, 0))
        screen.on_replay = lambda w=wid: self._enter_play(w, 0)
        screen.on_map = self._enter_level_select
        self._set_screen(screen)

    def _teardown_scene_to_idle(self) -> None:
        """Clear the gameplay diorama for the results screen.

        The bright, bloomed level geometry otherwise renders behind the summary
        panel and bleeds through its translucent backdrop, so the "<world>
        COMPLETE" popup reads as if it is buried under a coloured map overlay.
        Dropping the diorama (and its environment/camera) leaves the panel on a
        clean dim backdrop. Music is deliberately left playing for continuity
        (this is not ``_teardown_scene``, which also stops the bed).
        """
        self.room = None
        if self._scene is not None:
            self._scene.clear_children()
        self._env = self._diorama = self._entities = self._camera = None
        self._title_backdrop = None
        self._lights = None

    # ======================================================================
    # PAUSE overlay
    # ======================================================================

    def _open_pause(self) -> None:
        screen = PauseMenu(name="PauseMenu")
        screen.on_resume = self._resume_from_pause
        screen.on_restart = self._resume_then_restart
        screen.on_options = lambda: self._open_options(return_to=self._open_pause)
        screen.on_quit = self._enter_level_select
        self._set_screen(screen)

    def _resume_from_pause(self) -> None:
        self._set_screen(None)

    def _resume_then_restart(self) -> None:
        self._restart_room()
        self._set_screen(None)

    # ======================================================================
    # OPTIONS overlay
    # ======================================================================

    def _open_options(self, *, return_to) -> None:
        screen = OptionsMenu(self.progress, allow_fullscreen=False, name="OptionsMenu")
        screen.on_change = self._apply_option
        screen.on_back = lambda: (self.progress.save(), return_to())
        self._set_screen(screen)

    def _apply_option(self, key: str, value) -> None:
        """Apply a single option live and persist the whole document."""
        try:
            self.progress.set_option(key, value)
        except KeyError:
            # Assist-only keys the schema does not persist: keep them in-memory.
            if key in self._assist_extra:
                self._assist_extra[key] = bool(value)
        if key in ("master_volume", "sfx_volume", "music_volume"):
            self._apply_audio_volumes()
        elif key == "screenshake" and self._effects is not None:
            self._effects.screenshake_enabled = bool(value) and not self._effects.reduced_motion
        elif key == "photosensitive_safe" and self._effects is not None:
            self._effects.reduced_motion = bool(value)
            self._effects.screenshake_enabled = bool(self.progress.get_option("screenshake")) and not bool(value)
        self.progress.save()

    def _play_ui_sfx(self, name: str) -> None:
        """Play one menu sound and free the player when it ends.

        Parented to the game root rather than the menu screen, so a sound started
        by the button that closes a screen still finishes.
        """
        if self.tree is None:
            return
        player = AudioPlayer(stream=audio.get_sfx(name), bus=audio.SFX_BUS)
        player.autoplay = True
        player.queue_free_on_end = True
        self.add_child(player)

    def _apply_audio_volumes(self) -> None:
        layout = AudioBusLayout.get_default()
        for bus_name, opt in (
            (audio.MASTER_BUS, "master_volume"),
            (audio.SFX_BUS, "sfx_volume"),
            (audio.MUSIC_BUS, "music_volume"),
        ):
            if layout.has_bus(bus_name):
                layout.get_bus(bus_name).volume_db = _linear_to_db(float(self.progress.get_option(opt)))

    # ======================================================================
    # UI plumbing
    # ======================================================================

    def _set_screen(self, screen) -> None:
        """Swap the active menu overlay; ``None`` clears it (PLAY).

        The old screen is detached before it is freed. ``destroy()`` alone is a
        deferred delete, so the torn-down screen would stay in the tree (and its
        button stay focused) for the rest of the frame: a stray Enter could then
        re-fire the title's Play button and skip into a fresh room. Detaching
        runs ``Control._exit_tree`` immediately, which is where the engine hands
        focus back, so the dead screen is unreachable at once. The new screen
        re-establishes focus via its own ``focus_first()`` below.
        """
        if self._screen is not None:
            self.remove_child(self._screen)
            self._screen.destroy()
            self._screen = None
        if screen is not None:
            self.add_child(screen)
            self._screen = screen
            focus = getattr(screen, "focus_first", None)
            if focus is not None:
                focus()

    def _ensure_hud(self) -> None:
        if self._hud is None:
            self._hud = self.add_child(HUD(glow_max=GLOW_FROM_ORB, name="HUD"))
        self._hud.visible = True

    def _hide_play_overlays(self) -> None:
        """Hide the HUD + touch controls when leaving PLAY for a menu screen.

        Both are persistent children (built once, reused across rooms); hiding
        keeps the last room's readout and the virtual pad off the menus instead
        of drawing stale data / live inputs over the title, level-select, and
        results screens.
        """
        if self._hud is not None:
            self._hud.visible = False
        if self._touch is not None:
            self._touch.visible = False
        if self._intro is not None:
            self._intro.visible = False
        if self._hints is not None:
            self._hints.visible = False

    def _refresh_touch(self, *_args) -> None:
        # Only surface the touch overlay during PLAY; on the menus the HUD/touch
        # are hidden (see _hide_play_overlays). Accepts *args so it can also serve
        # as the screen_resized handler (which passes the new size).
        # Cover mode is a clean desktop-look thumbnail: keep the virtual pad off it.
        want = self.state == PLAY and self._cover_walk is None and should_show_touch(self.tree)
        if want and self._touch is None:
            self._touch = self.add_child(TouchControls(name="TouchControls"))
        elif want and self._touch is not None:
            self._touch.visible = True
        elif not want and self._touch is not None:
            self._touch.destroy()
            self._touch = None

    # ======================================================================
    # Quit
    # ======================================================================

    def _quit(self) -> None:
        try:
            self.progress.save()
        except OSError:
            log.exception("Afterglow: failed to save progress on quit")
        self.app.quit()

    def on_exit_tree(self) -> None:
        if menus.play_sound == self._play_ui_sfx:
            menus.play_sound = None  # never leave the menus holding a dead root
        try:
            self.tree.screen_resized.disconnect(self._refresh_touch)
        except (ValueError, KeyError):
            pass
        try:
            self.progress.save()
        except OSError:
            log.exception("Afterglow: failed to save progress on exit")


def _linear_to_db(linear: float) -> float:
    """Convert a 0..1 slider value to a bus dB (0 -> silence floor, 1 -> 0 dB)."""
    linear = max(0.0, min(1.0, linear))
    if linear <= 0.0:
        return -80.0
    return max(-80.0, 20.0 * math.log10(linear))