unreal-blueprints

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unreal Blueprints (Visual Scripting)

Unreal Blueprints（可视化脚本）

Structure gameplay logic in Unreal Engine 5 Blueprints: pick the right graph, expose data cleanly, and choose a communication method that doesn't create hard-reference spaghetti. Targets UE 5.4+. (Blueprints are node graphs; the snippets below describe node flows.)

在Unreal Engine 5 Blueprints中构建游戏玩法逻辑：选择合适的图表、清晰暴露数据，并选择不会产生硬引用“意大利面代码”的通信方式。适用版本UE 5.4+。（Blueprints是节点图；以下代码片段描述节点流程。）

When to use

使用场景

Use when authoring a Blueprint Class, wiring the Event Graph (BeginPlay/Tick/overlap), using the Construction Script, creating variables/functions/macros, or choosing how two Blueprints communicate (Cast, Interface, or Event Dispatcher).
Use when the project has
```
*.uproject
```
and Blueprint
```
*.uasset
```
files, and the user works visually rather than in C++.

When not to use: performance-critical systems, large data structures, or anything that benefits from source control diffs and unit tests →

unreal-cpp-gameplay

. Player input mapping →

unreal-enhanced-input

. AI logic →

unreal-behavior-trees

适用于创建Blueprint类、连线事件图表（BeginPlay/Tick/重叠事件）、使用构造脚本、创建变量/函数/宏，或选择两个Blueprints间的通信方式（Cast、接口或事件调度器）时。
适用于项目包含
```
*.uproject
```
和Blueprint
```
*.uasset
```
文件，且用户采用可视化方式而非C++进行开发的场景。

**不适用场景：**性能关键系统、大型数据结构，或任何受益于版本控制差异对比和单元测试的内容 → 请使用

unreal-cpp-gameplay

。玩家输入映射 → 请使用

unreal-enhanced-input

。AI逻辑 → 请使用

unreal-behavior-trees

。

Core workflow

核心工作流程

Choose the Blueprint type. A Blueprint Class (derived from Actor/Pawn/Character/ ActorComponent) defines a reusable object. The Level Blueprint is a per-level graph for level-specific scripting only — don't put reusable logic there.
Use the Construction Script for editor-time setup (procedural placement, configuring components from variables) — it runs when the actor is placed or edited, not during play.
Use the Event Graph for runtime logic.
```
Event BeginPlay
```
for init, input/overlap events for reactions. Avoid
```
Event Tick
```
unless you truly need per-frame work.
Expose data with variables; click the eye icon to make a variable Instance Editable, and group related ones with categories. Mark pure functions (no exec pin) for getters.
Pick a communication method by coupling (see Patterns): direct Cast for things you own, Blueprint Interface to call across types without hard references, Event Dispatcher to broadcast one-to-many.
Verify with the Blueprint debugger: drop breakpoints on nodes, watch variable values, and use Print String to confirm execution paths during Play In Editor (PIE).

选择Blueprint类型。Blueprint Class（派生自Actor/Pawn/Character/ActorComponent）定义可复用对象。Level Blueprint是每个关卡专属的图表，仅用于关卡特定脚本——请勿将可复用逻辑放在此处。
使用构造脚本进行编辑器阶段设置（程序化放置、通过变量配置组件）——它会在Actor被放置或编辑时运行，而非在游戏运行期间。
使用事件图表处理运行时逻辑。
```
Event BeginPlay
```
用于初始化，输入/重叠事件用于响应操作。除非确实需要每帧执行的操作，否则避免使用
```
Event Tick
```
。
通过变量暴露数据；点击眼睛图标将变量设置为“Instance Editable”（实例可编辑），并将相关变量按类别分组。将纯函数（无执行引脚）标记为获取器（getters）。
根据耦合度选择通信方式（参见模式部分）：直接Cast适用于你拥有的对象，Blueprint Interface用于跨类型调用且无硬引用，Event Dispatcher用于一对多广播。
使用Blueprint调试器验证：在节点上设置断点，监控变量值，并在编辑器内运行（PIE）期间使用Print String确认执行路径。

Patterns

模式

1. Reactive Event Graph (no Tick)

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

text

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

Prefer events (overlaps, timers, dispatchers) and Timelines over polling in Tick.

text

Event BeginPlay
  -> Set 'StartLocation' = GetActorLocation
  -> Bind Event to OnComponentBeginOverlap (TriggerVolume) [调用自定义事件OnEnterZone]

OnEnterZone (Other Actor)
  -> Branch: Other Actor == Player?
       True  -> Open Door (Timeline驱动旋转)   // 事件驱动，仅运行一次

