1
// ===== 声明（通常在类的顶部，函数体外）=====
2
DECLARE_DELEGATE(FMySimpleDelegate);                              // 无参数
3
DECLARE_DELEGATE_OneParam(FMyDelegate, int32);                    // 1 个参数
4
DECLARE_DELEGATE_TwoParams(FMyDelegate, int32, FString);          // 2 个参数
5
DECLARE_DELEGATE_RetVal(bool, FMyDelegate);                      // 返回值 + 无参数
6
DECLARE_DELEGATE_RetVal_OneParam(bool, FMyDelegate, int32);     // 返回值 + 1 个参数
7
//                        ↑ 返回值类型在最前面；带参数必须加 _OneParam/_TwoParams 后缀
8

9
// ===== 绑定 =====
10
class AMyActor : public AActor
11
{
12
    FMyDelegate OnSomethingHappened;
13

14
    void SetupDelegates()
15
    {
16
        // 绑定到 UObject 的成员函数（最常用）
17
        OnSomethingHappened.BindUObject(this, &AMyActor::MyHandler);
18

19
        // 绑定到 Lambda
20
        OnSomethingHappened.BindLambda([this](int32 Val) {
21
            UE_LOG(LogTemp, Log, TEXT("Lambda got: %d"), Val);
22
        });
23

24
        // 绑定到静态/全局函数
25
        OnSomethingHappened.BindStatic(&GlobalHandler);
26

27
        // 绑定到非 UObject 的 C++ 对象（通过 TSharedPtr 保证生命周期）
28
        TSharedPtr<FMyAlgorithm> Algo = MakeShared<FMyAlgorithm>();
29
        OnSomethingHappened.BindSP(Algo, &FMyAlgorithm::Process);
30
        //   ↑ BindSP = BindSharedPtr，委托持有 TSharedPtr 防止对象提前析构
31

32
        // 绑定到裸指针（危险：不保证生命周期！）
33
        FMyAlgorithm* RawAlgo = new FMyAlgorithm();
34
        OnSomethingHappened.BindRaw(RawAlgo, &FMyAlgorithm::Process);
35
        //   ↑ 如果 RawAlgo 在委托调用前被 delete → 崩溃！
36
        //     只用在你完全掌控生命周期、且委托生命周期短于被绑定对象的场景
37
    }
38

39
    void MyHandler(int32 Value)
40
    {
41
        // 处理事件
42
    }
43
};
44

45
// ===== 执行 =====
46
// 先检查是否已绑定，再执行
47
OnSomethingHappened.ExecuteIfBound(42);
48

49
// 不检查直接执行（未绑定时断言崩溃）
50
OnSomethingHappened.Execute(42);
51

52
// 检查是否已绑定
53
if (OnSomethingHappened.IsBound())
54
{
55
    OnSomethingHappened.Execute(42);
56
}
57

58
// 解绑
59
OnSomethingHappened.Unbind();

1
// ===== 声明 =====
2
DECLARE_MULTICAST_DELEGATE(FMyEvent);                                 // 无参
3
DECLARE_MULTICAST_DELEGATE_OneParam(FMyEvent, int32);                 // 1 参
4
DECLARE_MULTICAST_DELEGATE_TwoParams(FMyEvent, int32, FString);       // 2 参
5
// 注意：多播委托 不能有返回值！广播到 N 个监听者，返回哪一个？
6

7
// ===== 使用 =====
8
class UMyComponent : public UActorComponent
9
{
10
public:
11
    // 事件声明
12
    FMyEvent OnDamage;
13

14
    void TakeDamage(int32 Amount)
15
    {
16
        // Broadcast 向所有绑定的监听者广播
17
        // 等价于：遍历所有绑定 → 逐个调用
18
        OnDamage.Broadcast(Amount);
19
    }
20
};
21

