Unreal Engine GAS - Gameplay Cue

---

1. 개념과 역할

Gameplay Cue는 GAS에서 제공하는 이벤트/연출 시스템으로,
게임플레이 도중 발생하는 시각/청각 효과(이펙트, 사운드, UI 변경 등)를 관리하기 위한 분리된 구조를 갖습니다.

• 목적
  • 게임플레이의 논리(데미지 계산, 버프 적용 등)와 연출(비주얼/오디오)을 분리
  • 멀티플레이 환경에서 이펙트 실행을 일괄 통제 및 복제
  • 시스템 차원에서 커스텀 액터, 파티클, 사운드를 자유롭게 연결 가능
• 동작 방식
  • Gameplay Tag를 기준으로 Cue를 식별 (예: GameplayCue.Fire.Explosion)
  • 개발자는 ASC(AbilitySystemComponent)나 GameplayEffect를 통해 “Execute”, “Add/Remove” 등의 함수를 호출 → 내부에서 GameplayCueManager가Cue 로직 수행
  • NetMulticast로 자동 복제되어 모든 클라이언트에 동일 연출 보장

결과적으로 게임플레이 큐는 “어떤 이벤트가 발생했을 때 시각/청각적 효과(또는 부가 연출)를 재생”하는 장치이며,
GAS가 제공하는 예측(Prediction) 및 NetSync 덕분에 클라이언트-서버 간 동기화가 쉽게 이뤄집니다.

---

2. 구성 요소

2.1 GameplayCueManager

• 전역에서 Gameplay Cue를 검색·로드·실행하는 매니저 클래스
• DefaultGame.ini에서 GameplayCueNotifyPaths 설정으로 CueNotify들이 있는 폴더 지정 가능
• Cue 이벤트 발동 시 내부적으로 CueNotify(또는 IGameplayCueInterface)를 찾아 실행
• 로딩 최적화나 맞춤형 Cue 로드 로직을 위해 UGameplayCueManager를 서브클래싱하기도 함

2.2 GameplayCueNotify_Static

• 정적(Static) 타입의 Cue 노티파이. OnExecute 이벤트 중심
• 액터를 스폰하지 않고, 클래스 자체(CDO)로 즉시 효과(1회성 Impact 등) 표현
• 예) 피격 스파크, 폭발 이펙트처럼 짧고 임시적인 효과에 적합

2.3 GameplayCueNotify_Actor

• 액터(Actor) 타입의 Cue 노티파이. OnActive / WhileActive / OnRemove 이벤트 처리
• Cue가 트리거될 때 액터 인스턴스 스폰, 종료 시 제거 → 지속형(버프·오라 등) 이펙트에 사용
• 예) 버프 오라, 디버프 아이콘 등 지속 시간이 필요한 이펙트 표현
• 일반적으로 “Auto Destroy on Remove” 설정으로 OnRemove 시 액터 제거를 관리

2.4 GameplayCueParameters

• Cue 실행 시 전달되는 파라미터 구조체
• Instigator, Target, EffectContext(HitResult, InstigatorAbilitySystem, 등), 소스/타겟 태그, 위치/회전 등 다양한 정보를 포함
• C++에서 FGameplayCueParameters를 직접 생성해 호출하거나, GameplayEffect 적용 시 자동 채워짐
• 필요한 경우 SourceObject 필드 등에 임의 데이터(UObject 등)를 넣어 Cue 측에서 커스텀 처리 가능

---

3. C++에서의 사용법

3.1 Cue 트리거

• 즉발형(Execute):
• MyASC->ExecuteGameplayCue(CueTag, CueParams);
• CueTag: GameplayCue.Fire.Explosion 등
• CueParams: FGameplayCueParameters (위치, Instigator 등)
• 지속형(Add/Remove):

MyASC->AddGameplayCue(BuffTag, CueParams);    // 시작
MyASC->RemoveGameplayCue(BuffTag);           // 종료

• 서버 권한에서 호출 시 자동으로 NetMulticast되어 클라이언트에서도 동일 Cue 실행

FGameplayCueParameters Params;
Params.Location   = ExplosionLocation;
Params.Instigator = GetOwner();
// 기타 필요한 필드...
MyASC->ExecuteGameplayCue(FGameplayTag::RequestGameplayTag(FName("GameplayCue.Ability.Explosion")), Params);

