- 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
9.2 KiB
9.2 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
HealAllyHealAoeSilence(enum exists; not routed in switch)BuffSelfBuffAlliesDebuffEnrageShieldChargeRetreatPhaseChange
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:
- Some tested types are still not implemented in runtime effect switch (
HealAlly,HealAoe,Retreat, etc.). 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.
12) Effect Visual TODO
- Add per-ability effect animation binding for non-mob effects (projectile impact, ground AoE, buffs/debuffs).
- Add an effect animation builder/editor (parallel to mob animation assignment flow).
- For
ProjectileAoe: if no explicit impact animation is configured, render a fallback expanded effect to the AoE radius for hit readability. - For
GroundAoe: support explicit placement animation key at the cast location and optional looping zone effect key.
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