22
// 绑定：
23
class UMyComponent : public UActorComponent
24
{
25
public:
26
    FMyEvent OnDamage;
27

28
    // 缓存 Handle 以便后续精确移除
29
    FDelegateHandle DamageHandle;
30

31
    void Initialize()
32
    {
33
        // AddUObject 返回 FDelegateHandle——缓存它！
34
        DamageHandle = OnDamage.AddUObject(this, &UMyComponent::HandleDamage);
35

36
        // AddLambda 也返回 FDelegateHandle
37
        FDelegateHandle LambdaHandle = OnDamage.AddLambda([](int32 Amount) {
38
            UE_LOG(LogTemp, Log, TEXT("Damage: %d"), Amount);
39
        });
40
    }
41

42
    void HandleDamage(int32 Amount) { /* ... */ }
43
};
44

45
// 移除：
46
void UMyComponent::Cleanup()
47
{
48
    // 精准移除单个绑定（通过 Handle）
49
    OnDamage.Remove(DamageHandle);
50

51
    // 或移除该对象的所有绑定（最常用）
52
    OnDamage.RemoveAll(this);
53
}
54

55
// ⚠️ 重要：只有动态多播委托（DYNAMIC_MULTICAST）才支持
56
// Remove(this, TEXT("FunctionName")) 这种按函数名字符串移除的语法（内部走反射查找）。
57
// 普通多播委托也有 Remove(FDelegateHandle)，但不是走字符串反射——必须持有 Handle。
58
// 最常用的批量清理：RemoveAll(this) —— 普通多播和动态多播都支持。

1
// 多播委托的 Broadcast 按 Add 的顺序同步调用每一个监听者
2
// 意味着：如果监听者 B 在回调中修改了监听者 A 已读取的数据 → 顺序依赖 bug
3

4
DECLARE_MULTICAST_DELEGATE(FOnTick);
5

6
FOnTick OnTick;
7

8
// A 先绑定
9
OnTick.AddLambda([]() {
10
    // A: 读取 SharedData → 期望读到旧值
11
});
12

13
// B 后绑定
14
OnTick.AddLambda([]() {
15
    // B: 修改 SharedData → A 读到的其实是 B 修改后的值？
16
    // 实际上 A 先执行，B 后执行。所以 A 读到旧值，没问题。
17
    // 但如果 B 通过其他途径先于 A 影响了 SharedData → 隐蔽的 bug
18
});
19

20
// 结论：如果需要严格的回调顺序控制，不要依赖多播委托的 Add 顺序
21
// 改用显式的函数调用链或分阶段的多组委托

1
// ===== 动态单播 =====
2
DECLARE_DYNAMIC_DELEGATE(FMyDynamicDelegate);                       // 无参
3
DECLARE_DYNAMIC_DELEGATE_OneParam(FMyDynamicDelegate, int32, Value);
4
//    委托类型名                   参数类型   参数名（蓝图中的显示名）
5

6
// ===== 动态多播 —— 最常用的蓝图事件类型 =====
7
DECLARE_DYNAMIC_MULTICAST_DELEGATE(FMyEvent);
8
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FMyDamageEvent, AActor*, DamagedActor, float, Damage);
9
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FMyEvent, int32, A, FString, B);
10

11
// ===== 使用 =====
12
UCLASS(BlueprintType)
13
class AMyCharacter : public ACharacter
14
{
15
    GENERATED_BODY()
16

17
public:
18
    // BlueprintAssignable → 蓝图中可以绑定到此事件
19
    UPROPERTY(BlueprintAssignable, Category = "Events")
20
    FMyDamageEvent OnDamaged;
21

22
    void TakeDamage(AActor* Instigator, float Amount)
23
    {
24
        Health -= Amount;
25
        // 广播——所有绑定的蓝图和 C++ 都会收到通知
26
        OnDamaged.Broadcast(this, Amount);
27
    }
28
};
29

30
// 蓝图中的操作：
31
// 1. 在 Event Graph 中拖入 AMyCharacter 的 OnDamaged 节点
32
// 2. 选择 "Bind Event to OnDamaged"
33
// 3. 连接自定义逻辑 → 当 C++ 中 TakeDamage 调用 Broadcast 时触发

