unreal-blueprints

Unreal Blueprints（可视化脚本）

在 Unreal Engine 5 Blueprints 中构建游戏逻辑：选择合适的图表，清晰地暴露数据，并选择不会造成硬引用混乱的通信方式。 目标版本为 UE 5.8。（Blueprint 是节点图；下方片段描述了节点流程。）

适用场景

• 编写 Blueprint Class、连接 Event Graph（BeginPlay/Tick/重叠事件）、使用 Construction Script、创建变量/函数/宏，或选择两个 Blueprint 的通信方式（Cast、Interface 或 Event Dispatcher）时。
• 项目包含 *.uproject 和 Blueprint *.uasset 文件，且用户采用可视化方式而非 C++ 开发时。

不适用场景： 性能关键型系统、大型数据结构，或适合通过源代码控制差异和单元测试的内容 → unreal-cpp-gameplay。玩家输入映射 → unreal-enhanced-input。AI 逻辑 → unreal-behavior-trees。

核心工作流

1. 选择 Blueprint 类型。 Blueprint Class（派生自 Actor/Pawn/Character/ActorComponent）定义可复用对象。Level Blueprint 是每个关卡各自拥有的图表，仅用于关卡专属脚本 — 不要在其中放置可复用逻辑。
2. 使用 Construction Script 进行编辑器时的设置（程序化放置、根据变量配置组件）— 它会在放置或编辑 Actor 时运行，而不是在游戏过程中运行。
3. 使用 Event Graph 编写运行时逻辑。 使用 Event BeginPlay 进行初始化，使用输入/重叠事件处理响应。除非确实需要逐帧执行操作，否则避免使用 Event Tick。
4. 使用变量暴露数据；点击眼睛图标，将变量设为 Instance Editable，并用分类对相关变量分组。将 getter 标记为纯函数（无 exec 引脚）。
5. 根据耦合程度选择通信方式（参见 Patterns）：对自己拥有的对象使用直接 Cast，跨类型调用且不建立硬引用时使用 Blueprint Interface，一对多广播时使用 Event Dispatcher。
6. 进行验证：使用 Blueprint 调试器在节点上添加断点、监视变量值，并在 Play In Editor (PIE) 期间使用 Print String 确认执行路径。

模式

1. 响应式 Event Graph（不使用 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 会创建对该类的硬引用（该类会随此 Blueprint 一同加载）。当调用方确实依赖该类型时，这种做法没问题；否则优先使用 Interface。

3. Blueprint Interface（解耦调用）

// 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. Event Dispatcher（一对多广播）

// 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 会创建硬引用，将整个资源树载入内存。使用 Interface 或 Dispatcher 解耦。
• 在 Level Blueprint 中编写本应可复用的逻辑 — 这些逻辑无法在多个关卡间复用。将其放入 Blueprint Class。
• 过度使用 Event Tick — 逐帧执行的节点会迅速累积。改用事件、计时器（Set Timer by Event）和 Timeline。
• 在 Construction Script 中编写游戏逻辑 — 它会在编辑器中于编辑/放置时运行；在其中生成游戏 Actor 或启动逻辑会导致仅编辑器中出现的异常。应在 BeginPlay 中初始化。
• 变量在实例上不可见 — 切换 Instance Editable（眼睛图标）；若要通过 Spawn 节点在生成前编辑，还要启用“Expose on Spawn”。
• Interface 调用未生效 — 目标对象未实现该 Interface；调用前使用“Does Implement Interface”，或使用对未实现者也安全的 Message 版本。

参考资料

• 有关 Cast、Interface 与 Event Dispatcher 的选择指南以及逐步绑定 Dispatcher 的说明，请阅读 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 — 由 Blueprints 触发的 AI 决策逻辑。