Dungeon Explorer

Dungeon Explorer — 2D top-down dungeon crawler.

Run: uv run python games/dungeon_explorer/main.py

Controls: WASD/Arrows: Move Space: Attack Shift: Dodge roll I: Inventory E: Interact Escape: Pause L: Level up (if points) J: Quest log K: Skill tree 1-4: Use hotbar abilities N: Skip level (–debug only)

Source Code

#!/usr/bin/env python3
"""Dungeon Explorer — 2D top-down dungeon crawler.

Run: uv run python games/dungeon_explorer/main.py

Controls:
    WASD/Arrows: Move        Space: Attack       Shift: Dodge roll
    I: Inventory             E: Interact         Escape: Pause
    L: Level up (if points)  J: Quest log        K: Skill tree
    1-4: Use hotbar abilities N: Skip level (--debug only)
"""

from __future__ import annotations

import sys
from pathlib import Path

# Ensure game root is on sys.path for script imports
_GAME_DIR = str(Path(__file__).resolve().parent)
if _GAME_DIR not in sys.path:
    sys.path.insert(0, _GAME_DIR)

from simvx.core import CanvasLayer, Input, InputMap, Key, Node2D, ProcessMode, Vec2
from simvx.graphics import App

from scripts.boss_enemy import BossEnemy
from scripts.boss_health_bar import BossHealthBar
from scripts.camera_controller import CameraController
from scripts.combat import Hitbox, apply_defence
from scripts.confirm_dialog import ConfirmDialog
from scripts.death_screen import DeathScreen
from scripts.dialog_ui import DialogUI
from scripts.dungeon_generator import DungeonLevel, TILE_SIZE, generate_dungeon, path_exists
from scripts.dungeon_theme import get_theme
from scripts.enemy_base import EnemyBase
from scripts.enemy_spawner import spawn_all_dungeon_enemies
from scripts.fog_of_war import FogOfWar
from scripts.game_manager import GameManager
from scripts.inn import Inn
from scripts.inventory import Inventory
from scripts.inventory_ui import InventoryUI
from scripts.item_generator import ItemGenerator
from scripts.level_up_ui import LevelUpUI
from scripts.loot_drop import LootDrop
from scripts.loot_pickup import LootPickup
from scripts.particles2d import SimpleParticles
from scripts.pause_menu import PauseMenu
from scripts.player import Player
from scripts.player_hud import PlayerHUD
from scripts.player_skills import SkillTree
from scripts.player_stats import compute_derived_stats
from scripts.popup_manager import PopupManager
from scripts.projectile import Projectile
from scripts.quest_board import QuestBoardUI
from scripts.quest_log_ui import QuestLogUI
from scripts.quests import QuestManager
from scripts.save_system import capture_save_data, load_game, restore_save_data, save_game
from scripts.shop import ShopUI
from scripts.skill_tree_ui import SkillTreeUI
from scripts.title_screen import TitleScreen
from scripts.transition_overlay import TransitionOverlay
from scripts.village import VillageScene, VILLAGE_W, VILLAGE_H, TILE as VILLAGE_TILE
from scripts.victory_screen import VictoryScreen
from scripts.abilities import TrapNode
from scripts.achievements import AchievementLogUI, AchievementManager
from scripts.audio_manager import AudioManager
from scripts.enchanter import EnchanterUI
from scripts.item import Rarity, RARITY_NAMES
from scripts.loading_screen import LoadingScreen
from scripts.settings_ui import SettingsUI, game_settings
from scripts.stats_tracker import StatsPanel, StatsTracker
from scripts.tutorial import TutorialManager
from scripts.waypoint_ui import WaypointUI
from scripts.click_controller import ClickController
from scripts.hotbar_assign_ui import HotbarAssignUI
from scripts.virtual_controls_overlay import VirtualControlsOverlay
from scripts.weapons import melee_attack, ranged_attack, is_ranged, get_melee_profile, get_ranged_profile
from scripts.well import Well

try:
    import tomllib
except ImportError:
    import tomli as tomllib  # type: ignore[no-redef]

DATA_DIR = Path(__file__).resolve().parent / "data"
SAVE_PATH = Path(_GAME_DIR) / "savegame.json"

# Archetype -> loot table key mapping
_LOOT_TABLE_MAP = {
    "skeleton": "skeleton",
    "archer_skeleton": "skeleton",
    "slime": "slime",
    "bat_swarm": "bat",
    "goblin": "goblin",
    "wraith": "wraith",
    "golem": "golem",
    "demon": "demon",
    "elder_dragon": "boss",
}

# Game states
STATE_TITLE = "title"
STATE_DUNGEON = "dungeon"
STATE_TOWN = "town"


class _FogOverlayNode(Node2D):
    """World-space fog overlay drawn ABOVE enemies/particles to hide non-visible areas.

    z_index 20 ensures this draws after enemies (10) and particles (15)
    but before the CanvasLayer (HUD/popups).
    """

    def __init__(self, **kwargs):
        super().__init__(name="FogOverlay", **kwargs)
        self.z_index = 20
        self._fog = None
        self._dungeon_data = None

    def setup(self, fog, dungeon_data):
        self._fog = fog
        self._dungeon_data = dungeon_data

    def draw(self, renderer):
        fog = self._fog
        data = self._dungeon_data
        if not fog or not data:
            return
        ts = TILE_SIZE
        for y in range(data.height):
            for x in range(data.width):
                state = fog.get_state(x, y)
                if state == 2:
                    continue  # Fully visible — no overlay
                px, py_ = x * ts, y * ts
                if state == 0:
                    # Unexplored: opaque black
                    renderer.draw_filled_rect(px, py_, ts, ts, (0.0, 0.0, 0.0, 1.0))
                else:
                    # Explored but not currently visible: semi-transparent dark overlay
                    renderer.draw_filled_rect(px, py_, ts, ts, (0.0, 0.0, 0.0, 0.55))


class _StatusOverlay(Node2D):
    """Screen-space status text and controls help (lives inside CanvasLayer)."""

    def __init__(self, game, **kwargs):
        super().__init__(name="StatusOverlay", **kwargs)
        self._game = game

    def process(self, dt: float):
        g = self._game
        # Tick level-up timers
        if g._levelup_flash_timer > 0:
            g._levelup_flash_timer -= dt
        if g._levelup_text_timer > 0:
            g._levelup_text_timer -= dt
        # Tick boss phase flash/slowmo
        if g._boss_phase_flash > 0:
            g._boss_phase_flash -= dt
        if g._boss_phase_slowmo > 0:
            g._boss_phase_slowmo -= dt
        # Quest notification ticking
        hud = g._hud
        if hasattr(hud, '_quest_notifications'):
            hud._quest_notifications = [
                (text, t - dt) for text, t in hud._quest_notifications if t - dt > 0
            ]

    def draw(self, renderer):
        g = self._game
        if g._state == STATE_TITLE:
            return

        # Get actual screen size
        sw, sh = 1280, 720
        if self._tree:
            sw, sh = self._tree.screen_size

        # Level-up screen flash
        if g._levelup_flash_timer > 0:
            alpha = g._levelup_flash_timer / 0.15
            renderer.draw_filled_rect(0, 0, sw, sh, (1.0, 0.95, 0.7, alpha * 0.4))

        # Level-up animated text
        if g._levelup_text_timer > 0:
            alpha = min(1.0, g._levelup_text_timer / 0.5)
            if g._levelup_text_timer > 1.5:
                scale = 1.5 + (2.0 - g._levelup_text_timer) * 2.0
            else:
                scale = 2.5
            renderer.draw_text(f"LEVEL {g._levelup_level}!",
                              (sw / 2 - 100, sh * 0.39), scale=scale,
                              colour=(1.0, 0.9, 0.3, alpha))
            renderer.draw_text("+3 Stat Points  +1 Skill Point",
                              (sw / 2 - 120, sh * 0.44), scale=1.0,
                              colour=(0.8, 0.9, 1.0, alpha * 0.8))

        # Boss phase transition flash
        if g._boss_phase_flash > 0:
            alpha = g._boss_phase_flash / 0.2
            renderer.draw_filled_rect(0, 0, sw, sh, (1.0, 0.3, 0.1, alpha * 0.3))

        # Tutorial tip overlay
        g._tutorial.draw_tip(renderer, sw, sh)

        # Achievement notification
        notif = g._achievements.pop_notification()
        if notif:
            g._achievement_notif = notif
            g._achievement_notif_timer = 3.0
        if hasattr(g, '_achievement_notif_timer') and g._achievement_notif_timer > 0:
            g._achievement_notif_timer -= 0.016
            a = min(1.0, g._achievement_notif_timer / 0.5)
            name, desc = g._achievement_notif
            ax = sw - 380
            renderer.draw_filled_rect(ax, 20, 360, 50, (0.1, 0.1, 0.15, 0.9 * a))
            renderer.draw_filled_rect(ax, 20, 360, 2, (1.0, 0.85, 0.2, 0.8 * a))
            renderer.draw_text(f"Achievement: {name}", (ax + 10, 28), scale=1.0,
                              colour=(1.0, 0.85, 0.2, a))
            renderer.draw_text(desc, (ax + 10, 48), scale=0.8, colour=(0.7, 0.7, 0.7, a))

        if g._state == STATE_TOWN:
            renderer.draw_text("TOWN  |  Safe Zone", (10, sh - 20), scale=1, colour=(0.5, 0.7, 0.5))
            return

        # Dungeon info
        renderer.draw_text(
            f"Dungeon Lv {g._dungeon_level}  |  {get_theme(g._dungeon_level)['name']}",
            (10, sh - 20), scale=1, colour=(0.5, 0.5, 0.5),
        )
        enemies_alive = len(g.find_all(EnemyBase))
        if enemies_alive > 0:
            renderer.draw_text(
                f"Enemies: {enemies_alive}",
                (10, sh - 38), scale=1, colour=(0.8, 0.3, 0.3),
            )
        cx = sw - 380
        cy = sh - 50
        grey = (0.45, 0.45, 0.45, 1.0)
        renderer.draw_text("WASD: Move   Space: Attack   Shift: Dodge", (cx, cy), scale=0.9, colour=grey)
        renderer.draw_text("I: Inventory   K: Skills   L: Level Up   J: Quests", (cx, cy + 16), scale=0.9, colour=grey)
        renderer.draw_text("E: Interact   1-4: Abilities   Esc: Pause", (cx, cy + 32), scale=0.9, colour=grey)


