1
// ===== MyActor.h —— 你写的 =====
2
#pragma once
3
#include "CoreMinimal.h"
4
#include "GameFramework/Actor.h"
5
#include "MyActor.generated.h"    // ← 最后一行！UHT 会生成这个文件
6

7
UCLASS(Blueprintable)             // ← UHT 从这里开始解析
8
class MYPROJECT_API AMyActor : public AActor
9
{
10
    GENERATED_BODY()              // ← 展开为生成的胶水代码
11

12
public:
13
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
14
    float Speed = 600.0f;
15

16
    UFUNCTION(BlueprintCallable)
17
    void DoSomething();
18
};

1
// ==== 旧版：GENERATED_UCLASS_BODY()（UE4 早期）====
2
UCLASS()
3
class UMyClass : public UObject
4
{
5
    GENERATED_UCLASS_BODY()  // ← 旧版宏
6

7
public:
8
    // 强制要求：必须显式声明带 const FObjectInitializer& 的构造函数
9
    UMyClass(const FObjectInitializer& ObjectInitializer);
10
};
11

12
// .cpp 中必须这样写：
13
UMyClass::UMyClass(const FObjectInitializer& ObjectInitializer)
14
    : Super(ObjectInitializer)  // ← 必须手动调用 Super()
15
{
16
}
17

18
// ==== 新版：GENERATED_BODY()（UE4 后期至今）====
19
UCLASS()
20
class UMyClass : public UObject
21
{
22
    GENERATED_BODY()  // ← 新版宏
23

24
public:
25
    // 可以直接使用无参构造函数！
26
    UMyClass();
27
    // 核心机制（不是 UHT 代码生成！）：
28
    // 1. NewObject<T>() 在调用构造函数前，将 FObjectInitializer 压入当前线程的 TLS
29
    // 2. C++ 标准规定：子类默认构造函数自动调用基类默认构造函数 UObject::UObject()
30
    // 3. UObject 的默认构造函数内部从 TLS 中"偷出" FObjectInitializer 完成初始化
31
    // 这套隐式传递完全由 C++ 构造链 + 引擎 TLS 架构协同完成，与 UHT 无关
32
};
33

34
// .cpp 中简洁了：
35
UMyClass::UMyClass()
36
{
37
    // 不需要手动调 Super(ObjectInitializer)——
38
    // 基类 UObject 的默认构造函数已通过 TLS 拿到了 FObjectInitializer
39
}

1
// 你可以通过静态方法拿到类的类型信息：
2
UClass* MyClass = AMyActor::StaticClass();  // ← 类级别的反射入口
3

4
// 也可以通过实例拿到：
5
AActor* Instance = GetOwner();
6
UClass* InstanceClass = Instance->GetClass();  // ← 实例级别的反射入口
7
// 这两个返回的是同一个 UClass 对象（全局唯一）
8
check(MyClass == InstanceClass);  // 同一个指针
9

10
// UClass 能做什么？
11
const UClass* Class = AMyActor::StaticClass();
12

13
// 1. 查询类的继承链
14
Class->IsChildOf(AActor::StaticClass());   // true
15
Class->GetSuperClass();                     // AActor::StaticClass()
16

17
// 2. 查询类的属性
18
for (TFieldIterator<FProperty> It(Class); It; ++It)
19
{
20
    FProperty* Property = *It;
21
    UE_LOG(LogTemp, Log, TEXT("Property: %s, Type: %s"),
22
           *Property->GetName(), *Property->GetCPPType());
23
    // 输出：Property: Speed, Type: float
24
}
25

26
// 3. 查询类的函数
27
for (TFieldIterator<UFunction> It(Class); It; ++It)
28
{
29
    UFunction* Function = *It;
30
    UE_LOG(LogTemp, Log, TEXT("Function: %s"), *Function->GetName());
31
    // 输出：Function: DoSomething
32
}
33

34
// 4. 查询元数据（UCLASS 括号里的那些说明符）
35
if (Class->HasMetaData(TEXT("DisplayName")))
36
{
37
    FString Name = Class->GetMetaData(TEXT("DisplayName"));
38
}
39

