Getting started in Unity¶
- Project Settings → Arcana → Create Settings. This creates a settings asset, a tag database and an attribute database,
and adds the settings to the Preloaded Assets (builds load it without
Resources). - Declare tags and attributes in the two databases (
State.Debuff.Stun,Health,MaxHealth...). - Create effects and abilities: Create → Arcana → Gameplay Effect, Create → Arcana → Abilities → ...,
or subclass
ScriptableAbilityfor your own abilities. - Create a profile (Create → Arcana → Ability System Profile): starting attributes, abilities, effects and tags.
- Add an Ability System Component to your character (GameObject → Arcana → Ability System Component) and assign the profile.
- Play, then open Window → Arcana → Debugger to watch attributes, tags, effects and abilities live.
Samples¶
| Sample | Content | Run it |
|---|---|---|
| Recipes | Thirteen small examples, one feature each: abilities, attributes, periodic effects, stacking, cost and cooldown, set-by-caller, executions, async tasks, targeting, cues, owner/avatar, area targeting, an animation-driven combo. | Tools → Arcana → Create Recipes Scene, Play |
| Arena | A playable wave survival built only from Arcana: five abilities, two enemy types, armor, burn and poison stacks, freeze on chilled targets, dash invulnerability, a toggled shield draining Mana, wave scaling. Every tag, attribute and effect comes from the CSV tables of Data/. |
Tools → Arcana → Create Arena Scene, Play |
With the Package Manager, import them from the package's Samples tab. With the Asset Store package, they are already in
Assets/ZazuLabs/Arcana/Samples. Both samples set up their own runtime world, so they run without touching Project Settings.
The arena is made for URP, and its materials copy the active pipeline's default material, so it renders in any pipeline.
Edit Data/ArenaEffects.csv (damage, durations, cooldowns, stacks) and press Play again to rebalance it.
Unity components and assets¶
| Type | Role |
|---|---|
ArcanaSettings |
Project configuration: tag and attribute databases, recursion limit, scaled or unscaled time. |
GameplayTagDatabase / AttributeDatabase |
Tags and attributes declared without code. Several databases are merged. |
AbilitySystemComponent |
Puts an ability system on a GameObject. Lifecycle methods are protected virtual. |
AbilitySystemProfile |
Starting kit shared by many actors. |
GameplayEffectAsset |
An effect edited in the inspector. Magnitudes and executions use a type picker. |
ScriptableAbility |
Base class of abilities edited in the inspector. Built-in: EffectAbility (instant, timed, toggle, passive), ProjectileAbility, MeleeAbility. |
GameplayCueLibrary / GameplayCueHandler / GameplayCueNotify |
Map cue tags to pooled prefabs and play them on the actor. |
ArcanaProjectile / ArcanaPool |
Pooled projectile, with an optional tag query on targets (factions); generic prefab pool built on UnityEngine.Pool. |
TargetCollector / TargetFilter |
Find targets in a sphere, cone, box or line, or the source itself; filter by tag query (factions, alive), line of sight, count and distance. |
AnimationEventRelay |
Turns Animation Events (ArcanaEvent("Event.Attack.Hit")) into gameplay events. |
ArcanaDebugOverlay |
In-game view of every ability system (F1). |
Owner and avatar. The component can live on a persistent owner (a player state) while the avatar is the body in the world.
Call InitAbilityActorInfo(owner, newBody) on respawn: effects, cooldowns and abilities are kept, and lasting cues move to the new body.
In abilities, context.GetActorInfo() gives the avatar, its Animator and cached components (GetAvatarComponent<T>()), so abilities
never need GetComponent on the owner.
Shared assets. A ScriptableAbility asset is shared by every actor. Keep per-activation state in local variables of Activate
(they live as long as the activation) or in the AbilityContext, never in the asset's fields.
Custom magnitudes and executions appear in the inspector's type picker when they are [Serializable] classes with a
parameterless constructor: subclass MagnitudeSource, or implement IEffectExecution.
Editor buttons. [ArcanaButton] on a parameterless method adds a button to the inspector of any MonoBehaviour or
ScriptableObject that has no custom editor. Arcana's inspector keeps Unity's default one.