# Ability System Review (Dungeon) ## Scope - Files reviewed: `Game/Dungeon/MobAI.cs`, `Game/Dungeon/DungeonSimulation.cs`, `Game/Dungeon/DungeonHandler.cs`, `Game/Dungeon/DungeonHandlerAdmin.cs`. - Goal: document what works, what is missing, and the plan for per-ability animation binding when assigning abilities to mobs. ## How It Currently Works 1. Mob definitions and ability assignments are loaded into cache in `DungeonHandler` (`RefreshMobCacheAsync`). 2. When a dungeon simulation is created, each spawned mob gets runtime `MobAbilityState` entries from `MobAbilityAssignment`. 3. During ticks, mobs in `MobState.Attacking` call `ProcessMobAbility`. 4. `ProcessMobAbility` selects highest-priority available ability and routes to the implementation by `MobAbilityType`. 5. Ability visuals are emitted as `AbilityEvent` and now sent to clients in dungeon state packets (`events.abilities`). ## Ability Type Coverage ### Implemented in `DungeonSimulation.ProcessMobAbility` - `MeleeAttack` - `Cleave` - `ProjectileSingle` - `ProjectileAoe` - `GroundAoe` - `ConeAttack` - `SummonSingle` - `SummonBulk` - `Poison` - `Bleed` - `Burn` - `Stun` - `Slow` - `Root` - `Fear` - `Knockback` - `Pull` - `HazardZone` ### Declared in enum but not executed in `ProcessMobAbility` - `HealSelf` - `HealAlly` - `HealAoe` - `Silence` (status builder exists, but switch does not route this type) - `BuffSelf` - `BuffAllies` - `Debuff` - `Enrage` - `Shield` - `Charge` - `Teleport` - `Retreat` - `PhaseChange` ## Known Gaps / Risks - Healer AI can enter `MobState.Healing`, but ability execution currently only runs when state is `MobState.Attacking`. - `Targeting` metadata on ability definitions is currently not used in runtime targeting logic. - Player ability-cast pipeline is not present in dungeon simulation right now (player flow is basic attack), so player-ability mana enforcement is pending until player ability execution exists. ## Bonelord / Summon Issue Notes - Root cause for disappearing admin-spawned boss after cast: runtime mob ID collision risk between admin-spawned IDs and summoned IDs. - Fix approach implemented: centralized runtime ID allocation for both admin spawns and summons. ## Plan: Ability Animation Binding on Mob Ability Assignment 1. Add optional mapping from `MobAbilityAssignment` to animation key. 2. Resolve animation key for each runtime ability at load: - mapping override if present - else ability definition animation - else `attack` 3. Support directional placeholders (`[dir]` / `{dir}`) at cast time. 4. Emit resolved animation key in ability events. 5. Admin UX: when assigning ability, optionally choose animation key from assigned mob animations. 6. Show assigned/resolved animation in mob ability table for transparency. ## Implementation Checklist - [x] Load `mob_ability_animation_mappings` into dungeon mob cache. - [x] Pass ability-animation mappings into all `DungeonSimulation` constructors. - [x] Resolve mapped animation key into runtime `MobAbilityState`. - [x] Support `[dir]` / `{dir}` replacement when emitting ability animation key. - [x] Include ability events in outbound dungeon state payload (`events.abilities`). - [x] Enforce mob ability mana costs before casting. - [x] Add admin UI support to select optional animation key when assigning a mob ability. - [x] Display ability animation (and override marker) in mob ability list. - [x] Remove ability-animation mappings when removing an ability assignment. - [x] Fix runtime mob ID allocation so admin spawns and summons cannot collide. - [ ] Enforce mana for **player-cast abilities** once player ability casting exists in dungeon runtime.