40
// 5. 创建实例（等价于 NewObject<T>，但是运行时动态决定类型）
41
AActor* NewInstance = NewObject<AActor>(GetTransientPackage(), Class);

1
UCLASS()
2
class UMyComponent : public UActorComponent
3
{
4
    GENERATED_BODY()
5

6
public:
7
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Config",
8
              meta = (ClampMin = 0, ClampMax = 100))
9
    int32 Health = 100;
10

11
    // 这一个宏同时实现了：
12
    // ① 反射注册       → 运行时可通过 FindPropertyByName("Health") 访问
13
    // ② GC 追踪         → 如果类型是 UObject*，GC 会追踪这个引用（此处 int 不需要）
14
    // ③ 编辑器可见性    → Details 面板自动生成编辑控件（EditAnywhere）
15
    // ④ 蓝图可读写      → 蓝图中 get/set Health（BlueprintReadWrite）
16
    // ⑤ 序列化          → 保存/加载时自动处理（SaveGame、FArchive）
17
    // ⑥ 网络复制        → 如果加了 Replicated/ReplicatedUsing，自动网络同步
18
};

1
// 运行时获取属性的元数据：
2
UClass* Class = UMyComponent::StaticClass();
3

4
// 通过名字查找属性
5
FProperty* HealthProp = Class->FindPropertyByName(TEXT("Health"));
6

7
if (HealthProp)
8
{
9
    // 读取属性值
10
    UMyComponent* Comp = /* ... */;
11
    // ContainerPtrToValuePtr 是非模板函数，返回 void*，必须强转
12
    int32* ValuePtr = (int32*)HealthProp->ContainerPtrToValuePtr(Comp);
13
    int32 Value = *ValuePtr;  // 100
14

15
    // 写入属性值
16
    *ValuePtr = 80;
17

18
    // 查询属性的元数据
19
    if (HealthProp->HasMetaData(TEXT("ClampMin")))
20
    {
21
        FString MinStr = HealthProp->GetMetaData(TEXT("ClampMin"));
22
        int32 Min = FCString::Atoi(*MinStr);  // 0
23
    }
24

25
    // 查询属性的 Flag
26
    if (HealthProp->HasAnyPropertyFlags(CPF_Edit))  // EditAnywhere
27
    {
28
        // 该属性在编辑器中可编辑
29
    }
30
    if (HealthProp->HasAnyPropertyFlags(CPF_BlueprintVisible))  // BlueprintReadWrite
31
    {
32
        // 该属性对蓝图可见
33
    }
34
}

1
UCLASS()
2
class UMyActor : public AActor
3
{
4
    GENERATED_BODY()
5

6
    // ==== 编辑器可见性 ====
7
    UPROPERTY(EditAnywhere)           // 编辑器 + 蓝图默认值面板都可编辑
8
    float EditAny = 1.0f;
9

10
    UPROPERTY(EditDefaultsOnly)       // 只在蓝图默认值面板可编辑（关卡实例不可编辑）
11
    float EditDefault = 2.0f;
12

13
    UPROPERTY(EditInstanceOnly)       // 只在关卡实例上可编辑（蓝图默认值不可编辑）
14
    float EditInstance = 3.0f;
15

16
    UPROPERTY(VisibleAnywhere)        // 在编辑器中只读可见（灰色显示）
17
    float Visible = 4.0f;
18

19
    // ==== 蓝图可访问性 ====
20
    UPROPERTY(BlueprintReadOnly)      // 蓝图只读
21
    float BpRead = 5.0f;
22

23
    UPROPERTY(BlueprintReadWrite)     // 蓝图可读写
24
    float BpWrite = 6.0f;
25

26
    // ==== 网络复制 ====
27
    UPROPERTY(Replicated)             // 自动复制到所有客户端
28
    float ReplicatedValue;
29

30
    UPROPERTY(ReplicatedUsing = OnRep_Health)  // 复制时回调
31
    int32 Health;
32

33
    UFUNCTION()
34
    void OnRep_Health();              // 当 Health 被复制到客户端时调用
35

36
    // ==== 序列化控制 ====
37
    UPROPERTY(SaveGame)               // 包含在 SaveGame 序列化中
38
    int32 SavedData;
39

40
    UPROPERTY(Transient)              // 不序列化（临时/计算值），UE 中不存在 SkipSerialization 这个说明符
41
    int32 TempData;
42

43
    // ==== 高级说明符 ====
44
    UPROPERTY(Instanced)              // 该属性的对象实例和 Outer 一起序列化
45
    UMyComponent* InstancedComp;
46

47
    UPROPERTY(Interp)                 // 可通过 Matinee/Timeline 插值
48
    float InterpValue;
49

50
    UPROPERTY(Config)                 // 值保存在 .ini 文件中
51
    float ConfigValue;
52

53
    // ==== meta 标签 ====
54
    UPROPERTY(EditAnywhere, meta = (
55
        ClampMin = "0",               // 最小值
56
        ClampMax = "100",             // 最大值
57
        UIMin = "0",                  // 滑条最小值（可超出 ClampMin）
58
        UIMax = "100",                // 滑条最大值（可超出 ClampMax）
59
        DisplayName = "生命值",        // 编辑器中的显示名
60
        ToolTip = "角色的当前生命值",   // 悬浮提示
61
        EditCondition = "bIsAlive",   // 条件可编辑
62
        MakeEditWidget = true         // 在视口中显示 3D Widget
63
    ))
64
    float HP;
65
};

