-
Notifications
You must be signed in to change notification settings - Fork 194
Gameplay Effects
Gameplay Effects
are reponsible for applying attribute modifications. The built-in Gameplay Effect
caters for numerous scenarios, such as damage-over-time effects, temporary buffs, permanent buffs, etc. These should generally be sufficient for nearly all use cases.
We'll create a simple Gameplay Effect
that applies a temporary debuff that reduces a character's current health by 1 for 5 seconds, and then reverts it. For this exercise, you should have an Attribute
representing health ready to go.
Begin by creating a new Gameplay Effect
asset by going to Asset | Create | Gameplay Ability System | Gameplay Effect Definition
, and give it a useful name.
Define the properties of the Gameplay Effect
:
The Duration Policy
determines how long the Gameplay Effect
is applied for. Available options are: Instant
, Infinite
, Has Duration
.
An Instant
Gameplay Effect
is applied and then removed the same frame. This is used to capture one-off instances of attribute changes, such as taking damage. Infinite
Gameplay Effects
remain on the character indefinitely, until removed through interaction with other Gameplay Effects
or Abilities
. These are useful for temporary buffs that don't expire, or expire due to some condition other than time, such as bonus armour due to equipping armour, where the bonus is lost once the armour is unequipped. Has Duration
Gameplay Effects
remain on the character until their timer expires, or due to interaction with other Gameplay Effects
or Abilities
. The duration of the timer is controlled through the Duration Modifier
and Duration Multiplier
properties. Examples of Has Duration
Gameplay Effects
could include a temporary strength buff that lasts for 5 seconds.
The Duration Modifier
and Duration Multiplier
is used if the Duration Policy
of the Gameplay Effect
is Has Duration
. It is ignored for Instant
and Infinite
Duration Policy
.
The Duration Modifier
calculates the base duration of the Gameplay Effect
, using an asset derived from ModifierMagnitudeScriptableObject
to do the calculation by calling its CalculateMagnitude
method. For this example, we'll use the Simple Float
Modifier Magnitude
(included in the package), which we can configure to always provide a value of 1, allowing us to use the Duration Multiplier
property to determine how long the effect should last.
Create the Simple Float
Modifier Magnitude
asset by going to Asset | Create | Gameplay Ability System | Gameplay Effect | Modifier Magnitude | Simple Float
, and set the Scaling Function
curve to a straight horizontal line: y = 1
:
!.
Assign this new asset to the Duration Modifier
of the Gameplay Effect
, and set the Duration Multiplier
to 5 so the effect lasts for 5 seconds.
The attribute modifications in Attribute Modifiers
take place when the Gameplay Effect
is applied. Each Attribute Modifier
needs to define:
- The
Attribute
to modify - The mathematic
Operation
that takes place -Add
,Multiple
, orOverride
- The
Modifier Magnitude
, same as that defined for theDuration
, but here it is used to calculate the magnitude of theAttribute
modification. - The
Multplier
, which multiplies the result from theModifier Magnitude
.
For this sample, select any suitable Attribute
already created, such as health, and select the Simple Float
Modifier Magnitude
created earlier, so we can use the Multiplier
property to control the magnitude. Set the Multiplier
to -1, and the Operation
to Add
. This will reduce the target Attribute
by 1 while the Gameplay Effect
is active.
For this example, we'll define an Asset Tag
only. Create a new Gameplay Tag
via the Assets | Create | Gameplay Ability System | Tag
menu, and call it Physical.Damage.Debuff
. We won't worry about setting up it's ancestors.
Assign this new tag to the Asset Tag
of our new Gameplay Effect
.
Usually, a Gameplay Effect
is activated using an Ability
, but for this example, you'll manually apply it using a method of your choice (e.g. a GUI button, or an input event).
Applying a Gameplay Effect
is a two-step process:
- Create a
Gameplay Effect Spec
, which is a unique instance of aGameplay Effect
. - Apply the
Gameplay Effect Spec
to a character
We assume the AbilitySystemCharacter
property is called abilitySystemCharacter
, and the Gameplay Effect
is gameplayEffect
.
// Variables required:
// abilitySystemCharacter - reference to the Ability System Character component that is performing the action
// gameplayEffect - reference to the created Gameplay Effect Scriptable Object asset
GameplayEffectSpec spec = abilitySystemCharacter.MakeOutgoingSpec(gameplayEffect);
abilitySystemCharacter.ApplyGameplayEffectSpecToSelf(spec);
When this code is executed, the Ability System Character
will have their health reduced by 1 for 5 seconds, and then it will revert back, and will also have the Physical.Damage.Debuff
Gameplay Tag
applied while the Gameplay Effect
is active. Since we have not added any other Gameplay Effect
conditions (using Gameplay Tags
), this Gameplay Effect
can be applied endlessly (with an instance of Physical.Damage.Debuff
for each active application). If we wished for only 1 instance of this Gameplay Effect
to be applied at any given time, we could add the Physical.Damage.Debuff
Gameplay Tag
to the Application Required Tags / Ignore Tags
list.