Files
systemrevivalserver/AbilitySystemReview.md
2026-02-08 18:57:04 -05:00

83 lines
3.6 KiB
Markdown

# 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.