Dungeon Explorer

a 100-floor action-RPG descent with loot, skills, and a village hub.

▶ Run in browser

Fight down through procedurally generated floors, collect randomised loot with rolled affixes and rarities, spend skill points, and finish the run against a three-phase boss on floor 100. Every tenth floor returns you to a village hub with a shop, an inn, a quest board, an enchanter, a forge, and a seed-rerolling well. Beating the boss starts New Game+ with your gear and a harder dungeon.

A flagship showcase of the engine’s 2D stack:

• BSP dungeon generation stamped into an instanced TileMap (one draw for the whole floor), with per-floor themes, secret rooms, traps, and chests.

• CharacterBody2D movement and collision layers for player and enemies, plus NavGrid2D pathfinding behind the chase and kite AI (fleeing just runs the other way).

• Combat built from weapon profiles: melee arcs, projectiles, crits, knockback, dodge-roll invincibility frames, shield blocks, and hit-stop.

• Fog of war as a dimming layer on the floor TileMap, recomputed only when the player crosses a tile boundary.

• One-call save/load: SaveManager snapshots every persist=True Property in the tree, with the non-Node subsystems parked on a SaveBag node.

• Typed gameplay events (deaths, level-ups, boss phases, hotbar presses) on the SceneTree event bus, which holds a node’s handlers weakly.

• Twenty anchored Control screens (inventory, skill tree, shops, quest log, stats, achievements, settings, …) and procedural sound effects baked with AudioSynth: the demo ships no audio files.

• Playable with keyboard, mouse, or touch: Settings switches between keyboard, click-to-path, and an on-screen virtual controller.

Run: simvx examples run demos_dungeon_explorer

Saves are written to $XDG_DATA_HOME/simvx/dungeon_explorer/ (~/.local/share when that variable is unset), never beside the game; set $DUNGEON_EXPLORER_SAVE_DIR to put them somewhere else.

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

Source files

