Skip to content

ZazuLabs.Arcana.Unity

AbilityAnimationExtensions

Animation-driven abilities: play Animator states, wait for their events and their end, record hit windows.

Member Description
OpenHitWindow(AbilityContext, TargetCollector, TargetFilter, Action<AbilitySystem>) Opens a HitWindow: until it is disposed or the ability ends, collector is checked every frame from the avatar and each new target is passed once to onHit.
PlayAnimation(AbilityContext, string, float, int, string, float) Cross-fades the avatar's Animator to stateName on layer. If the ability is cancelled while the state plays and interruptState is set, the animator blends to it. Without animator or state, the returned playback has already ended and an error is logged for a missing state.
WaitAnimationEnd(AbilityContext, AnimationPlayback, float) Completes when playback has ended (or after timeout seconds, returning false).
WaitAnimationEnd(AbilityContext, float) Completes when the last state played by this activation has ended.
WaitAnimationEvent(AbilityContext, GameplayTag) Completes on the Animation Event that sends eventTag through an AnimationEventRelay (function ArcanaEvent, string parameter = the tag name).

AbilityInputBinder

Binds Input System actions to abilities, without code: a press activates the ability (or reaches it while active, for combos and charges), a release ends holds. Confirm and cancel actions drive targeting. Compiled only when the Input System package is installed.

Member Description
Bindings Bindings edited in the inspector. Changes apply on the next enable.

AbilityInputBinder.Binding

One action bound to one ability.

Member Description
Ability Ability asset granted to the target. Null to use InputId.
Action Button action, e.g. Player/Fire.
InputId Input id of abilities granted in code, used when Ability is null.

AbilitySystemComponent

Puts an AbilitySystem on a GameObject. Put it on the character, or on a persistent owner (player state) and call InitAbilityActorInfo with each new avatar.

Member Description
event AvatarChanged Raised when the avatar changes (respawn, possession).
ApplyEffectToSelf(GameplayEffectAsset, float) Applies an effect asset to this system.
ApplyEffectToTarget(GameplayEffectAsset, AbilitySystemComponent, float) Applies an effect asset to target, with this system as source.
Awake() Creates the system and applies the profile. Call the base when overriding.
Find(Component) Finds the component on component's GameObject or its parents.
Find(GameObject) Finds the component on obj or its parents.
FindSpec(ScriptableAbility) First granted spec created from ability, or null.
GetAttribute(GameplayAttribute) Current value of an attribute. 0 if the system does not have it.
GiveAbility(ScriptableAbility, float, int) Grants an ability asset.
InitAbilityActorInfo(GameObject, GameObject) Sets owner and avatar, e.g. when a persistent player state gets a new character.
OnAvatarChanged() Called after the avatar changed.
OnDestroy() Disposes the system. Call the base when overriding.
SendGameplayEvent(GameplayTag, GameplayEventData) Sends a gameplay event to this system.
TryActivateAbility(ScriptableAbility) Activates the first granted spec created from ability.
ActorInfo Owner, avatar and cached avatar components.
Profile Starting configuration.
System The core system. Null before Awake and after destruction.

AbilitySystemProfile

Starting kit of an actor: attributes, abilities, effects and tags. Shared by many actors.

Member Description
ApplyTo(AbilitySystemComponent) Applies the profile: attributes first, then effects, tags and abilities.

AbilitySystemProfile.AbilityEntry

A starting ability.

Member Description
Ability Ability granted.
InputId Input id for AbilityInputPressed. -1: none.
Level Level.

AbilitySystemProfile.AttributeEntry

A starting attribute.

Member Description
Attribute Attribute added.
BaseValue Starting base value.
OverrideBaseValue Use BaseValue instead of the default.

AbilitySystemProfile.EffectEntry

A starting effect.

Member Description
Effect Effect applied.
Level Level.

ActorInfo

Who an ability system belongs to. The owner holds persistent state (a player state, a character root); the avatar is the body in the world, which can die and respawn. Both can be the same object.

