Unreal) GameplayTags

GameplayTags란

GameplayTags는 언리얼 엔진(UE)에서 사용하는 강력한 계층적 이름표(Hierarchical Tagging) 시스템이다.

단순한 열거형(enum)이나 FName ID를 넘어, 게임 내 다양한 요소(액터, 오브젝트, 어빌리티, 이벤트 등)에 의미 있는 식별자를 부여하고, 이를 그룹화하여 체계적으로 관리하도록 돕는다.

마치 파일 시스템의 폴더 구조처럼, 점(.)을 사용하여 태그의 계층을 표현한다.

예를 들어, Character.State.Stunned 라는 태그는 ‘캐릭터’ 그룹의 ‘상태’ 하위에 있는 ‘기절’ 상태를 명확하게 나타낸다. 이러한 구조 덕분에 특정 태그 하나를 검사하는 것뿐만 아니라, 상위 카테고리에 속하는지 여부도 쉽게 확인할 수 있다. (Character.State 태그를 가지고 있는지 확인하면 Stunned, Poisoned 등 모든 상태를 한번에 감지 가능)

이러한 특징은 게임플레이 로직을 매우 유연하고 확장 가능하게 만들어주며, 특히 복잡한 상태 관리나 능력 시스템(GAS), 이벤트 처리 등에서 핵심적인 역할을 한다.

GameplayTags의 주요 장점

• 가독성 및 명확성: Character.Ability.Fireball 처럼 태그 이름 자체만으로도 그 의미를 명확하게 파악할 수 있다.
• 계층적 구조: 태그들을 논리적인 그룹으로 묶어 관리하므로, 관련 태그들을 한 번에 확인하거나 필터링하기 용이하다.
• 유연성과 확장성: 새로운 태그를 추가하거나 기존 태그를 수정하는 것이 매우 간편하다. 코드를 다시 컴파일할 필요 없이 에디터에서 새로운 태그를 추가하고 로직에 바로 활용할 수 있다.
• 중앙 집중 관리: 모든 게임플레이 태그는 GameplayTagManager를 통해 중앙에서 관리된다. 이를 통해 태그의 중복 생성을 방지하고 일관성을 유지할 수 있다.
• 성능: 내부적으로 FName을 기반으로 동작하므로, 문자열 비교보다 훨씬 빠른 성능을 보인다.

C++을 이용한 Native GameplayTags 정의 및 사용

게임의 핵심적이거나 자주 사용되는 태그들은 C++ 코드를 통해 ‘네이티브 태그(Native Tags)’로 미리 정의해두는 것이 좋다.

이는 오타를 방지하고, 코드 내에서 명시적으로 태그를 참조할 수 있게 하여 안정성을 높인다.

태그 선언 (.h 파일)

헤더 파일에서는 UE_DECLARE_GAMEPLAY_TAG_EXTERN 매크로를 사용하여 앞으로 사용할 게임플레이 태그가 외부에 존재함을 선언한다.

이는 다른 파일에서 이 태그를 인식하고 사용할 수 있도록 해준다.

#pragma once

#include "NativeGameplayTags.h"

namespace GameplayTags
{
    // Input.Action.Move 태그가 외부에 정의되어 있음을 선언
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Input_Action_Move);

    // Input.Action.Turn 태그가 외부에 정의되어 있음을 선언
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Input_Action_Turn);
}

태그 정의 (.cpp 파일)

소스 파일에서는 UE_DEFINE_GAMEPLAY_TAG 매크로를 사용하여 헤더에서 선언한 태그의 실제 값을 정의한다.

이 값은 에디터의 GameplayTagManager에 표시될 태그의 전체 경로명이다.

#include "GameplayTags.h"

namespace GameplayTags
{
    // Input_Action_Move 변수에 "Input.Action.Move"라는 실제 태그를 정의하여 할당
    UE_DEFINE_GAMEPLAY_TAG(Input_Action_Move, "Input.Action.Move");

    // Input_Action_Turn 변수에 "Input.Action.Turn"라는 실제 태그를 정의하여 할당
    UE_DEFINE_GAMEPLAY_TAG(Input_Action_Turn, "Input.Action.Turn");
}

엔진 등록 및 확인

프로젝트 설정(Project Settings) > 프로젝트(Project) > GameplayTags 메뉴로 이동한다.

결론

GameplayTags는 단순한 식별자를 넘어, 언리얼 엔진 프로젝트의 데이터와 로직을 체계적으로 설계하고 관리하기 위한 핵심적인 프레임워크다.

특히 C++을 통해 네이티브 태그를 정의하는 방식은 프로젝트의 안정성과 유지보수성을 크게 향상시키는 모범 사례다.

제공된 이미지의 코드는 이러한 네이티브 태그를 선언하고 정의하는 표준적인 방법을 보여주며, 이를 통해 생성된 태그가 에디터에서 어떻게 관리되는지를 명확히 이해할 수 있다.

복잡한 상호작용과 상태 변화가 많은 현대 게임 개발에서 GameplayTags의 올바른 이해와 활용은 필수적이다.