REPOSITORY NO LONGER IN DEVELOPMENT

This repository has not been updated in some time, and I do not have time to spend on this. As a result, I am archiving this repository. Existing README is below.

Unity Gameplay Ability System

Gameplay Ability System for Unity (or GAS for short) is a Unity framework for creating games which contain any kind of abilities (e.g. DotA, Skyrim). The framework helps to simplify the interaction between components in a unified manner.

This project is heavily inspired by the Unreal Gameplay Ability System, and uses similar terminology, but the implementation is specific to Unity.

There are three main components provided by Gameplay Ability System:

Attribute System - for managing character attributes, such as health, speed, etc.
Gameplay Tags - for managing character states
Ability System - for coordinating the attribute system and gameplay tags

This demo includes a simple game where you can run around with the character, and cast an Ice Blast ability by pressing the left mouse button, and a Blood Sacrifice ability by pressing the right mouse button. The Ice Blast ability fires a projectile forward if there is an enemy ahead, and damages the enemy (consuming mana and putting the ability on cooldown). Using the Blood Sacrifice restores mana based on the percentage left, at the expense of health (and puts the ability on cooldown).

Prerequisites

Unity 2021.1.1f1 (Unity 2020.3+ should also work)

Install Demo

To install this demo:

Clone the repository

git clone https://github.com/sjai013/unity-gameplay-ability-system.git

Run the main scene Scenes/Main

Package Installation

To install the latest version of the package, import the package from a git URL using the Unity Package Manager:

https://github.com/sjai013/unity-gameplay-ability-system.git#upm

Wiki

The Wiki is a useful resource for how-tos and tutorials on using the Unity Gameplay Ability System. Check it out!

Read on for specific details about how the Attribute System, Gameplay Tags, and Ability System were incorporated into this demo.

Attribute System

The Attribute System is a collection of code for defining attributes specific to a game (e.g. Strength, Health, etc.). It also manages how these attributes mutate over the course of a game - for example, taking damage reduces health, or levelling up increases strength.

Attributes have a Base Value and a Current Value, and currently active modifiers which may be additive, multiplicative, or overriding.

The Current Value is calculated as:

Current Value = (Base Value + Additive) * Multiplicative

Attribute assets are created through the Create/Gameplay Abiliy System/Attribute asset menu.

The behaviour of the default AttributeScriptableObject class can be modified by creating a child class derived from AttributeScriptableObject. There is an in-built child class included in this sample (LinearDerivedAttributeScriptableObject) which demonstrates how to create "derived attributes" - for example, a "Max Health" attribute which is linearly related to a "Strength" attribute.

This project contains the following attributes (see Assets/My Gameplay Ability System/Attributes/Base):

Strength
Agility
Intelligence

All other attributes derive from these, using instances of LinearDerivedAttributeScriptableObject (see Assets/My Gameplay Ability System/Attributes/Derived):

Armour 4 + 0.17 * Agility
Attack Speed 1 * Agility
Max Health 200 + 20 * Strength
Health Regen 1.25 + 0.1 * Strength
Max Mana 75 + 12 * Intelligence
Mana Regen 0.5 + 0.05 * Intelligence

In addition, there are also Health and Mana attributes for tracking the current health and mana.

Gameplay Tags

Gameplay Tags are a way of assigning tags to objects in the Ability System. They can be used to represent boolean states on a character.

A parent can be defined for each tag, allowing you to create hierarchical gameplay tags. Tags can be compared for an exact match, or partial matches (e.g. ancestor/descendant).

Gameplay Tags assets are created through the Create/Gameplay Abiliy System/Tag asset menu.

Gameplay Tag interaction is used in this sample for putting abilities on cooldown.

Gameplay Effects

Gameplay Effects (GE) are at the heart of the ability system. They are created through the Create/Gameplay Ability System/Gameplay Effect Definition asset menu.

When creating a new GE, the following data needs to be defined:

Duration

The duration policy controls how the GE is applied, and whether it needs to be removed at a later point in time (e.g. a buff/debuff). The Duration Policy can be one of:

Instant
Infinite
Durational

Instant GE affect an attribute's Base Value. Infinite and Duration GE are similar to Instant GE, but they modify an attribute's Current Value, and references to the effect are stored so the effect can be reverted. As their name implies, Infinite GE remain applied indefinitely, whereas Duration GE are applied for a set duration, and then automatically expire, reverting their change (like a temporary buff or debuff).

Generally, you would use Instant GE for base stats, Infinite GE for pseudo-temporary stat changes, such as extra damage from equipping a weapon, and Durational GE for timed duration stat changes.

The Duration Modifier and Duration Multiplier property controls the base value of the duration (in seconds). This is only applicable for Durational GE:

    Duration = Duration Modifier * Duration Multiplier

