EX-GAS: a Unity port of Unreal's Gameplay Ability System

Who does what, and why the author calls the effect the result

EX-GAS is described in the README as a Unity implementation of the Unreal Engine Gameplay Ability System, with some functionality implemented and more to come. The port is faithful enough that the README recommends getting a rough understanding of the Unreal version first, and it points at a Chinese-language documentation project for that.

The conceptual summary in the README is the sentence that makes the system click. Compressed to one line, the Gameplay Ability System is who does what.

Who is the AbilitySystemComponent, the instance object and the basic unit the system runs on. Do is the Ability, everything in the game that can be triggered as a behaviour or a skill. And What is the GameplayEffect, which holds the actual control over the numeric values in the game, and which the author wants you to understand as the result rather than the cause.

The reasoning behind that framing is worth following. Underneath the tag system and the abilities, the system is a manager of attribute values, and the GameplayCue is an addition on top of that, valuable as it is. The lowest level of authority over an attribute belongs to the GameplayEffect, which is why it is the result: the effect is what the system computes and applies, and the ability is the thing that triggers it.

The author also explains why he simplified the port. GAS has a high barrier to use, and he says that building the first version made him appreciate that further, so the Unity design aims to lower the entry cost, with a set of custom editors doing part of the work. Even so, he is honest that the parameter count makes the editor look bloated and that no parameter could be removed, and that in the prototype stage some functionality was still missing, which means some parameters were not even exposed yet.

The paid plugin dependency and the honest warning

The README leads with two warnings, and any evaluation has to start with them.

The first is a dependency. The project requires the Odin Inspector plugin, which is a paid product, and the author says in emphatic terms that you need to solve that yourself. The recommended version is 3.2 or later. A feedback group is offered for people who cannot find a way to resolve it.

The second is maturity. The README says EX-GAS does not have thorough testing, so there are unknown numbers of bugs and performance problems, and it advises anyone considering the plugin to think carefully. The author's own recommendation is narrower still: if you are an independent developer making RPG games in your spare time, with plenty of development time, he suggests trying it, because in practice the users become a kind of quality assurance for the project. And he states directly that the current version is not a stable one, while asking anyone who does go ahead to join the feedback group so he can fix what comes up.

That combination, a paid dependency plus an unfinished port with a self-described need for user testing, tells you what kind of project this is. It is an ambitious open source reimplementation of a famous, complicated system, offered by one developer who wants it to exist and is being candid about how far it has got.

The documentation reflects that stage as well. The API and source code documentation is marked as work in progress, the FAQ section of the contents is marked as being added to continuously, and the list of unsupported features is marked as possibly incomplete. There is also a tutorial series, a four-part walkthrough of a top-down two-dimensional bullet hell shooter covering preparation, basic logic, using EX-GAS for interaction logic and then polishing, which is the most direct evidence of how the system is meant to be used.

Installation is a git URL with a path, or a folder you copy

The install section has two steps, the paid plugin and the system itself, and for the system it offers two routes.

The first is the Unity Package Manager, where you add the git address of the repository with a path pointing at the package subfolder:

https://github.com/No78Vino/gameplay-ability-system-for-unity.git?path=Assets/GAS

A mirror is offered for users inside China, hosted on Gitee with the same path convention.

The second route is a plain git clone of the repository, after which you copy the Assets/GAS folder into your own project. The README notes that the plugin's own configuration files and generated scripts also live in that folder, so a partial copy would leave you with a broken setup.

The repository layout makes sense once you see that this is a complete Unity project rather than a bare package. There is an Assets/ directory, a Bundles/ directory, a Packages/ directory, a ProjectSettings/ directory, a Wiki/ directory and a UIElementsSchema/ directory, which is the layout the Unity editor expects and the reason the package manager path is scoped to the Assets subfolder.

After installation comes configuration, and the README is explicit that the system has a high learning curve. You set two paths in the project settings, one for the configuration assets, which cover the modifier magnitude calculations, the cues, the gameplay effects, the abilities and the component presets, and one for generated scripts, since the base configuration of tags, attributes and attribute sets all have corresponding generated code. After setting the paths for the first time you check the subdirectories so the necessary folders exist.

One button in that setup screen needs care. The script that extends the ability system component is a utility class and is generated only once, so the README says to press it only after the attribute, attribute set and ability library classes have been generated.

The tag tree is the design, and it is hard to change later

