Unreal 蓝图（可视化脚本）

在 Unreal Engine 5 蓝图中组织玩法逻辑：选择合适的图，干净地暴露数据，并选择不会造成硬引用意大利面的通信方式。目标 UE 5.8。（蓝图是节点图；下面的片段描述节点流程。）

何时使用

• 在编写蓝图类、连接事件图（BeginPlay/Tick/重叠）、使用构造脚本、创建变量/函数/宏，或选择两个蓝图如何通信（Cast、接口或事件分发器）时使用。
• 当项目包含 *.uproject 和蓝图 *.uasset 文件，并且用户以可视化方式而非 C++ 工作时使用。

何时不要使用：性能关键系统、大型数据结构，或任何受益于源代码控制差异和单元测试的内容 → unreal-cpp-gameplay。玩家输入映射 → unreal-enhanced-input。AI 逻辑 → unreal-behavior-trees。

核心工作流

1. 选择蓝图类型。 蓝图类（派生自 Actor/Pawn/Character/ActorComponent）定义可复用对象。关卡蓝图是每个关卡的图，仅用于特定关卡脚本——不要把可复用逻辑放在那里。
2. 使用构造脚本进行编辑器时设置（程序化放置、根据变量配置组件）——它在 actor 被放置或编辑时运行，*不是*在运行期间。
3. 使用事件图进行运行时逻辑。 用 Event BeginPlay 初始化，用输入/重叠事件响应。避免使用 Event Tick，除非确实需要逐帧工作。
4. 使用变量暴露数据；点击眼睛图标使变量成为 Instance Editable，并使用类别对相关变量分组。将 getter 标记为 pure 函数（没有 exec pin）。
5. 根据耦合选择通信方式（参见模式）：对你拥有的对象使用直接 Cast，使用 蓝图接口 在不产生硬引用的情况下跨类型调用，使用 事件分发器 进行一对多广播。
6. 验证：使用蓝图调试器：在节点上设置断点，观察变量值，并使用 Print String 确认在编辑器内运行（PIE）期间的执行路径。

模式

1. 响应式事件图（无 Tick）

Event BeginPlay
  -> Set 'StartLocation' = GetActorLocation
  -> Bind Event to OnComponentBeginOverlap (TriggerVolume) [calls custom event OnEnterZone]

OnEnterZone (Other Actor)
  -> Branch: Other Actor == Player?
       True  -> Open Door (Timeline drives the rotation)   // event-driven, runs once

优先使用事件（重叠、计时器、分发器）和 Timeline，而不是在 Tick 中轮询。

2. 直接引用 + Cast（紧耦合，谨慎使用）

Overlapped Actor (Actor ref)
  -> Cast To BP_Player
       Cast Failed -> (do nothing)
       Success     -> call BP_Player.ApplyDamage(10)

Cast To 会创建对该类的硬引用（它会随该蓝图加载）。当调用者确实依赖该类型时可以；否则优先使用接口。

3. 蓝图接口（解耦调用）

// 1. Create BPI_Interactable with function 'Interact(Instigator)'.
// 2. Add the interface to BP_Door, BP_Chest, BP_Lever and implement 'Interact' in each.
// 3. Caller, with any Actor ref:
Player presses Use
  -> Does Object Implement Interface (BPI_Interactable)?  // safe check, no Cast/hard ref
       True -> Interact (Message) on Target Actor

4. 事件分发器（一对多广播）

// In BP_Player: declare Event Dispatcher 'OnHealthChanged (float NewHealth)'.
TakeDamage -> Set Health -> Call 'OnHealthChanged' (Health)   // broadcast

// In WBP_HUD BeginPlay: Bind Event to 'OnHealthChanged' -> update health bar.
// Many listeners can bind; the player never references them.

陷阱

• Cast 意大利面 / 长时间加载 — Cast To 链会创建硬引用，把整个资源树拉入内存。使用接口或分发器解耦。
• 应该可复用的逻辑放在关卡蓝图中 — 它无法跨关卡复用。将其放入蓝图类。
• 过度使用 Event Tick — 逐帧节点会迅速累积。改用事件、计时器（Set Timer by Event）和时间线。
• 构造脚本执行玩法逻辑 — 它在编辑器中于编辑/放置时运行；在那里生成玩法 actor 或启动逻辑会导致仅编辑器产物。在 BeginPlay 中初始化。
• 变量在实例上不可见 — 切换 Instance Editable（眼睛图标）；若要在通过 Spawn 节点生成前编辑，还要标记 "Expose on Spawn"。
• 接口调用没有效果 — 目标未实现该接口；在调用前使用 "Does Implement Interface"，或使用 Message 版本，它对未实现者也是安全的。

参考

• 如需 Cast、接口与事件分发器 的决策指南以及逐步的分发器绑定说明，请阅读 references/communication.md。
• 主要文档："Blueprints Visual Scripting" (https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-blueprints-visual-scripting-in-unreal-engine)。

相关技能

• unreal-cpp-gameplay — 何时转向 C++；BP 与 C++ 类如何互操作。
• unreal-enhanced-input — 将输入事件馈入这些图的现代方式。
• unreal-behavior-trees — 由蓝图触发的 AI 决策逻辑。