做 Unreal 开发这些年我最常被问到的问题不是“C 难不难”而是“我 C 写了一个功能为什么蓝图里看不到”“为什么别人写的 C 类在蓝图里能当拖拽组件我写的却只有个白板”——说白了就是没搞懂 C 和蓝图之间那层“透明胶”元数据。这一期是《Unreal 对 C 做了什么》系列的第 08 篇主题正好卡在很多人半懂不懂的位置蓝图通信模式以及围绕 UFUNCTION、UPROPERTY 展开的整套元数据体系。这篇文章不聊纯 C也不聊纯蓝图只聊那座让两边互相看得见、调得动的桥以及这座桥上的每一个“开关”到底控制什么。无论你是刚把第一个 Actor 类拖进蓝图、还是已经在写 Gameplay 插件但总觉得暴露接口手感不对这篇都值得花十分钟看完。1. 为什么说 C 和蓝图之间隔着一座桥1.1 反射系统才是元数据的地基很多人把 UPROPERTY、UFUNCTION 当成“宏”以为它们只是给编译器看的标记。实际上Unreal 的 UHTUnreal Header Tool会在编译前扫描头文件里的这些标记生成一整份反射数据类的继承关系、属性的名字和类型、函数的参数和返回类型、哪些成员可以被蓝图访问、哪些属性会被 GC 追踪全部被登记成一张张元数据表。这张表的作用往浅了说是让蓝图编辑器能够在“完全没有 C 头文件信息”的情况下依然知道某个 UClass 有哪些可编辑的属性、哪些可调用的函数。往深了说编辑器里的 Details 面板、序列化存档、垃圾回收、网络复制、蓝图节点列表全部依赖这套反射数据。没有元数据C 类在 Unreal 眼里就是一个不透明的黑盒蓝图根本无法感知它的存在。这也是为什么在 Unreal 里写 C 不能随便用普通的 int、float 成员变量而要用 UPROPERTY 包一层。普通成员变量不会进入反射系统蓝图上自然看不见存档也存不下来复制更不可能。你可以把 UPROPERTY 理解为给变量办了一张“身份证”只有办了证的成员才被引擎视为“一等公民”。1.2 三种基本通信层次C 和蓝图之间的通信日常开发里逃不出三种层次属性通信C 暴露一个 UPROPERTY蓝图读取或修改它。适合传递状态、配置数值、引用对象。函数通信C 暴露一个 UFUNCTION蓝图直接调用或者反过来蓝图实现一个事件让 C 调用。适合行为触发、逻辑请求。事件通知C 在某个时机广播一个动态多播委托蓝图通过 Event Dispatcher 或绑定函数接收通知。适合解耦通知、跨模块广播。很多新手容易犯的错是所有通信都走属性或者所有通信都走函数调用。比如 UI 要监听血量变化有人会在 Tick 里每帧去 Get 一下当前血量然后和上一次保存的值比对变了就刷新。这属于典型的“用属性思维解决事件问题”性能差、逻辑绕、还容易漏帧。正确的做法是让血量变化这件事本身成为一个事件谁关心谁去绑定不用轮询。1.3 桥的朝向C 到蓝图、蓝图到 C这座桥还有个方向问题。C 侧可以主动调用蓝图里的事件蓝图侧也可以反过来调用 C 的函数。理解清楚两种方向分别对应哪些关键字你才算真正掌握了元数据的设计意图。方向一C 声明蓝图实现。在 C 里写一个虚函数加上 BlueprintImplementableEvent蓝图里就能看到这个事件节点然后你可以在蓝图的 Event Graph 里填上具体逻辑。C 调用这个函数时实际执行的是蓝图侧覆写的内容。方向二蓝图调用 C。在 C 函数上标 BlueprintCallable蓝图里就能右键搜索到这个函数并调用它。这类函数通常由 C 完成计算、数据读取等底层操作蓝图只负责决定“什么时候调”。方向三C 主动广播蓝图被动响应。C 定义一个动态多播委托用 BlueprintAssignable 暴露蓝图在 BeginPlay 时绑定一个自定义事件之后只要 C 那边执行 Broadcast()蓝图这边就会收到通知。这是典型的事件驱动模式后面第 2 节我会专门展开讲。2. 蓝图通信模式详解从直接调用到解耦2.1 直接引用最基础也最容易被误解的通信先讲最直觉的模式。假如你的 GameMode 里持有当前玩家 Character 的引用C 侧可能这么写UCLASS() class MYGAME_API AMyGameMode : public AGameModeBase { GENERATED_BODY() public: UPROPERTY(BlueprintReadOnly, Category GameMode) TObjectPtrAMyCharacter CurrentCharacter; };当你在蓝图里 Cast 到 AMyGameMode就能直接访问 CurrentCharacter 这个变量。同理如果 CurrentCharacter 被标记成 BlueprintReadWrite蓝图里还能重新赋值。这类通信的好处是简单、直接、可读性强缺点是强耦合。GameMode 直接依赖 Character 的具体类型你要是换了角色类GameMode 里的引用类型也得跟着改。直接引用还有一个常见误区在蓝图里拖一个变量类型选 AMyCharacter然后直接拖出来连线编译报错说“不是蓝图可访问类型”。原因往往是这个 C 类本身没有用 UCLASS 宏标记或者标记了但在 Settings 里没有把模块设置为 Included In Modules 里的“Engine”或“Game”而非“Editor”。这个坑我在第 5 节问题排查里会细说。2.2 Event Dispatcher 与动态委托C 侧的事件支持你可能会问蓝图里的 Event Dispatcher 用得好好的C 里对应的是什么答案是动态多播委托。看一个例子。我们需要在角色受到伤害时通知 UI 更新血条DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnHealthChanged, float, NewHealth); UCLASS() class MYGAME_API AMyCharacter : public ACharacter { GENERATED_BODY() public: UPROPERTY(BlueprintAssignable, Category Health) FOnHealthChanged OnHealthChanged; };DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam 声明了一个带一个参数的动态多播委托类型。UPROPERTY(BlueprintAssignable) 把它暴露给蓝图于是蓝图里就能对 OnHealthChanged 右键绑定事件。当角色受到伤害C 侧只要做一件事void AMyCharacter::ApplyDamage(float Amount) { CurrentHealth - Amount; OnHealthChanged.Broadcast(CurrentHealth); }任何在蓝图上绑定了 OnHealthChanged 的对象都会收到这次广播。UI 不需要每帧轮询血量伤害系统也不需要知道 UI 的存在。这个“发布-订阅”模式是解耦通信最核心的思想。这里有一个大多数教程不会强调的细节为什么用 DYNAMIC 多播委托而不是普通多播委托因为动态委托支持通过名字序列化、反射和蓝图绑定普通委托虽然性能更好但蓝图无法感知。既然目的是让蓝图参与进来就必须用带 DYNAMIC 前缀的版本。2.3 蓝图接口跨类通信的最优解很多时候我们希望“不管你是敌人、机关还是 NPC只要你有 Interact 能力玩家就能和你交互”。如果对每种类型都写死引用代码会膨胀到没法维护。C 侧的接口UINTERFACE就是为这类需求设计的。定义一个接口UINTERFACE(MinimalAPI, Blueprintable) class UInteractable : public UInterface { GENERATED_BODY() }; class MYGAME_API IInteractable { GENERATED_BODY() public: UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category Interact) void OnInteract(AActor* Instigator); };任何类只要继承自 IInteractable并实现 OnInteract就可以被玩家交互。玩家射线检测时不需要判断命中点是敌人还是机关只需要判断它是否实现了 IInteractable 接口IInteractable* Interactable CastIInteractable(HitActor); if (Interactable) { Interactable-Execute_OnInteract(HitActor, this); }注意这里的调用方式不是 HitActor-OnInteract(this)而是 Execute_OnInteract。因为蓝图实现的事件要通过执行函数来触发这是 Unreal 接口的标准调用姿势。如果你写的是 C 原生实现也可以直接在接口类里给默认实现用 Execute_ 前缀函数去调用蓝图侧和 C 侧都能获得一致的行为。接口相比直接引用最大的优势是调用方和被调用方完全解耦。交互逻辑不再关心对象的实际类只关心它“实现了什么”。这也让关卡策划能够在蓝图里自由组合比如一个 Box 既可以实现 Interactable也可以把同一接口用在完全不同类型的物体上。跨类通信的场景接口基本是首选。2.4 三种模式怎么选直接引用、事件分发器还是接口没有一种模式是万能的我整理了一张选型表方便你对照自己的场景决定通信场景推荐模式理由GameMode 明确知道并持有某个角色直接引用简单清晰性能最好一个状态变化要通知多个不相关的对象动态多播委托 / Event Dispatcher发布订阅解耦新增监听方不用改广播方不同类之间需要公共能力协议蓝图接口跨类复用调用方不需要依赖具体类型蓝图内部多个 Actor 之间互相通知蓝图原生 Event Dispatcher无需写 C编辑器中可视化绑定最方便子类需要覆写父类逻辑钩子BlueprintNativeEvent 虚函数既有 C 默认实现又允许蓝图覆写这张表不是铁律但绝大多数游戏逻辑都适用。我个人的习惯是能靠接口描述能力就尽量靠接口状态刷新类通知用动态委托只有确定性极强的层级关系才用直接引用。这么做的收益在项目后期尤其明显——模块之间的依赖图不再是一团乱麻。3. 元数据真正决定“可见性”和“编辑体验”的东西3.1 UPROPERTY 的核心说明符从蓝图可见到编辑器可编辑属性反射是元数据体系里最常用、也最容易出错的部分。核心规约就几个BlueprintReadWrite蓝图可读、可写是最高权限组合。适合游戏运行时需要蓝图动态修改的配置型数据。BlueprintReadOnly蓝图可读、不可写。适合内部维护、外部只能查询的状态数据比如当前血量。EditAnywhere编辑器 Details 面板中可编辑且每个实例都能独立设置。EditDefaultsOnly只能在类默认值里设置实例不能独立改。适合设计上全局统一、每个实例不应该有差异的数值。VisibleAnywhere编辑器可见但不可编辑。适合显示调试信息、内部状态。举个例子。武器类里有三个典型属性UPROPERTY(EditDefaultsOnly, Category Weapon) float BaseDamage 10.f; UPROPERTY(VisibleAnywhere, Category Weapon) float CurrentDurability 100.f; UPROPERTY(BlueprintReadWrite, EditAnywhere, Category Weapon) FName WeaponName TEXT(Default);BaseDamage 用 EditDefaultsOnly因为每个武器类型的伤害上限在类默认值里定好了实例最好不要随便改否则容易出现“为啥我这个实例伤害和别人不一样”的问题。CurrentDurability 用 VisibleAnywhere因为它是运行状态玩家只应该看、不应该在编辑器里手填。WeaponName 用 BlueprintReadWrite EditAnywhere因为策划很可能希望在编辑器里给每个散落在地图上的武器实例起不同的名字。这三者的区别如果没搞明白最常见的后果就是策划在编辑器中拖了一个武器实例想改伤害发现 Details 面板里根本没有这个字段或者你在蓝图里想读 AVehicle 的当前速度却因为属性只标了 EditAnywhere 没标 BlueprintReadOnly导致蓝图节点列表里搜不到。3.2 UFUNCTION 的核心说明符给蓝图哪些“操作权”函数暴露比属性更讲究因为函数背后是行为行为一旦暴露出去蓝图侧的使用自由度会直接影响项目的稳定性和可维护性。BlueprintCallable蓝图可以主动调用。适合计算、查询、请求类逻辑。BlueprintImplementableEventC 声明蓝图实现。C 只负责“在合适的时机调用”具体怎么做由蓝图决定。BlueprintNativeEventC 提供默认实现同时允许蓝图覆写。这是最灵活的选项既有兜底逻辑又给了策划和关卡脚本足够的发挥空间。对比一下后面两个。一个用 BlueprintImplementableEventC 侧你写的是UFUNCTION(BlueprintImplementableEvent, Category Combat) void OnTargetLocked(AActor* Target);C 里没有函数体蓝图里会自动生成一个同名事件节点。你只需要在合适的时机调用 OnTargetLocked蓝图就能收到。用 BlueprintNativeEventC 侧需要这样写UFUNCTION(BlueprintNativeEvent, Category Combat) void OnTargetLocked(AActor* Target); // 生成实现C 默认实现 void AMyCharacter::OnTargetLocked_Implementation(AActor* Target) { // 默认行为播放锁定音效 PlayLockSound(); }注意蓝图的覆写事件名是 OnTargetLocked对应到 C 的函数实现名会带 _Implementation 后缀。这个后缀记不住的话编译会报“无法解析的外部符号”新手经常卡在这里。其实理解了规则就很好记声明是什么名字实现就加 _Implementation。3.3 元数据标签meta决定编辑器体验的隐藏细节UPROPERTY、UFUNCTION 除了上面这些“可见性”说明符还可以在后面跟一对括号meta (...),里面塞各种编辑器提示。这些元数据直接影响你的操作体验。常用的几个UPROPERTY(EditAnywhere, meta (ClampMin 0.0, ClampMax 100.0)) float HealthPercent; UPROPERTY(EditAnywhere, meta (UIMin 0, UIMax 100)) int32 AmmoCount; UPROPERTY(EditAnywhere, meta (ToolTip 子弹飞行速度单位 cm/s)) float BulletSpeed 2000.f; UFUNCTION(BlueprintCallable, meta (DisplayName 计算抛物线落点)) FVector PredictLandingLocation();ClampMin/ClampMax 限制数值输入范围越界会被钳住UIMin/UIMax 只影响滑条显示范围不强制限制数值DisplayName 让蓝图节点显示成你想要的名字而不是 C 的函数名。这几个字段看着不起眼但项目里一旦有数值策划介入这些约束就是防止“手滑填错”的第一道防线。还有一个非常有用的元数据DeprecatedFunction、DeprecatedProperty。当你重构代码后希望旧蓝图节点尽量失效可以给旧函数打上标记编辑器里会提示该节点已弃用同时保留旧链路不直接崩掉。这在大型项目里特别重要因为蓝图资产通常比 C 代码更难大规模自动替换。3.4 元数据的设计思维把 C 类当成“给策划的 API”这部分我想多说一点因为它不是技术问题而是思路问题。很多 C 程序员把元数据当成“能编译就行的标志”来用结果东西是写完了蓝图侧面对却是一堆莫名其妙的节点函数名是英文缩写、参数全是无意义 bool、属性没做范围钳制策划根本不敢动。真正好的元数据设计是把自己当成一个“接口设计师”把蓝图用户当成你的下游伙伴。我在项目里会遵守几条硬性规则每个暴露给蓝图的 UFUNCTION 都要写清晰的名字必要的时候用 DisplayName 转换成业务语言而不是工程名。每个 UPROPERTY 都要考虑是否真的需要蓝图可写。能只读就只读能默认值编辑就不要实例编辑权限越少越好。每个 BlueprintNativeEvent 都必须提供默认实现。这样即使蓝图不覆写游戏也能正常运行不至于出现“蓝图忘了接线就永久卡死”的玄学问题。对外暴露的参数尽量用强类型少用 FString、int32 去代替枚举和结构体。蓝图侧看到一个 FString 参数根本不知道该传什么而一个枚举会自动生成下拉选项体验完全是两回事。4. 实操过程从零写一个“NPC 被击中触发任务”的完整链路光说不练假把式。这一节我带你完整过一遍C 里定义一个可交互 NPC暴露一个伤害事件给蓝图蓝图在事件里刷任务进度。整个过程能把你前面看的元数据知识全部串起来。4.1 搭建 C 基类新建一个 C 类继承 ACharacter命名为 AInteractableNPC#pragma once #include CoreMinimal.h #include GameFramework/Character.h #include InteractableNPC.generated.h UCLASS() class MYGAME_API AInteractableNPC : public ACharacter { GENERATED_BODY() public: AInteractableNPC(); // 蓝图可调用客户端请求交互 UFUNCTION(BlueprintCallable, Category Interaction) void RequestInteract(AActor* Interactor); // 蓝图实现事件C 只定义时机蓝图负责具体表现 UFUNCTION(BlueprintImplementableEvent, Category Interaction) void OnInteract(AActor* Interactor); protected: // NPC 的当前血量只读蓝图可以拿来显示血条 UPROPERTY(BlueprintReadOnly, Category Health) float CurrentHealth; // 最大血量只在默认值里配置 UPROPERTY(EditDefaultsOnly, Category Health) float MaxHealth 100.f; };在构造函数里初始化AInteractableNPC::AInteractableNPC() { MaxHealth 100.f; CurrentHealth MaxHealth; }然后在 .cpp 里实现 RequestInteractvoid AInteractableNPC::RequestInteract(AActor* Interactor) { if (!Interactor) { return; } // 蓝图侧如果实现了 OnInteract这里就会触发它 OnInteract(Interactor); }到这里C 侧的工作已经完成一半。编译生成后你在内容浏览器里右键这个 C 类选择“基于 AInteractableNPC 创建蓝图类”一个蓝图类就出来了。打开这个蓝图你会看到 Event Graph 里自动多了一个 OnInteract 事件节点这就是 BlueprintImplementableEvent 的功劳。4.2 给 NPC 加一个可变更的交互提示文本交互功能通常要告诉玩家“按 E 交互”这个提示文案如果写死在 C 里策划改起来就得麻烦程序。更好的方式是暴露一个可编辑文本属性UPROPERTY(EditAnywhere, BlueprintReadWrite, Category Interaction, meta (DisplayName 交互提示)) FText InteractPrompt;在蓝图里你随时可以通过 Get/Set 节点读取或修改它。更精细一点你还可以给它加一个 ToolTip 元数据这样策划把鼠标悬停在 Details 面板该属性上时能看到你留下的说明“在屏幕中显示为空则不显示”。4.3 用 BlueprintNativeEvent 做一个带默认行为的受击逻辑交互有了被打的逻辑也得有。受击这个行为我们希望 C 里先做一个通用默认处理——扣血血量低于 0 就销毁或播死亡动画——然后又允许每个 NPC 蓝图覆写比如 Boss 被打后进入二阶段。在头文件里加public: UFUNCTION(BlueprintNativeEvent, Category Combat) void ReceiveDamage(float DamageAmount); virtual void ReceiveDamage_Implementation(float DamageAmount);在 .cpp 里实现默认逻辑void AInteractableNPC::ReceiveDamage_Implementation(float DamageAmount) { CurrentHealth FMath::Clamp(CurrentHealth - DamageAmount, 0.f, MaxHealth); if (CurrentHealth 0.f) { // 默认死亡逻辑 Destroy(); } }编译后蓝图侧会看到一个 ReceiveDamage 事件节点。如果你希望 Boss 覆写这个事件就在 Boss 蓝图里创建这个事件节点然后写自己的逻辑甚至可以不调用父类实现完全替换默认行为。如果希望先执行 C 默认逻辑再做额外处理就在蓝图事件上右键 Add Call to Parent Function调用父类实现。这个模式是 Gameplay 系统里最常用的因为它兼顾了“可复用”和“可覆写”也是 Unreal 官方推荐的事件设计方式。4.4 把交互和受击串起来检查接口而不是检查类型最后一步我们要让“玩家按下 E”能同时作用于门、箱子、NPC而不是每一种都写死 Cast。回到第 2 节的接口思路定义一个 IInteractable 接口UINTERFACE(MinimalAPI, Blueprintable) class UInteractTarget : public UInterface { GENERATED_BODY() }; class MYGAME_API IInteractTarget { GENERATED_BODY() public: UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category Interaction) void PlayerInteract(AActor* Interactor); };让 AInteractableNPC 实现这个接口class MYGAME_API AInteractableNPC : public ACharacter, public IInteractTarget { GENERATED_BODY() ... }; // .cpp 里提供默认实现 void AInteractableNPC::PlayerInteract_Implementation(AActor* Interactor) { // 默认交互表现 OnInteract(Interactor); }这样任何 Actor 不管是 C 类还是纯蓝图类只要实现 IInteractTarget玩家交互系统就统一调用 PlayerInteract完全不需要关心目标的具体类型。以后新增任何可交互物体只需要在类里加上一行“实现接口”再补实现内容即可交互系统不用改一行代码。5. 常见问题与排查技巧实录5.1 蓝图通信元数据问题速查表现象可能原因解决思路蓝图中搜索不到 C 函数函数缺少 BlueprintCallable / BlueprintImplementableEvent / BlueprintNativeEvent检查 UFUNCTION 说明符蓝图中看不到 C 属性属性缺少 BlueprintReadWrite / BlueprintReadOnly检查 UPROPERTY 说明符函数有说明符但蓝图仍然搜不到类所在模块未列入 UnrealHeaderTool 扫描范围或类未使用 UCLASS 宏检查头文件是否包含 GENERATED_BODY()确认类名以 U/A 开头蓝图类复制后变量值丢失变量只标了 EditAnywhere没有默认值保护或复制的是浅拷贝导致引用失效重新断言变量或改用 Instanced / 引用类型BlueprintNativeEvent 编译报“无法解析的符号”忘记实现 _Implementation 函数在 .cpp 中添加类名::函数名_Implementation定义蓝图绑定 Event Dispatcher 后不触发C 侧没有调用 Broadcast()或调用的对象和绑定对象不是同一个实例检查广播时机和委托所属实例编辑器 Details 面板滑条范围不对数值超过 UIMin/UIMax 或 ClampMin/ClampMax根据需要的“硬限制/软限制”选对 meta 关键字蓝图里修改了 C 变量但存档后重置属性没有标记 SaveGame或构造函数里每次覆盖了值检查 SaveGame 标记和初始化顺序5.2 为什么蓝图里看不到我的 C 函数这个问题的排查顺序很重要我踩过一次大坑之后总结出了一条固定路径第一步确认头文件结构完整。类的第一行必须是 UCLASS()类体内第一行必须是 GENERATED_BODY()。如果缺了这个UHT 不会生成反射代码编译可能都过不去更别提蓝图可见。第二种情况是编译过了但编辑器里蓝图节点列表搜不到——这时候先别急着重编译把编辑器右下角的 Output Log 打开搜索 “Reflection” 或者 “UHT”看有没有警告提示某个类被跳过。第二步确认函数所在的头文件已经被模块正确包含。如果类定义在 Private 文件夹而模块的 Build.cs 没有正确暴露头文件路径UHT 可能扫描不到。常见解决方法是把公共类头文件移动到 Public 文件夹或者在 Build.cs 里使用PublicIncludePaths.Add(ModuleDirectory /Public)来指定扫描目录。第三步确认 BlueprintType / Blueprintable 等“类级别”标记。仅当一个类被标记为 Blueprintable 时它的成员才能被蓝图化。比如 UCLASS(Blueprintable) 或 UCLASS(BlueprintType)。否则就算成员函数标了 BlueprintCallable编辑器里也找不到这个类。5.3 复制蓝图后变量丢失是怎么回事这是社区里讨论度特别高的问题“复制出来的蓝图变量丢失了”。要说清楚需要区分几种情况。第一种默认值丢失。源蓝图里某个 C 属性在 Details 面板被改成 30复制蓝图后新蓝图却显示默认值 10。这通常是因为该属性没有标记 EditInstanceOnly 或 EditAnywhere而是 EditDefaultsOnly。EditDefaultsOnly 属性的配置存在 CDOClass Default Object里而蓝图复制走的是模板引用新蓝图默认还是继承原始的 CDO 数值。解决办法是用 EditAnywhere 替代 EditDefaultsOnly或者在新蓝图中重新配置。第二种引用丢失。复制蓝图后某个 Object 引用变成 None这是因为 Hard Reference 在复制时没有正确序列化尤其是跨地图引用或者引用的对象在当前加载上下文中不存在引擎会静默清空。解决办法是使用 Soft Object ReferenceTSoftObjectPtr 或 FSoftObjectPath来保存资源路径运行时再加载或者确保引用指向的对象和蓝图存在于同一个 Asset 包内。第三种变量容器结构丢失。如果你把蓝图类的一个数组或 Map 变量在默认值里填了元素复制后元素列表可能被清空。这种现象和 X.3 版本变更、蓝图编译失败都有关系比较玄学。我的建议是重要数据不要放在蓝图变量默认值里而是放到 DataTable / DataAsset 里由数据资产统一管理。蓝图变量用于运行时状态别做持久化存储。5.4 触摸输入蓝图不响应怎么排查社区里另一个高频问题是“UE5 双指触摸蓝图不生效”。这类问题往往不是元数据本身而是输入事件链路上缺了环节。排查顺序我一般这么走第一步确认 Enhanced Input 已配置。UE5 默认用 Enhanced Input如果你在 Project Settings - Input 里只配置了旧的 Action Mappings触摸事件很可能不会被触发需要把 Touch 事件绑定到 Enhanced Input Action 上。第二步确认设备类型和处理方式。触摸事件默认要启用触控项目设置里 Input - Default Player Input 需要设置成支持 Touch另外还要在设备上开启触控模拟器下可能默认不响应。第三步检查蓝图绑定方式。触摸事件的绑定对象应该是 Player Controller 或 Pawn 的 InputComponent而不是任意 Actor。在蓝图中如果你用一个 HUD 的 Widget 去响应触摸需要确认它的 Hit Test 是否拦截了事件以及 Widget 上的 Is Focusable 是否设置为 true。如果是双指手势蓝图上常见的处理方式是用 Input Touch 事件记录第一个手指的触碰点然后在第二个手指触发时计算两个点之间的距离差实现缩放。很多人失败的原因是把两个 Touch 事件绑定到了同一个组件上导致第二个手指永远无法触发独立事件。正确做法是分别给 Touch 1 和 Touch 2 建两个独立绑定函数或者用 Enhanced Input 的 Swipe / Pinch 组合 Axis。5.5 元数据导致的多余开销反射和序列化最后提醒一个容易忽略的性能点UPROPERTY 不是白用的。被反射的属性会被引擎追踪序列化、网络复制、GC 都要参与所以不要给不必要暴露的内部缓存变量也挂 UPROPERTY否则存档体积会变大网络同步的带宽也会白白消耗。我见过一个项目程序员图省事把类里所有变量一键全标了 BlueprintReadWrite EditAnywhere结果单局存档体积直接涨了 30%网络属性同步还多传了很多没用字段。正确的做法是每个 UPROPERTY 都要问一句蓝图真的需要访问它吗如果只是 C 内部用的就别加 UPROPERTY让它做普通 C 成员变量性能和性能反射开销都会更低。同理UFUNCTION 也不要全文暴露。内部计算函数标 BlueprintCallable 除了让蓝图界面变乱还会让函数调用做一层额外的 thunk 包装性能虽然损耗不大但架构层面暴露面太广后续改起接口来非常痛苦。写在最后的个人体会做 Unreal 项目这么多年我越来越觉得元数据与其说是一堆关键字不如说是一份“C 选择暴露什么、隐藏什么”的契约。蓝图侧看到的节点列表、属性面板、事件列表本质都是这份契约的呈现。一个项目如果 C 暴露接口混乱蓝图侧一定混乱反过来一个 C 类如果元数据设计精心蓝图侧几乎不需要文档也能顺畅使用。我现在的习惯是每写完一个类都会在建一个临时蓝图里实际拖一遍暴露出来的函数和属性用策划的视角问自己——这个名字清楚吗这个参数好填吗这个属性该不该被编辑这个方法真的需要蓝图调用还是内部逻辑十几分钟的自审能省掉后续大量的沟通成本。如果你现在正卡在某个节点搜不到、某个事件不触发、某个属性莫名丢失希望这篇文章能帮你把排查思路理顺。下一期《Unreal 对 C 做了什么》系列我想继续往反射系统深处走一层聊聊 UObject 的创建、销毁和 GC 到底是怎么运作的这也是很多 C 转 Unreal 的朋友最容易懵的一块。