File	Summary	Lines
main.py	Dungeon Explorer: a 100-floor action-RPG descent with loot, skills, and a village hub.	1947
collision_layers.py	Collision layers for Dungeon Explorer.	29
data/__init__.py		0
data/dialogs.py	NPC dialog trees: Python dicts with callable conditions and actions.	171
events.py	Typed event dataclasses for the Dungeon Explorer game.	86
nodes/__init__.py	Dungeon Explorer scene-graph node classes (Node2D, Popup, CharacterBody2D, etc.).	4
nodes/_back_button.py	Back-button helpers shared across popup screens.	57
nodes/abilities.py	Active ability implementations with visual effects.	366
nodes/achievements.py	Achievement system: unlock conditions, popup notifications, and log.	202
nodes/audio_manager.py	Centralised audio manager: procedural SFX via the engine AudioSynth API.	190
nodes/boss_enemy.py	Multi-phase boss enemy for level 100.	271
nodes/boss_health_bar.py	Boss HP bar overlay: displayed during boss encounters.	39
nodes/camera_controller.py	Camera2D controller: smooth follow with room bounds clamping and directional shake.	86
nodes/combat.py	Combat system: hitbox management, damage formulas, cooldowns.	140
nodes/confirm_dialog.py	Reusable Yes/No confirmation modal.	123
nodes/credits_screen.py	Animated credits screen with scrolling text.	138
nodes/death_screen.py	Death / respawn overlay: red vignette, stat summary, pulsing respawn prompt.	129
nodes/dialog_ui.py	Dialog box: NPC portrait area, proper dialog box, typewriter text reveal.	259
nodes/enchanter.py	Enchanter NPC: add a random affix to equipment for gold.	200
nodes/enemy_base.py	Base enemy: CharacterBody2D with AI state machine and pathfinding.	596
nodes/enemy_types.py	Concrete enemy variants: melee, ranged, swarm, boss.	225
nodes/game_manager.py	Game manager: global state, scene transitions, and save/load orchestration.	135
nodes/hotbar_assign_ui.py	Hotbar assignment popup: assign unlocked active abilities to hotbar slots.	211
nodes/inn.py	Inn: rest/heal for gold.	25
nodes/inventory_ui.py	Inventory popup: 48px cells, drawn icons, rarity borders, equipment panel, mouse support.	613
nodes/item_tooltip.py	Item tooltip: hover panel showing item details with rarity-coloured stats.	70
nodes/level_up_ui.py	Stat point allocation screen shown on level up.	116
nodes/loading_screen.py	Loading screen: ‘Generating Dungeon…’ with progress indicator.	115
nodes/loot_drop.py	Floating loot notification: coloured text that drifts upward and fades.	29
nodes/loot_pickup.py	World item pickup: dropped by enemies, collected by player proximity.	78
nodes/particles2d.py	Simple 2D particle system for visual effects.	278
nodes/pause_menu.py	Pause overlay: centred panel, animated selector, floor/level/gold display.	226
nodes/player.py	Player character: CharacterBody2D with 8-direction movement, combat, and dodge roll.	434
nodes/player_hud.py	Player HUD: HP/XP bars (rounded), minimap, level label, hotbar with drawn icons.	540
nodes/player_pause_bridge.py	PlayerPauseBridge: toggles only the player’s update_mode on overlay events.	106
nodes/projectile.py	Projectile node for ranged attacks: travels in a direction, damages on contact.	108
nodes/quest_board.py	Quest board popup: rotating selection of quests with scroll support.	294
nodes/quest_log_ui.py	Quest log popup: active/completed tabs, progress bars, type icons, claim indicators.	248
nodes/settings_ui.py	Settings menu: audio, display, gameplay options as a Control overlay.	249
nodes/shop.py	Shop: dual-panel buy/sell UI with comparison tooltips and buy confirmation.	405
nodes/skill_tree_ui.py	Skill tree popup UI: tree lines, unique drawn icons, glow effects, full tooltip.	427
nodes/stats_tracker.py	Statistics tracker: per-run and lifetime game statistics.	246
nodes/title_screen.py	Title screen: New Game / Continue / Quit with decorative styling.	420
nodes/town.py	Town hub: safe zone between dungeon runs with NPCs.	72
nodes/town_npc.py	Town NPC base: dialog trigger and trade interface.	74
nodes/transition_overlay.py	Fade-to-black transition overlay.	66
nodes/victory_screen.py	Victory sequence: gold theme, particle fireworks, final stats, credits option.	235
nodes/village.py	Tile-based village: replaces the flat brown town.	366
nodes/waypoint_ui.py	Waypoint selection popup: teleport to previously visited floors.	120
nodes/well.py	The Well: coin toss to re-roll the dungeon, resets save points.	34
scripts/__init__.py		0
scripts/blacksmith.py	Blacksmith: combine 3 same-rarity items into 1 next-rarity item.	44
scripts/click_controller.py	Click-to-path controller – click ground to move, click enemy to attack, click interactable to interact.	238
scripts/dungeon_generator.py	BSP-based dungeon generator: rooms, corridors, floor/wall TileMap + collision.	930
scripts/dungeon_theme.py	Per-tier visual theming: tile palette and enemy pool by dungeon depth.	63
scripts/enemy_spawner.py	Room-based enemy spawning for dungeon levels.	129
scripts/fog_of_war.py	Per-tile fog of war visibility tracking.	79
scripts/inventory.py	Inventory grid logic: add/remove/equip/stack items.	145
scripts/item.py	Item class: base template + affixes + stat rolls.	181
scripts/item_generator.py	Loot generator: roll random items from TOML data files.	197
scripts/mini_boss.py	Mini-boss enemies: named elites on floors 25/50/75 with unique visuals.	62
scripts/player_skills.py	Skill tree: unlock, cooldown, passive bonus tracking.	143
scripts/player_stats.py	Derived stat computation: base + gear + level bonuses.	72
scripts/quests.py	Quest system: tracking, progression, and rewards.	170
scripts/room_templates.py	Pre-designed room shapes, decoration rules, and visual room decorations.	121
scripts/save_state.py	SaveBag: a Node holding persist=True Property snapshots of game-state	34
scripts/tutorial.py	Tutorial system: contextual tooltips for first-time players.	92
scripts/weapons.py	Weapon behaviours: melee arc and ranged projectile attacks.	90

