[Wrath] Abilities

Last Updated For Game Version: 1.1.1

An ability represents actions a character can take. This includes spells, combat maneuvers, and class abilities. This does not include basic character behavior like movement or basic weapon attacks. Every ability is either an Ability or ActivatableAbility.

Ability

• Blueprint: Kingmaker.UnitLogic.Abilities.Blueprints.BlueprintAbility
• Code: Kingmaker.UnitLogic.Abilities.Ability

Most character actions are implemented as an Ability. These are usually triggered by selecting them on a unit's action bar.

Although the Ability class is the implementation, it mostly serves a proxy between the action bar and Kingmaker.UnitLogic.Abilities.AbilityData. When an ability is used in game AbilityData#Cast(AbilityExecutionContext) is called to execute the ability.

Ability Effects

• Code: Kingmaker.UnitLogic.Abilities.Components

Ability effects are a class of BlueprintComponent that attach mechanical effects to an ability. As a simple example, here are the components used for Two-Handed Fighter Devastation Blow:

Component	Field	Value
AbilityCustomMeleeAttack	m_Type	DevastatingBlow

When the ability is activated, the AbilityCustomMeleeAttack is triggered.

Types (#Types)

Important: There are 3 major types of ability effects and only the first of each will trigger when an ability is activated. The Miss Effect, AbilityEffectMiss is an exception to this rule, discussed below.

1. Deliver Effects: Kingmaker.UnitLogic.Abilities.Components.Base.AbilityDeliverEffect
   • These determine which targets are affected by the Apply Effect or Miss Effect.
   • These may also trigger effects of their own, e.g. AbilityDeliverAttackWithWeapon
   • To identify how it interacts with Apply Effect and Miss Effect, you'll need to look at its implementation of Deliver():
     • If it sets AttackRoll on the returned `AbilityDeliveryTarget, the Apply Effect only applies on a hit and the Miss Effect only applies on a miss.
     • Otherwise the Apply Effect is always applied and the Miss Effect is never applied. However, some of these components, e.g. AbilityDeliverChain, will not return targets that were missed. This means the Apply Effect is only applied to hit targets and Miss Effect is never applied.
   • Breakdown of some basic Deliver Effects:

Name	Effect	Apply Effect	Miss Effect
AbilityDeliverAttackWithWeapon	Attacks with main weapon	All targets	No effect
AbilityDeliverChain	Launches a chain projectile	Targets hit by the projectile	No effect
AbilityDeliverDelay	Waits before applying the effect	All targets	Does not apply
AbilityDeliveredByWeapon	Uses the last weapon attack roll made	Hit targets	Missed targets
AbilityDeliverProjectile	Launches a projectile	Hit targets	Missed targets
AbilityDeliverTouch	Makes a touch attack	Hit targets	Missed targets

2. Apply Effect: Kingmaker.UnitLogic.Abilities.Components.Base.AbilityApplyEffect
   • Used to apply an effect to the targets.
   • AbilityEffectRunAction is a notable Apply Effect which can be used for triggering multiple effects.
3. Select Target: Kingmaker.UnitLogic.Abilities.Components.Base.AbilitySelectTarget
   • Enables area of effect targeting, e.g. AbilityAffectLineOnGrid

The major difference between using ability effects and actions is the way the context behaves. Ability effects will modify the AbilityExecutionContext which is referenced by other ability effects in the same ability. For example, an ability which triggers a melee weapon attack that deals damage on a miss the blueprint components might look like this:

Component	Field	Value
AbilityExecuteActionOnCast	Actions.Actions	ContextActionMeleeAttack
AbilityDeliveredByWeapon
AbilityEffectRunAction	Actions.Actions
AbilityEffectMiss	UseTargetSelector	true
	MissAction.Actions	ContextActionDealDamage

Breaking it down:

1. AbilityExecuteActionOnCast initiates a melee attack using ContextActionMeleeAttack
   • This is not an ability effect component
2. AbilityDeliveredByWeapon is the first Deliver Effect
   • A special Deliver Effect which takes the result of the last weapon attack and stores it in AbilityExecutionContext
   • This propagates the results of the attack in step 1
3. AbilityEffectRunAction is the Apply Effect
   • Applies to targets hit by the last weapon attack. Any actions that apply only on a hit go here.
   • In this example it is used as a dummy Apply Effect so that Miss Effect works
4. AbilityEffectMiss is a special type of Apply Effect
   • Applies to missed targets

Miss Effect / AbilityEffectMiss

This should not be used as a normal Apply Effect. Here is a breakdown of the steps executed in AbilityExecutionProcess#ProcessRoutine() when an ability is used:

1. The first Deliver Effect, Select Target, and Apply Effect are collected
2. ApplyEffect() is called for each target returned by the Deliver Effect
3. For each target, determine whether to use the Apply Effect or Miss Effect
   • The internal call to ApplyEffect() (not shown) applies the Apply Effect using Select Target, if present

The reason Miss Effect needs special handling is because AbilityEffectMiss inherits from AbilityApplyEffect. This means in Step 1, if your Miss Effect is the first Apply Effect component it is used as the Apply Effect and is applied on hit and miss.

To use a Miss Effect:

1. Use an appropriate Deliver Effect; it must populate AbilityDeliveryTarget#AttackRoll. See Deliver Effect under Types.
2. Include AbilityEffectMiss in the components array after another Apply Effect

Other Types

• AbilityExecuteActionOnCast is not typed as an ability effect and can be used to trigger any arbitrary actions when the ability is used.
• AbilityEffectRunActionOnClickedTarget is the same as AbilityExecuteActionOnCast but does not support conditions.

Additional Code Links

• Kingmaker.Controllers.AbilityExecutionProcess and Kingmaker.Controllers.AbilityExecutionController
  • Manage the process of casting an ability and applying its effects
  • See AbilityExecutionProcess#ProcessRoutine() for details on how ability effects are triggered

Activatable Ability

• Blueprint: Kingmaker.UnitLogic.Abilities.Blueprints.BlueprintActivatableAbility
• Code: Kingmaker.UnitLogic.ActivatableAbilities.ActivatableAbility

Activatable abilities can be toggled on or off. Examples include Aasimar's Light Halo, Hunter's Animal Focus, and Barbian's Rage.

Most activatable abilities implement their functionality by applying a buff when activated and removing it when deactivated.