# Ability System Walkthrough (Dungeon Runtime) ## Purpose This document steps through the full mob ability pipeline in dungeon runtime, including: 1. Data model and cache load. 2. Simulation initialization. 3. AI/ability decision flow each tick. 4. Ability execution and event emission. 5. Current implementation gaps and likely causes of "animation plays but no effect". --- ## 1) Data Model Layer ### Enums - `data/enums/MobAbilityType.cs` - Defines ability type IDs (0..30). - `data/enums/MobAbilityTargeting.cs` - Defines targeting IDs (0..12). ### Entities - `data/entities/MobAbilityDefinition.cs` - Table: `dungeon_mob_abilities` - Holds type, targeting, damage/timing/range/status/summon/buff fields. - `data/entities/MobAbilityAssignment.cs` - Binds an ability definition to a mob definition. - Supports per-assignment phase and HP condition overrides. - `data/entities/DungeonMobDefinition.cs` - Has `AbilityAssignments`. - `data/entities/MobSpriteSheet.cs` (`MobAbilityAnimationMapping`) - Optional animation override per ability assignment. ### DbContext - `data/GameDbContext.cs` - `MobAbilityDefinitions` - `MobAbilityAssignments` - `MobAbilityAnimationMappings` --- ## 2) Cache Load (DungeonHandler) ### Class - `Game/Dungeon/DungeonHandler.MobCache.cs` (`DungeonHandler`) ### Method - `RefreshMobCacheAsync()` ### What it does 1. Loads enabled mobs + assignments + assignment ability definitions. 2. Loads enabled `MobAbilityDefinition` rows into `_abilityDefinitions`. 3. Loads `MobAbilityAnimationMapping` into `_abilityAnimationMappings`. 4. Builds sprite configs for mob visuals. This is the authoritative server cache used when creating or reinitializing simulation mobs. --- ## 3) Simulation Initialization (DungeonSimulation) ### Class - `Game/Dungeon/DungeonSimulation.cs` (`DungeonSimulation`) ### Methods - `InitializeMobs()` - `InitializeMobAbilities(MobInstance mob, DungeonMobDefinition mobDef, DungeonMobCombatStats stats)` - `LoadMobAbilities(MobInstance mob, DungeonMobDefinition mobDef)` - `ResolveMappedAnimationKey(int abilityAssignmentId, MobAbilityDefinition abilityDef)` ### Flow 1. Mobs are instantiated with stats and base runtime state. 2. `InitializeMobAbilities` calls `LoadMobAbilities`. 3. `LoadMobAbilities` creates runtime `MobAbilityState` entries from assignments. 4. Runtime animation key comes from mapping override if present, else ability definition key. 5. If no melee attack exists, a fallback `Basic Attack` (`MeleeAttack`) is injected. Note: - Fallback melee was added to prevent "all abilities unusable => mob never damages". --- ## 4) Tick Loop and Combat Entry (DungeonSimulation + MobAI) ### Tick entry - `DungeonSimulation.Tick(long tick)` ### Main calls 1. `MobAI.UpdateMob(mob, sim, TickDelta)` for each alive mob. 2. If mob state becomes `Attacking` and interval elapsed: - `ProcessMobAbility(mob, target)`. ### Key AI class - `Game/Dungeon/MobAI.cs` ### Key AI method - `UpdateMob(MobInstance mob, DungeonSimulation sim, float deltaTime)` ### Important detail `MobAI` has an internal casting path: - `ExecuteAbility(mob, mob.CastingAbility, sim)` but this path currently only implements summon types in `MobAI` itself. Primary combat ability execution for most types currently happens in: - `DungeonSimulation.ProcessMobAbility(...)` This split is a major complexity point. --- ## 5) Ability Selection and Execution (DungeonSimulation) ### Selection method - `ProcessMobAbility(MobInstance mob, PlayerInstance target)` ### Current selection filters 1. `IsAvailable` (cooldown + HP thresholds). 2. Phase match (`a.Phase == 0 || a.Phase == mob.CurrentPhase`). 3. Implemented type (`IsImplementedAbilityType`). 4. Runtime usability (`CanUseAbilityNow`) for mana/range. 5. Highest priority wins. ### Execution routing in `ProcessMobAbility` - `SummonSingle`, `SummonBulk` -> `ProcessSummonAbility` - `MeleeAttack`, `Cleave` -> `ProcessMeleeAbility` - `ProjectileSingle`, `ProjectileAoe` -> `SpawnProjectile` - `GroundAoe`, `ConeAttack` -> `ProcessAoeAbility` - `Poison`, `Bleed`, `Burn` -> `ApplyDotToPlayer` - `Stun`, `Slow`, `Root`, `Fear` -> `ApplyStatusToPlayer` - `Knockback` -> `ApplyKnockback` - `Pull` -> `ApplyPull` - `HazardZone` -> `SpawnHazardZone` ### Supporting methods - `CanUseAbilityNow(...)` - `IsImplementedAbilityType(...)` - `ResolveAbilityAnimationKey(...)` ### Event emission Before effect application, an `AbilityEvent` is queued: - `_pendingAbilityEvents.Add(...)` This drives client-side animation playback. --- ## 6) Effect Application Methods (DungeonSimulation) ### Direct damage - `ProcessMeleeAbility(...)` ### Projectiles - `SpawnProjectile(...)` - `UpdateProjectiles()` - `ProcessAoeAbilityAtLocation(...)` ### AOE - `ProcessAoeAbility(...)` ### DOT - `ApplyDotToPlayer(...)` ### Status effects - `ApplyStatusToPlayer(...)` ### Displacement - `ApplyKnockback(...)` - `ApplyPull(...)` ### Hazard zones - `SpawnHazardZone(...)` - `UpdateHazardZones()` ### Final damage application - `ApplyDamageToPlayer(...)` --- ## 7) Outbound State and Events (DungeonHandler) ### Class - `Game/Dungeon/DungeonHandler.cs` ### Methods - `TickAll(...)` - `SendDungeonStateAsync(...)` ### Ability event payload path 1. `TickAll` gets `TickResult` from simulation. 2. `SendDungeonStateAsync` filters events by spatial visibility. 3. `events.abilities` includes: - `sourceType`, `sourceId` - `abilityKey` - `animationKey` - `targetX`, `targetY`, `targetId` If animation is visible but no damage/effect occurs, failure is usually in selection or execution routing, not in transport. --- ## 8) What Is Implemented vs Missing ### Implemented in `DungeonSimulation.ProcessMobAbility` - `MeleeAttack` - `ProjectileSingle` - `ProjectileAoe` - `GroundAoe` - `ConeAttack` - `Cleave` - `SummonSingle` - `SummonBulk` - `Stun` - `Knockback` - `Fear` - `Pull` - `Root` - `Slow` - `Poison` - `Bleed` - `Burn` - `HazardZone` ### Not implemented in `DungeonSimulation.ProcessMobAbility` - `HealAlly` - `HealAoe` - `Silence` (enum exists; not routed in switch) - `BuffSelf` - `BuffAllies` - `Debuff` - `Enrage` - `Shield` - `Charge` - `Retreat` - `PhaseChange` ### Targeting support status - `MobAbilityTargeting` values are mostly not driving per-type targeting logic yet. - Current behavior is largely "target current combat target" in `ProcessMobAbility` path. --- ## 9) Why Your Recent Tests Can Fail Given tests like: - `TST Type 06 HealSelf` - `TST Target 07 RandomEnemy` - `TST Type 27 Teleport` Likely reasons: 1. Some tested types are still not implemented in runtime effect switch (`HealAlly`, `HealAoe`, `Retreat`, etc.). 2. `Targeting` enum values (like `RandomEnemy`) are not yet fully honored by ability resolution. 3. Previously, mana/range could select unusable abilities; this was partially guarded, but non-implemented types still naturally do nothing. 4. AI has a second ability executor (`MobAI.ExecuteAbility`) with limited coverage (summon-focused), creating behavior split risk. --- ## 12) Effect Visual TODO 1. Add per-ability effect animation binding for non-mob effects (projectile impact, ground AoE, buffs/debuffs). 2. Add an effect animation builder/editor (parallel to mob animation assignment flow). 3. For `ProjectileAoe`: if no explicit impact animation is configured, render a fallback expanded effect to the AoE radius for hit readability. 4. For `GroundAoe`: support explicit placement animation key at the cast location and optional looping zone effect key. --- ## 10) Refactor Targets (Recommended Order) 1. Unify execution entry - Keep a single authoritative executor (prefer `DungeonSimulation`). - Remove or delegate `MobAI.ExecuteAbility` to simulation. 2. Implement type coverage fully - Add switch handlers for all enum values or explicitly disable unsupported ones in data. 3. Implement targeting resolver - Central method that resolves target(s)/ground point from `MobAbilityTargeting`. 4. Separate "can cast" from "apply effect" - Pre-check phase, cooldown, mana, range, target validity. - Then execute. 5. Build test matrix - One test ability per type. - One test ability per targeting mode. - Run on controlled mob configs with known mana/stats. --- ## 11) Key Classes and Methods Index ### Data - `MobAbilityDefinition` - `MobAbilityAssignment` - `DungeonMobDefinition` - `MobAbilityAnimationMapping` - `MobAbilityType` - `MobAbilityTargeting` ### Runtime - `DungeonSimulation.Tick` - `DungeonSimulation.InitializeMobAbilities` - `DungeonSimulation.LoadMobAbilities` - `DungeonSimulation.ProcessMobAbility` - `DungeonSimulation.CanUseAbilityNow` - `DungeonSimulation.IsImplementedAbilityType` - `DungeonSimulation.ProcessSummonAbility` - `DungeonSimulation.ProcessMeleeAbility` - `DungeonSimulation.SpawnProjectile` - `DungeonSimulation.ProcessAoeAbility` - `DungeonSimulation.ApplyDotToPlayer` - `DungeonSimulation.ApplyStatusToPlayer` - `DungeonSimulation.ApplyKnockback` - `DungeonSimulation.ApplyPull` - `DungeonSimulation.SpawnHazardZone` - `DungeonSimulation.ApplyDamageToPlayer` ### AI - `MobAI.UpdateMob` - `MobAI.UpdateAggressive` - `MobAI.UpdateRanged` - `MobAI.UpdateSummoner` - `MobAI.ExecuteAbility` (secondary path, limited coverage) ### Handler / Networking - `DungeonHandler.RefreshMobCacheAsync` - `DungeonHandler.TickAll` - `DungeonHandler.SendDungeonStateAsync`