Source

#!/usr/bin/env python3
"""Dungeon Explorer: a 100-floor action-RPG descent with loot, skills, and a village hub.

Fight down through procedurally generated floors, collect randomised loot with
rolled affixes and rarities, spend skill points, and finish the run against a
three-phase boss on floor 100. Every tenth floor returns you to a village hub
with a shop, an inn, a quest board, an enchanter, a forge, and a seed-rerolling
well. Beating the boss starts New Game+ with your gear and a harder dungeon.

A flagship showcase of the engine's 2D stack:

- BSP dungeon generation stamped into an instanced ``TileMap`` (one draw for the
  whole floor), with per-floor themes, secret rooms, traps, and chests.
- ``CharacterBody2D`` movement and collision layers for player and enemies, plus
  ``NavGrid2D`` pathfinding behind the chase and kite AI (fleeing just runs the
  other way).
- Combat built from weapon profiles: melee arcs, projectiles, crits, knockback,
  dodge-roll invincibility frames, shield blocks, and hit-stop.
- Fog of war as a dimming layer on the floor ``TileMap``, recomputed only when
  the player crosses a tile boundary.
- One-call save/load: ``SaveManager`` snapshots every ``persist=True`` Property
  in the tree, with the non-Node subsystems parked on a ``SaveBag`` node.
- Typed gameplay events (deaths, level-ups, boss phases, hotbar presses) on the
  ``SceneTree`` event bus, which holds a node's handlers weakly.
- Twenty anchored ``Control`` screens (inventory, skill tree, shops, quest log,
  stats, achievements, settings, ...) and procedural sound effects baked with
  ``AudioSynth``: the demo ships no audio files.
- Playable with keyboard, mouse, or touch: Settings switches between keyboard,
  click-to-path, and an on-screen virtual controller.

Run: simvx examples run demos_dungeon_explorer

Saves are written to ``$XDG_DATA_HOME/simvx/dungeon_explorer/`` (``~/.local/share``
when that variable is unset), never beside the game; set
``$DUNGEON_EXPLORER_SAVE_DIR`` to put them somewhere else.

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

import math
import os
import random
import sys
import tomllib
from pathlib import Path

from events import (
    BossDefeated,
    BossPhaseChanged,
    EnemyKilled,
    HotbarSlotClicked,
    HotbarSlotLongPressed,
    PlayerDied,
    PlayerLevelledUp,
)
from nodes.abilities import TrapNode
from nodes.achievements import AchievementLogUI, AchievementManager
from nodes.audio_manager import AudioManager, Sfx
from nodes.boss_enemy import BossEnemy
from nodes.boss_health_bar import BossHealthBar
from nodes.camera_controller import CameraController
from nodes.combat import DamageNumber, 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, Controller, Input, InputMap, InputMethod, Key, Node2D, SaveManager, UpdateMode, Vec2
from simvx.core.ui import TouchController
from simvx.graphics import App


def default_save_dir() -> Path:
    """Per-user save directory, overridable via ``$DUNGEON_EXPLORER_SAVE_DIR``.

    Content the game only reads (``data/``, scripts, nodes) lives beside this
    file and is resolved from ``__file__``. Anything the game *writes* goes to a
    user-owned directory instead, because the copy of this example you are
    running may be read-only: an installed library, a container image or a
    root-owned distribution package. Honours ``$XDG_DATA_HOME`` (falling back to
    ``~/.local/share``) on every platform; this game has no platform-specific
    path needs beyond that.
    """
    override = os.environ.get("DUNGEON_EXPLORER_SAVE_DIR")
    if override:
        return Path(override)
    base = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
    return base / "simvx" / "dungeon_explorer"


DATA_DIR = Path(__file__).resolve().parent / "data"
SAVE_DIR = default_save_dir()
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 _StatusOverlay(Node2D):
    """Screen-space status text and controls help (lives inside CanvasLayer)."""

    # ``on_draw`` reads non-Property live state every frame: timer-driven flashes
    # (level-up, boss phase, achievement fade), the live enemy count, and
    # tree.screen_size. Same per-frame contract as PlayerHUD -> honestly dynamic.
    dynamic = True

    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
        # Achievement popup: claim the next unlock, then fade it out. Held back
        # on the title screen so an unlock earned on the way out still shows.
        if g._state != STATE_TITLE:
            notif = g._achievements.pop_notification()
            if notif:
                g._achievement_notif = notif
                g._achievement_notif_timer = 3.0
            if g._achievement_notif_timer > 0:
                g._achievement_notif_timer -= dt

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

        # Get actual screen size
        sw, sh = self.viewport_size

        # Level-up screen flash
        if g._levelup_flash_timer > 0:
            alpha = g._levelup_flash_timer / 0.15
            renderer.rect((0, 0), (sw, sh), fill=(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.text(
                f"LEVEL {g._levelup_level}!", (sw / 2 - 100, sh * 0.39), fill=(1.0, 0.9, 0.3, alpha), scale=scale
            )
            renderer.text(
                "+3 Stat Points  +1 Skill Point",
                (sw / 2 - 120, sh * 0.44),
                fill=(0.8, 0.9, 1.0, alpha * 0.8),
                scale=1.0,
            )

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

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

        # Achievement notification (ticked in on_update)
        if g._achievement_notif_timer > 0:
            a = min(1.0, g._achievement_notif_timer / 0.5)
            name, desc = g._achievement_notif
            ax = sw - 380
            renderer.rect((ax, 20), (360, 50), fill=(0.1, 0.1, 0.15, 0.9 * a))
            renderer.rect((ax, 20), (360, 2), fill=(1.0, 0.85, 0.2, 0.8 * a))
            renderer.text(f"Achievement: {name}", (ax + 10, 28), fill=(1.0, 0.85, 0.2, a), scale=1.0)
            renderer.text(desc, (ax + 10, 48), fill=(0.7, 0.7, 0.7, a), scale=0.8)

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

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


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
        # A controller binding beside the key wherever the on-screen pad draws
        # a button for it, so the touch player reaches the same actions. The
        # pad has six buttons and the game has more verbs than that: the two
        # abilities the pad cannot reach stay keyboard-only, which is recorded
        # in the project's deficiency log rather than hidden here.
        InputMap.add_action("pause", [Key.ESCAPE, Controller.START])
        InputMap.add_action("next_level", [Key.N])
        InputMap.add_action("inventory", [Key.I, Controller.Y])
        InputMap.add_action("interact", [Key.E, Controller.X])
        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, Controller.LEFT_BUMPER])
        InputMap.add_action("ability_2", [Key.KEY_2, Controller.RIGHT_BUMPER])
        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 anchor=Anchor.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))

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

        # Achievements
        self._achievements = AchievementManager()
        self._achievement_log_popup = _add_popup(AchievementLogUI(self._achievements))
        self._achievement_notif: tuple[str, str] = ("", "")
        self._achievement_notif_timer = 0.0

        # 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
        # Last player grid tile the fog was updated for; gates fog redraws.
        self._last_fog_tile: tuple[int, int] | None = 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. A node's bound
        # methods are held weakly and detach when the node is destroyed, as
        # this scene is when change_scene replaces it.
        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)
        bus.subscribe(EnemyKilled, self._on_enemy_killed_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()

        # On-screen controller. It publishes as a real controller, so the
        # bindings above are the whole of the touch support: nothing in the
        # game reads it. Its own layer, so it is not hidden with the HUD.
        #
        # It brings itself on and off: auto_hide shows the pad the moment a
        # finger is used and takes it away when a real controller is, which is
        # the answer to "is this a phone" that does not have to guess. The
        # starting state is the input method the engine resolved at startup,
        # which is touch on a coarse pointer. The VIRTUAL CONTROLLER control mode
        # pins it on instead, for a laptop player who wants it.
        self._touch_pad = TouchController(
            name="TouchController",
            buttons=(
                Controller.A,
                Controller.B,
                Controller.X,
                Controller.Y,
                Controller.LEFT_BUMPER,
                Controller.RIGHT_BUMPER,
            ),
            visible=Input.input_method is InputMethod.TOUCH,
        )
        self._touch_pad.update_mode = UpdateMode.ALWAYS
        self.add_child(self._touch_pad)

        # 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."""
        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
        # Resume into whichever location was saved. A town save returns to the
        # hub; a dungeon save rebuilds the floor (same seed) and keeps the saved
        # player position and explored fog rather than teleporting to the entrance.
        if self.gm.in_town:
            self._enter_town()
        else:
            self._state = STATE_DUNGEON
            self._load_dungeon(self._dungeon_level, spawn_at_entrance=False, keep_fog=True)

    def _clear_level_nodes(self):
        """Destroy the current level: dungeon geometry, camera, and every enemy.

        Called on each floor load and whenever the run leaves the dungeon (town,
        title). The fog dimming layer lives on the dungeon's floor TileMap and
        goes with it, so there is no separate fog teardown.
        """
        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()

    def _enter_town(self):
        """Transition to town hub."""
        self._save_current_game()
        self._state = STATE_TOWN
        self.gm.enter_town()
        self._clear_level_nodes()
        # 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, spawn_at_entrance: bool = True, keep_fog: bool = False
    ):
        """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.
        """
        self._clear_level_nodes()

        # 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

        dec_rng = random.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)

        # Resume reuses the restored fog (same seed -> same dimensions) so the
        # explored map survives a save/load; floor transitions start fresh.
        if not (
            keep_fog and self._fog is not None and self._fog.width == data.width and self._fog.height == data.height
        ):
            self._fog = FogOfWar(data.width, data.height, reveal_radius=6)
        # Fog dimming is a layer of the floor TileMap (one instanced draw,
        # recomputed only on tile-step). Hand the level its fog now so the
        # dynamic torch/stair overlay can self-cull; the layer itself fills in
        # on the floor build (on_ready) and the first dungeon process frame.
        dungeon.update_fog(self._fog)

        # Floor transitions drop the player at the entrance; resume keeps the
        # saved position (already applied by SaveManager) so you continue where
        # you left off rather than being teleported to a "random" entrance.
        # Assigning position teleports the CharacterBody2D physics handle too,
        # so move_and_slide does not snap the player back.
        if spawn_at_entrance:
            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)
        self._click_ctrl.setup(
            self._player,
            camera,
            dungeon.nav_grid,
            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)

        # Reset the fog-step tracker so the first dungeon frame reveals around
        # the player and queues the dungeon/fog overlay redraw (see _process_dungeon).
        self._last_fog_tile = None

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

    def on_update(self, dt: float):
        # F11 fullscreen toggle (always available)
        if Input.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)

        # The on-screen pad runs in ALWAYS mode, so it still works while a
        # popup has paused the tree. VIRTUAL CONTROLLER pins it on; every other
        # mode hands it back to auto_hide, which shows it for a finger and
        # takes it away for a real controller.
        pinned = game_settings.control_mode == "virtual_controller"
        self._touch_pad.auto_hide = not pinned
        if pinned:
            self._touch_pad.visible = True

        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.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.just_pressed("inventory"):
            self._popups.open(self._inventory_popup)
            return
        if Input.just_pressed("skill_tree"):
            self._popups.open(self._skill_tree_popup)
            return
        if Input.just_pressed("quest_log"):
            self._popups.open(self._quest_log_popup)
            return

        # NPC interaction / dungeon entrance
        if self._town_scene:
            if Input.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.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.just_pressed("inventory"):
            self._popups.open(self._inventory_popup)
            return
        if Input.just_pressed("level_up") and self._player.stat_points > 0:
            self._popups.open(self._level_up_popup)
            return
        if Input.just_pressed("skill_tree"):
            self._popups.open(self._skill_tree_popup)
            return
        if Input.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.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.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.on_update(dt)

        # Combat. The on-screen pad publishes as a real controller, so the
        # Controller binding covers touch and nothing here is mode-specific.
        if Input.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)
            dungeon = self.find(DungeonLevel, direct=True)
            # Fog only changes when the player's reveal centre moves to a new
            # tile. Re-running fog.update on the same tile is a no-op, so gate the
            # fog-overlay redraw on the tile step. The floor itself is a static
            # instanced TileMap (built once), so it needs no per-step redraw.
            if (gx, gy) != self._last_fog_tile:
                self._last_fog_tile = (gx, gy)
                self._fog.update(gx, gy)
                if dungeon:
                    dungeon.update_fog(self._fog)
                # Fog revealed new tiles: re-emit the retained minimap background.
                self._hud.notify_fog_changed()
            # Set fog + dungeon data on projectiles for visibility and wall collision
            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.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: one tree scan for the whole frame, not one per trap
        traps = self.find_all(TrapNode)
        enemies = [e for e in self.find_all(EnemyBase) if e.hp > 0] if traps else []
        for trap_node in traps:
            triggered = trap_node.check_trigger(enemies)
            for enemy in triggered:
                enemy.take_damage(trap_node._damage, self._player.position)

        # 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
        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(Sfx.SWING)
        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):
        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 random.random() < dodge_chance:
                return  # Dodged
            if random.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:
                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 = random.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(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:
                    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)

        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_event(self, event: EnemyKilled):
        """Bus handler: every enemy death arrives here, whatever dealt the blow."""
        self._on_enemy_killed(event.enemy)

    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(Sfx.DEATH)

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

        # Mini-bosses always drop an epic item
        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
        dungeon.reveal_floor_cell(sx, sy)  # Re-tile the revealed cell + neighbours in the instanced floor
        self._audio.play_sfx(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."""
        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(Sfx.PICKUP)
                # Track item collection for quests
                rarity_name = RARITY_NAMES.get(item.rarity, "Common").lower()
                self._quest_mgr.on_item_collected(rarity_name)
                # 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(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.

        The boss's own :class:`EnemyKilled` event already awarded its XP, gold,
        and loot through :meth:`_on_enemy_killed`, so only the run-ending
        bookkeeping happens 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
        self._clear_level_nodes()
        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
            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":
            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(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."""
        rng = random.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(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,
                        )
                    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.rect((ep.x - ts // 2, ep.y - ts // 2), (ts, ts), fill=(0.6, 0.1, 0.1, 0.8))
                renderer.text("EXIT", (ep.x - 14, ep.y - ts // 2 - 14), fill=(1.0, 0.4, 0.4), scale=1.2)
                if self._near(ep):
                    renderer.text("[E] Descend", (ep.x - 30, ep.y + ts // 2 + 4), fill=(1.0, 0.9, 0.3), scale=0.8)
            sp = dungeon.entrance_world_pos()
            if self._tile_visible(sp.x, sp.y):
                renderer.rect((sp.x - ts // 2, sp.y - ts // 2), (ts, ts), fill=(0.1, 0.4, 0.2, 0.5))
                renderer.text("STAIRS", (sp.x - 18, sp.y - ts // 2 - 14), fill=(0.4, 0.9, 0.5), scale=1.0)
                if self._near(sp):
                    renderer.text(
                        "[E] Return to town", (sp.x - 46, sp.y + ts // 2 + 4), fill=(1.0, 0.9, 0.3), scale=0.8
                    )

            # 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.rect((ox - 7, oy - 2), (14, 8), fill=(0.6, 0.45, 0.15, 0.9))
                        renderer.rect((ox - 8, oy - 5), (16, 4), fill=(0.75, 0.6, 0.2, 0.9))
                        renderer.rect((ox - 1, oy - 3), (2, 3), fill=(0.9, 0.8, 0.3, 1.0))
                        renderer.text("?", (ox - 3, oy - 16), fill=(1.0, 0.9, 0.3), scale=1.0)
                elif obj["type"] == "waypoint":
                    renderer.rect((ox - 3, oy - 2), (6, 12), fill=(0.5, 0.5, 0.55, 0.8))
                    renderer.polygon([(ox, oy - 10), (ox - 5, oy - 2), (ox + 5, oy - 2)], fill=(0.2, 0.5, 1.0, 0.8))
                    renderer.circle((ox, oy - 6), 3, fill=(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.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()