AGameplayAbilityWorldReticle

좋습니다! AGameplayAbilityWorldReticle의 기본적인 역할과 사용법, 그리고 이를 Grappling Hook 능력과 함께 사용하는 방법을 조사하겠습니다.

이 클래스는 주로 타겟팅 과정에서 목표 지점을 시각적으로 표시하는 역할을 합니다.

AGameplayAbilityWorldReticle의 역할과 타겟팅 시스템에서의 사용법

AGameplayAbilityWorldReticle은 Gameplay Ability System에서 타겟팅 지점을 시각화하는 액터입니다. 능력이 활성화되어 조준을 할 때, TargetActor가 이 Reticle 액터를 스폰하여 플레이어가 겨냥한 위치나 대상 위에 표시를 해줍니다 ([UE] Gameplay Ability System -10- Targeting). 이 Reticle은 일반적인 AActor처럼 Static Mesh, Decal, Widget 등 다양한 시각적 컴포넌트를 가질 수 있으며, 현재 조준 중인 위치를 가리키는 표식(예: 바닥에 데칼 표시, 적 상단의 아이콘 등)으로 활용됩니다 ([UE] Gameplay Ability System -10- Targeting).

GameplayAbilityTargetActor와의 상호작용: TargetActor(예: AGameplayAbilityTargetActor_SingleLineTrace)는 Reticle의 **생명주기(생성부터 파괴까지)**를 관리하고, 매 틱마다 조준 결과를 이용해 Reticle의 위치와 상태를 업데이트합니다 ([UE] Gameplay Ability System -10- Targeting). 예를 들어 SingleLineTrace 타겟 액터는 매 프레임 라인 트레이스를 수행한 뒤, 맞힌 위치로 Reticle을 이동시키고 해당 위치에 유효한 타겟이 있는지 여부를 Reticle에 전달합니다 (Gameplay Ability System Course Project - Development Blog - C++ - Epic Developer Community Forums). 이것은 SetActorLocation, SetIsTargetValid 등의 함수를 통해 이루어지며, Reticle은 이를 바탕으로 자신의 표시 상태를 갱신합니다 (Gameplay Ability System Course Project - Development Blog - C++ - Epic Developer Community Forums). TargetActor가 목표 확보를 완료하거나 취소하면 Reticle도 함께 파괴되어 조준 표시가 사라지도록 관리됩니다 ([UE] Gameplay Ability System -10- Targeting).

또한 Reticle 클래스에는 블루프린트로 구현 가능한 이벤트들이 있어, TargetActor로부터 전달된 정보에 따라 Reticle의 표시를 바꾸도록 설계되어 있습니다. 예를 들어 OnValidTargetChanged는 대상 유효성(bIsTargetValid)이 바뀔 때 호출되고, OnTargetingAnActor는 대상이 액터인지 여부(bIsTargetAnActor)가 바뀔 때 호출됩니다 ([UE] Gameplay Ability System -10- Targeting). 이를 활용하면 조준 중인 지점이 유효한지에 따라 Reticle의 색상 또는 투명도를 바꾸는 등의 피드백을 구현할 수 있습니다. 이외에도 OnParametersInitialized(초기 파라미터 설정 시 호출) 이벤트와, SetReticleMaterialParamFloat/Vector 같은 동적 머티리얼 파라미터를 설정하는 이벤트도 제공되어 ([UE] Gameplay Ability System -10- Targeting), Reticle의 머티리얼 속성을 능동적으로 변경할 수 있습니다. 즉, C++이나 능력 코드에서 ReticleActor->SetReticleMaterialParamFloat(Name, Value)를 호출하면 Reticle 블루프린트의 해당 이벤트가 실행되어 머티리얼 인스턴스에 파라미터를 적용하는 식입니다.

Grappling Hook 능력에서 AGameplayAbilityWorldReticle 활용 방법

Grappling Hook과 같은 능력에서는 조준 갈고리가 닿을 지점을 플레이어에게 보여주는 용도로 World Reticle을 사용할 수 있습니다. 이를 통해 플레이어는 갈고리가 어디에 걸릴지 미리 볼 수 있어 조준을 보정하기 쉽습니다. Grappling Hook에 Reticle을 적용할 때 고려해야 할 사항과 방법은 다음과 같습니다.

