Skip to content

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.