Dungeon Explorer

2D top-down dungeon crawler.

▶ Run in browser

Run: uv run python examples/demos/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

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

Run: uv run python examples/demos/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)
"""

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 events import (
    BossDefeated,
    BossPhaseChanged,
    HotbarSlotClicked,
    HotbarSlotLongPressed,
    PlayerDied,
    PlayerLevelledUp,
)
from nodes.abilities import TrapNode
from nodes.achievements import AchievementLogUI, AchievementManager
from nodes.audio_manager import AudioManager
from nodes.boss_enemy import BossEnemy
from nodes.boss_health_bar import BossHealthBar
from nodes.camera_controller import CameraController
from nodes.combat import Hitbox, apply_defence
from nodes.confirm_dialog import ConfirmDialog
from nodes.death_screen import DeathScreen
from nodes.dialog_ui import DialogUI
from nodes.enchanter import EnchanterUI
from nodes.enemy_base import EnemyBase
from nodes.game_manager import GameManager
from nodes.hotbar_assign_ui import HotbarAssignUI
from nodes.inn import Inn
from nodes.inventory_ui import InventoryUI
from nodes.level_up_ui import LevelUpUI
from nodes.loading_screen import LoadingScreen
from nodes.loot_drop import LootDrop
from nodes.loot_pickup import LootPickup
from nodes.particles2d import SimpleParticles
from nodes.pause_menu import PauseMenu
from nodes.player import Player
from nodes.player_hud import PlayerHUD
from nodes.player_pause_bridge import PlayerPauseBridge
from nodes.projectile import Projectile
from nodes.quest_board import QuestBoardUI
from nodes.quest_log_ui import QuestLogUI
from nodes.settings_ui import SettingsUI, game_settings
from nodes.shop import ShopUI
from nodes.skill_tree_ui import SkillTreeUI
from nodes.stats_tracker import StatsPanel, StatsTracker
from nodes.title_screen import TitleScreen
from nodes.transition_overlay import TransitionOverlay
from nodes.victory_screen import VictoryScreen
from nodes.village import VILLAGE_H, VILLAGE_W, VillageScene
from nodes.waypoint_ui import WaypointUI
from nodes.well import Well
from scripts.click_controller import ClickController
from scripts.dungeon_generator import TILE_SIZE, DungeonLevel, generate_dungeon, path_exists
from scripts.dungeon_theme import get_theme
from scripts.enemy_spawner import spawn_all_dungeon_enemies
from scripts.fog_of_war import FogOfWar
from scripts.inventory import Inventory
from scripts.item import RARITY_NAMES, Rarity
from scripts.item_generator import ItemGenerator
from scripts.player_skills import SkillTree
from scripts.player_stats import compute_derived_stats
from scripts.quests import QuestManager
from scripts.save_state import SaveBag
from scripts.tutorial import TutorialManager
from scripts.weapons import get_melee_profile, get_ranged_profile, is_ranged, melee_attack, ranged_attack

from simvx.core import CanvasLayer, Input, InputMap, Key, Node2D, SaveManager, UpdateMode, Vec2
from simvx.core.ui import GamepadOverlay
from simvx.graphics import App

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

DATA_DIR = Path(__file__).resolve().parent / "data"
SAVE_DIR = Path(_GAME_DIR) / "saves"
SAVE_SLOT = "savegame"
SAVE_PATH = SAVE_DIR / f"{SAVE_SLOT}.sav"

# 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 on_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_rect((px, py_), (ts, ts), colour=(0.0, 0.0, 0.0, 1.0), filled=True)
                else:
                    # Explored but not currently visible: semi-transparent dark overlay
                    renderer.draw_rect((px, py_), (ts, ts), colour=(0.0, 0.0, 0.0, 0.55), filled=True)

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 on_update(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 on_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_rect((0, 0), (sw, sh), colour=(1.0, 0.95, 0.7, alpha * 0.4), filled=True)

        # 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_rect((0, 0), (sw, sh), colour=(1.0, 0.3, 0.1, alpha * 0.3), filled=True)

        # 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_rect((ax, 20), (360, 50), colour=(0.1, 0.1, 0.15, 0.9 * a), filled=True)
            renderer.draw_rect((ax, 20), (360, 2), colour=(1.0, 0.85, 0.2, 0.8 * a), filled=True)
            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 on_ready(self):
        # PAUSABLE (default) so children (enemies, particles) pause when a
        # modal opens. PlayerPauseBridge handles the player pause; modals
        # and TransitionOverlay run in ALWAYS mode where needed.

        # 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)

        # SaveBag: child Node holding ``persist=True`` Property snapshots of the
        # non-Node subsystems (inventory, fog, quests, skills). Synced from the
        # live objects in :meth:`_save_current_game` and read back in
        # :meth:`_continue_game`. ``simvx.core.SaveManager`` walks every
        # ``persist=True`` Property in the tree on save/apply.
        self._save_bag = SaveBag()
        self.add_child(self._save_bag)
        self._save_mgr = SaveManager(save_dir=SAVE_DIR)

        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.update_mode = UpdateMode.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)

        # Player-pause bridge: toggles only player.update_mode on modal events
        # so HUD, ambient audio, and music keep ticking while a popup is open.
        self._popups = PlayerPauseBridge()
        self._ui_layer.add_child(self._popups)

        # Popup instances: modal Controls parented under the UI layer.
        # Each popup is a top-level Control with set_anchor_preset(FULL_RECT)
        # so it draws screen-space regardless of where it's parented.
        def _add_popup(popup):
            self._ui_layer.add_child(popup)
            return popup

        self._pause_popup = _add_popup(PauseMenu(on_action=self._on_pause_action))
        self._inventory_popup = _add_popup(InventoryUI(on_use_consumable=self._on_consumable_used))
        self._inventory_popup.set_inventory(self._inventory)
        self._level_up_popup = _add_popup(LevelUpUI())
        self._death_popup = _add_popup(DeathScreen(on_respawn=self._on_respawn))
        self._title_popup = _add_popup(TitleScreen(on_action=self._on_title_action, save_path=SAVE_PATH))
        self._dialog_popup = _add_popup(DialogUI())
        self._shop_popup = _add_popup(ShopUI(on_transaction=self._on_shop_transaction))
        self._victory_popup = _add_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 = _add_popup(SkillTreeUI(self._skill_tree))

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

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

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

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

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

        # Loading screen
        self._loading_popup = _add_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 = _add_popup(QuestBoardUI(self._quest_mgr))
        self._quest_log_popup = _add_popup(QuestLogUI(self._quest_mgr, on_claim=self._on_quest_claimed))

        # Waypoint popup
        self._waypoint_popup = _add_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.add_child(self._player)

        self._popups.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)

        # Typed-event connections via the engine EventBus. The bus holds
        # ``WeakMethod`` refs so handlers detach automatically when this
        # node is freed -- no explicit disconnect required on scene change.
        bus = self.tree.events
        bus.subscribe(PlayerDied, self._on_player_died_event)
        bus.subscribe(PlayerLevelledUp, self._on_player_levelled_up_event)
        bus.subscribe(HotbarSlotClicked, self._on_hotbar_clicked_event)
        bus.subscribe(HotbarSlotLongPressed, self._on_hotbar_long_pressed_event)
        bus.subscribe(BossDefeated, self._on_boss_defeated_event)
        bus.subscribe(BossPhaseChanged, self._on_boss_phase_changed_event)

        # 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 = GamepadOverlay()
        self._vc_draw_layer = _VirtualControlsDrawLayer(self._virtual_controls, self)
        self._ui_layer.add_child(self._vc_draw_layer)

        # Auto-detect mobile/web: WebApp exposes is_mobile (set by JS before
        # set_root); desktop App does not. Both have an `engine` attribute, so
        # is_mobile is the clean discriminator.
        app = self.app
        self._is_mobile_web = getattr(app, 'is_mobile', False) if app else False
        if app is not None and hasattr(app, 'is_mobile'):
            # 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.reset_run_state()
        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."""
        try:
            data = self._save_mgr.load(SAVE_SLOT)
        except FileNotFoundError:
            self._start_new_game()
            return
        # SaveManager pours every persisted Property back onto the live tree
        # (player stats including position, GameManager state, SaveBag dicts).
        # Procedural nodes (DungeonLevel, WallBody, EnemyBase) opt out of
        # snapshot via ``__save_persist__ = False`` and are rebuilt from the
        # dungeon seed in ``_load_dungeon`` below.
        self._save_mgr.apply(self, data)

        bag = self._save_bag
        if bag.inventory_data:
            self._inventory = Inventory.from_dict(bag.inventory_data)
        else:
            self._inventory = Inventory()
        self._inventory_popup.set_inventory(self._inventory)

        self._fog = FogOfWar.from_dict(bag.fog_data) if bag.fog_data else None
        if bag.quests_data:
            self._quest_mgr.from_dict(bag.quests_data)
        if bag.skills_data:
            self._skill_tree.from_dict(bag.skills_data)
        self._opened_chests = {tuple(t) for t in bag.opened_chests_data}
        self.tutorial_seen = bool(bag.tutorial_seen)

        self._dungeon_level = self.gm.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, direct=True)
        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
        import random as rng_mod

        from scripts.room_templates import apply_random_decoration
        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 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, CORRIDOR, FLOOR
        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, direct=True)
        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-specific events (BossDefeated, BossPhaseChanged) are
            # delivered via ``self.tree.events`` -- subscribed in ``ready``.
            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, direct=True)
        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 on_update(self, dt: float):
        # F11 fullscreen toggle (always available)
        if Input.is_action_just_pressed("toggle_fullscreen"):
            app = self.app
            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, direct=True)
            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, direct=True)
            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, direct=True)
            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.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, direct=True)
                        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, direct=True)
            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, direct=True)
            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 nodes.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, direct=True)
        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, direct=True)
        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, direct=True)
        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, direct=True)
        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, direct=True)
        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 nodes.enemy_types import create_enemy, make_elite
            dungeon_node = self.find(DungeonLevel, direct=True)
            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 ──────────────────────────────────────────────────────

    # Typed-event adapters. Subscribers on ``self.tree.events`` receive the
    # full event dataclass; these thin wrappers preserve the original handler
    # signatures so internal call sites stay unchanged.

    def _on_player_died_event(self, event: PlayerDied) -> None:
        self._on_player_died()

    def _on_player_levelled_up_event(self, event: PlayerLevelledUp) -> None:
        self._on_level_up(event.new_level)

    def _on_hotbar_clicked_event(self, event: HotbarSlotClicked) -> None:
        self._on_hotbar_slot_clicked(event.slot)

    def _on_hotbar_long_pressed_event(self, event: HotbarSlotLongPressed) -> None:
        self._on_hotbar_slot_long_pressed(event.slot)

    def _on_boss_defeated_event(self, event: BossDefeated) -> None:
        self._on_boss_killed()

    def _on_boss_phase_changed_event(self, event: BossPhaseChanged) -> None:
        self._on_boss_phase_change(event.new_phase)

    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, direct=True)
        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.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 _open_confirm(self, message: str, on_confirm) -> None:
        """Instantiate, parent, and open a ConfirmDialog."""
        dialog = ConfirmDialog(message, on_confirm=on_confirm)
        self._ui_layer.add_child(dialog)
        self._popups.open(dialog)

    def _on_title_action(self, action):
        if action == "confirm_new_game":
            self._open_confirm(
                "Overwrite existing save?",
                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._open_confirm("Quit to title?", 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 = self.app
        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_consumable_used(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):
        # Let SaveManager walk the tree and pickle every ``persist=True``
        # Property in one shot (player.position is now a persisted Property).
        bag = self._save_bag
        bag.inventory_data = self._inventory.to_dict() if self._inventory else {}
        bag.fog_data = self._fog.to_dict() if self._fog else {}
        bag.quests_data = self._quest_mgr.to_dict() if self._quest_mgr else {}
        bag.skills_data = self._skill_tree.to_dict() if self._skill_tree else {}
        seed = self.gm._dungeon_seed
        bag.has_dungeon_seed = seed is not None
        bag.dungeon_seed = int(seed) if seed is not None else 0
        bag.opened_chests_data = tuple(self._opened_chests)
        bag.tutorial_seen = bool(self.tutorial_seen)

        self._save_mgr.save(self, SAVE_SLOT)
        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, direct=True)
        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 on_draw(self, renderer):
        if self._state != STATE_DUNGEON:
            return
        dungeon = self.find(DungeonLevel, direct=True)
        if dungeon:
            ts = TILE_SIZE
            ep = dungeon.exit_world_pos()
            if self._tile_visible(ep.x, ep.y):
                renderer.draw_rect((ep.x - ts // 2, ep.y - ts // 2), (ts, ts), colour=(0.6, 0.1, 0.1, 0.8), filled=True)
                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_rect((sp.x - ts // 2, sp.y - ts // 2), (ts, ts), colour=(0.1, 0.4, 0.2, 0.5), filled=True)
                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_rect((ox - 7, oy - 2), (14, 8), colour=(0.6, 0.45, 0.15, 0.9), filled=True)
                        renderer.draw_rect((ox - 8, oy - 5), (16, 4), colour=(0.75, 0.6, 0.2, 0.9), filled=True)
                        renderer.draw_rect((ox - 1, oy - 3), (2, 3), colour=(0.9, 0.8, 0.3, 1.0), filled=True)
                        renderer.draw_text("?", (ox - 3, oy - 16), scale=1.0, colour=(1.0, 0.9, 0.3))
                elif obj["type"] == "waypoint":
                    renderer.draw_rect((ox - 3, oy - 2), (6, 12), colour=(0.5, 0.5, 0.55, 0.8), filled=True)
                    renderer.fill_triangle(ox, oy - 10, ox - 5, oy - 2, ox + 5, oy - 2,
                                                  colour=(0.2, 0.5, 1.0, 0.8))
                    renderer.draw_circle((ox, oy - 6), 3, colour=(0.4, 0.7, 1.0, 0.9), filled=True)

        # 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 (UpdateMode.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 on_fixed_update(self, dt: float):
        g = self._game
        overlay = self._overlay
        overlay.visible = game_settings.control_mode == "virtual_gamepad"
        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_TITLE
            or 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.on_update(dt)
        # GamepadOverlay exposes joystick_value; the player consumes it via
        # _virtual_input. Skip propagation while a popup owns input.
        if not g._popups.is_open:
            g._player._virtual_input = overlay.joystick_value

    def on_draw(self, renderer):
        self._overlay.on_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),
    )
    app.run(DungeonGame(name="DungeonGame", debug=debug))

if __name__ == "__main__":
    main()