class DungeonGame(Node2D):
    """Root node for the dungeon explorer game."""

    def __init__(self, *, debug: bool = False, **kwargs):
        super().__init__(**kwargs)
        self._debug = debug

    def ready(self):
        # PAUSABLE (default) so children (enemies, particles) pause when popup is open.
        # PopupManager and TransitionOverlay set their own ALWAYS mode.

        # Register input actions
        InputMap.add_action("pause", [Key.ESCAPE])
        InputMap.add_action("next_level", [Key.N])
        InputMap.add_action("inventory", [Key.I])
        InputMap.add_action("interact", [Key.E])
        InputMap.add_action("level_up", [Key.L])
        InputMap.add_action("skill_tree", [Key.K])
        InputMap.add_action("quest_log", [Key.J])
        InputMap.add_action("ability_1", [Key.KEY_1])
        InputMap.add_action("ability_2", [Key.KEY_2])
        InputMap.add_action("ability_3", [Key.KEY_3])
        InputMap.add_action("ability_4", [Key.KEY_4])
        InputMap.add_action("toggle_fullscreen", [Key.F11])

        # Core systems
        self.gm = GameManager()
        self.add_child(self.gm)

        self._inventory = Inventory()
        self._item_gen = ItemGenerator(DATA_DIR / "items.toml", DATA_DIR / "affixes.toml")
        with open(DATA_DIR / "loot_tables.toml", "rb") as f:
            self._loot_tables = tomllib.load(f)

        # UI layer
        self._ui_layer = CanvasLayer(name="UILayer")
        self._ui_layer.process_mode = ProcessMode.ALWAYS
        self.add_child(self._ui_layer)

        # HUD
        self._hud = PlayerHUD()
        self._ui_layer.add_child(self._hud)
        self._status_overlay = _StatusOverlay(self)
        self._ui_layer.add_child(self._status_overlay)

        # Transition overlay
        self._transition = TransitionOverlay()
        self._ui_layer.add_child(self._transition)

        # Popup manager
        self._popups = PopupManager()
        self._ui_layer.add_child(self._popups)

        # Popup instances
        self._pause_popup = PauseMenu(on_action=self._on_pause_action)
        self._inventory_popup = InventoryUI(on_use_consumable=self._on_consumable_used)
        self._inventory_popup.set_inventory(self._inventory)
        self._level_up_popup = LevelUpUI()
        self._death_popup = DeathScreen(on_respawn=self._on_respawn)
        self._title_popup = TitleScreen(on_action=self._on_title_action, save_path=SAVE_PATH)
        self._dialog_popup = DialogUI()
        self._shop_popup = ShopUI(on_transaction=self._on_shop_transaction)
        self._victory_popup = VictoryScreen(on_continue=self._on_victory_continue)

        # Skill tree
        self._skill_tree = SkillTree()
        self._skill_tree.load_from_toml(DATA_DIR / "skills.toml")
        self._skill_tree_popup = SkillTreeUI(self._skill_tree)

        # Sprint 74: Statistics tracker
        self._stats = StatsTracker()
        self._stats_popup = StatsPanel(self._stats)

        # Sprint 75: Achievements
        self._achievements = AchievementManager()
        self._achievement_log_popup = AchievementLogUI(self._achievements)
        self._achievement_display_timer = 0.0
        self._achievement_display_text = ""

        # Sprint 78: Enchanter
        self._enchanter_popup = EnchanterUI()

        # Settings popup
        self._settings_popup = SettingsUI(on_close_cb=self._on_settings_close)

        # Hotbar assignment popup
        self._hotbar_assign_popup = HotbarAssignUI(self._skill_tree)
        self._hotbar_assign_popup.set_inventory(self._inventory)

        # Loading screen
        self._loading_popup = LoadingScreen()

        # Tutorial system
        self._tutorial = TutorialManager()
        self.tutorial_seen = False

        # Quest system
        self._quest_mgr = QuestManager()
        self._quest_mgr.load_from_toml(DATA_DIR / "quests.toml")
        self._quest_board_popup = QuestBoardUI(self._quest_mgr)
        self._quest_log_popup = QuestLogUI(self._quest_mgr, on_claim=self._on_quest_claimed)

        # Waypoint popup
        self._waypoint_popup = WaypointUI(on_teleport=self._on_waypoint_teleport)
        self._opened_chests: set[tuple[int, int, int]] = set()  # (level, gx, gy)

        # Persistent player
        self._dungeon_level = 1
        self._fog = None
        self._pending_level_up = False
        self._town_scene: VillageScene | None = None
        self._boss: BossEnemy | None = None
        self._boss_hud: BossHealthBar | None = None
        self._rewarded_enemies: set[int] = set()  # Track enemies by _reward_id to prevent double-counting
        self._next_reward_id = 0
        self._return_floor: int | None = None  # Town portal return floor

        self._player = Player(name="Player")
        self._player.z_index = 10  # Above dungeon floor, below UI
        self._player.died.connect(self._on_player_died)
        self._player.levelled_up.connect(self._on_level_up)
        self.add_child(self._player)

        self._popups.set_player(self._player)
        self._inventory_popup.set_player(self._player)
        self._inventory_popup.set_skill_tree(self._skill_tree)
        self._skill_tree_popup.set_player(self._player)
        self._hud.set_quest_manager(self._quest_mgr)
        self._hud.set_skill_tree(self._skill_tree)
        self._hud.hotbar_slot_clicked.connect(self._on_hotbar_slot_clicked)
        self._hud.hotbar_slot_long_pressed.connect(self._on_hotbar_slot_long_pressed)

        # Particle system
        self._particles = SimpleParticles()
        self._particles.z_index = 15  # Above entities
        self.add_child(self._particles)

        # Audio manager (no-op without audio files)
        self._audio = AudioManager()
        self.add_child(self._audio)

        # Hit-stop
        self._hitstop_frames = 0
        self._hitstop_ramp = 0.0  # Time-scale ramp back after hit-stop
        self._prev_dodging = False  # Track dodge start for camera shake

        # Level-up celebration
        self._levelup_flash_timer = 0.0
        self._levelup_text_timer = 0.0
        self._levelup_level = 0

        # Boss phase transition
        self._boss_prev_phase = 1
        self._boss_phase_flash = 0.0
        self._boss_phase_slowmo = 0.0

        # Click-to-path controller
        self._click_ctrl = ClickController()

        # Virtual gamepad overlay
        self._virtual_controls = VirtualControlsOverlay()
        self._vc_draw_layer = _VirtualControlsDrawLayer(self._virtual_controls, self)
        self._ui_layer.add_child(self._vc_draw_layer)

        # Auto-detect mobile/web: WebApp sets is_mobile from JS navigator check
        app = getattr(self._tree, '_app', None)
        self._is_mobile_web = getattr(app, 'is_mobile', False) if app else False
        if app and not hasattr(app, 'engine'):
            # Web export — default to virtual gamepad
            game_settings.control_mode = "virtual_gamepad"

        # State machine
        self._state = STATE_TITLE
        self._popups.open(self._title_popup)

    # ── State transitions ──────────────────────────────────────────────

    def _start_new_game(self):
        """Start a fresh game."""
        # Reset player stats
        self._player.hp = 100
        self._player.max_hp = 100
        self._player.level = 1
        self._player.xp = 0
        self._player.xp_to_next = 100
        self._player.gold = 0
        self._player.strength = 5
        self._player.dexterity = 5
        self._player.vitality = 5
        self._player.intelligence = 5
        self._player.stat_points = 0
        self._player.skill_points = 0
        self._skill_tree.unlocked.clear()
        self._skill_tree.skill_points = 0
        self._skill_tree.hotbar = [None, None, None, None]
        self._quest_mgr.active.clear()
        self._quest_mgr.completed.clear()
        self._inventory = Inventory()
        self._inventory_popup.set_inventory(self._inventory)
        self._opened_chests.clear()
        self.gm.load_state_snapshot({
            "dungeon_level": 1, "max_dungeon_reached": 0,
            "save_point_level": 0, "in_town": False,
            "boss_defeated": False, "game_state": {},
            "activated_waypoints": [],
        })
        self._dungeon_level = 1
        self._enter_town()

    def _start_new_game_plus(self):
        """Start New Game+ — keep items/skills, reset dungeon, scale enemies (Sprint 73)."""
        self.gm.start_new_game_plus()
        self._stats.reset_run()
        self._stats.record_game_complete()
        self._quest_mgr.active.clear()
        self._quest_mgr.completed.clear()
        self._opened_chests.clear()
        self._dungeon_level = 1
        # Keep inventory, skills, and player stats
        self._enter_town()

    def _continue_game(self):
        """Load saved game and resume."""
        save = load_game(SAVE_PATH)
        if save is None:
            self._start_new_game()
            return
        inv, fog, quests_data, skills_data = restore_save_data(save, self._player, self.gm)
        self._inventory = inv
        self._inventory_popup.set_inventory(self._inventory)
        self._fog = fog
        if quests_data:
            self._quest_mgr.from_dict(quests_data)
        if skills_data:
            self._skill_tree.from_dict(skills_data)
        self._dungeon_level = save.dungeon_level
        self._state = STATE_DUNGEON
        self._load_dungeon(self._dungeon_level)

    def _enter_town(self):
        """Transition to town hub."""
        self._save_current_game()
        self._state = STATE_TOWN
        self.gm.enter_town()
        # Clean up dungeon nodes
        for old in self.find_all(DungeonLevel) + self.find_all(CameraController):
            if old.parent is self:
                old.destroy()
        for old in self.find_all(EnemyBase):
            old.destroy()
        # Disable fog overlay in town
        fog_node = self.find(_FogOverlayNode, recursive=False)
        if fog_node:
            fog_node.setup(None, None)
        # Remove old town scene if any
        if self._town_scene and self._town_scene.parent:
            self._town_scene.destroy()

        self._town_scene = VillageScene(self._player, on_interact=self._on_npc_interact)
        self.add_child(self._town_scene)
        self._player.position = Vec2(VILLAGE_W // 2, VILLAGE_H // 2)

        # Camera for town
        camera = CameraController(name="Camera")
        camera.zoom = 1.5
        camera.set_target(self._player)
        camera.set_bounds(Vec2(0, 0), Vec2(VILLAGE_W, VILLAGE_H))
        camera.position = Vec2(VILLAGE_W // 2, VILLAGE_H // 2)
        self.add_child(camera)

        self._hud.setup(self._player, inventory=self._inventory)
        self._tutorial.trigger("first_town")

    def _leave_town(self):
        """Exit town and enter next dungeon level."""
        def _do_leave():
            if self._town_scene and self._town_scene.parent:
                self._town_scene.destroy()
                self._town_scene = None
            for old in self.find_all(CameraController):
                if old.parent is self:
                    old.destroy()
            self._state = STATE_DUNGEON
            # If returning from town portal, go back to that floor
            if self._return_floor is not None:
                target = self._return_floor
                self._return_floor = None
                self._load_dungeon(target)
            else:
                self._load_dungeon(self._dungeon_level)
        self._transition.transition(_do_leave)

    # ── Dungeon loading ────────────────────────────────────────────────

    def _load_dungeon(self, level: int, seed: int | None = None):
        """Generate and load a dungeon level. Player persists across calls.

        Uses persistent seeds so the same level always produces the same layout
        until the player rerolls at the well.
        """
        # Clean up old dungeon/camera/enemy nodes
        for old in self.find_all(DungeonLevel) + self.find_all(CameraController):
            if old.parent is self:
                old.destroy()
        for old in self.find_all(EnemyBase):
            old.destroy()

        # Use persistent seed for this level (same layout until well reroll)
        if seed is None:
            seed = self.gm.get_dungeon_seed(level)

        w = min(48 + level * 2, 128)
        h = min(48 + level * 2, 128)
        data = generate_dungeon(
            width=w, height=h,
            min_rooms=min(5 + level // 5, 15),
            max_rooms=min(8 + level // 3, 20),
            seed=seed,
        )
        while not path_exists(data):
            seed = seed + 1
            data = generate_dungeon(width=w, height=h,
                                    min_rooms=min(5 + level // 5, 15),
                                    max_rooms=min(8 + level // 3, 20), seed=seed)

        self._populate_special_objects(data, level)

        # Apply random room decorations (pillars, cross-shapes)
        # Skip entrance (first) and exit (last) rooms to avoid blocking spawn/exit
        from scripts.room_templates import apply_random_decoration
        import random as rng_mod
        dec_rng = rng_mod.Random(seed or level)
        safe_rooms = {0, len(data.rooms) - 1} if len(data.rooms) >= 2 else set(range(len(data.rooms)))
        for i, room in enumerate(data.rooms):
            if i in safe_rooms:
                continue
            if dec_rng.random() < 0.3:
                apply_random_decoration(data.grid, room, dec_rng)
        # Guarantee entrance/exit tiles remain walkable
        from scripts.dungeon_generator import FLOOR as _FLOOR, ENTRANCE, EXIT
        ex, ey = data.entrance
        data.grid[ey][ex] = ENTRANCE
        xx, xy = data.exit
        data.grid[xy][xx] = EXIT

        from scripts.dungeon_generator import COLOURS, FLOOR, CORRIDOR
        theme = get_theme(level)
        COLOURS[FLOOR] = theme["floor_colour"]
        COLOURS[CORRIDOR] = theme["corridor_colour"]

        dungeon = DungeonLevel(data, level=level)
        self.add_child(dungeon)

        self._fog = FogOfWar(data.width, data.height, reveal_radius=6)
        # Fog overlay node covers enemies/particles in world space
        old_fog_overlay = self.find(_FogOverlayNode, recursive=False)
        if old_fog_overlay:
            old_fog_overlay.destroy()
        self._fog_overlay = _FogOverlayNode()
        self._fog_overlay.setup(self._fog, data)
        self.add_child(self._fog_overlay)

        self._player.position = dungeon.entrance_world_pos()

        camera = CameraController(name="Camera")
        camera.zoom = 2.5
        camera.smoothing = 8.0
        camera.set_target(self._player)
        camera.set_bounds_from_dungeon(data.width, data.height)
        camera.position = Vec2(self._player.position)
        self.add_child(camera)

        # Clean up boss/reward state
        self._boss = None
        self._rewarded_enemies.clear()
        if self._boss_hud and self._boss_hud.parent:
            self._boss_hud.destroy()
            self._boss_hud = None

        if level >= 100 and not self.gm.boss_defeated:
            # Boss level — spawn only the boss in the last room
            boss = BossEnemy(name="Elder Dragon")
            # Scale boss for level
            scale = 1 + (level - 1) * 0.15
            boss.hp = int(500 * scale)
            boss.max_hp = boss.hp
            boss.damage = int(25 * (1 + (level - 1) * 0.08))
            boss._base_damage = boss.damage
            boss.speed = 50.0 * (1 + (level - 1) * 0.005)
            boss._base_speed = boss.speed
            last_room = data.rooms[-1]
            boss.position = Vec2(
                (last_room.x + last_room.w // 2) * TILE_SIZE,
                (last_room.y + last_room.h // 2) * TILE_SIZE,
            )
            boss.setup(self._player, dungeon.nav_grid)
            boss.died.connect(self._on_boss_killed)
            boss.phase_changed.connect(self._on_boss_phase_change)
            boss._reward_id = self._next_reward_id
            self._next_reward_id += 1
            boss.z_index = 10
            self.add_child(boss)
            self._boss = boss
            # Boss health bar in UI layer
            self._boss_hud = BossHealthBar()
            self._boss_hud.setup(boss)
            self._ui_layer.add_child(self._boss_hud)
        else:
            enemies = spawn_all_dungeon_enemies(
                data, level, dungeon.nav_grid, self._player, seed=seed,
                difficulty_mults=self.gm.difficulty_multipliers,
            )
            for enemy in enemies:
                enemy._fog = self._fog
                enemy._reward_id = self._next_reward_id
                self._next_reward_id += 1
                enemy.z_index = 10
                self.add_child(enemy)

        self._hud.setup(self._player, data, self._fog, inventory=self._inventory)
        self._level_up_popup.set_player(self._player)

        # Set up click-to-path controller with dungeon nav grid
        camera = self.find(CameraController, recursive=False)
        sw, sh = (self._tree.screen_size if self._tree else (1280, 720))
        self._click_ctrl.setup(
            self._player, camera, dungeon.nav_grid, screen_size=(sw, sh),
            enemies_fn=lambda: [e for e in self.find_all(EnemyBase) if e.hp > 0],
            attack_fn=self._player_attack,
            interact_fn=lambda: self._check_special_interact() or self._check_stairs(),
        )

        self.gm.enter_dungeon(level)
        self._dungeon_level = level
        # Tutorial tips
        self._tutorial.trigger("move")
        if level == 1:
            self._tutorial.trigger("first_stairs")
        self._quest_mgr.on_floor_reached(level)

    # ── Per-frame processing ───────────────────────────────────────────

    def process(self, dt: float):
        # F11 fullscreen toggle (always available)
        if Input.is_action_just_pressed("toggle_fullscreen"):
            app = getattr(self._tree, '_app', None)
            if app and hasattr(app, 'toggle_fullscreen'):
                app.toggle_fullscreen()
                game_settings.fullscreen = getattr(app, 'is_fullscreen', False)

        # Virtual gamepad is processed by _VirtualControlsDrawLayer (in UILayer, ALWAYS mode)
        # so it works even when the tree is paused for popups.

        if self._popups.is_open:
            return

        if self._state == STATE_TITLE:
            # Title screen popup handles everything
            return

        if self._transition.is_transitioning:
            return

        if self._hitstop_frames > 0:
            self._hitstop_frames -= 1
            if self._hitstop_frames == 0:
                self._hitstop_ramp = 0.15  # Ramp back over 0.15s
            return

        # Time-scale ramp back after hit-stop
        if self._hitstop_ramp > 0:
            self._hitstop_ramp -= dt
            ramp_factor = max(0.5, 1.0 - self._hitstop_ramp / 0.15)
            dt = dt * ramp_factor

        # Track play time
        self._stats.update_time(dt)

        # Boss phase transition slow-motion
        if self._boss_phase_slowmo > 0:
            self._boss_phase_slowmo -= dt
            dt = dt * 0.3  # 30% speed during boss phase transition

        if self._state == STATE_TOWN:
            self._process_town(dt)
            return

        # STATE_DUNGEON
        self._process_dungeon(dt)

    def _process_town(self, dt: float = 0.016):
        """Town-specific input processing."""
        self._sync_derived_stats()
        self._tutorial.update(dt)
        if not self._tutorial.tutorial_seen:
            self._tutorial.trigger("first_town")

        if Input.is_action_just_pressed("pause"):
            self._pause_popup.set_context(player=self._player, dungeon_level=self._dungeon_level)
            self._popups.open(self._pause_popup)
            return
        if Input.is_action_just_pressed("inventory"):
            self._popups.open(self._inventory_popup)
            return
        if Input.is_action_just_pressed("skill_tree"):
            self._popups.open(self._skill_tree_popup)
            return
        if Input.is_action_just_pressed("quest_log"):
            self._popups.open(self._quest_log_popup)
            return

        # NPC interaction / dungeon entrance
        if self._town_scene:
            if Input.is_action_just_pressed("interact") and self._town_scene.is_near_dungeon_entrance():
                self._leave_town()
                return
            self._town_scene.check_interactions()

        # Clamp player to village bounds
        if self._town_scene:
            self._town_scene.clamp_player()

    def _process_dungeon(self, dt: float = 0.016):
        """Dungeon-specific input processing."""
        # Tutorial tick
        self._tutorial.update(dt)

        if Input.is_action_just_pressed("pause"):
            self._pause_popup.set_context(player=self._player, dungeon_level=self._dungeon_level)
            self._popups.open(self._pause_popup)
            return
        if Input.is_action_just_pressed("inventory"):
            self._popups.open(self._inventory_popup)
            return
        if Input.is_action_just_pressed("level_up") and self._player.stat_points > 0:
            self._popups.open(self._level_up_popup)
            return
        if Input.is_action_just_pressed("skill_tree"):
            self._popups.open(self._skill_tree_popup)
            return
        if Input.is_action_just_pressed("quest_log"):
            self._popups.open(self._quest_log_popup)
            return

        # Debug: next level (only when launched with --debug)
        if self._debug and Input.is_action_just_pressed("next_level"):
            self._dungeon_level += 1
            # Town every 10 levels
            if self._dungeon_level % 10 == 1 and self._dungeon_level > 1:
                self._transition.transition(self._enter_town)
            else:
                lvl = self._dungeon_level
                self._transition.transition(lambda: self._load_dungeon(lvl))
            return

        # Interact: stairs, chests, waypoints, secret walls
        if Input.is_action_just_pressed("interact"):
            if self._check_stairs():
                return
            if self._check_secret_wall():
                return
            self._check_special_interact()

        # Click-to-path mode
        if game_settings.control_mode == "click_to_path":
            self._click_ctrl.process(dt)

        # Combat (keyboard + virtual gamepad inject key events, so this works for all modes)
        if Input.is_action_just_pressed("attack"):
            self._player_attack()

        # Sync derived stats (vitality → max_hp, dex → speed, gear, passives)
        self._sync_derived_stats()

        # Fog of war
        if self._fog:
            gx = int(self._player.position.x / TILE_SIZE)
            gy = int(self._player.position.y / TILE_SIZE)
            self._fog.update(gx, gy)
            # Set fog + dungeon data on projectiles for visibility and wall collision
            dungeon = self.find(DungeonLevel, recursive=False)
            dungeon_data = dungeon.dungeon_data if dungeon else None
            for proj in self.find_all(Projectile):
                if proj._fog is None:
                    proj._fog = self._fog
                if proj._dungeon_data is None and dungeon_data:
                    proj._dungeon_data = dungeon_data

        # Corner collision safety: prevent diagonal squeeze through wall corners
        self._clamp_to_walkable()

        # Abilities / hotbar items
        for i in range(4):
            if Input.is_action_just_pressed(f"ability_{i + 1}"):
                self._activate_hotbar(i)
        self._skill_tree.process_cooldowns(dt)
        self._hud.handle_hotbar_input(dt)

        self._check_enemy_attacks()
        self._check_player_attacks()
        self._check_loot_pickups()

        # Check traps
        for trap_node in self.find_all(TrapNode):
            enemies = [e for e in self.find_all(EnemyBase) if e.hp > 0]
            triggered = trap_node.check_trigger(enemies)
            for enemy in triggered:
                enemy.take_damage(trap_node._damage, self._player.position)
                if enemy.hp <= 0:
                    self._on_enemy_killed(enemy)

        # Dodge shake detection
        if self._player.is_dodging and not self._prev_dodging:
            camera = self.find(CameraController, recursive=False)
            if camera:
                camera.dodge_shake()
        self._prev_dodging = self._player.is_dodging

        # Boss ground slam screen shake (A2)
        if self._boss and self._boss._slam_fired:
            self._boss._slam_fired = False
            camera = self.find(CameraController, recursive=False)
            if camera:
                camera.boss_shake(intensity=10.0, duration=0.2)

        # Update combo display when combo breaks
        if self._player.combo_count == 0 and self._hud._combo_display_count >= 2:
            self._hud.update_combo(0)

        # Combo time-slow at 5x/10x milestones
        if self._player.combo_count in (5, 10) and self._hitstop_frames == 0:
            if self._player._combo_timer > self._player._combo_window - 0.05:
                self._hitstop_frames = 2  # Brief time-slow at milestone

        # Level-up notification: _pending_level_up is set by the signal but we
        # no longer auto-open the popup.  The player presses L to allocate.
        # Clear the flag once the player has no remaining stat points.
        if self._pending_level_up and self._player.stat_points <= 0:
            self._pending_level_up = False

    def _compute_stats(self) -> dict[str, float]:
        """Compute derived stats with skill passive bonuses applied."""
        return compute_derived_stats(
            self._player.strength, self._player.dexterity,
            self._player.vitality, self._player.intelligence,
            self._player.level, self._inventory,
            skill_bonuses=self._skill_tree.get_passive_bonuses(),
        )

    def _sync_derived_stats(self):
        """Apply derived max_hp and speed to the player so vitality/dex actually matter."""
        derived = self._compute_stats()
        new_max = int(derived["max_hp"])
        if new_max != self._player.max_hp:
            delta = new_max - self._player.max_hp
            self._player.max_hp = new_max
            # If max_hp increased, grant the extra HP immediately
            if delta > 0:
                self._player.hp = min(self._player.max_hp, self._player.hp + delta)
            else:
                self._player.hp = min(self._player.hp, self._player.max_hp)
            self._player.hp_changed(self._player.hp, self._player.max_hp)
        self._player.speed = derived["speed"]
        # Sync shield state for block mechanic
        shield = self._inventory.get_equipped("offhand")
        self._player._has_shield = shield is not None and getattr(shield, 'template_key', '') == "shield"

    # ── Combat ─────────────────────────────────────────────────────────

    def _player_attack(self):
        if self._player.is_dodging or self._player._attack_cooldown > 0:
            return
        self._audio.play_sfx("attack")
        derived = self._compute_stats()
        base_dmg = 5 + int(derived["damage"])
        crit = derived["crit_chance"]
        str_val = int(derived["damage"])
        weapon = self._inventory.get_equipped("weapon")
        weapon_key = weapon.template_key if weapon else ""

        if is_ranged(weapon_key):
            colour, style, speed, rng, cooldown = get_ranged_profile(weapon_key)
            ranged_attack(self._player, self._player.facing,
                          base_damage=base_dmg, speed=speed, max_range=rng,
                          attacker_str=str_val, crit_chance=crit,
                          colour=colour, style=style)
        else:
            arc_colour, arc_spread, hitbox_r, cooldown = get_melee_profile(weapon_key)
            melee_attack(self._player, self._player.facing,
                         base_damage=base_dmg, attacker_str=str_val,
                         crit_chance=crit, hitbox_radius=hitbox_r)
            self._player.start_attack_lunge()
            self._player.start_melee_arc(spread=arc_spread, colour=arc_colour)
        self._player._attack_cooldown = cooldown
        # Degrade weapon durability
        if weapon:
            weapon.degrade(1)
            if weapon.is_broken:
                notif = LootDrop("Weapon broken!", colour=(0.8, 0.2, 0.2, 1.0))
                notif.position = Vec2(self._player.position.x, self._player.position.y - 30)
                self.add_child(notif)

    def _check_enemy_attacks(self):
        import random as _rng
        derived = self._compute_stats()
        player_defence = int(derived["defence"])
        dodge_chance = derived["dodge_chance"]
        block_chance = derived["block_chance"]

        def _apply_hit(target, raw_dmg, from_boss=False, source_pos=None):
            if _rng.random() < dodge_chance:
                return  # Dodged
            if _rng.random() < block_chance:
                self.add_child(LootDrop("Blocked!", colour=(0.6, 0.8, 1.0, 1.0)))
                return
            # Active shield block
            if self._player._blocking and source_pos is not None:
                import math as _math
                atk_dx = source_pos[0] - self._player.position.x
                atk_dy = source_pos[1] - self._player.position.y
                atk_dist = _math.sqrt(atk_dx * atk_dx + atk_dy * atk_dy)
                if atk_dist > 0.01:
                    atk_nx = atk_dx / atk_dist
                    atk_ny = atk_dy / atk_dist
                    dot = self._player._block_direction.x * atk_nx + self._player._block_direction.y * atk_ny
                    if dot > 0.588:  # cos(54deg) ~ 0.588, ~108 degree cone
                        shield = self._inventory.get_equipped("offhand")
                        shield_def = shield.total_stats().get("defence", 0) if shield else 0
                        blocked_dmg = max(1, raw_dmg - shield_def * 3)
                        target.take_damage(blocked_dmg)
                        self._player._block_flash_timer = 0.15
                        pos = Vec2(self._player.position.x, self._player.position.y - 20)
                        drop = LootDrop("Blocked!", colour=(0.4, 0.7, 1.0, 1.0))
                        drop.position = pos
                        self.add_child(drop)
                        camera = self.find(CameraController, recursive=False)
                        if camera:
                            camera.damage_shake(blocked_dmg * 0.5, self._player.max_hp)
                        return
            # Enemy crit: 10% chance, 1.5x damage
            is_crit = _rng.random() < 0.10
            dmg = apply_defence(raw_dmg, player_defence)
            if is_crit:
                dmg = int(dmg * 1.5)
                self._player.trigger_crit_flash()
            target.take_damage(dmg)
            self._stats.record_damage_taken(dmg)
            self._audio.play_sfx("hit")
            # Degrade armour durability
            for slot in ("body", "head", "feet"):
                armour = self._inventory.get_equipped(slot)
                if armour:
                    armour.degrade(1)
            camera = self.find(CameraController, recursive=False)
            if camera:
                if from_boss:
                    camera.boss_shake(intensity=8.0, duration=0.25)
                else:
                    camera.damage_shake(dmg, self._player.max_hp)

        boss_active = self._boss is not None and self._boss.hp > 0
        for hitbox in self.find_all(Hitbox):
            if hitbox.name == "EnemyHit":
                hits = hitbox.check_hits([self._player])
                for target in hits:
                    _apply_hit(target, hitbox.damage, from_boss=boss_active,
                               source_pos=(hitbox.position.x, hitbox.position.y))
        for proj in self.find_all(Projectile):
            if proj.name == "EnemyProjectile":
                hits = proj.check_hits([self._player])
                for target in hits:
                    _apply_hit(target, proj.damage, from_boss=boss_active,
                               source_pos=(proj.position.x, proj.position.y))

    def _check_player_attacks(self):
        enemies = [e for e in self.find_all(EnemyBase) if e.hp > 0]
        derived = self._compute_stats()
        life_steal = derived["life_steal"]
        hp_on_kill = derived["hp_on_kill"]

        knockback_dist = derived["knockback"]

        def _handle_hit(enemy, dmg):
            dx = enemy.position.x - self._player.position.x
            dy = enemy.position.y - self._player.position.y
            dist = (dx * dx + dy * dy) ** 0.5
            direction = Vec2(dx / dist, dy / dist) if dist > 0.01 else Vec2(0, 1)
            is_crit = dmg > (10 + int(derived["damage"])) * 1.3  # Approximate crit detection
            is_boss = isinstance(enemy, BossEnemy)
            enemy.take_damage(dmg, self._player.position)
            self._stats.record_damage_dealt(dmg)
            # Knockback scales with stat; bosses resist 70%
            kb = knockback_dist * (0.3 if is_boss else 1.0)
            if kb > 0.5:
                enemy.apply_knockback(direction, kb, 0.1)
            # Hit-stop: 2 normal, 4 crit, 4 boss
            if is_boss:
                self._hitstop_frames = 4
            elif is_crit:
                self._hitstop_frames = 4
            else:
                self._hitstop_frames = 2
            # Melee hit sparks
            if self._particles:
                self._particles.emit_melee_sparks(enemy.position, direction, is_crit=is_crit)
            # Directional camera shake on hit
            camera = self.find(CameraController, recursive=False)
            if camera:
                camera.directional_shake(direction, intensity=4.0 + dmg * 0.1, duration=0.1)
            if life_steal > 0:
                heal_amt = int(dmg * life_steal)
                self._player.heal(heal_amt)
                if heal_amt > 0:
                    from scripts.combat import DamageNumber
                    hn = DamageNumber(heal_amt, is_heal=True)
                    hn.position = Vec2(self._player.position.x, self._player.position.y - 15)
                    self.add_child(hn)
            if enemy.hp <= 0:
                if hp_on_kill > 0:
                    self._player.heal(int(hp_on_kill))
                    hn = DamageNumber(int(hp_on_kill), is_heal=True)
                    hn.position = Vec2(self._player.position.x, self._player.position.y - 15)
                    self.add_child(hn)
                self._on_enemy_killed(enemy)

        for hitbox in self.find_all(Hitbox):
            if hitbox.name == "MeleeHit":
                hits = hitbox.check_hits(enemies)
                for enemy in hits:
                    _handle_hit(enemy, hitbox.damage)
        for proj in self.find_all(Projectile):
            if proj.name == "EnemyProjectile":
                continue
            hits = proj.check_hits(enemies)
            for enemy in hits:
                # Ranged hit particles
                if self._particles:
                    style = getattr(proj, '_style', 'arrow')
                    self._particles.emit_ranged_hit(enemy.position, style=style)
                    # Enemy impact flash
                    enemy._flash_on_ranged_hit = 0.08
                _handle_hit(enemy, proj.damage)

    def _on_enemy_killed(self, enemy: EnemyBase):
        """Award XP, gold, and loot from killed enemy."""
        # Guard against double-counting (death animation keeps enemy in tree)
        rid = getattr(enemy, '_reward_id', id(enemy))
        if rid in self._rewarded_enemies:
            return
        self._rewarded_enemies.add(rid)
        self._audio.play_sfx("death")

        import random

        # Stats tracking
        self._stats.record_kill()
        if getattr(enemy, '_is_elite', False):
            self._stats.record_elite_kill()
        if getattr(enemy, '_is_mini_boss', False):
            self._stats.record_mini_boss_kill()

        # Combo tracking
        combo = self._player.register_kill()
        self._stats.record_combo(combo)
        self._hud.update_combo(combo)

        # Achievements — check all thresholds against stats
        self._achievements.check(self._stats)
        combo_bonus = max(0, (combo - 1) * 5)  # +5 XP per combo stack

        xp = enemy.xp_reward + combo_bonus
        self._player.gain_xp(xp)

        archetype = enemy.name.lower().replace(" ", "_")
        # Check for quest completion before and after kill tracking
        pre_complete = {q.quest_id for q in self._quest_mgr.active if q.is_complete}
        self._quest_mgr.on_enemy_killed(archetype)
        post_complete = {q.quest_id for q in self._quest_mgr.active if q.is_complete}
        for qid in post_complete - pre_complete:
            quest = next((q for q in self._quest_mgr.active if q.quest_id == qid), None)
            if quest:
                self._hud.notify_quest_complete(quest.name)
        loot_key = _LOOT_TABLE_MAP.get(archetype)
        loot_table = self._loot_tables.get(loot_key, {}) if loot_key else {}

        gold_range = loot_table.get("gold_range", [1, 5])
        gold = random.randint(gold_range[0], gold_range[1])
        self._player.gold += gold
        self._stats.record_gold(gold)

        # Floating notifications
        y_off = -10
        notif = LootDrop(f"+{gold} Gold", colour=(1.0, 0.85, 0.2, 1.0))
        notif.position = Vec2(enemy.position.x, enemy.position.y + y_off)
        self.add_child(notif)

        xp_notif = LootDrop(f"+{xp} XP", colour=(0.4, 0.7, 1.0, 1.0))
        xp_notif.position = Vec2(enemy.position.x, enemy.position.y + y_off - 14)
        self.add_child(xp_notif)

        if loot_table:
            rng = random.Random()
            drops = self._item_gen.roll_from_loot_table(loot_table, self._dungeon_level, rng)
            for item in drops:
                pickup = LootPickup(item)
                pickup.position = Vec2(enemy.position.x, enemy.position.y)
                self.add_child(pickup)

        # Sprint 69: Mini-boss guaranteed epic drop
        if getattr(enemy, '_guaranteed_epic', False):
            rng = random.Random()
            epic_item = self._item_gen.roll_item(ilvl=self._dungeon_level, rarity=Rarity.EPIC, rng=rng)
            pickup = LootPickup(epic_item)
            pickup.position = Vec2(enemy.position.x + 10, enemy.position.y)
            self.add_child(pickup)

        # Death particles
        if self._particles:
            self._particles.emit(10, enemy.position, vel_range=(-60, 60),
                                colour=(0.8, 0.2, 0.1, 1.0), lifetime=0.5)

        # Camera shake on kill
        camera = self.find(CameraController, recursive=False)
        if camera:
            camera.directional_shake(Vec2(0, -1), intensity=3.0, duration=0.1)

    def _clamp_to_walkable(self):
        """Prevent player from squeezing through diagonal wall corners.

        After move_and_slide, check if any corner of the player's bounding
        circle overlaps a wall tile and push back into walkable space.
        """
        dungeon = self.find(DungeonLevel, recursive=False)
        if not dungeon:
            return
        data = dungeon.dungeon_data
        px, py = self._player.position.x, self._player.position.y
        r = 10  # Player collision radius
        ts = TILE_SIZE

        # Check the 4 diagonal corners of the player bounding box
        for dx, dy in ((-r, -r), (r, -r), (-r, r), (r, r)):
            cx, cy = px + dx, py + dy
            gx, gy = int(cx / ts), int(cy / ts)
            if not data.is_walkable(gx, gy):
                # This corner is inside a wall — push player away from this cell
                wall_cx = gx * ts + ts / 2
                wall_cy = gy * ts + ts / 2
                # Push along the axis with less penetration
                pen_x = (ts / 2 + r) - abs(px - wall_cx)
                pen_y = (ts / 2 + r) - abs(py - wall_cy)
                if pen_x > 0 and pen_y > 0:
                    if pen_x < pen_y:
                        self._player.position = Vec2(
                            px + (pen_x if px > wall_cx else -pen_x), py,
                        )
                    else:
                        self._player.position = Vec2(
                            px, py + (pen_y if py > wall_cy else -pen_y),
                        )
                    px, py = self._player.position.x, self._player.position.y

    def _near(self, pos, radius=24) -> bool:
        """Return True if the player is within *radius* px of *pos*."""
        dx = self._player.position.x - pos.x
        dy = self._player.position.y - pos.y
        return dx * dx + dy * dy < radius * radius

    def _is_near_interactable(self) -> bool:
        """Check if the player is near stairs, chests, or waypoints in the dungeon."""
        dungeon = self.find(DungeonLevel, recursive=False)
        if not dungeon:
            return False
        if self._near(dungeon.exit_world_pos(), 30) or self._near(dungeon.entrance_world_pos(), 30):
            return True
        ts = TILE_SIZE
        px, py = self._player.position.x, self._player.position.y
        for obj in dungeon.dungeon_data.special_objects:
            ox = obj["gx"] * ts + ts / 2
            oy = obj["gy"] * ts + ts / 2
            if (px - ox) ** 2 + (py - oy) ** 2 < 30 * 30:
                return True
        return False

    def _check_stairs(self) -> bool:
        """Handle interact on dungeon stairs. Returns True if a transition fired."""
        dungeon = self.find(DungeonLevel, recursive=False)
        if not dungeon:
            return False
        # Exit stairs → descend deeper
        if self._near(dungeon.exit_world_pos()):
            self._dungeon_level += 1
            self._stats.record_floor()
            if self._dungeon_level % 10 == 0:
                self.gm.dungeon_level = self._dungeon_level
                self.gm.set_save_point()
            if self._dungeon_level % 10 == 1 and self._dungeon_level > 1:
                self._transition.transition(self._enter_town)
            else:
                lvl = self._dungeon_level
                self._transition.transition(lambda: self._load_dungeon(lvl))
            return True
        # Entrance stairs → return to town
        if self._near(dungeon.entrance_world_pos()):
            self._transition.transition(self._enter_town)
            return True
        return False

    def _check_secret_wall(self) -> bool:
        """Check if the player is near a secret wall and reveal it."""
        dungeon = self.find(DungeonLevel, recursive=False)
        if not dungeon:
            return False
        gx = int(self._player.position.x / TILE_SIZE)
        gy = int(self._player.position.y / TILE_SIZE)
        result = dungeon.dungeon_data.has_secret_wall_near(gx, gy)
        if result is None:
            return False
        sx, sy = result
        dungeon.dungeon_data.reveal_secret_wall(sx, sy)
        dungeon.rebuild_wall_bodies()  # Remove wall collision so player can walk through
        self._audio.play_sfx("chest_open")
        # Floating notification
        notif = LootDrop("Secret room found!", colour=(0.8, 0.6, 1.0, 1.0))
        notif.position = Vec2(sx * TILE_SIZE + TILE_SIZE / 2,
                              sy * TILE_SIZE - 10)
        self.add_child(notif)
        if hasattr(self, '_stats'):
            self._stats.record_secret_room()
        # Populate the secret room with a reward
        self._populate_secret_room(dungeon.dungeon_data, sx, sy)
        return True

    def _populate_secret_room(self, data, door_x: int, door_y: int):
        """Spawn a chest or elite enemy inside the secret room behind the door."""
        import random
        from scripts.dungeon_generator import FLOOR

        # Find which side of the door leads to the secret room (not the parent room).
        # The door has exactly two floor neighbors: one in the parent room, one in
        # the secret room.  The secret room side is the one NOT inside any known room.
        seed_tiles = []
        parent_tiles = []
        for dx, dy in ((0, -1), (0, 1), (-1, 0), (1, 0)):
            nx, ny = door_x + dx, door_y + dy
            if 0 <= nx < data.width and 0 <= ny < data.height and data.grid[ny][nx] == FLOOR:
                in_room = any(
                    r.x <= nx < r.x + r.w and r.y <= ny < r.y + r.h
                    for r in data.rooms
                )
                if in_room:
                    parent_tiles.append((nx, ny))
                else:
                    seed_tiles.append((nx, ny))
        # Fallback: if heuristic fails, use all neighbors
        if not seed_tiles:
            seed_tiles = parent_tiles

        # Flood-fill only into the secret room (block the door to prevent leaking
        # back into the parent room)
        room_tiles: list[tuple[int, int]] = []
        visited = {(door_x, door_y)}  # Block the door cell
        stack = list(seed_tiles)
        while stack:
            tx, ty = stack.pop()
            if (tx, ty) in visited:
                continue
            visited.add((tx, ty))
            if data.grid[ty][tx] != FLOOR:
                continue
            room_tiles.append((tx, ty))
            if len(room_tiles) > 20:  # Safety cap — secret rooms are 4x4=16
                break
            for dx, dy in ((0, -1), (0, 1), (-1, 0), (1, 0)):
                nx, ny = tx + dx, ty + dy
                if 0 <= nx < data.width and 0 <= ny < data.height and (nx, ny) not in visited:
                    stack.append((nx, ny))

        if not room_tiles:
            return

        # Center of the secret room
        avg_x = sum(t[0] for t in room_tiles) / len(room_tiles)
        avg_y = sum(t[1] for t in room_tiles) / len(room_tiles)
        cx = avg_x * TILE_SIZE + TILE_SIZE / 2
        cy = avg_y * TILE_SIZE + TILE_SIZE / 2

        rng = random.Random()
        if rng.random() < 0.5:
            # Chest with guaranteed rare+ loot
            data.special_objects.append({"type": "chest", "gx": int(avg_x), "gy": int(avg_y)})
        else:
            # Elite guardian enemy
            from scripts.enemy_types import create_enemy, make_elite
            dungeon_node = self.find(DungeonLevel, recursive=False)
            enemy = create_enemy("golem", dungeon_level=self._dungeon_level)
            make_elite(enemy, rng)
            enemy.display_name = "Secret Guardian"
            enemy.xp_reward = int(enemy.xp_reward * 1.5)
            enemy._guaranteed_epic = True  # Drop epic on death
            enemy.position = Vec2(cx, cy)
            enemy.setup(self._player, dungeon_node.nav_grid if dungeon_node else None)
            enemy._reward_id = self._next_reward_id
            self._next_reward_id += 1
            enemy.z_index = 10
            self.add_child(enemy)

    def _check_loot_pickups(self):
        for pickup in self.find_all(LootPickup):
            # Grab item reference before try_collect (which destroys the node)
            item = pickup.item
            if pickup.try_collect(self._player.position, self._inventory):
                self._audio.play_sfx("pickup")
                # Sprint 71: Track item collection for quests
                rarity_name = RARITY_NAMES.get(item.rarity, "Common").lower()
                self._quest_mgr.on_item_collected(rarity_name)
                # Sprint 74: Stats
                self._stats.record_item()

    # ── Callbacks ──────────────────────────────────────────────────────

    def _on_player_died(self):
        self._stats.record_death()
        self._death_popup.set_context(player=self._player, dungeon_level=self._dungeon_level)
        self._popups.open(self._death_popup)

    def _on_respawn(self):
        # Respawn in village — player recovers at town after death
        self._player.hp = self._player.max_hp
        self._transition.transition(self._enter_town)

    def _on_level_up(self, new_level):
        self._pending_level_up = True
        self._audio.play_sfx("level_up")
        # Level-up celebration visuals
        self._levelup_flash_timer = 0.15
        self._levelup_text_timer = 2.0
        self._levelup_level = new_level
        if self._particles:
            self._particles.emit_levelup(self._player.position)

    def _on_boss_phase_change(self, new_phase):
        """Boss transitioned to a new phase — screen flash, slow-motion."""
        self._boss_phase_flash = 0.2
        self._boss_phase_slowmo = 0.3
        self._hitstop_frames = 4  # Brief freeze on transition
        camera = self.find(CameraController, recursive=False)
        if camera:
            camera.boss_shake(intensity=10.0, duration=0.3)

    def _on_boss_killed(self):
        """Boss defeated — show victory screen.

        Note: _on_enemy_killed is already called from _check_player_attacks
        when the boss hp hits 0, so we don't call it again here.
        """
        self.gm.boss_defeated = True
        self._stats.record_boss_kill()
        self._achievements.check(self._stats)
        self._victory_popup.set_context(player=self._player, dungeon_level=self._dungeon_level)
        self._popups.open(self._victory_popup)

    def _on_consumable_used(self, template_key: str):
        """Handle scroll/consumable effects from inventory UI."""
        if template_key == "town_portal_scroll":
            if self._state == STATE_DUNGEON:
                self._return_floor = self._dungeon_level
                self._popups.close()
                self._transition.transition(self._enter_town)
        elif template_key == "fire_scroll":
            self._popups.close()
            # AoE fire burst at player position
            derived = self._compute_stats()
            dmg = 40 + int(derived.get("spell_power", 0))
            hitbox = Hitbox(damage=dmg, direction=Vec2(0, 1), name="MeleeHit")
            hitbox.position = Vec2(self._player.position.x, self._player.position.y)
            hitbox._col.radius = 80
            hitbox.lifetime = 0.25
            self.add_child(hitbox)
            # Fire particles
            if self._particles:
                self._particles.emit(
                    12, self._player.position, vel_range=(-60, 60),
                    colour=(1.0, 0.4, 0.1, 1.0), lifetime=0.5,
                )

    def _on_victory_continue(self):
        """Continue to free play after boss victory."""
        self._dungeon_level += 1
        lvl = self._dungeon_level
        self._transition.transition(lambda: self._load_dungeon(lvl))

    def _on_title_action(self, action):
        if action == "confirm_new_game":
            self._popups.open(ConfirmDialog(
                "Overwrite existing save?",
                on_confirm=lambda yes: self._transition.transition(self._start_new_game) if yes else
                           self._popups.open(self._title_popup),
            ))
        elif action == "settings":
            self._settings_popup._on_close_cb = self._on_title_settings_close
            self._popups.open(self._settings_popup)
        elif action == "new_game":
            self._transition.transition(self._start_new_game)
        elif action == "continue":
            self._transition.transition(self._continue_game)
        elif action == "quit":
            if hasattr(self, 'app') and self.app:
                self.app.quit()

    def _on_title_settings_close(self):
        """Return to title screen after closing settings from the title menu."""
        self._on_settings_close()
        self._settings_popup._on_close_cb = self._on_settings_close  # Restore normal callback
        self._popups.open(self._title_popup)

    def _on_pause_action(self, action):
        if action == "confirm_quit_to_title":
            self._popups.open(ConfirmDialog("Quit to title?", on_confirm=self._on_quit_confirmed))
        elif action == "quit_to_title":
            self._do_quit_to_title()
        elif action == "save_game":
            self._save_current_game()
        elif action == "stats":
            self._popups.open(self._stats_popup)
        elif action == "achievements":
            self._popups.open(self._achievement_log_popup)
        elif action == "settings":
            self._popups.open(self._settings_popup)
        elif action == "level_up":
            if self._player.stat_points > 0:
                self._popups.open(self._level_up_popup)

    def _on_settings_close(self):
        """Apply settings when settings menu closes."""
        # Sync fullscreen state
        app = getattr(self._tree, '_app', None)
        if app and hasattr(app, 'is_fullscreen') and hasattr(app, 'toggle_fullscreen'):
            if app.is_fullscreen != game_settings.fullscreen:
                app.toggle_fullscreen()

    def _on_hotbar_slot_clicked(self, slot_index: int):
        """Activate ability or use item in hotbar slot."""
        self._activate_hotbar(slot_index)

    def _activate_hotbar(self, slot: int):
        """Activate a hotbar slot — skill or consumable item."""
        entry = self._skill_tree.hotbar[slot] if 0 <= slot < 4 else None
        if not entry:
            return
        if entry.startswith("item:"):
            template_key = entry[5:]
            self._use_hotbar_item(template_key)
        else:
            nearby = [e for e in self.find_all(EnemyBase) if e.hp > 0]
            nodes = self._skill_tree.activate(slot, self._player, targets=nearby)
            for node in nodes:
                self.add_child(node)

    def _use_hotbar_item(self, template_key: str):
        """Use a consumable item from inventory via hotbar."""
        if self._inventory is None:
            return
        for idx in range(self._inventory.capacity):
            item = self._inventory.get(idx)
            if item and item.is_consumable and item.template_key == template_key:
                if template_key == "potion":
                    heal = int(item.base_stats.get("heal", 30))
                    self._player.heal(heal)
                elif template_key in ("town_portal_scroll", "fire_scroll"):
                    self._on_use_consumable(template_key)
                if item.stack_count > 1:
                    item.stack_count -= 1
                else:
                    self._inventory.remove(idx)
                return

    def _on_hotbar_slot_long_pressed(self, slot_index: int):
        """Open hotbar assignment popup for the given slot."""
        self._hotbar_assign_popup.open_for_slot(slot_index)
        self._popups.open(self._hotbar_assign_popup)

    def _on_quit_confirmed(self, confirmed: bool):
        if confirmed:
            self._do_quit_to_title()

    def _do_quit_to_title(self):
        self._save_current_game()
        self._popups.close()
        self._state = STATE_TITLE
        for old in self.find_all(DungeonLevel) + self.find_all(CameraController):
            if old.parent is self:
                old.destroy()
        for old in self.find_all(EnemyBase):
            old.destroy()
        if self._town_scene and self._town_scene.parent:
            self._town_scene.destroy()
            self._town_scene = None
        self._popups.open(self._title_popup)

    def _save_current_game(self):
        save = capture_save_data(self._player, self._inventory, self.gm, self._fog,
                                quest_manager=self._quest_mgr, skill_tree=self._skill_tree)
        save_game(save, SAVE_PATH)
        self._hud.show_save_indicator()

    def _on_npc_interact(self, npc_id: str):
        """Handle NPC interaction in town."""
        from data.dialogs import DIALOGS

        dialog_tree = DIALOGS.get(npc_id)
        if not dialog_tree:
            return

        game_state = {
            "gold": self._player.gold,
            "level": self._player.level,
            "dungeon_level": self._dungeon_level,
            "max_dungeon_reached": self.gm.max_dungeon_reached,
        }
        self._dialog_popup.start(dialog_tree, game_state, on_action=self._on_dialog_action)
        self._popups.open(self._dialog_popup)

    def _on_dialog_action(self, action: str):
        if action == "inn_rest":
            Inn.rest(self._player)
        elif action == "well_reroll":
            Well.reroll(self._player, self.gm)
        elif action == "open_shop":
            # Generate shop items
            import random
            rng = random.Random(self._dungeon_level)
            shop_items = [self._item_gen.roll_item(ilvl=self._dungeon_level, rng=rng) for _ in range(6)]
            self._shop_popup.setup(self._inventory, shop_items, player=self._player)
            # Close dialog first, then open shop
            self._popups.close()
            self._popups.open(self._shop_popup)
        elif action == "open_sell":
            import random
            rng = random.Random(self._dungeon_level)
            shop_items = [self._item_gen.roll_item(ilvl=self._dungeon_level, rng=rng) for _ in range(6)]
            self._shop_popup.setup(self._inventory, shop_items, player=self._player)
            self._shop_popup._selected_side = 1  # Start on player inventory (sell side)
            self._popups.close()
            self._popups.open(self._shop_popup)
        elif action == "open_quest_board":
            self._quest_board_popup.set_floor(self._dungeon_level)
            self._popups.close()
            self._popups.open(self._quest_board_popup)
        elif action == "open_blacksmith":
            self._popups.close()
            from scripts.blacksmith import upgrade
            # Find first group of 3 same-rarity items
            items_by_rarity: dict[int, list[int]] = {}
            for idx, item in self._inventory.items():
                r = int(item.rarity)
                items_by_rarity.setdefault(r, []).append(idx)
            forged = False
            for _, idxs in items_by_rarity.items():
                if len(idxs) >= 3:
                    result = upgrade(self._inventory, idxs[:3])
                    if result:
                        notif = LootDrop(f"Forged: {result.display_name}", colour=result.colour)
                        notif.position = Vec2(self._player.position.x, self._player.position.y - 20)
                        self.add_child(notif)
                        self._audio.play_sfx("level_up")
                        forged = True
                    break
            if not forged:
                notif = LootDrop("Need 3 items of the same rarity!", colour=(0.8, 0.4, 0.4, 1.0))
                notif.position = Vec2(self._player.position.x, self._player.position.y - 20)
                self.add_child(notif)
        elif action == "repair_equipment":
            if self._player.gold >= 50:
                self._player.gold -= 50
                repaired = 0
                for slot in ("weapon", "offhand", "head", "body", "feet", "ring", "neck"):
                    item = self._inventory.get_equipped(slot)
                    if item and item.durability < item.max_durability:
                        item.repair()
                        repaired += 1
                msg = f"Repaired {repaired} items!" if repaired > 0 else "All equipment in good shape!"
                notif = LootDrop(msg, colour=(0.4, 0.8, 0.4, 1.0))
                notif.position = Vec2(self._player.position.x, self._player.position.y - 20)
                self.add_child(notif)
        elif action == "open_enchanter":
            self._enchanter_popup.setup(self._inventory, player=self._player)
            self._popups.close()
            self._popups.open(self._enchanter_popup)

    def _on_shop_transaction(self, txn_type, item, price):
        pass  # Gold is updated directly in ShopUI

    # ── Quest rewards ─────────────────────────────────────────────────

    def _on_quest_claimed(self, quest_name: str, rewards: dict):
        """Apply quest rewards to the player."""
        gold = rewards.get("gold", 0)
        xp = rewards.get("xp", 0)
        if gold:
            self._player.gold += gold
            self._stats.record_gold(gold)
        if xp:
            self._player.gain_xp(xp)
        self._stats.record_quest_complete()
        self._hud.notify_quest_complete(f"Claimed: {quest_name}")

    # ── Waypoints / chests ─────────────────────────────────────────────

    def _on_waypoint_teleport(self, floor: int):
        """Teleport player to a previously activated waypoint floor."""
        self._save_current_game()
        self._dungeon_level = floor
        self._transition.transition(lambda: self._load_dungeon(floor))

    def _populate_special_objects(self, data, level):
        """Add chests and waypoints to dungeon data."""
        import random as rng_mod
        rng = rng_mod.Random(level)
        # Skip entrance room (first) and exit room (last) for chests
        safe_rooms = data.rooms[1:-1] if len(data.rooms) > 2 else []
        for room in safe_rooms:
            if rng.random() < 0.15:
                data.special_objects.append({"type": "chest", "gx": room.cx, "gy": room.cy})
        if level % 10 == 0:
            data.special_objects.append({"type": "waypoint", "gx": data.entrance[0], "gy": data.entrance[1]})

    def _check_special_interact(self):
        """Check if the player is near a chest or waypoint and interact."""
        dungeon = self.find(DungeonLevel, recursive=False)
        if not dungeon:
            return
        data = dungeon.dungeon_data
        px, py = self._player.position.x, self._player.position.y
        for obj in data.special_objects:
            ox = obj["gx"] * TILE_SIZE + TILE_SIZE / 2
            oy = obj["gy"] * TILE_SIZE + TILE_SIZE / 2
            dx, dy = px - ox, py - oy
            if dx * dx + dy * dy > 30 * 30:
                continue
            if obj["type"] == "chest":
                key = (self._dungeon_level, obj["gx"], obj["gy"])
                if key not in self._opened_chests:
                    self._opened_chests.add(key)
                    self._stats.record_chest_opened()
                    self._audio.play_sfx("chest_open")
                    # Sparkle particles on chest open
                    if self._particles:
                        self._particles.emit(
                            8, Vec2(ox, oy), vel_range=(-40, 40),
                            colour=(1.0, 0.85, 0.3, 1.0), lifetime=0.4,
                        )
                    import random
                    item = self._item_gen.roll_item(ilvl=self._dungeon_level, rng=random.Random())
                    pickup = LootPickup(item)
                    pickup.position = Vec2(ox, oy - 10)
                    self.add_child(pickup)
            elif obj["type"] == "waypoint":
                self.gm.activate_waypoint(self._dungeon_level)
                self._save_current_game()
                self._waypoint_popup.set_waypoints(self.gm.activated_waypoints)
                self._popups.open(self._waypoint_popup)
                break

    # ── Draw ───────────────────────────────────────────────────────────

    def _tile_visible(self, world_x: float, world_y: float) -> bool:
        """Check if a world position is in a currently visible fog tile."""
        if not self._fog:
            return True
        gx = int(world_x / TILE_SIZE)
        gy = int(world_y / TILE_SIZE)
        return self._fog.get_state(gx, gy) == 2

    def draw(self, renderer):
        if self._state != STATE_DUNGEON:
            return
        dungeon = self.find(DungeonLevel, recursive=False)
        if dungeon:
            ts = TILE_SIZE
            ep = dungeon.exit_world_pos()
            if self._tile_visible(ep.x, ep.y):
                renderer.draw_filled_rect(ep.x - ts // 2, ep.y - ts // 2, ts, ts, (0.6, 0.1, 0.1, 0.8))
                renderer.draw_text("EXIT", (ep.x - 14, ep.y - ts // 2 - 14), scale=1.2, colour=(1.0, 0.4, 0.4))
                if self._near(ep):
                    renderer.draw_text("[E] Descend", (ep.x - 30, ep.y + ts // 2 + 4), scale=0.8, colour=(1.0, 0.9, 0.3))
            sp = dungeon.entrance_world_pos()
            if self._tile_visible(sp.x, sp.y):
                renderer.draw_filled_rect(sp.x - ts // 2, sp.y - ts // 2, ts, ts, (0.1, 0.4, 0.2, 0.5))
                renderer.draw_text("STAIRS", (sp.x - 18, sp.y - ts // 2 - 14), scale=1.0, colour=(0.4, 0.9, 0.5))
                if self._near(sp):
                    renderer.draw_text("[E] Return to town", (sp.x - 46, sp.y + ts // 2 + 4), scale=0.8, colour=(1.0, 0.9, 0.3))

            # Special objects (chests, waypoints) — only draw if visible
            for obj in dungeon.dungeon_data.special_objects:
                ox = obj["gx"] * ts + ts // 2
                oy = obj["gy"] * ts + ts // 2
                if not self._tile_visible(ox, oy):
                    continue
                if obj["type"] == "chest":
                    key = (self._dungeon_level, obj["gx"], obj["gy"])
                    if key not in self._opened_chests:
                        renderer.draw_filled_rect(ox - 7, oy - 2, 14, 8, (0.6, 0.45, 0.15, 0.9))
                        renderer.draw_filled_rect(ox - 8, oy - 5, 16, 4, (0.75, 0.6, 0.2, 0.9))
                        renderer.draw_filled_rect(ox - 1, oy - 3, 2, 3, (0.9, 0.8, 0.3, 1.0))
                        renderer.draw_text("?", (ox - 3, oy - 16), scale=1.0, colour=(1.0, 0.9, 0.3))
                elif obj["type"] == "waypoint":
                    renderer.draw_filled_rect(ox - 3, oy - 2, 6, 12, (0.5, 0.5, 0.55, 0.8))
                    renderer.draw_filled_triangle(ox, oy - 10, ox - 5, oy - 2, ox + 5, oy - 2,
                                                  (0.2, 0.5, 1.0, 0.8))
                    renderer.draw_filled_circle(ox, oy - 6, 3, (0.4, 0.7, 1.0, 0.9))

        # Click-to-path visual feedback (drawn in world space)
        if game_settings.control_mode == "click_to_path":
            self._click_ctrl.draw(renderer)


class _VirtualControlsDrawLayer(Node2D):
    """Screen-space overlay for virtual controls (drawn in CanvasLayer).

    Lives in UILayer (ProcessMode.ALWAYS) so it processes even when the
    tree is paused — this is what makes the gamepad work inside popups.

    Uses physics_process (runs before process in the frame) so injected
    key events are visible to game code in the same frame's process().
    """

    def __init__(self, overlay, game, **kwargs):
        super().__init__(name="VirtualControlsLayer", **kwargs)
        self._overlay = overlay
        self._game = game

    def physics_process(self, dt: float):
        g = self._game
        overlay = self._overlay
        overlay.visible = (
            game_settings.control_mode == "virtual_gamepad"
            and g._state != STATE_TITLE
        )
        if not overlay.visible:
            return
        sw, sh = (self._tree.screen_size if self._tree else (1280, 720))
        overlay.configure(sw, sh, mobile=g._is_mobile_web)
        near_interact = g._state == STATE_TOWN
        if not near_interact and g._state == STATE_DUNGEON:
            near_interact = g._is_near_interactable()
        in_menu = g._state == STATE_TOWN or g._popups.is_open
        overlay.set_context(
            has_shield=g._player._has_shield,
            near_interactable=near_interact,
            in_menu=in_menu,
        )
        overlay.process(dt, None if g._popups.is_open else g._player)

    def draw(self, renderer):
        self._overlay.draw(renderer)


def main():
    debug = "--debug" in sys.argv
    app = App(
        title="Dungeon Explorer",
        width=1280,
        height=720,
        bg_colour=(0.08, 0.07, 0.06, 1.0),
        backend="sdl3",
    )
    app.run(DungeonGame(name="DungeonGame", debug=debug))


if __name__ == "__main__":
    main()