Storing state in Gameplay Tags makes it easier to store state and create interesting gameplay. At the same time it lets you create data inside the editor without the need to write extra lines of code.
Unfortunately, not many Unreal Engine developers are aware that they exist or their usefulness and end up writing unneeded code.
What are gameplay tags
Gameplay tags are “names” that can be added to actors to represent multiple things.
Ex: Character, Enemy, Interactable, Locked
They have a hierarchical form so you can group them to represent complex data, this is done using a dot between names.
Ex: StatusEffect.Burn, StatusEffect.Poison, Character, Character.NPC, Character.NPC.Enemy
How to use them in Unreal
To use gameplay tags we require that an actor implements the IGameplayTagAssetInterface and implement the four functions that come with it. We then can store the tags into a FGameplayTagContainer or a more complex structure like the UAbilitySystemComponent if we are using Unreal GAS ( Gameplay Ability System ).
The functions that we must implement from the interface are:
- GetOwnedGameplayTags
- HasMatchingGameplayTag
- HasAllMatchingGameplayTags
- HasAnyMatchingGameplayTags
Tags can be easily edited in Unreal Project Settings under the Gameplay Tags category:
Querying tags
Using the IGameplayTagAssetInterface we can ask actors multiple things. For instance we can query if they have any gameplay tag using the HasMatchingGameplayTag function.
Ex: If an actor has the gameplay tag CharacterNPC they will respond to queries for the tag Character and for the tag CharacterNPC, but not for the tag CharacterNPCEnemy.
This is useful as it gives as a generic way to ask for the state of the actor. Knowing if a door is locked is as easy as asking if it has the tag InteractableLocked, knowing if the player is invincible means simply asking if the player has the StateInvincible tag.
Reacting to state changes
We can easily register to tag changes to know when a tag has been added or removed. This way we can create behavior out of state.
For instance we could have a door that opens when a switch is in the “on” state and it will be as easy as reacting to changes on the tag SwitchStateActivated. If the tag is present we open the door, if the tag goes away we close it.
Same thing can be done for applying Status Effects to characters or reacting to Power Ups.
Recap
- A tag is a hierarchical name (Character.NPC.Enemy) you attach to an actor, and querying it respects the hierarchy: an actor tagged Character.NPC answers yes to Character and to Character.NPC, but no to Character.NPC.Enemy.
- To make an actor queryable, implement IGameplayTagAssetInterface and its four functions. Tags themselves live in Project Settings under Gameplay Tags, so designers can add new state without touching code.
- Registering for tag add and remove events is what turns tags from data into behavior: open the door while Switch.State.Activated is present, close it when the tag goes away.
What this doesn’t cover
This is the single-actor picture. It does not get into how the Ability System Component replicates its owned tags to clients, or how to build and match an FGameplayTagQuery for the more involved “has all of these but none of those” checks. Both start to matter once you move past a local prototype.
