GameplayMessageRouter Plugin 1

GameplayMessageSubsystem

GameplayMessageSubsystem은 Unreal Engine에서 제공하는 GameplayTag 기반 메시지 전달 시스템이다.
특정 GameplayTag 채널에 메시지를 발행하고, 해당 채널을 구독한 객체들이 메시지를 받는 구조다.

송신자와 수신자가 서로를 직접 몰라도 구독해 두면
메시지를 받아 Payload를 쓸 수 있다.

Sender
 └─ BroadcastMessage(ChannelTag, Payload)

GameplayMessageSubsystem
 └─ ChannelTag를 기준으로 Listener 검색

Receiver
 └─ RegisterListener(ChannelTag, Callback)

서로 직접 참조하지 않는 객체들이 같은 GameplayTag 채널을 기준으로
USTRUCT인 Payload를 주고받는 메시지 라우터다.

사용 방식

메시지 발행

UGameplayMessageSubsystem::Get(this).BroadcastMessage(
    TAG_Game_EnemyKilled,
    MessagePayload
);

메시지 수신 등록

ListenerHandle = UGameplayMessageSubsystem::Get(this).RegisterListener(
    TAG_Game_EnemyKilled,
    this,
    &ThisClass::OnEnemyKilledMessage
);

콜백 함수

void ThisClass::OnEnemyKilledMessage(
    FGameplayTag Channel,
    const FEnemyKilledMessage& Message
)
{
    // 처리
}

Payload

메시지와 함께 전달되는 데이터 구조체
단순 값뿐만 아니라 UObject, AActor, UActorComponent 같은 객체 참조도 담을 수 있다.

Payload로 쓰이는 데이터 구조체 예시

USTRUCT(BlueprintType)
struct FLyraVerbMessage
{
    GENERATED_BODY()

    UPROPERTY(BlueprintReadWrite, Category=Gameplay)
    FGameplayTag Verb;

    UPROPERTY(BlueprintReadWrite, Category=Gameplay)
    TObjectPtr<UObject> Instigator = nullptr;

    UPROPERTY(BlueprintReadWrite, Category=Gameplay)
    TObjectPtr<UObject> Target = nullptr;

    UPROPERTY(BlueprintReadWrite, Category=Gameplay)
    FGameplayTagContainer InstigatorTags;

    UPROPERTY(BlueprintReadWrite, Category=Gameplay)
    FGameplayTagContainer TargetTags;

    UPROPERTY(BlueprintReadWrite, Category=Gameplay)
    FGameplayTagContainer ContextTags;

    UPROPERTY(BlueprintReadWrite, Category=Gameplay)
    double Magnitude = 1.0;

    // Returns a debug string representation of this message
    LYRAGAME_API FString ToString() const;
};

Delegate와 GameplayMessageSubsystem

Delegate

Delegate는 특정 객체가 가진 이벤트에 다른 객체가 직접 바인딩하는 구조다.

HealthComponent->OnHealthChanged.AddDynamic(
    this,
    &ThisClass::OnHealthChanged
);

호출은 보통 이렇게 한다.

OnHealthChanged.Broadcast(OldHealth, NewHealth);

구조적으로는 다음과 같다.

HealthComponent
 └─ OnHealthChanged Delegate
      └─ UI / Actor / Component가 직접 바인딩

이벤트의 소유자가 명확하다.

GameplayMessageSubsystem

GameplayMessageSubsystem은 특정 객체의 이벤트에 직접 붙는 것이 아니라, GameplayTag 채널을 기준으로 메시지를 주고받는 구조다.

UGameplayMessageSubsystem::Get(this).BroadcastMessage(
    TAG_UI_Notification,
    NotificationMessage
);

수신자는 해당 태그 채널을 구독한다.

RegisterListener(
    TAG_UI_Notification,
    this,
    &ThisClass::OnNotificationMessage
);

구조적으로는 다음과 같다.

Sender
 └─ TAG_UI_Notification 채널로 메시지 발행

GameplayMessageSubsystem
 └─ 해당 채널을 듣는 Listener들에게 전달

Receiver
 └─ 메시지 수신 후 처리

항목	Delegate	GameplayMessageSubsystem
연결 방식	객체 직접 참조	GameplayTag 채널 기반
이벤트 소유자	명확함	느슨함
송신자/수신자 관계	서로를 아는 경우가 많음	서로 몰라도 됨
데이터 전달	함수 파라미터	Payload 구조체
타입 안정성	강함	Payload 타입 + 채널 관리 필요
사용 범위	객체 내부/로컬 이벤트	시스템 간 전역 이벤트
디버깅	비교적 쉬움	메시지 흐름 추적 필요
결합도	높을 수 있음	낮음
대표 용도	HP 변경, 탄약 변경, 버튼 클릭	처치 알림, 퀘스트 진행, UI Notification

Delegate 특화 구조

이벤트의 소유자가 명확한 경우에 적합하다.

HealthComponent의 HP 변경
WeaponComponent의 탄약 변경
InventoryComponent의 슬롯 변경
InteractionComponent의 포커스 대상 변경
Widget의 버튼 클릭
Enemy의 사망 이벤트
Projectile의 충돌 이벤트
WagonPart의 내구도 변경

GameplayMessagaeSubsystem 특화 구조

신자와 수신자가 서로 몰라야 하거나, 여러 시스템이 같은 사건에 관심을 가질 때 적합

적이 처치되었다
아이템을 획득했다
퀘스트 목표가 진행되었다
UI 알림을 띄워야 한다
점수가 증가했다
게임 규칙 이벤트가 발생했다
GameFeature Plugin이 관심 가질 수 있는 사건이 발생했다
플레이어가 특정 Gameplay Event를 발생시켰다

EnemySystem
 └─ EnemyKilled 메시지 발행

GameplayMessageSubsystem
 └─ TAG_Game_EnemyKilled 채널로 전달

UI
 └─ 킬로그 표시

QuestSystem
 └─ 처치 퀘스트 진행

ScoreSystem
 └─ 점수 증가

AudioSystem
 └─ 처치 사운드 재생

---

정리

Component / Actor 내부 이벤트
→ Delegate

여러 시스템이 반응해야 하는 게임 사건
→ GameplayMessageSubsystem