A custom scriptable object inheriting from ModifierMagnitudeScriptableObject can be used to create new behaviours, such as using another attribute on the character as a base - see the AttributeBackedModifierMagnitude class, and it's instantiated Scriptable Objects MaxHealthAttributeBackedModifier and MaxManaAttributeBackedModifier in Asset/My Gameplay Ability System/Ability System/Gameplay Effects/Modifiers. These particular modifiers are used to initialise the Health and Mana attributes to the same value as that of the Max Health and Max Mana attributes, respectively.

Modifiers

The Modifiers collection defines what attributes this GE modifies, and how it modifies them.

The Attribute property defines what attributes this modifier affects. The Modifier Operator property, which can be one of Add, Multiply, or Override, determines how this modifier interacts with other modifiers on this attribute. The Modifier Magnitude property is used to calculate the magnitude of the effect, which is then multiplied by the Multiplier to give the final modification value:

Effect Magnitude = Modifier Magnitude * Multiplier

Conditional Gameplay Effects

WIP

Gameplay Effect Tags

Tags are used to describe the GE, as well as dictate how it interacts with other GEs.

Asset Tag

The Asset Tag is used to identify (usually uniquely, but not always) the GE. The intent is instead of checking if the GE is an instance of some class, we can compare asset tags to determine if any two GE are the same.

Granted Tags

These tags are added to the character while the GE is applied.

Ongoing Tag Requirements

These tags determine if the GE is active or temporarily disabled. For a GE to remain active, all tags in the Require Tags collection must be present on the character, and none of the tags in the Ignore Tags must be present.

Application Tag Requirements

These tags determine if the GE can be applied or not. Since Instant GE are never applied, these tags only affect Infinite and Durational GE. For an Infinite or Durational GE to be successfully applied, all tags in the Require Tags must be present on the character, and none of the tags in the Ignore Tags must be present.

Removal Tag Requirements

These tags determine if the GE should be removed prematurely after application. Since Instant GE are never applied, these tags only affect Infinite and Durational GE. For an Infinite or Durational GE to be removed, all tags in the Require Tags must be present on the character, and none of the tags in the Ignore Tags must be present.

Remove Gameplay Effects With Tag

Any existing GE on the character which have an Asset Tag contained in this list are prematurely removed.

Period

The period determines how often to apply a Gameplay Effect. A durational or infinite Gameplay Effect will continuously apply its Gameplay Effect at regular intervals. This can be used for things such as health regen.

Ability System

The Ability System is the most complex of the three, and ties together the Attribute System and Gameplay Tags.

The Ability System allows you to define how abilities in the game work, and how they interact with characters, characters' attributes, and each other.

Abilities, at some point of their execution, create Gameplay Effects, which are applied to a character, resulting in a change to the character's attributes.

An ability is defined by two classes, deriving from AbstractAbilityScriptableObject and AbstractAbilitySpec, respectively. It is recommended to define the AbstractAbilitySpec class inside the AbstractAbilityScriptableObject.

As the name suggests, AbstractAbilityScriptableObject is a scriptable object, so remember to annotate the class with [CreateAssetMenu] to create assets from it using the Assets menu.

Assets created from AbstractAbilityScriptableObject class defines the static data associated with an ability, such as its associated Gameplay Tags and what Gameplay Effects it applies. This data is shared amongst all characters that have this ability. The corresponding AbstractAbilitySpec defines the logic to execute, and any stateful data.

To activate an ability, an Ability Spec is created using the CreateSpec method on objects inheriting from AbstractAbilityScriptableObject. This is then granted to the character using the GrantSpec method on the AbilitySystemCharacter component.

Code Example