• SingleLineTrace TargetActor와 Reticle 연동: Grappling Hook 능력은 보통 라인 트레이스 방식으로 갈고리 착지점을 찾습니다. WaitTargetData로 AGameplayAbilityTargetActor_SingleLineTrace를 스폰하면서 해당 TargetActor의 ReticleClass를 설정하면, 시스템이 자동으로 지정된 Reticle 액터를 생성하여 조준 지점을 표시해줍니다 ([UE] Gameplay Ability System -10- Targeting). 예를 들어 GrapplingHook 능력에서 ReticleClass를 우리가 만든 커스텀 조준점 표시 액터로 지정하면, SingleLineTrace TargetActor가 활성화되는 동안 매 틱마다 라인 트레이스 결과 (FHitResult) 위치로 Reticle을 이동시켜 줍니다. 플레이어가 조준선을 옮기면 Reticle도 실시간으로 이동하여 갈고리가 닿을 예상 지점을 가리킵니다. 목표를 확정하면 TargetActor는 해당 위치를 타겟 데이터로 능력에 전달하고, Reticle은 파괴되어 사라집니다.
• Reticle로 Grappling Hook 목표 지점 시각화: Reticle 액터 자체는 갈고리 착지 지점을 나타내는 시각 요소를 담고 있어야 합니다. 예를 들어 벽이나 지형을 향해 조준 중이라면 그 표면 위에 작은 표식이나 아이콘이 나타나 갈고리 걸릴 위치를 보여줄 수 있습니다. 이를 위해 커스텀 Reticle BP를 만들어 StaticMesh나 Decal 컴포넌트를 추가하고, 항상 플레이어 쪽을 향하는 아이콘이나 표식을 표현하게 할 수 있습니다. Reticle은 TargetActor로부터 조준 지점이 유효한 타겟인지 통보받기 때문에(SetIsTargetValid 호출), 만약 조준 위치가 너무 멀거나 갈고리를 걸 수 없는 곳이면 Reticle의 색상을 바꾸거나 아예 숨기도록 블루프린트 로직을 작성할 수 있습니다 ([UE] Gameplay Ability System -10- Targeting). 예컨대 갈고리 사정거리 밖이면 OnValidTargetChanged(false) 이벤트에서 Reticle 아이콘을 붉게 빛나게 하거나 깜빡이도록 하여 사거리에 벗어났음을 시각적으로 피드백할 수 있습니다. 반대로 적절한 표면에 조준하고 있으면 Reticle을 녹색으로 표시하거나 확연히 보이게 할 수 있겠죠. 이처럼 머티리얼 파라미터 변경 이벤트(SetReticleMaterialParam***)를 통해 Reticle 머티리얼의 색상이나 크기를 동적으로 조절하면, 사거리나 타겟 유효성에 따른 시각효과를 줄 수 있습니다 ([UE] Gameplay Ability System -10- Targeting).
• bSnapToTargetedActor 설정: AGameplayAbilityWorldReticle에는 스냅 기능이 있습니다. bSnapToTargetedActor가 true이면 조준한 대상이 액터일 때 그 액터의 중심 위치에 Reticle을 스냅시킵니다 (unreal.GameplayAbilityWorldReticle — Unreal Python 5.0 (Experimental) documentation). Grappling Hook의 경우, 일반적으로 조준한 정확한 지점에 갈고리가 걸리는 것이 중요하므로 이 옵션을 끄는 것이 낫습니다. 스냅이 켜져 있으면, 예를 들어 벽면의 한 점을 겨냥했더라도 그 벽이 하나의 StaticMesh 액터라면 Reticle이 그 액터의 원점(피벗)으로 순간 이동할 수 있습니다. 이는 플레이어 조준점과 불일치하게 되어 혼란을 줄 수 있습니다. 기본값은 false이므로 별도로 켜지 않았다면 Reticle은 정확히 트레이스가 맞은 위치에 표시됩니다 (RealtimeStyleTransferRuntime/GameplayAbilityTargetActor_Interact.cpp at 7eb843d6c2d39efb154b06665d6ffab30ed09b17 - RealtimeStyleTransferRuntime - Gitea: Git with a cup of tea). (만약 갈고리를 이동하는 캐릭터나 액터에 붙일 수 있고, 항상 그 중심에 걸리도록 의도한 경우에만 스냅을 고려해볼 수 있지만, 대부분의 경우에는 조준한 지점 그대로 걸리는 편이 일관성 있습니다.)
• bFaceOwnerFlat 설정: 이 프로퍼티는 Reticle이 플레이어를 바라보는 방식을 제어합니다. 기본값(true)일 때 Reticle은 항상 플레이어 쪽을 평면 방향으로(face flat) 바라보도록 회전합니다 (unreal.GameplayAbilityWorldReticle — Unreal Python 5.0 (Experimental) documentation). 즉, Reticle 아이콘이 언제나 카메라를 향하지만 상하로는 기울지 않게 유지됩니다. Grappling Hook 조준에서는 이 동작이 시인성을 높이는 장점이 있습니다 – 예를 들어 위아래 경사진 벽을 겨냥해도 Reticle 아이콘이 똑바로 보이도록 세워져 표시되므로, 플레이어가 어떤 각도로 보든 아이콘을 쉽게 인지할 수 있습니다. 그러나 만약 Reticle을 벽면에 붙는 데칼 형태로 만들고 싶다면, 항상 카메라를 향하는 기본 동작을 조정해야 합니다. bFaceOwnerFlat을 false로 변경하면 Reticle이 소유자 쪽을 3D로 완전히 바라보게 되지만, 그렇다고 표면에 맞춰지지는 않으므로 여전히 데칼 용도로는 부족합니다 (unreal.GameplayAbilityWorldReticle — Unreal Python 5.0 (Experimental) documentation). 표면에 밀착되는 조준점을 원한다면, Reticle의 블루프린트에서 OnValidTargetChanged나 Tick 등을 활용해 HitResult.Normal 방향으로 수동 회전시키는 방법도 있습니다. 실제로 GAS 샘플에서는 지면 범위표시용 Reticle에 표면 법선 방향으로 회전값을 설정하여 데칼이 지형에 붙도록 처리합니다 (Gameplay Ability System Course Project - Development Blog - C++ - Epic Developer Community Forums). 요약하면, Grappling Hook의 Reticle을 항상 화면을 향한 아이콘으로 쓸지, 표면에 정착하는 표시로 쓸지에 따라 bFaceOwnerFlat 설정과 추가 회전 로직을 결정하면 됩니다.
• SetReticleMaterialParamFloat/Vector 활용: 앞서 언급한 머티리얼 파라미터 함수들은 Grappling Hook의 Reticle 피드백을 풍부하게 해줄 수 있습니다. 예를 들어 갈고리 사거리에 따라 Reticle 색상을 바꾸고 싶다면, 능력 코드에서 현재 조준점까지의 거리를 계산하여 Reticle에 SetReticleMaterialParamFloat("Distance", CurrentDistance) 등을 호출할 수 있습니다. 그러면 Reticle 블루프린트의 해당 이벤트에서 머티리얼 인스턴스의 파라미터를 변경하여, 거리에 비례해 색깔이나 크기가 변하도록 만들 수 있습니다. 혹은 SetReticleMaterialParamVector로 색상 값을 직접 전달해 유효 타겟일 때는 녹색, 무효일 때는 빨간색으로 아이콘 머티리얼을 변경할 수도 있습니다. 이러한 방식으로 Grappling Hook 능력은 실시간으로 Reticle의 머티리얼 효과를 제어하여, 플레이어에게 갈고리 사용 가능 여부나 조건을 직관적으로 전달할 수 있습니다.

