Files
systemrevivalserver/AbilitySystemWalkthrough.md
dingo 7e8d195aec Implement Teleport ability and update ability/effects TODO docs
- Add Teleport handling in DungeonSimulation ability switch and implemented-type list

- Teleport mob toward target using displacement distance with walkable-position fallback search

- Add Teleport success/failure diagnostics

- Update AbilitySystemWalkthrough status and add effect animation builder TODOs
2026-02-11 09:15:39 -05:00

326 lines
9.2 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`
- `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`