Skip to content

ZazuLabs.Arcana

AbilityActivationFailure

Why AbilitySystem.TryActivateAbility failed.

Member Description
AlreadyActive Already active and AbilityReactivationPolicy.Fail.
BlockedByAbility An active ability blocks this one through GameplayAbility.BlockAbilitiesWithTags.
BlockedByTags The owner has an GameplayAbility.ActivationBlockedTags tag.
CustomCheckFailed GameplayAbility.CanActivateAbility returned false.
InsufficientCost The owner cannot pay the cost.
MissingRequiredTags The owner lacks an GameplayAbility.ActivationRequiredTags tag.
None Activation succeeded.
NotGranted The handle is unknown to this system.
OnCooldown A cooldown tag is present.
RecursionLimit Recursion limit reached. Details are logged.

AbilityContext

One activation of an ability: commit, effects, waits and end. Invalid once the activation ends: every call is then ignored, and waits never complete.

Member Description
AddGameplayCue(GameplayTag, Object) Starts a lasting cue on the owner, stopped when the activation ends.
ApplyEffectToSelf(GameplayEffectSpec) Applies an effect to the owner.
ApplyEffectToSelfUntilEnd(GameplayEffectSpec) Applies an effect to the owner and removes it when the activation ends (channels, stances).
ApplyEffectToTarget(GameplayEffectSpec, AbilitySystem) Applies an effect to target.
ApplyEffectToTargets(GameplayEffectSpec, TargetData) Applies an effect to every target. Returns how many succeeded.
CancelAbility() Ends the activation as cancelled.
CancelTargeting() Completes a pending AbilityContext.WaitTargetData with null.
CheckCooldown() True if no cooldown tag of the ability is on the owner.
CheckCost() True if the owner can pay the cost.
CommitAbility() Checks then applies cost and cooldown. False, and nothing applied, if either fails.
CommitCooldown() Checks then applies the cooldown only.
CommitCost() Checks then applies the cost only.
ConfirmTargetData(TargetData) Completes a pending AbilityContext.WaitTargetData with data.
EndAbility() Ends the activation normally.
ExecuteGameplayCue(GameplayTag, Single, Object) Sends a one-shot cue on the owner.
GetCooldownRemaining() Seconds left on the cooldown, 0 if none.
MakeOutgoingSpec(GameplayEffectDefinition) Creates a spec from the owner at the ability level.
MarkEnded(Boolean) Marks the activation ended and drops its waits. Returns false if it already ended.
ReleaseOwnedResources() Removes effects and cues tied to the activation.
RemoveGameplayCue(GameplayTag) Stops a cue started by AbilityContext.AddGameplayCue.
WaitAttributeChange(GameplayAttribute) Completes on the next change of the owner's current value of attribute. Returns the new value.
WaitDelay(Single) Completes after seconds of world time.
WaitGameplayEvent(GameplayTag, Boolean) Completes on the next gameplay event sent to the owner whose tag matches eventTag (children included unless exactMatch).
WaitInputPressed() Completes on the next press of the bound input.
WaitInputReleased() Completes when the bound input is released; at once if it is not held. Returns seconds held.
WaitTagAdded(GameplayTag) Completes when the owner gains tag (or one of its children); at once if it has it.
WaitTagRemoved(GameplayTag) Completes when the owner loses tag; at once if it does not have it.
WaitTargetData() Completes when targeting is confirmed with AbilityContext.ConfirmTargetData (returns the data) or cancelled with AbilityContext.CancelTargeting (returns null). A targeting actor calls those.
WaitUntil(Boolean>, Single) Completes when condition returns true, checked now and after every world tick. Returns true then, or false once timeout seconds have passed (negative: no timeout). For engine state the core cannot observe: an animation ending, a projectile landing, a combo input.
Ability Object running this activation (the template or a copy, see AbilityInstancingPolicy).
IsActive True until the activation ends.
IsWaitingForTargets True while a AbilityContext.WaitTargetData is pending.
Level Ability level.
Spec Granted ability.
System System running the ability.
TriggerEventData Event that triggered the activation, if any.
WasCancelled True if the activation ended by cancellation.
World World of the system.

AbilityInstancingPolicy

Which object runs an activation.

Member Description
InstancedPerActor One copy per actor, created when granted and reused. Fields may hold state.
InstancedPerExecution A new copy per activation. Several activations can run at once.
NonInstanced The granted ability object itself, shared by every actor. Keep per-activation state in the AbilityContext, never in fields.

AbilityReactivationPolicy

What activating an ability that is already active does.

Member Description
Fail Activation fails with AbilityActivationFailure.AlreadyActive.
Restart The running activation is cancelled and a new one starts.
Toggle The running activation ends (an on/off ability such as a sprint or an aura).

AbilityState

A granted ability.