Member Description
GetAvatarComponent() Component T on the avatar or its children, looked up once and cached. Null if absent. Use it for movement, weapons, input...
Animator First Animator on the avatar or its children. Null if none.
AvatarObject Body in the world. May be null between death and respawn.
AvatarTransform Avatar transform. Null without avatar.
Component The component holding the ability system.
OwnerObject Persistent owner.

AnimationCurveAdapter

Wraps an AnimationCurve as an ICurve.

Member Description
constructor(AnimationCurve) Wraps curve.
Evaluate(float)

AnimationEventRelay

Forwards Animation Events to the ability system: add an event calling ArcanaEvent with a tag name as string parameter (e.g. Event.Attack.Hit).

Member Description
ArcanaEvent(string) Called by Animation Events.

AnimationPlayback

An Animator state played by an ability (see AbilityAnimationExtensions.PlayAnimation). Tells when the state has ended and blends out of it if the ability is cancelled.

Member Description
Animator The animator playing the state; null if the avatar has none.
HasEnded True once the state has played to its end (normalized time ≥ the end time; never for looping states) or was left for another state. True at once without animator or without such a state.
NormalizedTime Normalized time of the state (0 to 1 over one play), or 0 when not in it.

ArcanaButtonAttribute

Shows a button for a parameterless method in the inspector of any MonoBehaviour or ScriptableObject without a custom editor.

Member Description
constructor() Uses the method name as label.
constructor(string) Uses label as label.
Label Button label; null for the method name.
PlayModeOnly Only enabled in Play Mode.

ArcanaDebugOverlay

In-game view of every ability system: attributes, tags, active effects and abilities. Toggle it with ToggleKey. Works in development builds; uses IMGUI, so no input package is needed.

Member Description
ToggleKey Key that shows or hides the overlay.

ArcanaPointer

Screen position of the pointer used by targeting. Reads the Input Manager by default; the Input System integration replaces it when the package is installed. Set it to drive targeting from anything else (gamepad cursor, touch, AI).

Member Description
ScreenPosition Returns the pointer position in screen pixels (origin bottom-left).

ArcanaPool

Prefab pools used by projectiles and gameplay cues, built on ObjectPool{T}. Released objects are deactivated and kept under a persistent root.

Member Description
Prewarm(GameObject, int) Creates count instances ahead of time.
Release(GameObject) Returns an instance to its pool. Objects not created by a pool are destroyed.
Spawn(GameObject, Vector3, Quaternion, Transform) Gets an instance of prefab from its pool, active, at the given pose.
Spawn(T, Vector3, Quaternion, Transform) Gets an instance of prefab and returns its component.

ArcanaProjectile

A straight-moving projectile that applies an effect spec to the first ability system it touches, then returns to its pool. Detection uses an overlap sphere: no Rigidbody needed.

Member Description
event Hit Raised when the projectile hits a system, before it is released.
Launch(AbilitySystem, GameplayEffectSpec, Vector3) Starts flying. spec is applied to the first system hit other than the instigator.
OnHit(AbilitySystemComponent) Called on hit, before release. Spawn impact feedback here.
Update() Moves and checks hits. Call the base when overriding.
Speed Speed in units per second.
TargetRequirement Tags a target must match to be hit, such as exclude: Faction.Enemy for enemy projectiles. Null hits every ability system but the instigator.

ArcanaRuntime

The ArcanaWorld of the running game, built from ArcanaSettings on first use and ticked once per frame by a hidden ArcanaTicker.

Member Description
event WorldCreated Raised after a world is created, including re-initializations.
EnsureInitialized() Creates the world from ArcanaSettings.Instance if it does not exist yet.
Initialize(GameplayTagRegistry, GameplayAttributeRegistry, int, bool, bool) Replaces the world with one built from explicit registries (tests, samples, mods). Ability system components created before keep the previous world: create them after this call.
ResolveAttribute(string) Resolves an attribute name, warning once per unknown name. GameplayAttribute.None if empty or unknown.
ResolveTag(string) Resolves a tag name, warning once per unknown name. GameplayTag.None if empty or unknown.
Attributes Attribute registry of the world.
IsInitialized True once a world exists.
Tags Tag registry of the world.
World The world. Initializes Arcana on first access.