1
// 动态委托的简化内部结构（概念）：
2
struct FDynamicDelegate
3
{
4
    TWeakObjectPtr<UObject> Object;   // ① 对象的弱引用（存储 GUObjectArray 索引）
5
    FName FunctionName;                // ② 函数的字符串标识（FName）
6
};
7

8
// 执行流程：
9
// 1. 检查 Object 是否有效（弱引用 + Garbage 标记）
10
// 2. 通过反射在 Object 上查找 FunctionName 对应的 UFunction
11
// 3. 调用 UObject::ProcessEvent(UFunction*, Params)
12
//    → ProcessEvent 是蓝图虚拟机的入口（参见 Ch2 2.8.2）
13
//    → 将参数压入 VM 栈帧，执行字节码或桥接到 C++
14

15
// 这解释了动态委托的全部特性：
16
// ✓ 可序列化     → FName + TWeakObjectPtr 都是可序列化的基本类型
17
// ✓ 蓝图可绑定   → 通过 FName 查找 UFunction，不依赖 C++ 函数指针
18
// ✓ 对象安全     → TWeakObjectPtr 架构，即使 GC Sweep 释放内存也能安全检测
19
//                   （比常规委托 BindUObject 的裸指针 + Garbage 标记检查更彻底）
20
// ✗ 性能较慢     → 每次执行都要走反射 + ProcessEvent（而非直接函数调用）
21
// ✗ 不支持 Payload → 参数走 VM 栈，没有空间夹带额外数据

1
DECLARE_DELEGATE_OneParam(FMyDelegate, int32);
2
FMyDelegate Delegate;
3

4
// 1. BindUObject —— 绑定到 UObject 成员函数（★ GC 安全）
5
//    底层机制：内部使用 FWeakObjectPtr（弱引用）追踪 UObject 生命周期。
6
//    执行 ExecuteIfBound 时，委托内部通过 FWeakObjectPtr::Get() 检查对象有效性。
7
//    → 对象被标记为 Garbage（PendingKill 已废弃）：弱引用检测到 → IsBound() 返回 false
8
//    → 对象被 GC Sweep 彻底释放：弱引用自动失效 → Get() 返回 nullptr → 安全跳过
9
//    ★ 结论：BindUObject 在 GC 全生命周期都是安全的——不会野指针闪退
10
//
11
//    ⚠️ 唯一的例外：BindRaw —— 绑定非 UObject 的 C++ 对象（裸指针无弱引用保护）
12
//    对象销毁后裸指针变野指针 → ExecuteIfBound() 时 Access Violation 闪退！
13
//    BindRaw 的正确使用前提：调用方必须保证被绑定对象在委托执行时仍然存活。
14
//    正确用法：在对象析构前主动 Unbind() 或 RemoveAll(this)；
15
//    需要跨越 GC 清扫周期的绝对安全 → 使用动态委托（存 TWeakObjectPtr 架构）
16
Delegate.BindUObject(MyActor, &AMyActor::Handler);
17

18
// 2. BindSP —— 绑定到 TSharedPtr 管理的对象
19
//    生命周期：Strong——委托持有一个 TSharedPtr，保证对象不会提前析构
20
TSharedPtr<FMyAlgo> Algo = MakeShared<FMyAlgo>();
21
Delegate.BindSP(Algo, &FMyAlgo::Process);
22

23
// 3. BindLambda —— 绑定 Lambda
24
//    生命周期：随 Lambda 捕获的变量而定
25
Delegate.BindLambda([this](int32 Val) { /* ... */ });
26

27
// 4. BindStatic —— 绑定到静态/全局函数
28
//    生命周期：永远有效（静态函数不在对象上）
29
Delegate.BindStatic(&MyGlobalFunction);
30

31
// 5. BindRaw —— 绑定到裸 C++ 指针
32
//    生命周期：无保护——你全权负责保证被绑定对象的生命周期
33
//    ⚠️ 最容易出问题的绑定方式
34
FMyAlgo* Raw = new FMyAlgo();
35
Delegate.BindRaw(Raw, &FMyAlgo::Process);