Grappling Hook에서 WorldReticle 활용 총정리

정리하면, Grappling Hook 능력에서는 AGameplayAbilityWorldReticle을 TargetActor와 함께 사용하여 갈고리 착지 지점을 효과적으로 표시할 수 있습니다. 이를 구현하려면:

1. Reticle 액터 서브클래스 준비: 우선 StaticMesh나 Decal, 또는 WidgetComponent 등을 이용해 표시하고 싶은 조준 UI를 담은 Reticle BP 클래스를 제작합니다 (예: 갈고리 아이콘이 포함된 Decal 액터).
2. WaitTargetData로 TargetActor 스폰: 능력에서 WaitTargetData를 사용할 때 TargetActor로 AGameplayAbilityTargetActor_SingleLineTrace를 지정하고, ReticleClass를 위에서 만든 BP로 설정합니다 ([UE] Gameplay Ability System -10- Targeting). 필요하면 StartLocation을 캐릭터의 눈이나 총구 등으로 지정하고, ShouldProduceTargetDataOnServer 설정도 게임에 맞게 조정합니다.
3. Reticle 업데이트: 능력이 실행되면 TargetActor가 스폰되어 매 틱 라인 트레이스로 갈고리 목표를 탐색하고, Reticle을 그 위치로 이동시킵니다. 이때 bSnapToTargetedActor는 보통 끄고 사용하여 Reticle이 항상 실제 충돌 지점에 나타나게 합니다. Reticle이 표시되는 동안 블루프린트 이벤트들을 통해 유효 타겟 여부에 따른 시각 효과(색상 변경 등)를 줄 수 있습니다.
4. 타겟 확정 및 사용: 플레이어가 입력을 통해 목표 지점을 확정하면 (Confirm 입력 또는 Instant 모드), TargetActor는 해당 지점의 TargetData를 능력에 반환하고 Reticle을 제거합니다. 능력은 받은 위치 정보로 실제 갈고리 발사 체인을 이어갑니다 (예: 케이블 컴포넌트 생성 후 캐릭터를 당기거나, 갈고리 발사체를 날림).
5. 결과: 플레이어는 Reticle 덕분에 갈고리가 어디에 걸릴지 명확히 인지하면서 능력을 사용하게 되고, 능력 확정 시 정확한 목표 지점에 갈고리 기능을 적용할 수 있습니다. 이 전체 과정에서 AGameplayAbilityWorldReticle은 시각적 가이드로서 작동하여 Grappling Hook 능력의 사용자 경험을 향상시킵니다.

