- 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
8.7 KiB
8.7 KiB
Ability System Walkthrough (Dungeon Runtime)
Purpose
This document steps through the full mob ability pipeline in dungeon runtime, including:
- Data model and cache load.
- Simulation initialization.
- AI/ability decision flow each tick.
- Ability execution and event emission.
- 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.
- Table:
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.
- Has
data/entities/MobSpriteSheet.cs(MobAbilityAnimationMapping)- Optional animation override per ability assignment.
DbContext
data/GameDbContext.csMobAbilityDefinitionsMobAbilityAssignmentsMobAbilityAnimationMappings
2) Cache Load (DungeonHandler)
Class
Game/Dungeon/DungeonHandler.MobCache.cs(DungeonHandler)
Method
RefreshMobCacheAsync()
What it does
- Loads enabled mobs + assignments + assignment ability definitions.
- Loads enabled
MobAbilityDefinitionrows into_abilityDefinitions. - Loads
MobAbilityAnimationMappinginto_abilityAnimationMappings. - 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
- Mobs are instantiated with stats and base runtime state.
InitializeMobAbilitiescallsLoadMobAbilities.LoadMobAbilitiescreates runtimeMobAbilityStateentries from assignments.- Runtime animation key comes from mapping override if present, else ability definition key.
- 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
MobAI.UpdateMob(mob, sim, TickDelta)for each alive mob.- If mob state becomes
Attackingand 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 inMobAIitself.
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
IsAvailable(cooldown + HP thresholds).- Phase match (
a.Phase == 0 || a.Phase == mob.CurrentPhase). - Implemented type (
IsImplementedAbilityType). - Runtime usability (
CanUseAbilityNow) for mana/range. - Highest priority wins.
Execution routing in ProcessMobAbility
SummonSingle,SummonBulk->ProcessSummonAbilityMeleeAttack,Cleave->ProcessMeleeAbilityProjectileSingle,ProjectileAoe->SpawnProjectileGroundAoe,ConeAttack->ProcessAoeAbilityPoison,Bleed,Burn->ApplyDotToPlayerStun,Slow,Root,Fear->ApplyStatusToPlayerKnockback->ApplyKnockbackPull->ApplyPullHazardZone->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
TickAllgetsTickResultfrom simulation.SendDungeonStateAsyncfilters events by spatial visibility.events.abilitiesincludes:sourceType,sourceIdabilityKeyanimationKeytargetX,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
MeleeAttackProjectileSingleProjectileAoeGroundAoeConeAttackCleaveSummonSingleSummonBulkStunKnockbackFearPullRootSlowPoisonBleedBurnHazardZone
Not implemented in DungeonSimulation.ProcessMobAbility
HealSelfHealAllyHealAoeSilence(enum exists; not routed in switch)BuffSelfBuffAlliesDebuffEnrageShieldChargeTeleportRetreatPhaseChange
Targeting support status
MobAbilityTargetingvalues are mostly not driving per-type targeting logic yet.- Current behavior is largely "target current combat target" in
ProcessMobAbilitypath.
9) Why Your Recent Tests Can Fail
Given tests like:
TST Type 06 HealSelfTST Target 07 RandomEnemyTST Type 27 Teleport
Likely reasons:
- Types like
HealSelfandTeleportare not implemented in runtime effect switch. Targetingenum values (likeRandomEnemy) are not yet fully honored by ability resolution.- Previously, mana/range could select unusable abilities; this was partially guarded, but non-implemented types still naturally do nothing.
- AI has a second ability executor (
MobAI.ExecuteAbility) with limited coverage (summon-focused), creating behavior split risk.
10) Refactor Targets (Recommended Order)
-
Unify execution entry
- Keep a single authoritative executor (prefer
DungeonSimulation). - Remove or delegate
MobAI.ExecuteAbilityto simulation.
- Keep a single authoritative executor (prefer
-
Implement type coverage fully
- Add switch handlers for all enum values or explicitly disable unsupported ones in data.
-
Implement targeting resolver
- Central method that resolves target(s)/ground point from
MobAbilityTargeting.
- Central method that resolves target(s)/ground point from
-
Separate "can cast" from "apply effect"
- Pre-check phase, cooldown, mana, range, target validity.
- Then execute.
-
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
MobAbilityDefinitionMobAbilityAssignmentDungeonMobDefinitionMobAbilityAnimationMappingMobAbilityTypeMobAbilityTargeting
Runtime
DungeonSimulation.TickDungeonSimulation.InitializeMobAbilitiesDungeonSimulation.LoadMobAbilitiesDungeonSimulation.ProcessMobAbilityDungeonSimulation.CanUseAbilityNowDungeonSimulation.IsImplementedAbilityTypeDungeonSimulation.ProcessSummonAbilityDungeonSimulation.ProcessMeleeAbilityDungeonSimulation.SpawnProjectileDungeonSimulation.ProcessAoeAbilityDungeonSimulation.ApplyDotToPlayerDungeonSimulation.ApplyStatusToPlayerDungeonSimulation.ApplyKnockbackDungeonSimulation.ApplyPullDungeonSimulation.SpawnHazardZoneDungeonSimulation.ApplyDamageToPlayer
AI
MobAI.UpdateMobMobAI.UpdateAggressiveMobAI.UpdateRangedMobAI.UpdateSummonerMobAI.ExecuteAbility(secondary path, limited coverage)
Handler / Networking
DungeonHandler.RefreshMobCacheAsyncDungeonHandler.TickAllDungeonHandler.SendDungeonStateAsync