언리얼 델리게이트 완전정복 (Single, Multicast, Dynamic, Event, Params)

Unreal Engine에서 Delegate는 함수 포인터보다 진보된 이벤트 전달 시스템입니다. 블루프린트와의 연동, 여러 함수 동시 바인딩, 동적 언바인딩, 안전한 메모리 관리까지 지원합니다. 특히 DECLARE_DELEGATE, DECLARE_DYNAMIC_DELEGATE, DECLARE_EVENT, DECLARE_MULTICAST_DELEGATE, DECLARE_DELEGATE_OneParam 등 다양한 형태가 존재하며 목적에 맞게 사용해야 합니다. 이 글은 언리얼 Delegate의 모든 종류와 사용 예시, 파라미터 전달법을 한번에 정리한 최신 가이드입니다.

1. Delegate의 종류 총정리

종류	설명	특징	블루프린트 연동
DECLARE_DELEGATE	단일 바인딩 Delegate	가장 기본 형태	❌
DECLARE_MULTICAST_DELEGATE	여러 함수에 이벤트 전달	Broadcast()로 전파	❌
DECLARE_DYNAMIC_DELEGATE	UFUNCTION 함수에 바인딩	리플렉션 + GC 안정성	✅
DECLARE_DYNAMIC_MULTICAST_DELEGATE	BP에서 바인딩된 함수 전파	UI/이벤트 시스템에 적합	✅
DECLARE_EVENT	Event 시스템용 Delegate	C# 스타일 이벤트	❌

2. 파라미터 전달 방식 (OneParam, TwoParams 등)

델리게이트는 파라미터를 전달하기 위해 다음과 같은 접미어 버전을 사용합니다:

선언 매크로	파라미터 수	사용 예
DECLARE_DELEGATE_OneParam(Type, Param1Type)	1개	DECLARE_DELEGATE_OneParam(FOnScoreUpdated, int32)
DECLARE_DELEGATE_TwoParams(Type, P1, P2)	2개	DECLARE_DELEGATE_TwoParams(FOnHit, int32, FVector)
DECLARE_DYNAMIC_DELEGATE_OneParam(...)	1개 + UFUNCTION 필수	Blueprint 연동
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(...)	2개 + UFUNCTION 필수	UI 시스템용

3. 사용 예제 모음

✅ Single Delegate (OneParam 예제)

// MyCharacter.h
DECLARE_DELEGATE_OneParam(FOnHealthChanged, float)

class UMyCharacter : public UObject {
public:
    FOnHealthChanged OnHealthChanged;
    void SetHealth(float NewHealth);
    void HandleHealth(float Health);
};

// MyCharacter.cpp
void UMyCharacter::SetHealth(float NewHealth) {
    OnHealthChanged.ExecuteIfBound(NewHealth);
}

void UMyCharacter::HandleHealth(float Health) {
    UE_LOG(LogTemp, Warning, TEXT("New Health: %f"), Health);
}

✅ Multicast Delegate (TwoParams 예제)

// Enemy.h
DECLARE_MULTICAST_DELEGATE_TwoParams(FOnDamageTaken, float, AActor*)

class UEnemy : public UObject {
public:
    FOnDamageTaken OnDamage;
    void TakeDamage(float Damage, AActor* Instigator);
    void LogDamage(float Damage, AActor* Source);
};

// Enemy.cpp
void UEnemy::TakeDamage(float Damage, AActor* Instigator) {
    OnDamage.Broadcast(Damage, Instigator);
}

void UEnemy::LogDamage(float Damage, AActor* Source) {
    UE_LOG(LogTemp, Warning, TEXT("Damage: %f from %s"), Damage, *Source->GetName());
}

✅ Dynamic Multicast Delegate (Blueprint + UFUNCTION)

// MyWidget.h
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnButtonPressed, FString, ButtonName);

UCLASS()
class UMyWidget : public UUserWidget {
    GENERATED_BODY()

public:
    UPROPERTY(BlueprintAssignable)
    FOnButtonPressed OnPressed;

    UFUNCTION()
    void RespondToButton(FString Name);
};

// MyWidget.cpp
void UMyWidget::RespondToButton(FString Name) {
    UE_LOG(LogTemp, Warning, TEXT("Button %s Pressed"), *Name);
}

📌 참고

• UFUNCTION()은 Blueprint 연동 시 필수
• BlueprintAssignable은 블루프린트 바인딩 가능하도록 허용

4. Event 사용 예시

// MyGameInstance.h
DECLARE_EVENT(UMyGameInstance, FOnGameOverEvent)

class UMyGameInstance : public UGameInstance {
public:
    FOnGameOverEvent& OnGameOver() { return GameOverEvent; }

private:
    FOnGameOverEvent GameOverEvent;
};

// SomeOtherClass.cpp
void SomeFunction() {
    if (UGameInstance* GI = GetGameInstance()) {
        Cast(GI)->OnGameOver().Broadcast();
    }
}

5. 결론: 델리게이트는 언리얼 로직 설계의 중추

언리얼에서 Delegate는 단순한 이벤트 전달을 넘어서 게임 구조를 느슨하게 연결하는 강력한 수단입니다. Single/Multicast/Dynamic/Event Delegate 각각의 목적을 이해하고, 파라미터 전달 및 블루프린트 연동까지 정확히 사용하는 것이 전문가 개발자로 가는 지름길입니다. 복잡한 이벤트 처리를 깔끔하게 관리하고 싶다면 Delegate를 제대로 마스터하세요!

🔗 관련 공식 문서 (Unreal Engine)

✅ 언리얼 엔진의 Delegate 및 람다 함수 (공식 문서)