• 이렇게 파라미터를 채워주면 CueNotify_BP에서 OnExecute 등에서 Location, Instigator를 받아 활용 가능

 

3.3 GameplayEffect에서 Cue 사용

• GameplayEffect 자산에 GameplayCues 추가하면 Effect 적용/제거 시 자동 실행
  • 예) Instant Effect면 OnExecute, Duration Effect면 OnActive / OnRemove 이벤트 발생
• **C++**에서 FGameplayEffectSpec을 만들고 Spec->AddGameplayCue(Tag) 호출 시에도 동일

 

4. 블루프린트에서의 사용법

4.1 Cue 트리거 노드

• “Execute GameplayCue”, “Add GameplayCue”, “Remove GameplayCue” 등 Blueprint 노드 제공
• Ability Blueprint나 ASC 참조가 있는 Any BP에서 노드 호출 → 해당 Cue 발동

4.2 GameplayEffect로 연결

• GameplayEffect 자산의 Display -> GameplayCues 항목에 Cue 태그 설정
• 블루프린트에서 “Apply GameplayEffect to Target” 노드만 써도 Cue가 자동 재생
• Duration 기반 Buff/DeBuff → OnActive(시작), OnRemove(종료) 이펙트가 자연스레 구현

4.3 GameplayCueNotify 블루프린트

• GameplayCueNotify_Static BP: OnExecute 이벤트에서 1회성(스파크, 임팩트) 구현
• GameplayCueNotify_Actor BP: OnActive/WhileActive/OnRemove로 지속형(오라, 빛줄기) 구현
• BP 내에서 파티클, 사운드, 카메라 진동 등 원하는 연출 로직 추가
• Cue 태그와 매칭: Class Settings에서 GameplayCue.Tag = GameplayCue.XXX.XXX 지정

---

5. 응용 예제

1. 상태 이펙트 (버프/디버프)
   • 버프 효과 GameplayEffect가 적용될 때 GameplayCue.Buff.* Cue 발생
   • Actor 타입 CueNotify로 오라 파티클을 OnActive에서 스폰, OnRemove에서 제거
   • 디버프도 동일하게 스턴, 슬로우 이펙트 표시 가능
2. 폭발 효과
   • 총알 충돌, 폭탄 스킬 등에서 ExecuteGameplayCue("GameplayCue.Explosion.Fire")
   • Static Cue 블루프린트로 폭발 파티클, 폭음 사운드 즉시 재생
3. 피격 반응 처리
   • 공격이 적중 → GameplayEffect가 적용되는 순간 GameplayCue.Hit.* 자동 트리거
   • 피격 스파크, 피 물튀기는 파티클, Hit Direction 등에 맞게 처리
   • 공격자/피격자 쌍 모두 CueParameters 통해 HitResult를 참조해 정교한 연출 가능
4. 그 외
   • AoE 스킬의 범위 이펙트, 체력 회복 시 이펙트(힐링 오라), 환경 상호작용(번개, 불꽃) 등
   • Lyra Starter Game 등 샘플에서도 캐릭터 움직임, 발사, 임팩트 전부 Cue로 연결

---

마무리

Gameplay Cue는 Unreal Engine GAS의 연출(Event) 시스템으로,
효과와 비주얼/사운드를 네트워크 친화적이며 구조적으로 구현할 수 있게 돕습니다.

• 핵심 요점
  1. Tag 기반으로 Cue 이벤트를 찾고, ASC → CueNotify → 모든 클라이언트 동기화
  2. Static vs Actor Notify: 한 번 실행/지속 실행을 구분하여 사용하는 구조
  3. Blueprint 노드로 쉽게 Add/Remove/Execute 가능, GameplayEffect와 연동해 자동 발동도 가능
  4. 다양한 응용(버프/디버프, 폭발, 피격 반응 등)에서 로직과 연출을 분리하고 네트워크와 예측까지 효율적으로 지원받을 수 있음

이상으로 Gameplay Cue에 대한 TIL을 마칩니다.
더 자세한 내용은 언리얼 소스(예: GAS 소스, 샘플)나 공식 문서를 참고해보면 좋습니다.