Concepts¶
Tags¶
Tags are registered once in a GameplayTagRegistry. Registering State.Debuff.Stun also registers State and State.Debuff.
A query on a parent matches its children: an actor with State.Debuff.Stun has State.Debuff.
GameplayTagSet: immutable set, used in definitions.GameplayTagCountContainer: live, reference-counted tags of an actor.GameplayTagQuery: require all / require any / exclude.
Every query is a bitset operation and allocates nothing.
Attributes¶
Current value:
((Base + ΣAdd) × (1 + Σ(MultiplyAdditive − 1)) × ΠMultiplyCompound) ÷ ΠDivide
unless an Override is active (the most recent one wins).
Use MultiplyAdditive for percentage bonuses (two +30% give +60%) and MultiplyCompound when bonuses should compound (×1.69).
Values clamp to MinValue / MaxValue and to an optional max attribute (Health ≤ MaxHealth).
Lowering the max attribute lowers the base value too; raising it does not heal.
A meta attribute (IsMeta = true, e.g. Damage) carries a value from an effect to
IAttributeEventHandler.PostEffectExecute, where game rules turn it into a real change
(armor, shields, death), then resets to 0.
Gameplay effects¶
| Setting | Behaviour |
|---|---|
DurationPolicy.Instant |
Changes base values once. |
DurationPolicy.HasDuration / Infinite |
Modifies current values while active. |
Period > 0 |
Changes base values on each period instead (damage or healing over time). A period that falls exactly on the end time still executes. |
Stacking |
AggregateBySource or AggregateByTarget, with StackLimit, duration refresh, period reset and expiration policies. |
GrantedTags |
Given to the target while the effect is active. |
ApplicationRequirement |
Target tags needed to apply. |
OngoingRequirement |
Target tags needed to work. While unmet, the effect is inhibited: no modifier, no granted tag, no periodic execution, but the duration keeps running. |
GrantedApplicationImmunity |
Blocks incoming effects whose AssetTags match. |
RemoveEffectsWithTags |
Removes matching active effects on application. |
Stacks scale magnitudes: Add × stacks, MultiplyAdditive bonus × stacks, MultiplyCompound and Divide to the power of stacks. Override is not scaled.
Magnitudes: ConstantMagnitude, ScalableMagnitude (value × curve at the spec level), AttributeBasedMagnitude (reads an attribute of the source or target; live by default, or Snapshot), SetByCallerMagnitude (a value set on the spec at runtime), or your own IMagnitude.
Executions (IEffectExecution) run custom formulas that read several attributes, such as damage reduced by armor.
Abilities¶
Subclass GameplayAbility, implement ActivateAbility, grant it with GiveAbility:
public sealed class Fireball : GameplayAbility
{
private readonly GameplayEffectDefinition _damage;
private readonly GameplayTag _release;
public Fireball(GameplayEffectDefinition damage, GameplayTag release) : base("Fireball")
{
_damage = damage;
_release = release;
}
protected override async AbilityTask ActivateAbility(AbilityContext context)
{
if (!context.CommitAbility()) { context.CancelAbility(); return; } // pays Cost, starts Cooldown
var cast = await context.WaitGameplayEvent(_release); // e.g. an animation event
if (cast.Target != null)
context.ApplyEffectToTarget(context.MakeOutgoingSpec(_damage), cast.Target);
}
}
var handle = hero.GiveAbility(new Fireball(damage, releaseTag) { Cost = manaCost, Cooldown = fireballCooldown }, inputId: 0);
hero.AbilityInputPressed(0); // or hero.TryActivateAbility(handle)
hero.HandleGameplayEvent(releaseTag, new GameplayEventData { Target = enemy });
| Setting | Behaviour |
|---|---|
Cost |
Instant effect applied by CommitAbility. Activation fails if an Add modifier would take the attribute below 0 (override CheckCost for other rules). |
Cooldown |
Timed effect applied by CommitAbility. Its granted tags block activation while present. |
ActivationRequiredTags / ActivationBlockedTags |
Owner tags needed / forbidden to activate. |
ActivationOwnedTags |
Given to the owner while active. |
BlockAbilitiesWithTags / CancelAbilitiesWithTags |
Blocks, or cancels on activation, abilities whose AbilityTags match. |
InstancingPolicy |
NonInstanced (shared object: keep state in the context), InstancedPerActor (default: fields are per actor), InstancedPerExecution (concurrent activations). |
ReactivationPolicy |
Activating while active: Fail, Restart or Toggle (sprint, aura). |
Triggers |
Start on a gameplay event, when the owner gains a tag, or while it has a tag. |
ActivateWhenGranted |
Passive abilities. |
EndWhenActivationReturns |
Default true. Set false for abilities that stay active, and call EndAbility yourself. |
Waits available on AbilityContext: WaitDelay, WaitGameplayEvent, WaitTagAdded, WaitTagRemoved, WaitAttributeChange, WaitInputPressed, WaitInputReleased (returns seconds held), WaitTargetData.
They run on the world thread, without Task or coroutines. When an ability ends or is cancelled, its pending waits never resume:
put cleanup in OnEndAbility, not in finally. ApplyEffectToSelfUntilEnd and AddGameplayCue clean up by themselves.
Gameplay cues¶
Effects list cue tags in GameplayCues; abilities call ExecuteGameplayCue or AddGameplayCue.
AbilitySystem.GameplayCueTriggered reports each cue with its moment (Executed, OnActive, WhileActive, Removed) and parameters.
Play VFX and sounds there; game logic never depends on cues.
World, time and threads¶
ArcanaWorld.Tick advances time and fires timers from a single priority queue. An effect costs nothing on frames where its duration or period does not end.
The world is single-threaded: calls from another thread throw. Use ArcanaWorld.Enqueue to defer work from another thread to the next tick.
Effects that trigger each other (A removes a tag that applies B, which applies A...) are stopped at MaxRecursionDepth (16 by default), and the chain is logged.
Route logs with ArcanaLog.Sink.