1
// ⚠️ 场景 1：BindUObject + 对象被 GC 标记为垃圾 → 暂时安全
2
UCLASS()
3
class UMyComponent : public UActorComponent
4
{
5
public:
6
    void BindCallback(AActor* SomeActor)
7
    {
8
        OnEvent.BindUObject(SomeActor, &AActor::TakeDamage);
9
        // ★ BindUObject 内部使用 FWeakObjectPtr 追踪 SomeActor：
10
        // SomeActor 被 Destroy() → 标记为 Garbage → 弱引用检测到 → IsBound() 返回 false
11
        // SomeActor 被 GC Sweep 彻底释放 → 弱引用自动失效 → Get() 返回 nullptr → 安全跳过
12
        // 结论：BindUObject 跨越 GC 全生命周期绝对安全——无需 Unbind！
13
        //
14
        // ⚠️ 真正的危险：BindRaw（绑定非 UObject 的裸 C++ 指针——无弱引用保护）
15
        // 对象销毁后裸指针变野指针 → ExecuteIfBound() 时 Access Violation 闪退
16
        // BindRaw 必须在对象销毁前手动 Unbind()
17
    }
18
};
19
// BindUObject = FWeakObjectPtr 架构 → GC 全生命周期安全
20
// BindRaw = 裸指针，无 GC 保护 → 对象销毁前必须 Unbind()
21

22
// ✗ 场景 2：BindRaw + 对象析构 → 必定崩溃
23
FMyAlgo* Algo = new FMyAlgo();
24
Delegate.BindRaw(Algo, &FMyAlgo::Process);
25
delete Algo;              // ← 委托不知道 Algo 已经没了（裸指针，无追踪机制）
26
Delegate.ExecuteIfBound(42);  // ← 崩溃！无任何安全防护
27

28
// 解决：用 BindSP 替代 BindRaw，让 TSharedPtr 管理生命周期
29

30
// 场景 3：Lambda 捕获 this + Actor Destroy → 崩溃（和 Ch3 的异步陷阱一样）
31
void UMyComponent::SetupTimer()
32
{
33
    GetWorld()->GetTimerManager().SetTimer(TimerHandle,
34
        [this]() {  // ← this 可能在定时器触发前被 Destroy
35
            DoSomething();
36
        }, 1.0f, false);
37
}
38
// 解决：用 TWeakObjectPtr 捕获 + IsValid() 检查（参见 Ch3 3.9.3）

1
// 需要澄清一个常见误解：UE 委托并非"没有虚函数调用"。
2
// 它的底层同样使用了多态——IDelegateInstance 接口 + 各子类（如
3
// TBaseUObjectMethodDelegateInstance）——因此依然存在 vtable 间接寻址。
4

5
// UE 委托真正胜出的原因是 内联分配器（Inline Allocator）的疯狂优化：
6

7
// UE 委托内部预留了一块连续的栈空间缓冲区（TAlignedBytes）：
8
DECLARE_DELEGATE_OneParam(FMyDelegate, int32);
9
FMyDelegate D;
10
D.BindLambda([x, y, z](int32 Val) { /* 捕获了 3 个变量 */ });
11
// ↑ 如果 Lambda 捕获的数据 + Payload 小于预设的内部缓冲区阈值，
12
//   委托 完全不会触发堆分配！零 Malloc！
13
//   而对于 std::function，捕获超过小对象优化（SOO）阈值时，
14
//   大概率会触发一次全局堆分配。
15

16
// 性能差异总结：
17
// - UE 委托：内联分配器 → 小回调零堆分配 → 缓存友好
18
// - std::function：类型擦除 + 可能堆分配 → 更不可预测的开销
19
// 对于每帧高频创建/销毁委托的场景（如 UI 事件绑定），差异显著
20

21
// 此外，UE 委托是编译期强类型的——不像 std::function 需要运行时
22
// 类型擦除带来的额外间接层，这也是性能优势的一部分。