Gameplay tags are the core of the system, and the README treats their design as the first thing a developer has to get right.

A tag is a hierarchical name, a parent, a child, a grandchild, used to describe character states, events and properties, with a stun debuff as the example. The tree is organised in that form and the tags are attached to the ability system component so that the effects, cues and abilities can interact with it. The main use is to replace booleans and enums in logic checks, and the example in the README is a field on the gameplay effect called required tags, which the component must possess in full for the effect to apply.

The point of the tree is that it makes bulk operations cheap. Removing every debuff is one operation on a tag rather than an inheritance hierarchy over poisoning, slow and burning classes, and the author notes that the tag system almost replaced all of his state variables during the demo, to the point that he designed a global component for global state before deciding the demo did not need it.

The editor side is a tree view modelled on the Unreal one, where you select a node to add or remove children and drag nodes to change the parent and child relationship. The warning that follows is the important part for planning: tag categories need careful design, and designers have to plan the rough classification at the start of the project, because a large restructuring late in development will seriously affect the logic that already works.

And after every edit there is a generation step. The tag library class holds all current tags for use by code, and the generated variable names replace the dots with underscores, so a tag written as a state, buff and power up becomes a state buff power up constant. Skipping the generation step leaves the code out of sync with the editor, which is why the README puts a note after every such instruction.

An attribute only has an identity inside an attribute set

The attribute system is a two-level scheme, and the README explains the levels with a naming analogy that makes it memorable. The attribute set is the surname and the attribute is the given name, and the combination is what uniquely identifies a value.

An attribute is the core data unit, describing things like health, attack and defence. An attribute set is a collection of attributes for one category of thing. Different sets can carry the same attribute name, because a character set and a weapon set can both have health, attack and defence with entirely different meanings, and the two can belong to the same unit. Within one set the names must be unique.

The design freedom is in the sets. The README says the design of an attribute set can be relatively casual, and that most people prefer one set per unit because it is easier to manage and to classify, with different categories of unit using different sets, while a unit can in fact have several.

The author states a preference of his own here, agreeing with the single set design because it is better for programming, because the logic is simpler and more direct. That is a small design opinion from someone who has shipped the prototype, and it is the kind of thing that saves a Unity team a refactor.

The editor side follows the same pattern as the tags. There is an attribute manager whose job is simply to manage attribute names, and those names then become the options available in an attribute set. And again there is a generation step, with the note that the options for attributes inside an attribute set only change once the attribute library has been generated.

The eight step workflow, and one line that saves garbage collections

The usage flow in the README is a numbered sequence, and it is the clearest statement of how the pieces fit together.

You set the two base paths, then configure tags, then attributes, then attribute sets, then design the modifier magnitude calculations and the cues, then the gameplay effects, then the abilities, and finally, optionally, the ability system component presets. Each step in the list links to the section that explains it.

The ordering is not arbitrary, because of the code generation. Tags and attributes are the inputs to the generated libraries, the attribute sets and abilities are built on those libraries, and the component presets package the result. A developer who skips ahead will find that the options they expect in a picker are not there, because the library has not been generated.

The last piece of the workflow is a performance fix, and it is a good example of a framework documenting its own rough edges. The system pre-caches attribute set names to work around garbage collection problems caused by using the type name at runtime. The fix is to call a cache function during game initialisation, passing the mapping of attribute set types to names, and that call caches every key and value pair so that the type name lookup is avoided. If you do not call it, the README is clear that nothing breaks functionally, but you will pay extra garbage collection.

That is a small, specific, well-explained piece of engineering advice, and it is the kind of thing you only get from a framework that has been run in a real project and has written down what hurt. The same is true of the design decision behind the global component experiment, which the author tried and abandoned, and of the note that the tag library is what makes the tags usable from code at all.

Editorial conclusion

Adopt EX-GAS if you are building an ability driven RPG in Unity and want the Unreal design rather than a bespoke implementation, and you can budget the Odin Inspector licence and the debugging time that a partially finished port implies. Do not adopt it for a project on a tight schedule, because the README says the system is not comprehensively tested, warns of unknown bugs and performance problems, and says plainly that it is not yet a stable version. Before you commit, read the compatibility notes and the tutorial series, install the plugin from the git URL, and plan the tag hierarchy before you write any gameplay code, because the README warns that restructuring tags late breaks existing logic.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. No78Vino/gameplay-ability-system-for-unity on GitHub
4. README