Build a Gameplay Ability System

A guided example: create an attribute set with health and speed, author a gameplay effect that buffs speed and grants a tag, wire the gameplay cue that plays when it fires, build the ability that applies it, and validate the lot.

This walkthrough builds a working Gameplay Ability System setup from nothing: an attribute set with health and speed, a speed buff that expires on its own, the tag it grants, the cue that plays when it fires, and an ability that applies the whole thing. Every command is listed in the Gameplay Ability System reference.

Turn the plugin on first

Unreal ships GameplayAbilities disabled by default on 5.6, 5.7 and 5.8. Enable it under Edit, Plugins, Gameplay, Gameplay Abilities, then restart the editor. Every ability command refuses by name until you do. The gameplay tag commands need nothing and work in any project.

Tags come first, and the order matters

A gameplay cue binds to its tag by name, and Unreal only ever looks up a tag that already exists. Create the tags before anything that references them and the rest of the build has nothing to trip over. Tags live in ini files rather than assets, so they are shared by the whole project.

Add the tags you need

Comments are worth writing. They are what tells the next person, or the next agent, whether a tag is safe to delete.

bash

cfa add_gameplay_tag --tag Buff.ExtraSpeed --comment "Granted while the sprint buff is active"
cfa add_gameplay_tag --tag Ability.Sprint --comment "Identifies the sprint ability"

Or add a whole set at once

One round trip instead of one per tag, and it lands as a single undo step. A hundred tags this way takes under two seconds.

bash

cfa batch --json '{"steps":[
  {"command":"add_gameplay_tag","params":{"tag":"Buff.ExtraHealth"}},
  {"command":"add_gameplay_tag","params":{"tag":"Buff.Immune"}},
  {"command":"add_gameplay_tag","params":{"tag":"State.Sprinting"}}
]}'

Create the attributes

An attribute set holds the numbers your game cares about. You can create it and every attribute in one call, and they are real attributes that gameplay effects can modify and that replicate to clients.

Create the set and its attributes

Each one becomes a replicated attribute the ability system recognises. No C++ required.

bash

cfa create_attribute_set --name AS_Hero --path /Game/GAS/Attributes \
  --attributes "Health,MaxHealth,Speed,MaxSpeed"

Read them back

Confirms the engine sees them as attributes rather than ordinary variables, and shows the value each one starts at.

bash

cfa list_attributes --attribute-set /Game/GAS/Attributes/AS_Hero

Blueprint attribute sets hold values, they do not enforce rules

An attribute set built this way stores and replicates perfectly well, but Unreal does not let a Blueprint clamp a value, turn an incoming damage number into lost health, or correct a predicted value on a client. That is fine for prototyping and for server authoritative games. If you need clamping, meta attributes or client prediction, declare the attribute set in C++ and every command here still works on it.validate_attribute_set tells you which kind you have.

Build the effect

A gameplay effect is the only sanctioned way to change an attribute. It carries the numbers it changes, how long it lasts, and any behaviour beyond that, which since Unreal 5.3 lives in components.

Create the effect

Instant applies once and is gone. HasDuration expires on its own. Infinite lasts until something removes it.

bash

cfa create_gameplay_effect --name GE_Buff_ExtraSpeed --path /Game/GAS/Effects \
  --duration-policy HasDuration

Say what it changes

Name the attribute as SetName.AttributeName, or give the asset path when two sets share a name.

bash

cfa set_gameplay_effect_modifier --gameplay-effect /Game/GAS/Effects/GE_Buff_ExtraSpeed \
  --attribute "/Game/GAS/Attributes/AS_Hero.Speed" --operation Additive --magnitude 300

See what behaviour this engine offers

The list is not the same on every version, so read it rather than assuming. It also shows what is already attached.

bash

cfa list_gameplay_effect_components

Grant a tag while it is active

Add the component, then set the tags it grants. Anything can then ask whether the actor currently has Buff.ExtraSpeed.

bash

cfa add_gameplay_effect_component --gameplay-effect /Game/GAS/Effects/GE_Buff_ExtraSpeed \
  --component-class TargetTagsGameplayEffectComponent

cfa set_object_property --asset-path /Game/GAS/Effects/GE_Buff_ExtraSpeed \
  --property-path "GEComponents[0].InheritableGrantedTagsContainer.Added" \
  --value '{"GameplayTags":[{"TagName":"Buff.ExtraSpeed"}]}'