각 설정값과 함수(bSnapToTargetedActor, bFaceOwnerFlat, SetReticleMaterialParamXYZ)를 능력의 의도와 플레이 경험에 맞게 조정함으로써, Grappling Hook 능력에서 World Reticle을 효과적으로 활용할 수 있습니다. 이는 타겟ting 시스템의 장점(자동 목표 추적 및 네트워크 동기화)을 살리면서도 직관적인 UI 피드백을 제공하는 방법입니다 (unreal.GameplayAbilityWorldReticle — Unreal Python 5.0 (Experimental) documentation) (unreal.GameplayAbilityWorldReticle — Unreal Python 5.0 (Experimental) documentation). 즉, Gameplay Ability System의 Reticle 기능을 사용해 갈고리 목표 지점을 실시간으로 표시 및 조정함으로써, 플레이어에게 정확한 정보를 주고 능력의 신뢰성을 높일 수 있습니다.

참고 자료: Unreal 공식 문서 및 GAS 예제 코드에서는 TargetActor와 WorldReticle의 활용법을 확인할 수 있습니다 (RealtimeStyleTransferRuntime/GameplayAbilityTargetActor_Interact.cpp at 7eb843d6c2d39efb154b06665d6ffab30ed09b17 - RealtimeStyleTransferRuntime - Gitea: Git with a cup of tea) ([UE] Gameplay Ability System -10- Targeting). 특히 GAS Shooter 샘플에서는 Reticle을 이용해 적을 조준/락온하는 예제를 보여주며, Devin Sherry의 GAS 코스 프로젝트 등에서도 커스텀 Reticle의 활용을 다루고 있으므로 참고하면 도움이 됩니다 ([UE] Gameplay Ability System -10- Targeting) (Gameplay Ability System Course Project - Development Blog - C++ - Epic Developer Community Forums).