1
UCLASS()
2
class UMyComponent : public UActorComponent
3
{
4
    GENERATED_BODY()
5

6
    // 场景：你缓存了一个资产引用
7
    UPROPERTY()               // ← 有这个 → GC 知道这里引用了 Asset
8
    UMyAsset* CachedAsset;    // 安全：Asset 不会被 GC 误回收
9

10
    UMyAsset* DangerousAsset; // ← 没 UPROPERTY → GC 不知道这里有引用
11
    //                              → GC 可能把 DangerousAsset 指向的对象回收
12
    //                              → DangerousAsset 变成野指针
13
    //                              → 下一次访问 → 崩溃（随机、难复现）
14

15
public:
16
    void CacheAsset(UMyAsset* InAsset)
17
    {
18
        CachedAsset = InAsset;     // ✓ 安全
19
        DangerousAsset = InAsset;  // ✗ 危险！GC 不可见
20
    }
21
};
22

23
// 典型崩溃场景：
24
// 1. 加载了一个 UMyAsset
25
// 2. 把它缓存到 DangerousAsset（忘加 UPROPERTY）
26
// 3. 之后的某个时刻，GC 发现没有 UPROPERTY 引用这个 Asset → 回收它
27
// 4. 你尝试通过 DangerousAsset 访问 → 访问已释放的内存 → 崩溃
28
// 5. 崩溃栈完全看不出和你的 CacheAsset 有什么关系（因为 GC 随机触发）
29
//
30
// 排查方法：
31
// - 在对象的 BeginDestroy() 中打断点，看谁在引用它
32
// - 使用 TWeakObjectPtr 替代原始指针（至少能检测到已释放）
33
// - 开启 GC 日志：-LogGarbage 启动参数

1
UCLASS()
2
class AMyCharacter : public ACharacter
3
{
4
    GENERATED_BODY()
5

6
public:
7
    // ==== 蓝图互操作 ====
8
    UFUNCTION(BlueprintCallable)                  // 蓝图中可调用
9
    void DoDamage(float Amount);
10

11
    UFUNCTION(BlueprintCallable, BlueprintPure)   // 纯函数（无副作用，无执行引脚）
12
    float GetDamageMultiplier() const { return 1.5f; }
13

14
    UFUNCTION(BlueprintImplementableEvent)        // 蓝图实现（C++ 只声明，由蓝图图表来实现逻辑）
15
    void OnDamageReceived(float Amount);           // C++ 中不写函数体！蓝图覆写后自动调用蓝图版本
16

17
    UFUNCTION(BlueprintNativeEvent)               // C++ 有默认实现，蓝图可覆写
18
    void OnHealReceived(float Amount);             // 需提供 _Implementation 后缀的实现
19

20
    // ==== 网络 RPC ====
21
    UFUNCTION(Server, Reliable)                   // 客户端 → 服务器（可靠）
22
    void ServerDoAction(int32 ActionID);
23

24
    UFUNCTION(Server, Unreliable)                 // 客户端 → 服务器（不可靠）
25
    void ServerPing(float Timestamp);
26

27
    UFUNCTION(Client, Reliable)                   // 服务器 → 所属客户端
28
    void ClientDisplayMessage(const FString& Msg);
29

30
    UFUNCTION(NetMulticast, Reliable)             // 服务器 → 所有客户端（包括自己）
31
    void MulticastPlayEffect(const FVector& Location);
32

33
    // ==== 编辑器 ====
34
    UFUNCTION(CallInEditor)                       // 编辑器中可在此类的 Details 面板中点击执行
35
    void DebugPrintValues();
36

37
    // ==== 高级 ====
38
    UFUNCTION(Exec)                               // 可通过控制台命令调用
39
    void MyConsoleCommand(float Value);
40
    // 控制台中输入：MyConsoleCommand 3.14
41

42
    UFUNCTION(BlueprintCallable, meta = (
43
        ExpandEnumAsExecs = "Result"              // 枚举展开为执行引脚
44
    ))
45
    void TrySomething(TEnumAsByte<EMyResult>& Result);
46
};

