공개 노트

[ 2026-06-04 ] Gameplay Tags

2026-06-04Views 15약 2분

Summary

Gameplay Tags 가이드

Unreal Engine 5 빠른 참조 가이드

1. 게임플레이 태그란?

Gameplay Tags는 언리얼 엔진에서 계층 구조로 관리되는 문자열 식별자 시스템입니다.
단순한 bool 플래그나 enum 대신 유연하고 확장 가능한 방식으로 게임 상태, 능력, 속성 등을 분류할 수 있습니다.

핵심 특징

점(.) 구분자로 계층 구조 표현: Character.State.Jumping
Blueprint와 C++ 모두에서 사용 가능
런타임 비교 비용이 낮음 (FName 기반)
프로젝트 설정 또는 .ini 파일로 중앙 관리

2. 태그 추가 방법

방법 A — 프로젝트 설정 (권장)

편집 → 프로젝트 설정 → GameplayTags
+ 버튼으로 태그 추가

방법 B — 태그 매니저

도구(Tools) → 게임플레이 태그 매니저(Gameplay Tag Manager)
새 태그 추가 클릭

방법 C — .ini 직접 편집

Config/DefaultGameplayTags.ini 파일에 직접 작성:

[/Script/GameplayTags.GameplayTagsSettings]
+GameplayTagList=(Tag="Character.State.Jumping",DevComment="점프 상태")
+GameplayTagList=(Tag="Character.State.Running",DevComment="달리기 상태")
+GameplayTagList=(Tag="Ability.Attack.Melee",DevComment="근접 공격")

팀 프로젝트에서는 .ini 방식이 Git 버전 관리에 유리합니다.

3. 태그 네이밍 규칙

계층 구조를 활용해 일관성 있게 관리하세요.

카테고리	예시 태그	설명
캐릭터 상태	`Character.State.Idle / Jumping / Dead`	캐릭터의 현재 행동 상태
능력	`Ability.Attack.Melee / Ability.Skill.Dash`	게임플레이 어빌리티 분류
버프/디버프	`Effect.Buff.Haste / Effect.Debuff.Slow`	상태 효과 식별
UI	`UI.Menu.Main / UI.HUD.Minimap`	UI 상태 및 화면 분류
팀/진영	`Team.Player / Team.Enemy`	팀 식별 태그

가능한 한 3단계 이하 계층으로 유지하면 관리가 쉽습니다.

4. Blueprint에서 사용하기

노드	설명
`Has Tag`	컨테이너에 특정 태그가 있는지 확인
`Has Any Tags`	지정 태그 중 하나라도 있으면 true
`Has All Tags`	지정 태그가 모두 있어야 true
`Add Tag`	런타임에 태그 컨테이너에 태그 추가
`Remove Tag`	런타임에 태그 컨테이너에서 태그 제거

5. C++에서 사용하기

헤더 포함

#include "GameplayTagContainer.h"

변수 선언

// 단일 태그
UPROPERTY(EditAnywhere, BlueprintReadWrite)
FGameplayTag MyTag;

// 복수 태그 컨테이너
UPROPERTY(EditAnywhere, BlueprintReadWrite)
FGameplayTagContainer MyTagContainer;

태그 요청 및 비교

// 태그 요청
FGameplayTag Tag = FGameplayTag::RequestGameplayTag(FName("Character.State.Jumping"));

// 단일 태그 확인
if (TagContainer.HasTag(Tag))
{
    // 태그 보유 중
}

// 태그 추가 / 제거
TagContainer.AddTag(Tag);
TagContainer.RemoveTag(Tag);

6. GAS (Gameplay Ability System)와의 연계

GAS 태그 속성	역할
`Ability Tags`	어빌리티 자체를 식별하는 태그
`Cancel Abilities with Tag`	이 태그를 가진 어빌리티를 자동 취소
`Block Abilities with Tag`	이 태그를 가진 어빌리티 실행 차단
`Activation Required Tags`	어빌리티 발동에 필요한 태그 조건
`Activation Blocked Tags`	존재 시 어빌리티 발동을 막는 태그

7. 실무 팁

오타 방지 — Native Gameplay Tag 사용

태그 이름에 오타가 있어도 컴파일 에러가 나지 않습니다.
C++ 전역 변수 방식을 사용하면 오타를 방지할 수 있습니다.

// 헤더에 선언
UE_DECLARE_GAMEPLAY_TAG_EXTERN(TAG_Character_State_Jumping)

// .cpp에 정의
UE_DEFINE_GAMEPLAY_TAG(TAG_Character_State_Jumping, "Character.State.Jumping")

// 사용
TagContainer.HasTag(TAG_Character_State_Jumping);