ArcanaSave

Saves and loads ability systems as JSON (Unity's JsonUtility). Effects and abilities are stored by name and found again through a SaveCatalog or your own resolvers.

Member Description
FromJson(string) Parses a state written by ToJson.
Restore(AbilitySystem, string, Func<string,GameplayEffectDefinition>, Func<string,GameplayAbility>, bool, Object) Restores system from JSON with your own resolvers (code-defined effects and abilities).
RestoreFromJson(AbilitySystemComponent, string, SaveCatalog, bool) Restores the component's system from JSON with the catalog's effects and abilities. Returns what could not be restored (see AbilitySystem.RestoreState); each is also logged as a warning.
ToJson(AbilitySystem, bool) The state of system as JSON.
ToJson(AbilitySystemComponent, bool) The state of the component's system as JSON.

ArcanaSettings

Project-wide configuration. Create and assign it in Project Settings → Arcana, which also adds it to the Preloaded Assets so builds load it without Resources.

Member Description
BuildAttributeRegistry() Builds the attribute registry from every database. Later duplicates are skipped with a warning.
BuildTagRegistry() Builds the tag registry from every database.
AttributeDatabases Attribute databases merged into the registry.
Instance Active settings. Set by the editor from Project Settings, and in builds when the preloaded asset loads. Assign it yourself to use another asset.
LogInfo True to print info messages.
MaxRecursionDepth See ArcanaWorld.MaxRecursionDepth.
TagDatabases Tag databases merged into the registry.
UseUnscaledTime True to ignore Time.timeScale.

ArcanaTargeting

Targeting helpers for abilities.

Member Description
CollectTargets(AbilityContext, TargetCollector, TargetFilter, TargetData) Collects targets around the ability owner's avatar.
TryGetPoint(TargetData, Vector3) The world point of the target data (ground targeting), if it has one.

ArcanaTicker

Ticks ArcanaRuntime.World once per frame. Created automatically.

ArcanaUnityExtensions

Unity helpers for core types.

Member Description
GetActorInfo(AbilityContext) Actor info of the system running the ability.
GetAvatarTransform(AbilityContext) Avatar transform of the system running the ability.
GetComponent(AbilitySystem) Component holding system, or null if it is not on a GameObject.

AttributeBasedMagnitudeSource

(Attribute + Pre) × Coefficient + Post, read on the source or the target.

Member Description
constructor() Creates an empty source. Used by the inspector type picker.
constructor(AttributeReference, AttributeSource, float, bool) Creates an attribute-based source.
Build()

AttributeDatabase

Attributes declared without code. Merged into the runtime registry by ArcanaSettings.

Member Description
Add(Entry) Adds an attribute. Editor tooling and importers use it.
Find(string) Entry named name (case-insensitive), or null.
Remove(string) Removes the entry named name. Returns false if absent.
Attributes Declared attributes.

AttributeDatabase.Entry

One attribute declaration.

Member Description
DefaultBaseValue Base value given to a new ability system.
HasMaxValue Apply MaxValue.
HasMinValue Apply MinValue.
IsMeta Meta attribute: reset to 0 after PostEffectExecute.
MaxAttribute Attribute whose current value caps this one. Empty for none.
MaxValue Highest base and current value.
MinValue Lowest base and current value.
Name Unique name, e.g. Health.
FromData(AttributeData) Overwrites the entry with a table row.
ToData() Table form.
ToDefinition() Converts to a core definition.

AttributeReference

An attribute picked in the inspector, stored by name.

Member Description
constructor(string) Creates a reference by name.
ToString()
op_GameplayAttribute(AttributeReference) Resolves the attribute.
Attribute Resolved attribute, GameplayAttribute.None if empty or unknown.
IsEmpty True if no attribute is picked.
Name Attribute name as stored.

BoxTargets

Targets in a box in front: wide slashes, walls, corridors.

Member Description
constructor() Parameterless constructor for the inspector.
constructor(Vector3, float) Creates a box of size starting distance in front.
Overlap(TargetingOrigin, LayerMask)

ConeTargets

Targets in front within an angle: sword swings, breaths, shotgun blasts.

Member Description
constructor() Parameterless constructor for the inspector.
constructor(float, float, bool) Creates a cone of range and full angle in degrees.
Contains(TargetingOrigin, Vector3)
Overlap(TargetingOrigin, LayerMask)
Angle Full angle in degrees.
Range Length in meters.

ConstantMagnitudeSource

A fixed value.

Member Description
constructor() Creates a value of 0. Used by the inspector type picker.
constructor(float) Creates a fixed value.
Build()

EffectAbility

Applies effects to its owner: instant buff, timed buff, toggle or passive.

Member Description
Activate(AbilityContext)
Configure(GameplayAbility)

EffectAbilityMode

How an EffectAbility lasts.

Member Description
Instant Applies the effects and ends.
Passive Starts when granted and stays active; effects are removed when the ability is removed.
Timed Stays active for a duration; effects are removed at the end.
Toggle Activating again turns it off; effects are removed at the end (sprint, stance, aura).

GameplayCueHandler

Plays the gameplay cues of the AbilitySystemComponent on the same GameObject.

Member Description
Libraries Libraries searched in order.

GameplayCueLibrary

Maps gameplay cue tags to prefabs. A cue with no entry uses its closest parent's entry.

Member Description
Find(GameplayTag) Prefab for cue or its closest listed parent. Null if none.
Entries Entries as edited.

GameplayCueLibrary.Entry

One cue mapping.

Member Description
Cue Cue tag, e.g. GameplayCue.Fire.Burn.
Prefab Prefab spawned from a pool.

GameplayCueNotify

Base of cue prefabs. Override the callbacks to play particles, sounds or camera shakes. The instance returns to its pool ReleaseDelay seconds after a one-shot or a removal.

Member Description
OnActive(AbilitySystemComponent, GameplayCueParameters) A lasting cue starts.
OnExecute(AbilitySystemComponent, GameplayCueParameters) One-shot cue (hit, tick of damage).
OnRemove(AbilitySystemComponent, GameplayCueParameters) A lasting cue stops.
Update() Releases the instance when its delay is over. Call the base when overriding.
WhileActive(AbilitySystemComponent, GameplayCueParameters) A lasting cue is running; sent right after OnActive.
AttachToTarget Follow the target's avatar.
Offset Spawn offset in the avatar's space.
ReleaseDelay Seconds before release.

GameplayEffectAsset

A gameplay effect edited in the inspector. Definition builds the core definition once and rebuilds it after an edit or a registry change.

Member Description
Invalidate() Forces a rebuild on next access.
op_GameplayEffectDefinition(GameplayEffectAsset) Converts to the core definition.
Definition The core definition. Built on first access.
Modifiers Modifiers as edited.

GameplayEffectAsset.ModifierEntry

One modifier as edited.

Member Description
Attribute Attribute changed.
Op Operation.

GameplayTagDatabase

A list of gameplay tag names. Every database referenced by ArcanaSettings is merged into the runtime registry; parents (State for State.Stun) are added automatically.

Member Description
AddTag(string) Adds a tag if missing. Editor tooling and importers use it.
RemoveTag(string) Removes a tag. Returns false if it was not listed.
Tags Tag names as written.

GameplayTagQueryReference

A GameplayTagQuery edited in the inspector.

Member Description
Invalidate() Drops the cached query.
Resolve() The query, or null when it has no condition.
Exclude None of these is allowed.
RequireAll All of these are required.
RequireAny At least one of these is required, unless empty.

GameplayTagReference

A gameplay tag picked in the inspector, stored by name and resolved against the runtime registry.

Member Description
constructor(string) Creates a reference by name.
ToString()
op_GameplayTag(GameplayTagReference) Resolves the tag.
IsEmpty True if no tag is picked.
Name Tag name as stored.
Tag Resolved tag, GameplayTag.None if empty or unknown.

GameplayTagSetReference

A list of tags picked in the inspector, resolved to a cached GameplayTagSet.

Member Description
Invalidate() Drops the cached set. Call it after editing Tags at runtime.
Resolve() The set, or null when empty. Rebuilt when the registry changes.
IsEmpty True if no tag is picked.
Tags Tags as stored.

GroundTargetingActor

Follows the pointer for a pending GroundTargetingExtensions.WaitGroundTarget and answers the confirm input. Added on demand to the ability system's GameObject.

Member Description
Confirm() Confirms the aimed area, as the confirm input does.
TryGetAimedPoint(Vector3) The point currently aimed at, if any.
IsAiming True while an area is being aimed.

GroundTargetingExtensions

Ground-targeted abilities: aim an area with the pointer, confirm or cancel.

Member Description
WaitGroundTarget(AbilityContext, GroundTargetingOptions) Shows an area under the pointer and completes when the player confirms (AbilitySystem.InputConfirm): the target data holds the systems inside and a TargetPoint (read it with ArcanaTargeting.TryGetPoint). Completes with null on AbilitySystem.InputCancel.

GroundTargetingOptions

Settings of GroundTargetingExtensions.WaitGroundTarget.

Member Description
Camera Camera the pointer ray starts from; null for Camera.main.
Filter Which systems in the area become targets.
GroundLayers Layers the pointer ray can land on.
Indicator Prefab shown at the aimed point; null for a flat disc.
IndicatorColor Color of the default disc.
MaxRange Farthest distance from the caster; 0 for no limit.
Radius Radius of the area.

HitWindow

Records hits during an animation window: every target the collector finds while the window is open is reported once. Open it on the swing's start event, dispose it on the end event; it closes by itself when the ability ends.

Member Description
Dispose() Closes the window. Later frames hit nothing.
Sample() Checks the shape now. Called every frame while open.
Hits Systems hit so far.
IsOpen True until disposed or the ability ends.

HitWindowDriver

Samples open hit windows every frame. Added on demand to the ability system's GameObject.

LineTargets

Targets along a line: beams, piercing shots. With a limit of 1, the first target hit.

Member Description
constructor() Parameterless constructor for the inspector.
constructor(float, float) Creates a line of range and thickness radius.
Overlap(TargetingOrigin, LayerMask)

MagnitudeSource

Inspector-editable magnitude. Subclass it (mark the subclass [Serializable]) to add a custom magnitude: it then appears in the type picker of every magnitude field.

Member Description
Build() Creates the core magnitude. Called once per definition build.

MeleeAbility

Hits every ability system in a sphere in front of the avatar, after a delay or an animation event.

Member Description
Activate(AbilityContext)

PooledInstance

Marks an object created by ArcanaPool. Added automatically.

ProjectileAbility

Launches a pooled ArcanaProjectile from the avatar, carrying a damage effect.

Member Description
Activate(AbilityContext)

SaveCatalog

Lists the effect and ability assets a save can refer to, so a saved state finds them again by name. Use Collect All in its inspector to fill it with every effect and ability of the project.

Member Description
FindAbility(string) The ability of the asset named key, or null.
FindEffect(string) The definition of the effect asset named key, or null.
Abilities Ability assets, found by asset name.
Effects Effect assets, found by asset name.

ScalableMagnitudeSource

Value × curve sampled at the spec level.

Member Description
constructor() Creates a value of 1 with no curve. Used by the inspector type picker.
constructor(float, AnimationCurve) Creates a scalable value.
Build()

ScriptableAbility

An ability configured in the inspector. Subclass it, implement Activate, and add a [CreateAssetMenu] attribute to create assets of it.

The asset is shared by every actor: never keep per-activation state in its fields. Keep it in local variables of Activate (they live as long as the activation), or in the AbilityContext.

Member Description
Activate(AbilityContext) Runs the ability.
CanActivate(AbilitySystem, GameplayAbilitySpec) Extra activation condition.
Configure(GameplayAbility) Called when the core ability is built. Override to adjust settings in code.
Invalidate() Forces a rebuild of Ability on next access.
OnEnd(AbilityContext, bool) Called once when an activation ends or is cancelled.
OnInputPressed(AbilityContext) Called when the bound input is pressed while active.
OnInputReleased(AbilityContext) Called when the bound input is released while active.
OnValidate() Unity callback. Drops the built ability after an edit; call the base when overriding.
Ability The core ability granted to systems. Built on first access.
Cooldown Cooldown effect.
Cost Cost effect.

ScriptableAbility.TriggerEntry

One automatic activation rule as edited.

Member Description
Source Kind of trigger.
Tag Event or owned tag watched.

SelfTargets

Only the source itself: self buffs, heals.

Member Description
Overlap(TargetingOrigin, LayerMask)
TargetsSource

SetByCallerMagnitudeSource

A value set at runtime with GameplayEffectSpec.SetByCaller.

Member Description
constructor() Creates an empty source. Used by the inspector type picker.
constructor(GameplayTagReference, float) Creates a set-by-caller source.
Build()

SphereTargets

Every target within a radius: explosions, auras, novas.

Member Description
constructor() Parameterless constructor for the inspector.
constructor(float, Vector3) Creates a sphere of radius, optionally offset in the origin's space.
Overlap(TargetingOrigin, LayerMask)
Radius Radius in meters.

SubclassSelectorAttribute

Shows a type picker for a [SerializeReference] field: every non-abstract, serializable type assignable to the field type is offered.

TargetCollector

A shape that finds ability systems around an origin. Pick one in the inspector (type picker) or create one in code, then call Collect. Collection allocates nothing once its buffers are warm.

Member Description
Collect(TargetingOrigin, TargetFilter, TargetData) Adds the systems found to into (a new TargetData when null) and returns it. Each system appears once, even with several colliders.
Contains(TargetingOrigin, Vector3) Exact test on a candidate's position, for shapes the overlap only approximates (cones).
Overlap(TargetingOrigin, LayerMask) Fills results with the colliders of the shape and returns how many.
OverlapSphere(Vector3, float, LayerMask) Overlap helper for subclasses.
TargetsSource True for collectors meant to find the source itself, whatever TargetFilter.ExcludeSource.

TargetFilter

Which ability systems a collection keeps: a tag query on the target (faction, alive), the source itself, line of sight, and how many, sorted by distance.

Member Description
Accepts(AbilitySystem, AbilitySystem) True if target passes the tag query and the source rule.
ExcludeSource True to skip the source system.
Layers Layers of the colliders that can be found.
LineOfSightBlockers Layers that block line of sight; 0 for no check.
MaxTargets Maximum number of targets kept; 0 for no limit.
Requirement Tag query on the target, or null for any target. Setting it overrides the inspector value.
Sort Order applied before the limit.

TargetingOrigin

Where a collection starts: the source system, a position and a facing.

Member Description
constructor(AbilitySystem, Vector3, Vector3) Origin at position, facing forward.
FromAvatar(AbilityContext) The avatar of the ability's owner: its position and forward.
Forward Normalized facing used by cones, boxes and lines.
Position World position the shapes are placed from.
Source System collecting targets, excluded unless the filter allows it. May be null.

TargetPoint

Payload of target data aimed at a place rather than only at actors.

Member Description
constructor(Vector3, Vector3) A point with the ground normal at it.
Normal Surface normal at the position.
Position World position.

TargetSort

Order of collected targets, applied before TargetFilter.MaxTargets.

Member Description
Farthest Farthest from the origin first.
Nearest Closest to the origin first.
None Physics order.