1
// .h 文件
2
UCLASS()
3
class AMyCharacter : public ACharacter
4
{
5
    GENERATED_BODY()
6

7
public:
8
    UFUNCTION(BlueprintNativeEvent, BlueprintCallable)
9
    void OnHealReceived(float Amount);
10

11
    // BlueprintNativeEvent 的底层原理：
12
    // UHT 会生成一个 _Implementation 函数和一个默认的桥接函数：
13
    //
14
    // 生成的代码（概念）：
15
    // void AMyCharacter::OnHealReceived(float Amount) {
16
    //     // 如果有蓝图覆写了这个事件 → 调蓝图的实现
17
    //     // 否则 → 调 C++ 的 _Implementation
18
    //     ProcessEvent(FindFunction("OnHealReceived"), &Amount);
19
    // }
20
};
21

22
// .cpp 文件 —— 必须提供 _Implementation 后缀的默认实现
23
void AMyCharacter::OnHealReceived_Implementation(float Amount)
24
{
25
    // 这是 C++ 的默认实现
26
    // 如果蓝图覆写了 OnHealReceived，这个不会被调用
27
    Health = FMath::Min(MaxHealth, Health + Amount);
28
    UE_LOG(LogTemp, Log, TEXT("Healed: %f"), Amount);
29
}
30

31
// ⚠️ 常见错误：忘记 _Implementation 后缀，导致链接错误！
32
// ✗ void AMyCharacter::OnHealReceived(float Amount)  // 链接错误！找不到符号
33
// ✓ void AMyCharacter::OnHealReceived_Implementation(float Amount)

1
// 场景：你有一个 SaveGame 系统，需要把某个 Actor 的所有
2
// SaveGame 标记的属性复制到另一个 Actor
3

4
void CopySaveGameProperties(AActor* From, AActor* To)
5
{
6
    UClass* FromClass = From->GetClass();
7
    UClass* ToClass = To->GetClass();
8

9
    // 遍历源对象的所有属性
10
    for (TFieldIterator<FProperty> PropIt(FromClass); PropIt; ++PropIt)
11
    {
12
        FProperty* Property = *PropIt;
13

14
        // 只处理标记了 SaveGame 的属性
15
        if (!Property->HasAnyPropertyFlags(CPF_SaveGame))
16
        {
17
            continue;
18
        }
19

20
        // 目标对象也要有同名属性
21
        FProperty* TargetProperty = ToClass->FindPropertyByName(
22
            Property->GetFName());
23
        if (!TargetProperty)
24
        {
25
            continue;
26
        }
27

28
        // 复制属性值（通过反射——无需知道具体类型！）
29
        void* SourceValue = Property->ContainerPtrToValuePtr(From);
30
        void* DestValue = TargetProperty->ContainerPtrToValuePtr(To);
31
        Property->CopyCompleteValue(DestValue, SourceValue);
32
    }
33
}
34

35
// 这段代码的关键：你不需要知道 Actor 有哪些属性，
36
// 它在运行时自动发现所有 SaveGame 属性并复制。
37
// 这是反射系统真正的威力。