As an example, let's say we wanted to create a simple ability type that heals our character. We would first create a new class inheriting from AbstractAbilityScriptableObject with the required data fields, and also create an inner class that inherits from AbstractAbilitySpec. We'll call them SimpleAbilityScriptableObject and SimpleAbilitySpec, respectively. In order to heal (or damage) a character, we have to use a Gameplay Effect, so our SimpleAbilityScriptableObject needs to contain a field for specifying the Gameplay Effect as well.

    /// <summary>
    /// Simple Ability that applies a Gameplay Effect to the activating character
    /// </summary>
    [CreateAssetMenu(menuName = "Gameplay Ability System/Abilities/Simple Ability")]
    public class SimpleAbilityScriptableObject : AbstractAbilityScriptableObject
    {
        /// <summary>
        /// Gameplay Effect to apply
        /// </summary>
        public GameplayEffectScriptableObject GameplayEffect;

        /// <summary>
        /// Creates the Ability Spec, which is instantiated for each character.
        /// </summary>
        /// <param name="owner"></param>
        /// <returns></returns>
        public override AbstractAbilitySpec CreateSpec(AbilitySystemCharacter owner)
        {
            var spec = new SimpleAbilitySpec(this, owner);
            spec.Level = owner.Level;
            return spec;
        }

        /// <summary>
        /// The Ability Spec is the instantiation of the ability.  Since the Ability Spec
        /// is instantiated for each character, we can store stateful data here.
        /// </summary>
        public class SimpleAbilitySpec : AbstractAbilitySpec
        {
            public SimpleAbilitySpec(AbstractAbilityScriptableObject abilitySO, AbilitySystemCharacter owner) : base(abilitySO, owner)
            {
            }

            /// <summary>
            /// What to do when the ability is cancelled.  We don't care about there for this example.
            /// </summary>
            public override void CancelAbility() { }

            /// <summary>
            /// What happens when we activate the ability.
            /// 
            /// In this example, we apply the cost and cooldown, and then we apply the main
            /// gameplay effect
            /// </summary>
            /// <returns></returns>
            protected override IEnumerator ActivateAbility()
            {
                // Apply cost and cooldown
                var cdSpec = this.Owner.MakeOutgoingSpec(this.Ability.Cooldown);
                var costSpec = this.Owner.MakeOutgoingSpec(this.Ability.Cost);
                this.Owner.ApplyGameplayEffectSpecToSelf(cdSpec);
                this.Owner.ApplyGameplayEffectSpecToSelf(costSpec);


                // Apply primary effect
                var effectSpec = this.Owner.MakeOutgoingSpec((this.Ability as SimpleAbilityScriptableObject).GameplayEffect);
                this.Owner.ApplyGameplayEffectSpecToSelf(effectSpec);

                yield return null;
            }

            /// <summary>
            /// Checks to make sure Gameplay Tags checks are met. 
            /// 
            /// Since the target is also the character activating the ability,
            /// we can just use Owner for all of them.
            /// </summary>
            /// <returns></returns>
            public override bool CheckGameplayTags()
            {
                return AscHasAllTags(Owner, this.Ability.AbilityTags.OwnerTags.RequireTags)
                        && AscHasNoneTags(Owner, this.Ability.AbilityTags.OwnerTags.IgnoreTags)
                        && AscHasAllTags(Owner, this.Ability.AbilityTags.SourceTags.RequireTags)
                        && AscHasNoneTags(Owner, this.Ability.AbilityTags.SourceTags.IgnoreTags)
                        && AscHasAllTags(Owner, this.Ability.AbilityTags.TargetTags.RequireTags)
                        && AscHasNoneTags(Owner, this.Ability.AbilityTags.TargetTags.IgnoreTags);
            }

            /// <summary>
            /// Logic to execute before activating the ability.  We don't need to do anything here
            /// for this example.
            /// </summary>
            /// <returns></returns>

            protected override IEnumerator PreActivate()
            {
                yield return null;
            }
        }
    }

We can now create abilities that allow us to apply 3 Gameplay Effects to a single character - a Cost (which controls what resources our character must have to activate this ability), a Cooldown (which controls when the ability can be activated), and the actual Gameplay Effect, which could be anything we want - increase our strength, decrease our agility, whatever.

To activate this ability, we need to create an asset for this ability. Because we took advantage of the [CreateAssetMenu] attribute, we just have to right click in the Project tab in Unity, and select Create | Gameplay Ability System | Abilities | Simple Ability, and fill in the required fields.

We can then create a new Component on our character, that takes in this AbstractAbilityScriptableObject-derived class, and calls CreateSpec, passing in the character's AbilitySystemCharacter component. We then grant this ability to the AbilitySystemCharacter using the GrantAbility method.

When we want to activate this ability, we call this component's ActivateAbility method.

public class AbilityController : MonoBehaviour
{
    [SerializeField] private AbstractAbilityScriptableObject Ability;

    [SerializeField] AbilitySystemCharacter abilitySystemCharacter;

    private AbstractAbilitySpec abilitySpec;

    void Start() 
    {
      abilitySpec = Ability.CreateSpec(abilitySystemCharacter);
      abilitySystemCharacter.GrantAbility(spec);
    }

    public void ActivateAbility() 
    {
      StartCoroutine(abilitySpec.TryActivateAbility());
    }
}

And that's it! A really simple ability, where all the data associated with the ability is now set through the inspector. Go ahead and uninstall your code editor.

Contributing

You can contribute to this project by:

Posting issues
Creating PRs with bug fixes or new features
Testing this in your own games and providing feedback
Adding to the Wiki
Helping with documentation
Telling your friends!

License

Gameplay Ability System for Unity is release under the MIT license. You are free to use, modify, and distribute this software, as long as the copyright header is left intact.

Thank You

Thanks to @tranek for providing a comprehensive overview of the functionality of Unreal's Gameplay Ability System (https://github.com/tranek/GASDocumentation). This resource is used heavily in understanding how Unreal's Gameplay Ability System works, so it can be recreated for Unity.

sjai013/unity-gameplay-ability-system

sjai013

Reviews

Repository Details