《Unreal 对 C++ 做了什么》系列 05. UFUNCTION：让函数在引擎内可见 (RPC, Exec, Blueprint)-编程实验室

《Unreal 对 C++ 做了什么》系列 (05/54)

05. UFUNCTION：让函数在引擎内可见 (RPC, Exec, Blueprint) ⚡

🚀 导言：超越 C++ 的调用限制

在标准 C++ 中，调用函数是“硬跳转”：编译器在编译期确定内存地址。但在虚幻引擎中，函数需要具备**“动态分发”**的能力。UFUNCTION宏通过“劫持”函数名，在静态的 C++ 之上构建了一套动态调用体系。

📊 核心对比：标准 C++ vs. 虚幻 C++

特性	标准 C++ 函数	虚幻 C++ (`UFUNCTION`)
可见性	仅限代码链接期	全局运行时可见，蓝图/编辑器可识别
调用方式	内存地址直接跳转	支持字符串搜索调用、网络转发调用
多态性	依赖原生虚函数表 (vtable)	支持蓝图重写、C++/脚本混合多态
参数传递	栈/寄存器传参	支持通过反射数据包（Stack Buffer）传参

🛠️ 关键说明符：赋予函数“超能力”

通过在UFUNCTION()中添加不同的说明符，你可以精准定义函数在引擎中的身份。

1. 蓝图交互类

BlueprintCallable：最常用的标记，让函数在蓝图中作为一个节点被手动调用。
BlueprintPure：定义“纯函数”。这种函数没有执行线（白线），通常用于获取数据而不改变对象状态。
BlueprintImplementableEvent：C++ 声明触发，蓝图完全实现。
BlueprintNativeEvent：C++ 提供默认实现（_Implementation），蓝图可以重写。

2. 网络 RPC 类

Server：客户端调用，服务器执行。
Client：服务器调用，特定客户端执行。
NetMulticast：服务器调用，所有连接的客户端同步执行。
**Reliable/Unreliable**：定义网络包是否必须到达（可靠性）。
WithValidation：要求必须实现_Validate逻辑，用于服务器防外挂检查。

3. 编辑器与调试类

Exec：将函数变为控制台命令，在游戏中按~键输入函数名即可运行。
CallInEditor：在编辑器的属性面板中生成一个按钮，点击即可在非运行状态下触发该函数。
Category：定义函数在蓝图搜索列表中的目录分类。

4. 元数据类 (`meta`)

meta = (AllowPrivateAccess = "true")：允许私有函数在蓝图中被访问。
meta = (WorldContext = "WorldContextObject")：标记某个参数为世界上下文，蓝图调用时会自动填充，无需手动连线。

🔑 核心黑科技：Thunk (exec) 函数

当你编译一个带有UFUNCTION的类时，UHT 会在.generated.cpp中为你生成一个以exec开头的静态函数。这就是Thunk 函数。

1. 为什么需要 Thunk？

蓝图虚拟机（VM）手里只有一个uint8*类型的栈空间（Stack Buffer）。Thunk 的工作就是“翻译”：它从虚拟机栈中取出字节，转换成真实的 C++ 类型，然后再调用你写的函数。

2. Thunk 的内部长什么样？（伪代码）

voidAMyActor::execNativeEvent(FFrame&Stack,RESULT_DECL){P_GET_PROPERTY(FFloatProperty,Value);// 从栈里解析出参数P_FINISH;P_NATIVE_BEGIN;this->NativeEvent_Implementation(Value);// 真正调用你的 C++P_NATIVE_END;}

💻 代码实战：四种不同的实现姿势

1. 声明部分 (MyActor.h)

UCLASS()classAMyActor:publicAActor{GENERATED_BODY()public:UFUNCTION(BlueprintCallable)voidSimpleCall();UFUNCTION(BlueprintNativeEvent)voidNativeEvent(floatValue);UFUNCTION(BlueprintImplementableEvent)voidOnlyBlueprintEvent();UFUNCTION(Server,Reliable,WithValidation)voidServer_UpdateHealth(floatNewHealth);};

2. 实现部分 (MyActor.cpp)

voidAMyActor::SimpleCall(){UE_LOG(LogTemp,Warning,TEXT("Simple Call"));}voidAMyActor::NativeEvent_Implementation(floatValue){UE_LOG(LogTemp,Warning,TEXT("Default C++ Logic"));}// OnlyBlueprintEvent 无需且禁止在 .cpp 实现boolAMyActor::Server_UpdateHealth_Validate(floatNewHealth){returnNewHealth>=0.0f;// 防外挂校验}voidAMyActor::Server_UpdateHealth_Implementation(floatNewHealth){CurrentHealth=NewHealth;}

🛠️ 总结速查表：实现规范与幕后英雄

UFUNCTION 类型	实现后缀	是否有 Thunk (exec)	核心逻辑流
BlueprintCallable	无	有	VM -> Thunk -> C++ 原生函数
BlueprintNativeEvent	`_Implementation`	有	原名函数 -> (判断) -> 蓝图或 C++ Impl
BlueprintImplementableEvent	无实现	有	原名函数 -> 直接丢给 VM 执行蓝图
Server / Client	`_Implementation`	有	原名函数 -> 网络序列化 -> 远端 Thunk -> Impl