1
// 场景：从配置文件读取"当玩家死亡时，调用哪个函数"
2
// Config.ini: OnDeathFunction=ExplodeAndRespawn
3

4
void AMyCharacter::HandleDeath()
5
{
6
    FString FunctionName = ReadFromConfig(TEXT("OnDeathFunction"));
7
    // FunctionName = "ExplodeAndRespawn"
8

9
    // 通过名字找到函数
10
    UFunction* Function = GetClass()->FindFunctionByName(*FunctionName);
11

12
    if (Function)
13
    {
14
        // 通过反射调用——不需要 if-else 或 switch-case！
15
        ProcessEvent(Function, nullptr);
16

17
        // 深入一点：ProcessEvent 就是虚幻引擎虚拟机（Blueprint VM）的真正入口。
18
        // 无论是：
19
        //   - 蓝图调用 C++ 函数（BlueprintCallable 的 UFUNCTION）
20
        //   - C++ 调用蓝图实现（BlueprintImplementableEvent）
21
        //   - 通过字符串反射调用（你这里写的这种）
22
        //   - 网络 RPC 的本地执行
23
        // 底层最终都会走到 UObject::ProcessEvent。
24
        //
25
        // ProcessEvent 负责：
26
        //   1. 解析参数栈（把 C++ 参数打入 VM 的字节码栈帧）
27
        //   2. 切换执行上下文（如果当前在蓝图中，切到 C++；反之亦然）
28
        //   3. 把控制权交给对应函数的字节码执行器
29
        //
30
        // 你可以把 ProcessEvent 理解为 UE 反射世界的"万能函数调用器"。
31
    }
32
    else
33
    {
34
        UE_LOG(LogTemp, Warning, TEXT("Function %s not found in %s"),
35
               *FunctionName, *GetClass()->GetName());
36
    }
37
}

1
// 场景：编辑器中选中 100 个 Actor，批量设置它们的一个属性
2
// 用反射——不需要知道具体类型
3

4
void SetPropertyOnAllSelectedActors(FName PropertyName, float NewValue)
5
{
6
    for (FSelectionIterator It(GEditor->GetSelectedActorIterator()); It; ++It)
7
    {
8
        AActor* Actor = Cast<AActor>(*It);
9
        if (!Actor) continue;
10

11
        // 查找该 Actor 是否有所需属性
12
        FProperty* Property = Actor->GetClass()->FindPropertyByName(PropertyName);
13
        if (!Property) continue;
14

15
        // 检查类型是否匹配
16
        if (FFloatProperty* FloatProp = CastField<FFloatProperty>(Property))
17
        {
18
            FloatProp->SetPropertyValue_InContainer(Actor, NewValue);
19
        }
20
        // else if (FIntProperty* IntProp = ...) { ... }
21
        // 对不同类型的属性做不同处理
22
    }
23
}

1
// ✗ 错误
2
#pragma once
3
#include "CoreMinimal.h"
4
#include "MyActor.h"          // 包含其他类 OK
5
// 忘记 #include "MyComponent.generated.h" ← 致命错误
6

7
UCLASS()
8
class MYPROJECT_API UMyComponent : public UActorComponent
9
{
10
    GENERATED_BODY()  // ← 编译器报错：GENERATED_BODY 未定义！
11
    // 因为 GENERATED_BODY 宏定义在 .generated.h 中
12
};
13

14
// ✓ 正确
15
#pragma once
16
#include "CoreMinimal.h"
17
#include "MyActor.h"
18
#include "MyComponent.generated.h"  // ← 必须最后 #include

1
UCLASS()
2
class UMyActor : public AActor
3
{
4
    GENERATED_BODY()
5

6
    // ✗ 错误：声明为 UPROPERTY，但类型不支持反射
7
    UPROPERTY()
8
    std::string Name;  // UHT 在编译前置阶段直接硬报错（如"Cannot find class, struct,
9
                       // or enum named 'std::string'"），强制中断整个编译管线。
10
                       // 绝不可能"编译通过"或延后到运行时——UHT 有一票否决权。
11

12
    // ✓ 正确
13
    UPROPERTY()
14
    FString Name;  // FString 支持反射
15
};