Add the cue that plays

A cue is the cosmetic half: a tag under GameplayCue. and a notify asset that answers to it. The notify is bound to its tag by name, which is why creating it is a single command rather than a create and a wire.

Create the notify

The tag is derived from the asset name, so GC_Buff_ExtraSpeed answers to GameplayCue.Buff.ExtraSpeed. The tag is created for you if it does not exist yet.

bash

cfa create_gameplay_cue_notify --name GC_Buff_ExtraSpeed --path /Game/GAS/Cues

Point the effect at it

Now applying the effect fires the cue, and the notify plays.

bash

cfa set_object_property --asset-path /Game/GAS/Effects/GE_Buff_ExtraSpeed \
  --property-path "GameplayCues[0]" \
  --value '{"GameplayCueTags":{"GameplayTags":[{"TagName":"GameplayCue.Buff.ExtraSpeed"}]}}'

Why a cue sometimes looks perfect and never plays

A notify carries two fields: the cue tag itself, and a searchable mirror of it. Unreal finds notifies through the mirror, so an asset with only the first one set looks correctly configured in the details panel and is never found at runtime. create_gameplay_cue_notify writes both and reads the mirror back, andvalidate_gameplay_cues catches any that are wrong.

Build the ability

Create the ability asset

This makes a real Gameplay Ability Blueprint, which is a different asset type from an ordinary Blueprint.

bash

cfa create_gameplay_ability --name GA_Sprint --path /Game/GAS/Abilities

Find the nodes it can use

Read the real node ids rather than guessing names, then use them in the graph build.

bash

cfa search_nodes --blueprint-path /Game/GAS/Abilities/GA_Sprint --filter "ApplyGameplayEffectToOwner"

Build the graph in one call

Activate, apply the effect, add the cue, end the ability. Spawned and wired and compiled in a single atomic build.

bash

cfa build_blueprint_graph --json '{
  "blueprint_path": "/Game/GAS/Abilities/GA_Sprint",
  "nodes": [
    {"ref":"evt","kind":"node_id","id":"<id from search_nodes>"},
    {"ref":"apply","kind":"call","class":"GameplayAbility","function":"BP_ApplyGameplayEffectToOwner"},
    {"ref":"cue","kind":"call","class":"GameplayAbility","function":"K2_AddGameplayCue"},
    {"ref":"end","kind":"call","class":"GameplayAbility","function":"K2_EndAbility"}
  ],
  "connections": [
    {"from_ref":"evt","from_pin":"then","to_ref":"apply","to_pin":"execute"},
    {"from_ref":"apply","from_pin":"then","to_ref":"cue","to_pin":"execute"},
    {"from_ref":"cue","from_pin":"then","to_ref":"end","to_pin":"execute"}
  ]
}'

Check it before the game does

Each check returns a verdict of pass, pass with warnings, or fail. The effect check runs the validation Unreal itself ships, so the wording comes from the engine.

Validate everything

Catches an effect that would do nothing when applied, a cue tag with no notify behind it, a notify pointing at a tag that no longer exists, and an attribute set with nothing in it.

bash

cfa validate_attribute_set --attribute-set /Game/GAS/Attributes/AS_Hero
cfa validate_gameplay_effect --gameplay-effect /Game/GAS/Effects/GE_Buff_ExtraSpeed
cfa validate_gameplay_cues
cfa validate_gameplay_tags

Finding things in a big project

A real project has thousands of tags, so listing them is not useful. One search covers tags, cues, attributes, attribute sets, effects, abilities and effect components, takes several terms at once, and can be pointed at a single branch instead of the whole library.

Ask for several things at once

Each term gets its own ranked shortlist. Results carry what kind of thing they are and what owns them.

bash

cfa search_gas --query "buff,protect,attack" --top 10

Search inside one branch

Everything under Buff.Archer, without listing anything else. Leave the query off entirely to just see what is in that branch.

bash

cfa search_gas --query power --under Buff --top 5
cfa search_gas --under Buff.Archer --kind tags

What undo does and does not cover

Edits inside an asset, like adding an attribute or changing an effect, undo normally. Creating an asset does not, by design, because undoing that leaves it half built. Tag writes go to an ini file rather than an asset, so undo cannot touch them either, exactly as in Unreal's own tag editor. Use remove_gameplay_tag instead.

Loading…

PreviousGrow a Tree with AI NextGenerate a Landscape with AI