Define a spell once. Give it to a hundred enemies.
Ability System is a tag-based gameplay framework for Unity. Abilities, effects, attributes and cues are assets; every character keeps its own state.
Unity 6000.0 or newer. Tested in URP and HDRP, Mono and IL2CPP. Full C# source included.
Enemy
100 / 100- Granted tags
- Active effects
- Playing cues
A small simulation of the Basic Combat sample. Numbers are illustrative. Stack the poison three times: three stacks, one particle effect.
Five building blocks, all data
Designers change numbers in the Inspector. Programmers add behaviour in small C# classes. Nothing is hardcoded to a character.
- Gameplay Tags
- Hierarchical names like
State.Stunned.Frozen, stored as integers. A child tag matches its parents, and queries are bit operations. A Tag Manager window and Inspector pickers are included. - Attributes
- Base and current value with min and max. A max can follow another attribute, so
Healthnever exceedsMaxHealth. Add, Multiply and Override modifiers. - Effects
- Instant, Duration and Infinite. Periodic ticks, stacking, immunity, cleanse and ongoing requirements. Magnitudes can be fixed, read from an attribute, or set by the caller. Custom executions for damage formulas.
- Abilities
- Cost and cooldown are effects. Activation tags, cancel-by-tag, event triggers, and waits for a delay, an event or a tag that clean up when the ability ends.
- Cues
- Pooled particles and sounds that effects request by tag. Swap the visuals without touching gameplay. Attribute reactions and gameplay events connect the rest, with no code.
Built to stay out of the garbage collector
Measured with the Unity Profiler. Ticking, applying an instant effect and removing an effect allocate no managed memory. Applying a timed effect allocates about 150 bytes.
- Shared assetsHundreds of characters use one definition.
- Pooled cuesNo instantiate or destroy after warm-up.
- Debugger windowAttributes, effects, tags, cues and abilities, live.
- Tests40+ automated EditMode tests.
using UnityEngine;
using supercachola.AbilitySystem;
using supercachola.AbilitySystem.Tags;
using supercachola.AbilitySystem.Effects;
public class Example : MonoBehaviour
{
[SerializeField] AbilitySystemComponent self;
[SerializeField] AbilitySystemComponent enemy;
[SerializeField] GameplayEffectDefinition poison;
// Activate an ability by tag
public void Cast() =>
self.TryActivateAbility(GameplayTag.Request("Ability.Fireball"));
// Apply an effect to another character
public void Poison() =>
self.TryApplyEffectTo(enemy, poison, out _);
}
Documentation
Start with the Getting Started guide. It runs the Basic Combat sample, then rebuilds it step by step.
- Getting Started
Run the sample, then build the same character from scratch.
- Tags
Hierarchy, containers and the Tag Manager.
- Attributes
Limits, dynamic maximum and modifiers.
- Effects
Duration types, stacking, executions and set by caller.
- Abilities
Activation rules, cost, cooldown and waits.
- Events
Tag-based gameplay events and the Animation Event relay.
- Cues
Pooled visual and audio feedback.
- Attribute reactions
Apply effects and send events at a threshold.
- Debugging
The Debugger window and console warnings.
- Performance
Allocation profile and how to measure it yourself.
Requirements
Ability System is plain C# and ScriptableObjects. Only the sample depends on a render pipeline and the Input System.
- Unity6000.0 or newer.
- Render pipelinesThe sample works in URP and HDRP.
- Input SystemOptional. Needed for the input binder and the sample.
- SourceFull C# source with assembly definitions.