- 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
320 lines
8.7 KiB
Markdown
320 lines
8.7 KiB
Markdown
# 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`
|
|
|