Member Description
Ability Key given by the capture (the ability's name by default).
InputId Bound input id, or -1.
Level Level of the grant.

AbilitySystem

Attributes, tags and active effects of one actor. Created by ArcanaWorld.CreateAbilitySystem.

Member Description
event AbilityActivated Raised after an ability starts.
event AbilityActivationFailed Raised when an activation attempt fails, with the reason.
event AbilityEnded Raised after an ability ends: context, true if cancelled.
event AttributeChanged Raised when a current value changes: attribute, old value, new value.
event EffectApplied Raised after a new active effect is added.
event EffectExecuted Raised after an instant effect executed or a periodic effect ticked.
event EffectInhibitionChanged Raised when an effect becomes inhibited (true) or works again (false).
event EffectRemoved Raised when an active effect is removed, before it is recycled.
event EffectStackChanged Raised when a stack count changes: effect, old count, new count.
event GameplayCueTriggered Raised for every gameplay cue on this system: cue tag, moment, parameters.
event GameplayEventReceived Raised for every gameplay event sent to this system.
event TagPresenceChanged Raised when a tag becomes present (true) or absent (false), parents included.
event TargetingCancelRequested Raised by AbilitySystem.InputCancel, before pending targeting is cancelled.
event TargetingConfirmRequested Raised by AbilitySystem.InputConfirm. Targeting actors (ground circle, aim line) confirm the target data of the ability they serve.
AbilityInputPressed(Int32) Input inputId was pressed: activates bound abilities, or notifies them if active.
AbilityInputReleased(Int32) Input inputId was released: notifies active bound abilities.
AddAttribute(GameplayAttribute) Adds an attribute with its default base value.
AddAttribute(GameplayAttribute, Single) Adds an attribute with baseValue.
AddLooseTag(GameplayTag, Int32) Adds a tag not tied to any effect. Reference-counted.
ApplyGameplayEffectToSelf(GameplayEffectSpec) Applies spec to this system.
ApplyGameplayEffectToTarget(GameplayEffectSpec, AbilitySystem) Applies spec to target.
ApplyPooled(GameplayEffectDefinition, Single) Applies an instant or timed definition to this system through a pooled spec.
CanActivateAbility(GameplayAbilitySpecHandle) Checks whether a granted ability could activate now, without activating it.
CancelAbilitiesWithTags(GameplayTagSet) Cancels active abilities whose tags match any of abilityTags. Returns how many.
CancelAbility(GameplayAbilitySpecHandle) Cancels every activation of a granted ability. False if not found.
CancelAllAbilities() Cancels every running activation.
CaptureState(String>, String>) Captures the state to save it: attribute base values, loose tags, granted abilities and active effects. Effects and abilities are saved by key: effectKey and abilityKey (default: their names), which return null to skip one.
ClearAbility(GameplayAbilitySpecHandle) Removes a granted ability, cancelling its activations. False if not found.
ClearAllAbilities() Removes every granted ability.
ClearInputBuffer() Drops the buffered press, if any.
Dispose() Removes every active effect and detaches from the world.
GetBaseValue(GameplayAttribute) Base value, without temporary modifiers.
GetCooldownRemaining(GameplayAbility) Seconds left on the cooldown of ability, 0 if none.
GetCurrentValue(GameplayAttribute) Current value, with active modifiers.
GiveAbility(GameplayAbility, Single, Int32, Object) Grants ability. inputId binds it to AbilitySystem.AbilityInputPressed (-1: no input).
HandleGameplayEvent(GameplayTag, GameplayEventData) Sends a gameplay event to this system: completes matching waits, then activates abilities triggered by it. Returns how many abilities started.
HasAttribute(GameplayAttribute) True if the attribute was added.
InputCancel() Cancel input (right click, gamepad B): asks targeting actors to cancel, then cancels every pending AbilityContext.WaitTargetData, which completes with null.
InputConfirm() Confirm input (click, gamepad A): asks targeting actors to confirm their targets.
MakeOutgoingSpec(GameplayEffectDefinition, Single) Creates a spec with this system as source.
RemoveActiveEffect(ActiveEffectHandle, Int32) Removes stacks stacks, or the whole effect if 0 or less. False if not found.
RemoveActiveEffectsWithTags(GameplayTagSet) Removes active effects whose asset or granted tags match any of tags. Returns the count removed.
RemoveLooseTag(GameplayTag, Int32) Removes a loose tag added by AbilitySystem.AddLooseTag.
RentScratchSpec(GameplayEffectDefinition, Single) Rents a pooled spec for internal applications (cost, cooldown). Return it with AbilitySystem.ReturnScratchSpec.
RestoreState(AbilitySystemState, GameplayEffectDefinition>, GameplayAbility>, Boolean) Restores a saved state. With clear, active effects, granted abilities and loose tags are removed first; otherwise the saved ones are added. Effects come back with their remaining time, stacks and period, without executing again or checking requirements. Returns what could not be restored (unknown attributes, tags, effects or abilities); everything else is.
RetryBufferedInput() Activates the buffered press if it can now. False while it keeps waiting.
ScaleByStacks(ModifierOp, Single, Int32) Effective magnitude of stacks stacks of one modifier.
SetBaseValue(GameplayAttribute, Single) Sets the base value directly, outside any effect. Clamped.
TryActivateAbilitiesWithTags(GameplayTagSet) Tries to activate every granted ability whose tags match any of abilityTags. Returns how many started.
TryActivateAbility(GameplayAbilitySpecHandle) Tries to activate a granted ability.
TryActivateAbility(GameplayAbilitySpecHandle, AbilityActivationFailure) Tries to activate a granted ability and reports why it failed.
TryGetAbilitySpec(GameplayAbilitySpecHandle, GameplayAbilitySpec) Finds a granted ability by handle.
TryGetActiveEffect(ActiveEffectHandle, ActiveGameplayEffect) Finds an active effect by handle.
Abilities Granted abilities, in grant order.
ActiveAbilities Running activations.
ActiveEffects Active duration and infinite effects, in application order.
AttributeEventHandler Game rules for clamping and meta attributes. May be null.
CurrentCause Spec of the effect whose processing is changing this system now, or null.
HasBufferedInput True while a press waits in the input buffer.
InputBufferTime Seconds a press that could not activate its ability is kept and retried every tick: pressed just before a cooldown ends, or while another ability blocks it. Only the last such press is kept. 0 (default) disables it. Presses refused for cost or a custom check are not kept.
Owner Free reference to the game object that owns this system.
Tags Current tags: loose tags plus tags granted by active effects.
World World the system belongs to.

AbilitySystemHistory

Records what happens to an ability system, newest last, up to a capacity: effects, attribute changes with the effect that caused them, tags, abilities and gameplay events. For debugging: it allocates on every event. Dispose it to stop recording.

Member Description
event Recorded Raised after each new entry.
constructor(AbilitySystem, Int32, String>) Starts recording system. describe names source systems in causes (default: none).
Clear() Drops every entry.
Dispose() Stops recording.
Capacity Maximum number of entries kept; older ones are dropped.
Entries Entries, oldest first.
System The recorded system.

AbilitySystemState

Saved state of an ability system: attribute base values, loose tags, granted abilities and active effects with their remaining time, stacks and period. Plain public fields, so any serializer handles it (Unity's JsonUtility, System.Text.Json with fields included, Newtonsoft).

Not saved: running activations (abilities restart idle), effects owned by running activations, and the source system of effects. Effects and abilities are saved by key (their name by default) and found again by the resolvers given to AbilitySystem.RestoreState.

Member Description
Abilities Granted abilities.
Attributes Base values by attribute name. Current values follow from effects.
Effects Active effects, cooldowns included.
LooseTags Tags added with AbilitySystem.AddLooseTag, with their counts.
Version Format version.

AbilityTask

Return type of GameplayAbility.ActivateAbility and of async helpers awaited from it. Runs on the world thread, driven by world events: no thread pool, no Task.

A method that completes without awaiting allocates nothing. A method that awaits allocates its state once, on the first await; further awaits allocate nothing. When an ability ends, pending waits never resume: put cleanup in GameplayAbility.OnEndAbility, not in finally.

Member Description
GetAwaiter() Awaiter used by await.
OnCompleted(Action) Runs callback when the task completes, or now if it already has.
CompletedTask An already completed task.
Exception Exception thrown by the method, if any.
IsCompleted True once the method returned or threw.

AbilityTask.Awaiter

Awaiter of AbilityTask.

Member Description
GetResult() Rethrows the task's exception, if any.
OnCompleted(Action)
UnsafeOnCompleted(Action)
IsCompleted True once the task completed.

AbilityTaskMethodBuilder

Compiler support for async AbilityTask methods. Not meant to be called directly.

Member Description
AwaitOnCompleted(``0, ``1) Compiler support.
AwaitUnsafeOnCompleted(``0, ``1) Compiler support.
Create() Compiler support.
SetException(Exception) Compiler support.
SetResult() Compiler support.
SetStateMachine(IAsyncStateMachine) Compiler support.
Start(``0) Compiler support.
Task Compiler support.

AbilityTaskPromise

Completion state of an AbilityTask that awaited.

AbilityTaskPromise`1

Promise that also holds the boxed state machine and its MoveNext delegate.

AbilityTrigger

Automatic activation rule.

Member Description
constructor(GameplayTag, AbilityTriggerSource) Creates a trigger.
Source Kind of trigger.
Tag Event or owned tag watched.

AbilityTriggerSource

What starts an ability automatically.

Member Description
GameplayEvent A gameplay event whose tag matches (children included).
OwnedTagAdded The owner gains the tag.
OwnedTagPresent Active while the owner has the tag: starts when it is added, cancelled when it is removed.

AbilityWait

Awaitable returned by waits that produce no value.

Member Description
GetAwaiter() Awaiter used by await.

AbilityWait.Awaiter

Awaiter of AbilityWait.

Member Description
GetResult() Releases the wait.
OnCompleted(Action)
UnsafeOnCompleted(Action)
IsCompleted True once the wait completed.

AbilityWait`1

Awaitable returned by waits that produce a T.

Member Description
GetAwaiter() Awaiter used by await.

AbilityWait`1.Awaiter

Awaiter of AbilityWait.

Member Description
GetResult() Returns the result and releases the wait.
OnCompleted(Action)
UnsafeOnCompleted(Action)
IsCompleted True once the wait completed.

ActiveEffectHandle

Refers to an active effect. Stays safe to use after the effect is removed: it becomes invalid.

Member Description
Equals(Object)
Equals(ActiveEffectHandle)
GetHashCode()
Id Unique id within the owner. 0 for an invalid handle.
IsValid True while the effect is active.
Owner System the effect is on.

ActiveGameplayEffect

A duration or infinite effect currently on an AbilitySystem. Instances are pooled: keep an ActiveEffectHandle, not this object.

Member Description
GetRemainingTime() Seconds left before expiry. Infinity for infinite effects.
Definition Definition applied.
Duration Duration in seconds. Infinity for infinite effects.
EndTime World time at which the effect expires. Infinity for infinite effects.
Handle Handle to this effect.
IsInhibited True while GameplayEffectDefinition.OngoingRequirement is not met.
Owner System the effect is on.
Spec Copy of the spec applied. Do not modify it.
StackCount Current stack count, at least 1.
StartTime World time of the first application.

ArcanaLog

Logging entry point of the core. The core has no engine reference, so it writes nowhere until a sink is set. The Unity layer routes it to the Unity console.

Member Description
Sink Receives every message. Null discards them.

ArcanaLogLevel

Severity of an ArcanaLog message.

Member Description
Error A failed operation. Arcana aborted it and kept the state consistent.
Info Diagnostic detail.
Warning Something unexpected that Arcana recovered from.

ArcanaWorld

Owns time and every AbilitySystem of a game. Call ArcanaWorld.Tick once per frame.

Single-threaded by contract: every call must come from the thread that created the world. Other threads use ArcanaWorld.Enqueue; commands run at the start of the next tick.

Member Description
constructor(GameplayTagRegistry, GameplayAttributeRegistry) Creates a world.
CreateAbilitySystem() Creates an ability system with no attribute.
Enqueue(ArcanaWorld>) Queues a command from any thread. It runs on the world thread at the next ArcanaWorld.Tick.
EnterGuard(String) Enters one level of nesting. False, with an error logged, if the limit is reached.
EvaluateCondition(WaitNode) Completes node with true if its condition holds. A throwing condition completes it with false.
Tick(Single) Advances time by deltaTime seconds: runs queued commands, then due timers in order.
Attributes Attribute registry shared by every system.
MaxRecursionDepth Maximum nesting of effect applications, tag reactions and attribute reactions. Deeper chains are aborted and logged with the chain, which catches infinite loops.
Systems Systems created by this world and not disposed.
Tags Tag registry shared by every system.
Time Seconds elapsed through ArcanaWorld.Tick.

AttributeBasedMagnitude

(Attribute + PreMultiplyAdditive) × Coefficient + PostMultiplyAdditive. Reads 0 if the system or attribute is missing.

Member Description
constructor(GameplayAttribute, AttributeSource, Single) Creates an attribute-based value.
Calculate(MagnitudeContext)
CollectDependencies(AttributeDependency>)
Attribute Attribute read.
Calculation Value of the attribute to read.
Coefficient Multiplier.
From Side read.
PostMultiplyAdditive Added after the multiplier.
PreMultiplyAdditive Added before the multiplier.
Snapshot True: the value is read once, when the effect is applied. False: a duration effect follows the attribute while active.

AttributeCalculation

Which value of an attribute an AttributeBasedMagnitude reads.

Member Description
BaseValue Base value.
BonusValue Current minus base.
CurrentValue Current value, modifiers included.

AttributeDefinition

Declares an attribute before the registry is built.

Member Description
constructor(String, Single) Declares an attribute with no bound.
DefaultBaseValue Base value given to a new ability system.
IsMeta A meta attribute (e.g. Damage) only carries a value from an effect to IAttributeEventHandler.PostEffectExecute. Its base value returns to 0 afterwards.
MaxAttributeName Attribute whose current value caps this one, e.g. MaxHealth for Health. Lowering the cap also lowers the base value. Null for none.
MaxValue Highest base and current value.
MinValue Lowest base and current value.
Name Unique name, case-insensitive.

AttributeDependency

An attribute read by a live magnitude.

Member Description
constructor(AttributeSource, GameplayAttribute) Creates a dependency.
Attribute Attribute read.
Source Side the attribute is read from.

AttributeInfo

Resolved data of one attribute.

AttributeSource

Which side of an effect an attribute is read from.

Member Description
Source The system that created the spec.
Target The system receiving the effect.

AttributeState

Base value of one attribute.

Member Description
BaseValue Base value.
Name Attribute name.

AttributeStore

Attribute values and modifier contributions of one AbilitySystem.

Member Description
ApplyToBase(GameplayAttribute, ModifierOp, Single) Applies one operation to the base value and returns (old, new).
SetContribution(GameplayAttribute, Object, Int32, ModifierOp, Single) Adds or updates the contribution identified by (owner, key).

ConstantMagnitude

A fixed value.

Member Description
constructor(Single) Creates a fixed value.
Calculate(MagnitudeContext)
Value The value.

DurationPolicy

How long a gameplay effect lasts.

Member Description
HasDuration Active for GameplayEffectDefinition.Duration seconds.
Infinite Active until removed.
Instant Changes base values once and is gone.

EffectApplication

Result of AbilitySystem.ApplyGameplayEffectToSelf.

Member Description
Handle Active effect created or stacked. Invalid for instant effects and failures.
Result What happened.
Succeeded True if the effect executed, was applied or stacked.

EffectApplicationResult

Outcome of an application attempt.

Member Description
Applied A new active effect was added.
BlockedByImmunity An active effect on the target grants immunity to this one.
BlockedByRequirements The target's tags failed GameplayEffectDefinition.ApplicationRequirement.
Executed An instant effect changed base values.
Failed Invalid input or recursion limit reached. Details are logged.
Stacked An existing stack was increased or refreshed.

EffectExecutionContext

Data available to an IEffectExecution.

Member Description
Source System that created the spec. May be null.
Spec Spec executing.
StackCount Stacks of a periodic effect; 1 for an instant effect.
Target System receiving the effect.

EffectExecutionData

A base value change made by an instant or periodic effect.

Member Description
Attribute Attribute changed.
Magnitude Magnitude applied, stacks included.
NewBaseValue Base value after the change, clamped.
OldBaseValue Base value before the change.
Op Operation applied.
Spec Spec that executed.

EffectExecutionOutput

Base value changes produced by an IEffectExecution.

Member Description
Add(GameplayAttribute, ModifierOp, Single) Queues a change to a base value of the target.

EffectState

An active effect.

Member Description
Duration Full duration in seconds; -1 for infinite effects.
Effect Key given by the capture (the definition's name by default).
Level Spec level.
NextPeriodIn Seconds until the next period tick; -1 for non-periodic effects.
Remaining Seconds left; -1 for infinite effects.
SetByCaller Set-by-caller values of the spec.
Stacks Stack count.

GameplayAbility

Base class of every ability. Subclass it and implement GameplayAbility.ActivateAbility. The object you grant holds the configuration; copies are made according to GameplayAbility.InstancingPolicy.

Member Description
constructor(String) Creates an ability.
ActivateAbility(AbilityContext) Runs the ability. Await AbilityContext waits for timings and events.
CanActivateAbility(AbilitySystem, GameplayAbilitySpec) Extra activation condition. Called after tag, cooldown and cost checks.
CheckCost(AbilitySystem, GameplayAbilitySpec) True if the owner can pay GameplayAbility.Cost. Default rule: every ModifierOp.Add modifier must leave the attribute's current value at 0 or more.
CreateInstance() Creates the copy used by instanced policies. Default: shallow copy.
OnEndAbility(AbilityContext, Boolean) Called once when the ability ends or is cancelled. Pending waits are already dropped.
OnGiven(GameplayAbilitySpec) Called on the instance that will run, when the ability is granted.
OnInputPressed(AbilityContext) Called when the bound input is pressed while active.
OnInputReleased(AbilityContext) Called when the bound input is released while active.
OnRemoved(GameplayAbilitySpec) Called when the ability is removed from its owner.
AbilityTags Tags describing the ability, used by cancel and block rules (e.g. Ability.Attack.Melee).
ActivateWhenGranted Activates as soon as it is granted (passives).
ActivationBlockedTags The owner must have none of these.
ActivationOwnedTags Tags given to the owner while active.
ActivationRequiredTags The owner must have all of these.
BlockAbilitiesWithTags While active, blocks abilities whose GameplayAbility.AbilityTags match.
CancelAbilitiesWithTags On activation, cancels active abilities whose GameplayAbility.AbilityTags match.
Cooldown Timed effect applied to the owner on commit. Its GameplayEffectDefinition.GrantedTags are the cooldown tags: while present, the ability cannot activate. May be null.
Cost Instant effect applied to the owner by AbilityContext.CommitAbility. May be null.
EndWhenActivationReturns Ends the ability when GameplayAbility.ActivateAbility returns. Set it to false for abilities that stay active after their method returns, then call AbilityContext.EndAbility yourself.
InstancingPolicy Which object runs an activation.
Name Name used in logs and debug views.
NetExecutionPolicy Network behaviour, for the networking adapters.
ReactivationPolicy What activating it while active does. Ignored for AbilityInstancingPolicy.InstancedPerExecution.
Triggers Automatic activation rules.

GameplayAbilitySpec

An ability granted to an AbilitySystem, with its level and input binding.

Member Description
Ability The ability object passed to AbilitySystem.GiveAbility.
ActiveCount Activations currently running.
Handle Handle to this grant.
InputId Input bound by AbilitySystem.AbilityInputPressed. -1 for none.
InputPressedTime World time of the last input press.
Instance Copy used by AbilityInstancingPolicy.InstancedPerActor.
IsActive True while at least one activation runs.
IsInputPressed True while the bound input is held.
Level Level, passed to the specs the ability creates.
Owner System the ability is granted to.
SourceObject Object that granted the ability (an item, a talent...). May be null.

GameplayAbilitySpecHandle

Refers to a granted ability. Becomes invalid when the ability is removed.

Member Description
Equals(Object)
Equals(GameplayAbilitySpecHandle)
GetHashCode()
Id Unique id within the owner. 0 for an invalid handle.
IsValid True while the ability is granted.
Owner System the ability is granted to.

GameplayAttribute

Identifies a numeric attribute such as Health, resolved by a GameplayAttributeRegistry. default is GameplayAttribute.None.

Member Description
Equals(Object)
Equals(GameplayAttribute)
GetHashCode()
ToString() Index-based description. Use GameplayAttributeRegistry.GetName for the name.
op_Equality(GameplayAttribute, GameplayAttribute) Equality by index.
op_Inequality(GameplayAttribute, GameplayAttribute) Inequality by index.
Index Position in the registry. -1 for GameplayAttribute.None.
IsValid True for any attribute except GameplayAttribute.None.
None No attribute.

GameplayAttributeRegistry

The immutable list of attributes known to a game.

Member Description
Build(AttributeDefinition>) Builds a registry. Names must be unique; max attributes must exist.
Get(String) Returns the attribute named name.
GetAt(Int32) Attribute at position index, from 0 to GameplayAttributeRegistry.Count - 1.
GetDefinition(GameplayAttribute) Definition of attribute.
GetName(GameplayAttribute) Name of attribute.
TryGet(String, GameplayAttribute) Looks up an attribute by name.
Count Number of attributes.

GameplayCueEvent

Moment of a gameplay cue (visual or audio feedback).

Member Description
Executed One-shot: an instant effect executed or a periodic effect ticked. Play a burst.
OnActive A lasting cue started. Play its start (e.g. ignition).
Removed A lasting cue stopped. Stop loops.
WhileActive A lasting cue is running, sent right after GameplayCueEvent.OnActive. Start loops here.

GameplayCueParameters

Data sent with a gameplay cue.

Member Description
constructor(AbilitySystem, AbilitySystem, Single, Single, Object) Creates parameters.
EffectSpec Spec that raised the cue, if it came from an effect. Do not keep it.
Level Level of the effect or ability.
Magnitude Size of the change, e.g. the damage dealt (first modifier of the effect).
Source System that caused the cue. May be null.
Target System the cue plays on.
UserData Free data from the spec or the caller.

GameplayEffectDefinition

Shared, read-only description of an effect: what it changes, for how long, and under which tag rules. Configure it, then treat it as immutable once applied: it is validated on first use.

Member Description
constructor(String, DurationPolicy) Creates an empty definition.
EnsureValid() Checks the configuration once. Throws on invalid settings.
Validate() Checks the configuration. Returns what is wrong, or null if the effect can be applied.
ApplicationRequirement Target tags required to apply the effect.
AssetTags Tags describing the effect itself (e.g. Effect.Damage.Fire).
Duration Seconds, for DurationPolicy.HasDuration. Calculated on application.
DurationPolicy Instant, timed or infinite.
ExecutePeriodicOnApplication Periodic effects also execute when applied.
Executions Custom logic run on instant execution and on each period.
GameplayCues Gameplay cue tags (GameplayCue.Fire.Burn) raised on the target: GameplayCueEvent.Executed on each execution, GameplayCueEvent.OnActive / GameplayCueEvent.Removed while active.
GrantedApplicationImmunity While active, blocks incoming effects whose asset tags match any of these.
GrantedTags Tags given to the target while the effect is active and not inhibited.
Modifiers Attribute changes.
Name Name used in logs and debug views.
OngoingRequirement Target tags required for the effect to work. While unmet, it is inhibited but keeps its duration.
Period Seconds between executions. 0: not periodic. A periodic effect changes base values on every execution instead of modifying current values while active.
RemoveEffectsWithTags On application, removes active effects whose asset or granted tags match any of these.
StackDurationRefresh Duration behaviour on a new stack.
StackExpiration What expiry does to a stack.
StackLimit Maximum stack count. 0 or less: no limit.
StackPeriodReset Period behaviour on a new stack.
Stacking How applications of this effect combine.

GameplayEffectSpec

A definition ready to apply: level, source and runtime values. Applying copies what it needs, so a spec can be reused.

Member Description
constructor(GameplayEffectDefinition, AbilitySystem, Single) Creates a spec. Prefer AbilitySystem.MakeOutgoingSpec.
SetByCaller(GameplayTag, Single) Sets a value read by SetByCallerMagnitude. Returns this spec.
TryGetSetByCaller(GameplayTag, Single) Reads a set-by-caller value.
Definition Definition applied.
Level Level, sampled by ScalableMagnitude curves.
Source System that created the spec. May be null for environment effects.
UserData Free data for executions and handlers (hit point, weapon...).

GameplayEventData

Payload of a gameplay event sent with AbilitySystem.HandleGameplayEvent: a hit landing, an animation notify, an interaction.

Member Description
EventTag Tag of the event (e.g. Event.Montage.Release).
Instigator System that caused the event. May be null.
Magnitude Free number (damage dealt, combo index...).
Payload Free data.
Target System the event is about. May be null.
TargetData Targets attached to the event. May be null.

GameplayTag

A hierarchical name such as State.Debuff.Stun, resolved to an index by a GameplayTagRegistry. Four bytes, compared by index.

A tag is only meaningful for the registry that created it. default is GameplayTag.None.

Member Description
Equals(Object)
Equals(GameplayTag)
GetHashCode()
ToString() Index-based description. Use GameplayTagRegistry.GetName for the name.
op_Equality(GameplayTag, GameplayTag) Equality by index.
op_Inequality(GameplayTag, GameplayTag) Inequality by index.
Index Position in the registry. -1 for GameplayTag.None.
IsValid True for any tag except GameplayTag.None.
None The empty tag.

GameplayTagCountContainer

Live, reference-counted tags of an actor. Two effects granting State.Stun keep it present until both are removed.

Member Description
event TagPresenceChanged Raised when a tag becomes present (true) or absent (false), parents included. Raised once per call, after every count is updated.
constructor(GameplayTagRegistry) Creates an empty container.
AddTag(GameplayTag, Int32) Adds count references to tag.
AddTags(GameplayTagSet) Adds one reference to every tag of tags.
GetCount(GameplayTag) Count of tag and all its children.
GetExplicitCount(GameplayTag) Times tag itself was added, minus removals.
RemoveTag(GameplayTag, Int32) Removes up to count references to tag.
RemoveTags(GameplayTagSet) Removes one reference from every tag of tags.

GameplayTagQuery

A tag condition: all of GameplayTagQuery.RequireAll, at least one of GameplayTagQuery.RequireAny (if not empty), none of GameplayTagQuery.Exclude. Null sets are treated as empty.

Member Description
constructor(GameplayTagSet, GameplayTagSet, GameplayTagSet) Creates a query. Any argument may be null.
Matches(GameplayTagView) Evaluates the query against tags.
Any A query that matches everything.
Exclude No tag may be present.
IsEmpty True if the query has no condition.
RequireAll Every tag must be present.
RequireAny At least one tag must be present, unless the set is empty.

GameplayTagRegistry

The immutable list of tags known to a game. Registering A.B.C also registers A and A.B. Names are case-insensitive; the first spelling is kept.

Member Description
Build(String>) Builds a registry from tag names. Duplicates are ignored.
CreateSet(String[]) Creates an immutable set from tag names.
CreateSet(GameplayTag[]) Creates an immutable set of tags.
Get(String) Returns the tag for name.
GetAt(Int32) Tag at position index, from 0 to GameplayTagRegistry.Count - 1. Parents come before children.
GetName(GameplayTag) Full name of tag, or an empty string for GameplayTag.None.
GetParent(GameplayTag) Direct parent of tag, or GameplayTag.None for a root tag.
Matches(GameplayTag, GameplayTag) True if tag equals other or descends from it.
TryGet(String, GameplayTag) Looks up a tag by name.
Count Number of tags, parents included.
Empty A set with no tag.

GameplayTagSet

An immutable set of tags, used in definitions: granted tags, requirements, immunities. Create it with GameplayTagRegistry.CreateSet.

Member Description
ToString() Tag names joined by ", ".
Count Number of tags, without implied parents.
Tags Tags in the set, without implied parents.

GameplayTagView

Read access shared by GameplayTagSet and GameplayTagCountContainer. Queries match parents: a view holding State.Debuff.Stun has State.Debuff.

Every query is a bitset operation and allocates nothing.

Member Description
HasAll(GameplayTagSet) True if every tag of tags matches. True for an empty set.
HasAny(GameplayTagSet) True if at least one tag of tags matches. False for an empty set.
HasNone(GameplayTagSet) True if no tag of tags matches.
HasTag(GameplayTag) True if tag or one of its children is present.
HasTagExact(GameplayTag) True if tag itself was added. Children do not count.
IsEmpty True if no tag is present.
Registry Registry the tags belong to.

HistoryEntry

One recorded change of an ability system.

Member Description
ToString()
Cause For attribute changes: the effect that caused it and its source, e.g. fireball_damage (Hero); null if unknown. For effects: their source. For failures: the reason.
Kind What happened.
NewValue New value (attributes) or new stack count.
OldValue Old value (attributes) or old stack count.
Subject Effect, attribute, tag, ability or event name.
Time World time of the change.

HistoryKind

Kind of a recorded HistoryEntry.

Member Description
AbilityActivated An ability started.
AbilityCancelled An ability was cancelled.
AbilityEnded An ability ended normally.
AbilityFailed An activation was refused.
AttributeChanged The current value of an attribute changed.
EffectApplied A duration or infinite effect was added.
EffectExecuted An instant effect executed, or a periodic effect ticked.
EffectRemoved An active effect was removed or expired.
GameplayEvent A gameplay event was received.
StacksChanged The stack count of an active effect changed.
TagAdded A tag appeared on the system.
TagRemoved A tag left the system.

IAttributeDependent

Notified when an attribute's current value changes.

IAttributeEventHandler

Game rules attached to an AbilitySystem: clamping and turning meta attributes into real changes (e.g. Damage into Health).

Member Description
PostEffectExecute(AbilitySystem, EffectExecutionData) Called after an instant or periodic effect changed a base value. Applying effects or setting base values here is allowed.
PreAttributeChange(AbilitySystem, GameplayAttribute, Single) Called before a current value changes, after Min/Max/MaxAttribute clamps. Change newValue to clamp further. Do not apply effects here.

ICurve

A function of one variable, typically the effect level.

Member Description
Evaluate(Single) Value at x.

IEffectExecution

Custom logic run when an instant effect executes or a periodic effect ticks, for formulas that read several attributes (damage with armor and resistances, for example).

Member Description
Execute(EffectExecutionContext, EffectExecutionOutput) Reads context and adds base value changes to output.

ILiveMagnitude

A magnitude that reads attributes and must be recalculated when they change. Duration effects recalculate it while active; instant and periodic executions always read fresh values.

Member Description
CollectDependencies(AttributeDependency>) Adds the attributes the value depends on.

IMagnitude

Computes a modifier or duration value. Implement it for custom formulas.

Member Description
Calculate(MagnitudeContext) Returns the value for context.

ITimerTarget

Receives timers scheduled on an ArcanaWorld.

Member Description
OnTimer(Int32, Int32, Double) Called when the timer fires. Ignore it if version is stale.

LinearCurve

Piecewise linear curve through sorted keys. Clamped to the first and last key outside their range.

Member Description
constructor(Single>>) Creates a curve from (x, y) keys in any order.
constructor(Single[]) Creates a curve from alternating x, y values: new LinearCurve(1, 10, 5, 40).
Evaluate(Single)

MagnitudeContext

Data available when a magnitude is calculated.

Member Description
Level Level of the spec.
Source System that created the spec. May be null.
Spec Spec being applied.
Target System receiving the effect.

ModifierDefinition

One change an effect makes to one attribute.

Member Description
constructor(GameplayAttribute, ModifierOp, Single) Creates a modifier with a constant magnitude.
constructor(GameplayAttribute, ModifierOp, IMagnitude) Creates a modifier.
Attribute Attribute changed.
Magnitude Value used by the operation.
Op Operation.

ModifierOp

How a modifier changes an attribute. Current value = ((Base + ΣAdd) × (1 + Σ(MultiplyAdditive − 1)) × ΠMultiplyCompound) ÷ ΠDivide, unless an ModifierOp.Override is active.

Member Description
Add Adds the magnitude.
Divide Divides by the magnitude. A magnitude of 0 is ignored.
MultiplyAdditive Multiplies, summing bonuses with other modifiers of this op: two ×1.3 give ×1.6. Use it for percentage bonuses.
MultiplyCompound Multiplies, compounding with other modifiers of this op: two ×1.3 give ×1.69.
Override Replaces the value. The most recently applied override wins.

NetExecutionPolicy

Intended network behaviour. Stored now, used by the networking adapters.

Member Description
LocalOnly Runs on the owning client only.
LocalPredicted Runs on the owning client at once, confirmed by the server.
ServerInitiated Started by the server, then runs on the owning client.
ServerOnly Runs on the server only.

ScalableMagnitude

Value × Curve(Level). Without a curve, Value.

Member Description
constructor(Single, ICurve) Creates a scalable value.
Calculate(MagnitudeContext)
Curve Curve sampled at the spec level. May be null.
Value Multiplier applied to the curve.

SetByCallerMagnitude

A value provided at runtime through GameplayEffectSpec.SetByCaller.

Member Description
constructor(GameplayTag, Single) Creates a set-by-caller value.
Calculate(MagnitudeContext)
DefaultValue Used, with a warning, when the caller did not set the key.
Key Key the caller sets.

SetByCallerState

One set-by-caller value.

Member Description
Tag Tag name of the key.
Value Value.

StackDurationRefreshPolicy

What a new application does to the remaining duration of a stack.

Member Description
NeverRefresh Keeps the current end time.
RefreshOnSuccessfulApplication Restarts the duration.

StackExpirationPolicy

What happens when a stack's duration ends.

Member Description
ClearEntireStack Removes every stack.
RemoveSingleStackAndRefreshDuration Removes one stack and restarts the duration for the others.

StackingType

How repeated applications of the same effect combine.

Member Description
AggregateBySource One stack per source system on the target.
AggregateByTarget One stack on the target, whatever the source.
None Each application is a separate active effect.

StackPeriodResetPolicy

What a new application does to the period timer of a stack.

Member Description
NeverReset Keeps the current period timer.
ResetOnSuccessfulApplication The next execution happens one full period after the application.

TagBits

Bitset helpers over ulong[], one bit per tag index.

Member Description
ContainsAll(UInt64[], UInt64[]) True if every bit of required is set in bits.
Overlaps(UInt64[], UInt64[]) True if a and b share a bit.

TagCountState

A loose tag and its count.

Member Description
Count Reference count.
Tag Tag name.

TargetData

Result of targeting: chosen systems and an optional point or object.

Member Description
Payload Engine-specific data: hit point, hit result, aim direction...
Targets Targeted systems.

TimerQueue

Min-heap of timers ordered by time, then priority, then insertion. Cancelling is done by the target ignoring stale versions, so nothing is ever searched or removed from the middle.

WaitAwaiting

Shared awaiter logic.

WaitNode

One pending wait of an ability. Pooled by the world; WaitNode.Version makes stale awaiters harmless.