From 8f90f23fd047e7b86d65f119d7ae2d773b7037b9 Mon Sep 17 00:00:00 2001 From: dingo Date: Tue, 10 Feb 2026 15:21:35 -0500 Subject: [PATCH] Add end-to-end dungeon ability system walkthrough document - Document data model, cache load, simulation init, AI/tick flow, and event emission - Enumerate implemented vs missing ability types and targeting support gaps - Include class/method index for refactor planning --- AbilitySystemWalkthrough.md | 319 ++++++++++++++++++++++++++++++++++++ 1 file changed, 319 insertions(+) create mode 100644 AbilitySystemWalkthrough.md diff --git a/AbilitySystemWalkthrough.md b/AbilitySystemWalkthrough.md new file mode 100644 index 0000000..c748c9c --- /dev/null +++ b/AbilitySystemWalkthrough.md @@ -0,0 +1,319 @@ +# 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` +- `HealSelf` +- `HealAlly` +- `HealAoe` +- `Silence` (enum exists; not routed in switch) +- `BuffSelf` +- `BuffAllies` +- `Debuff` +- `Enrage` +- `Shield` +- `Charge` +- `Teleport` +- `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. Types like `HealSelf` and `Teleport` are not implemented in runtime effect switch. +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. + +--- + +## 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` +