Skip to main content

Looking into Lyra - Gameplay Tags

How Gameplay Tags work and how Lyra uses them

Gameplay tags are strings like "Player.Weapon.Shotgun" represented by a FGameplayTag type:

  • they are a hierarchy of any number of parts separated by "."
  • FGameplayTag has support for comparison and matching against individual tags and collections of tags
  • gameplay tags are stored in the collection class FGameplayTagContainer which has support for searching, matching and filtering tags
  • higher parts of the hierarchy implicitly exist - meaning if you create a tag such as "Player.Weapon.Shotgun" then the tags "Player.Weapon" and "Player" are also created
  • all tags exist in one game-specific global dictionary. This facilitates mapping them to numeric types for fast comparison.

Gameplay tags can be created by:

  • creating and editing .ini files in the "GameplayTags" folder.
  • manually adding or removing them in the Project Settings menu (which will add them to the chosen .ini file)
  • building Data Table Assets
  • adding them from c++ by calling UGameplayTagsManager::Get().AddNativeGameplayTag(). The code comments for this say "This can only be called during engine initialization, the table needs to be locked down before replication"

One important thing to note is that gameplay tags exist as a global pool accessible everywhere in the project.

Viewing Tags in Project Settings:​

The project settings window shows all the tags in the project, including tags read from .ini files, tags read from data tables (likes the DT_AnimEffectTags shown), and tags created in c++:

If you mouse over a tag in the project settings you can see its source:

By clicking the drop-down arrow next to a gameplay tag you can see where it is used:

Ticking the "Show Native Packages" checkbox will show if there are references from c++ code, but not the actual code.

Tags from c++​

Lyra adds about 30 gameplay tags in the FLyraGameplayTags::AddAllTags() method like so:

AddTag(Ability_ActivateFail_IsDead, 
    "Ability.ActivateFail.IsDead", "Ability failed to activate because its owner is dead.");
AddTag(Ability_ActivateFail_Cooldown, 
	"Ability.ActivateFail.Cooldown", "Ability failed to activate because it is on cool down.");
AddTag(Ability_ActivateFail_Cost, 
	"Ability.ActivateFail.Cost", "Ability failed to activate because it did not pass the cost checks.");

Tags from .ini files​

The .ini files listed here create gameplay tags like this:

[/Script/GameplayTags.GameplayTagsList]
GameplayTagList=(Tag="Ability.ActivateFail.MagazineFull",DevComment="")
GameplayTagList=(Tag="Ability.ActivateFail.NoSpareAmmo",DevComment="")
GameplayTagList=(Tag="Event.Movement.ADS",DevComment="")
GameplayTagList=(Tag="Event.Movement.Dash",DevComment="")
...

These .ini files are used by Lyra.

  • Plugins\Gamesubtitles\Config\Tags\PluginTags.ini -- 2 gameplay tags
  • Plugins\GameFeatures\TopDownArena\Config\Tags\TopDownArenaTags.ini -- 8 gameplay tags
  • Plugins\GameFeatures\ShooterCore\Config\Tags\ShooterCoreTags.ini -- 60 gameplay tags

Tags from Data Tables​

In the project settings the property "Gameplay Tag Table List" is a list of data tables such as /Game/ContextEffects/DT_AnimEffectTags and /Game/ContextEffects/DT_SurfaceTypes. These are data tables with the GameplayTagTableRow type and have this structure:

Gameplay tag data tables can be maintained or generated by tools outside of Unreal. For example a file "fishing.csv" which has these contents:

RowName,Tag
StartToFish,AnimEffect.Fish.Start
FinishFishing,AnimEffect.Fish.End

can be imported into Unreal to create gameplay tags by clicking the Import button in the content browser. When the file changes the Reimport button in the data table editor can be used to update Unreal with the changes.

References​