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.