优先使用事件（重叠、计时器、调度器）和Timeline，而非在Tick中轮询。

2. Direct reference + Cast (tight coupling, use sparingly)

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

text

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

Cast To

creates a hard reference to that class (it loads with this Blueprint). Fine when the caller genuinely depends on that type; otherwise prefer an Interface.

text

Overlapped Actor (Actor ref)
  -> Cast To BP_Player
       Cast Failed -> (不执行任何操作)
       Success     -> 调用BP_Player.ApplyDamage(10)

Cast To

会创建对该类的硬引用（该类会与此Blueprint一同加载）。当调用者确实依赖该类型时适用；否则优先使用接口。

3. Blueprint Interface (decoupled call)

3. Blueprint Interface（解耦调用）

text

// 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

text

// 1. 创建带有函数'Interact(Instigator)'的BPI_Interactable。
// 2. 将该接口添加到BP_Door、BP_Chest、BP_Lever，并在每个对象中实现'Interact'。
// 3. 调用者（持有任意Actor引用）：
Player presses Use
  -> Does Object Implement Interface (BPI_Interactable)?  // 安全检查，无需Cast/硬引用
       True -> 对Target Actor调用Interact (Message)

4. Event Dispatcher (one-to-many broadcast)

4. Event Dispatcher（一对多广播）

text

// 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.

text

// 在BP_Player中：声明事件调度器'OnHealthChanged (float NewHealth)'。
TakeDamage -> Set Health -> 调用'OnHealthChanged' (Health)   // 广播

// 在WBP_HUD的BeginPlay中：绑定事件到'OnHealthChanged' -> 更新生命值条。
// 多个监听器可绑定；玩家无需引用它们。

Pitfalls

常见陷阱

Cast spaghetti / long load times — chains of
```
Cast To
```
create hard references that pull whole asset trees into memory. Decouple with Interfaces or Dispatchers.
Logic in the Level Blueprint that should be reusable — it can't be reused across levels. Put it in a Blueprint Class.
Event Tick
overuse — every-frame nodes add up fast. Use events, Timers (
```
Set Timer by Event
```
), and Timelines instead.
Construction Script doing gameplay — it runs in the editor on edit/placement; spawning gameplay actors or starting logic there causes editor-only artifacts. Init in BeginPlay.
Variable not visible on the instance — toggle Instance Editable (the eye); to edit before spawn via Spawn node, also mark "Expose on Spawn".
Interface call did nothing — the target doesn't implement the interface; use "Does Implement Interface" before calling, or use the Message version which is safe on non-implementers.

Cast spaghetti / 加载时间过长 —— 链式
```
Cast To
```
会创建硬引用，将整个资源树拉入内存。使用接口或调度器解耦。
Level Blueprint中存放应复用的逻辑 —— 它无法跨关卡复用。请将逻辑放入Blueprint Class。
过度使用
Event Tick
—— 每帧执行的节点会快速累积性能开销。请改用事件、计时器（
```
Set Timer by Event
```
）和Timeline。
构造脚本处理游戏玩法逻辑 —— 它会在编辑器中于编辑/放置时运行；在此处生成游戏玩法Actor或启动逻辑会导致编辑器专属的异常问题。请在BeginPlay中初始化。
变量在实例上不可见 —— 切换“Instance Editable”（眼睛图标）；若要在通过Spawn节点生成前编辑变量，还需标记“Expose on Spawn”。
接口调用无响应 —— 目标未实现该接口；调用前使用“Does Implement Interface”检查，或使用Message版本（对未实现接口的对象调用也安全）。

References

参考资料

For a decision guide on Cast vs Interface vs Event Dispatcher and step-by-step dispatcher binding, read
```
references/communication.md
```
.

Primary docs: "Blueprints Visual Scripting" (

https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-blueprints-visual-scripting-in-unreal-engine

关于Cast vs Interface vs Event 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-blueprints

Original

Translation

Unreal Blueprints (Visual Scripting)

Unreal Blueprints（可视化脚本）

When to use

使用场景

Core workflow

核心工作流程

Patterns

模式

1. Reactive Event Graph (no Tick)

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

2. Direct reference + Cast (tight coupling, use sparingly)

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

3. Blueprint Interface (decoupled call)

3. Blueprint Interface（解耦调用）

4. Event Dispatcher (one-to-many broadcast)

4. Event Dispatcher（一对多广播）

Pitfalls

常见陷阱

References

参考资料

Related skills

相关技能