Files
systemrevivalserver/AbilitySystemWalkthrough.md
T
dingo 8f90f23fd0 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
2026-02-10 15:21:35 -05:00

8.7 KiB

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.

  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