GameplayTag는 Actor Tag와 다른 Tag 시스템으로 계층적 구조를 통해 기존의 단순 boolean flag 문제들을 해결하는 기능이다.
문제점 예시
스턴 기능을 구현하다고 하면, 캐릭터 BP에 bIsStunned라는 boolean 변수를 추가하고 해당 값이 true일 때 이동을 차단하는 방식으로 구현할 수 있다.
이후 속박처럼 이동을 막는 상태가 추가되면 변수를 늘리고 이동 조건도 수정해야 한다.
const bool bCanMove = !bIsStunned && !bIsRooted;
상태가 많아질수록 유지보수가 힘들어 지고 같은 스턴이 여러 번 적용되는 경우에는 각 효과의 적용과 해제를 구분할 방법도 필요하다.
해결 방향
Gameplay Tag는 .으로 구분된 계층을 가진 식별자이다. 다음과 같이 상태를 구성할 수 있다.
State
└─ MovementBlocked
├─ Stun
└─ Root
캐릭터가 State.MovementBlocked.Stun이나 State.MovementBlocked.Root를 가지고 있다면, 상위 태그인 State.MovementBlocked를 검사하는 코드로 이동 제한 여부를 판단할 수 있다.
const FGameplayTag MovementBlockedTag = FGameplayTag::RequestGameplayTag(TEXT("State.MovementBlocked"));
const bool bCanMove = !StateTags.HasTag(MovementBlockedTag);
StateTree나 Gameplay Ability System과 같은 플러그인에서 적극적으로 활용되고 있고 꼭 두 플러그인이 아니더라도 위의 예시처럼 boolean flag를 대신하여 사용할 수 있다.
태그 정의
태그를 정의하는 방법에는 에디터에서 정의하는 방법, C++로 정의 하는 방법 2가지가 있다.
1. 에디터의 경우 Project Settings > Gameplay Tags > Gameplay Tag List 에서 편집할 수 있다.
태그를 에디터에서 정의한 경우 C++ 에서 사용하려면 FGameplayTag::RequestGameplayTag(TEXT("State.MovementBlocked")); 와 같이 Text Literal로 별도로 요청을 해야한다.
2. C++에서 사용하려면 모듈의 .Build.cs에 GameplayTags 의존성을 추가해야 한다.
PublicDependencyModuleNames.AddRange(new string[] { ..., "GameplayTags" });
이후 아래와 같이 헤더와 소스 파일을 만들고 구성하면 된다.
MyTags.h
#pragma once
#include "CoreMinimal.h"
#include "NativeGameplayTags.h"
namespace MyTags
{
UE_DECLARE_GAMEPLAY_TAG_EXTERN(None);
namespace Abilities
{
UE_DECLARE_GAMEPLAY_TAG_EXTERN(ActivateOnGiven);
UE_DECLARE_GAMEPLAY_TAG_EXTERN(Primary);
namespace Enemy
{
UE_DECLARE_GAMEPLAY_TAG_EXTERN(Attack);
}
}
MyTags.cpp
#include "GameplayTags/CCTags.h"
namespace MyTags
{
namespace Abilities
{
UE_DEFINE_GAMEPLAY_TAG_COMMENT(ActivateOnGiven, "MyTags.Abilities.ActivateOnGiven", "Tag for Abilities that should activate immediately once given.")
UE_DEFINE_GAMEPLAY_TAG_COMMENT(Primary, "MyTags.Abilities.Primary", "Tag for the Primary Ability")
namespace Enemy
{
UE_DEFINE_GAMEPLAY_TAG_COMMENT(Attack, "MyTags.Abilities.Enemy.Attack", "Enemy Attack Tag")
}
}
계층적으로 namespace를 구성하는 것은 필수가 아니다.
다만 MyTagsAbilitiesEnemyAttack 보다 MyTags::Abilities::Enemy::Attack 처럼 작성할 수 있어 가독성면에서 좀 더 용이하다.
Match Tag
태그를 비교할 때 계층 구조를 고려하여 비교가 가능하다.
bool FGameplayTag::MatchesTag(const FGameplayTag& TagToCheck) const 를 통해 단일 태그 끼리 비교할 수 있다.
== 연산자를 통해 Exact Match로 계층 구조를 고려하지 않고 완벽히 동일한 태그인지 판별 가능하다.
| 태그 | 검사 태그 | 일반 매칭 | Exact Match |
|---|---|---|---|
A.B |
A |
true |
false |
A.B |
A.B |
true |
true |
A |
A.B |
false |
false |
A.B |
A.C |
false |
false |
FGameplayTagContainer
위에서 알아본 FGameplayTag는 단일 태그를 나타내며, FGameplayTagContainer는 여러 태그를 보관하는 구조체이다.
컨테이너는 같은 태그를 여러번 추가해도 한 번만 적용된다.
컨테이너 편집
| 용도 | C++ |
|---|---|
| 태그 추가 | Container.AddTag(Tag) |
| 태그 제거 | Container.RemoveTag(Tag) |
| 컨테이너 합치기 | Container.AppendTags(Other) |
쿼리
| 용도 | C++ |
|---|---|
| 태그 포함 검사 | Container.HasTag(Tag) |
| 정확한 태그 포함 검사 | Container.HasTagExact(Tag) |
| 하나라도 포함하는지 검사 | Container.HasAny(Other) |
| 전부 포함하는지 검사 | Container.HasAll(Other) |
Filter & Union
원본 컨테이너에서 조건에 맞는 태그만 골라 새 컨테이너로 반환하는 연산이다.
const FGameplayTagContainer Filtered = StateTags.Filter(FilterTags);
const FGameplayTagContainer Intersection = StateTags.FilterExact(OtherTags);
원본: { State.MovementBlocked.Stun, State.Dead }
조건: { State.MovementBlocked }
Filter 결과: { State.MovementBlocked.Stun }
FilterExact 결과: { }
GameplayTagQuery
여러 태그 조건을 AND, OR, NOT 관계로 묶어 하나의 식 (Expression) 으로 표현할 수 있는 구조체이다.
조건식을 계층적으로 구성할 수 있어 복잡한 판정을 데이터로 관리하는 데 유용하다.
FGameplayTagQueryExpression ReadyExpression;
ReadyExpression.AnyTagsMatch().AddTag(ReadyTag).AddTag(AimingTag);
FGameplayTagQueryExpression BlockedExpression;
BlockedExpression.NoTagsMatch().AddTag(DeadTag).AddTag(MovementBlockedTag);
FGameplayTagQueryExpression RootExpression;
RootExpression.AllExprMatch().AddExpr(ReadyExpression).AddExpr(BlockedExpression);
const FGameplayTagQuery Query = FGameplayTagQuery::BuildQuery(RootExpression);
const bool bCanAct = Query.Matches(StateTags);
IGameplayTagAssetInterface
IGameplayTagAssetInterface를 통해 TagContainer를 반환하는 인터페이스가 미리 만들어져있다.
오브텍트가 TagContainer를 가질 때 직접적으로 해당 오브젝트를 참조하지 않고 싶을 때 유용하다.
class IGameplayTagAssetInterface
{
virtual void GetOwnedGameplayTags(FGameplayTagContainer& TagContainer) const=0;
}
에디터에서 태그 필터링
태그가 많아지면 에디터에서 전체 태그 리스트에서 원하는 태그를 찾아 들어가는게 귀찮은 경우가 생긴다.
이 경우 Root Tag를 지정하여 해당 Tag의 하위 태그들만 나오도록 C++에서 Property나 Method의 인자에 지정이 가능하다.
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Tag Example Actor", meta = (Categories = "Frontend.WidgetStack"))
FGameplayTag WidgetStackTag;
UFUNCTION(BlueprintCallable, Category = "Tag Example Actor")
void SetWidgetStack(UPARAM(meta = (Categories = "Frontend.WidgetStack")) FGameplayTag InWidgetStackTag);
내부 구현
GameplayTag는 Property로 FName을 딱 하나만 가진다.
GameplayTagContainer는 TArray로 들어있는 태그와 해당 태그들의 부모 태그를 미리 계산해서 가진다. 덕분에 Match Tag 시 매번 부모를 계산할 필요없이 빠르게 쿼리를 계산할 수 있다.
단일 GameplayTag Match 시에도 부모 태그 계산을 위해 GameplayTagContainer로 변환 수 Match를 수행한다.