[Unreal Engine] Delegate

개요

이번 포스팅에서는 언리얼 엔진에서의 이벤트를 처리하기 위한 기능 중 하나인 델리게이트(Delegate)에 대해 정리해보도록 하겠습니다.

---

Delegate란?

델리게이트(Delegate)는 C++의 함수 포인터처럼 특정 함수를 등록해 호출할 수 있는 일종의 콜백 메커니즘입니다. 언리얼 엔진에서는 게임 이벤트를 처리하기 위해 델리게이트를 주로 사용합니다.

 

언리얼의 델리게이트는 C++의 델리게이트와 유사하면서도, 언리얼의 리플렉션 시스템과 결합되어 블루프린트에서 호출할 수도 있기에 코드와 비주얼 스크립트를 쉽게 연동할 수 있습니다.

 

델리게이트의 선언은 제공되어 있는 선언 매크로 중 하나를 사용하여 이루어집니다. 사용되는 매크로는 델리게이트에 바인딩되는 함수의 시그너처에 따라 결정됩니다. 

 

아래의 표에서 델리게이트 선언에 사용할 매크로를 찾을 수 있습니다.

 

델리게이트 시스템은 특정 유형의 오브젝트를 이해하고 있으며, 이러한 오브젝트를 사용할 때는 추가적으로 사용할 수 있는 기능이 있습니다. UObject 나 공유 포인터 클래스 멤버에 델리게이트를 바인딩하는 경우, 델리게이트 시스템은 그 오브젝트에 대한 약한 레퍼런스를 유지할 수 있어, 델리게이트 치하에서 오브젝트가 소멸된 경 IsBound() 나 ExecuteIfBound() 함수를 호출하여 처리해 줄 수 있습니다.

 

델리게이트에 바인딩된 함수는 델리게이트의 Execute() 함수를 호출하여 실행됩니다. 델리게이트를 실행하기 전 "바인딩" 되었는지 반드시 확인해야 합니다. 이는 코드 안전성을 도모하기 위함인데, 초기화되지 않은 상태로 접근이 가능한 반환값과 출력 파라미터가 델리게이트에 있을 수 있기 때문입니다.

 

델리게이트가 실행해도 안전한 지는 IsBound() 를 호출하여 검사해 볼 수 있습니다. 또한 반환값이 없는 델리게이트에 대해서는 ExecuteIfBound() 를 호출할 수 있으나, 출력 파라미터는 초기화되지 않을 수 있다는 점 주의하시기 바랍니다.

---

Delegate 종류

언리얼 엔진에는 여러 종류의 델리게이트가 존재합니다.

 

1. 일반 델리게이트 (Delegate)

일반 델리게이트는 특정 함수 하나만 등록할 수 있는 델리게이트입니다. 주로 간단한 이벤트를 처리할 때 사용됩니다.

// 델리게이트 정의
DECLARE_DELEGATE(FTestDelegate);

// 델리게이트 호출 예제
FTestDelegate TestDelegate;

// 함수 정의
void MyFunction() 
{
    UE_LOG(LogTemp, Warning, TEXT("MyFunction is called!"));
}

// 함수에 델리게이트 연결
TestDelegate.BindUObject(this, &Myclass::MyFunction);

// 이벤트 발생 시 연결된 함수 호출
TestDelegate.ExecuteIfBound();

 

2. 동적 델리게이트 (Dynamic Delegate)

동적 델리게이트는 리플렉션 시스템을 통해 블루프린트에서 호출할 수 있는 델리게이트입니다. 블루프린트와 C++간의 상호작용이 필요한 경우에 유용합니다.

// 동적 델리게이트 정의
DECLARE_DYNAMIC_DELEGATE(FTestDynamicDelegate);

// 함수 정의
// * 동적 델리게이트에 바인딩 되는 함수는 리플렉션 시스템에 등록하기 위해 UFUNCTION() 매크로를 추가해야 함
UFUNCTION()
void MyDynamicFunction() 
{
    UE_LOG(LogTemp, Warning, TEXT("MyDynamicFunction is called!"));
}

FTestDynamicDelegate DynamicDelegate;

// 함수 바인딩
DynamicDelegate.BindUFunction(this, FName("MyDynamicFunction"));

// 이벤트 발생 시 연결된 함수 호출
DynamicDelegate.ExecuteIfBound();

 

3. 멀티캐스트 델리게이트 (Multicast Delegate)

멀티캐스트 델리게이트는 여러 함수를 등록하여 한 번의 호출로 여러 함수가 동시에 실행되도록 합니다. 하나의 이벤트 발생 시 여러 함수를 호출하기 위해 사용됩니다.

// 멀티캐스트 델리게이트 정의
DECLARE_MULTICAST_DELEGATE(FTestMulticastDelegate);

// 멀티캐스트 델리게이트 사용 예제
FTestMulticastDelegate TestMulticastDelegate;

// 함수 정의
void FirstFunction() {
    UE_LOG(LogTemp, Warning, TEXT("FirstFunction is called!"));
}

void SecondFunction() {
    UE_LOG(LogTemp, Warning, TEXT("SecondFunction is called!"));
}

// 델리게이트에 여러 함수 바인딩
TestMulticastDelegate.AddUObject(this, &Myclass::FirstFunction);
TestMulticastDelegate.AddUObject(this, &Myclass::SecondFunction);

// 연결된 함수 전부 호출
TestMulticastDelegate.Broadcast();

 

4. 동적 멀티캐스트 델리게이트 (Dynamic Multicast Delegate)

동적 멀티캐스트 델리게이트는 멀티캐스트 델리게이트와 유사하지만, 블루프린트에서도 호출이 가능합니다.

// 동적 멀티캐스트 델리게이트 정의
DECLARE_DYNAMIC_MULTICAST_DELEGATE(FTestDynamicMulticastDelegate);

UCLASS()
class AMyActor : public AActor
{
    GENERATED_BODY()
    
public:
    // 동적 멀티캐스트 델리게이트 선언
    // * OnMyEvent는 블루프린트에서 노드로 표시됨
    UPROPERTY(BlueprintAssignable)
    FTestDynamicMulticastDelegate OnMyEvent;
    
    // 함수 호출 예제
    UFUNCTION()
    void TestFunc() {}
    
    ...
    
    // 코드에서의 함수 바인딩
    OnMyEvent.AddDynamic(this, &AMyActor::TestFunc);
    
    // 코드에서 이벤트 발생 처리
    OnMyEvent.Broadcast();
};

---

참고 자료

https://dev.epicgames.com/documentation/ko-kr/unreal-engine/delegates-and-lamba-functions-in-unreal-engine?application_version=5.3