蓝图编辑器使用指南

本指南介绍如何在 Cocos Creator 中使用蓝图可视化脚本编辑器。

下载与安装

下载

从 GitHub Release 下载最新版本（免费）：

技术交流 QQ 群：481923584 | 官网：esengine.cn

安装步骤

解压 cocos-node-editor.zip 到项目的 extensions 目录：

your-project/
├── assets/
├── extensions/
│   └── cocos-node-editor/    ← 解压到这里
└── ...

重启 Cocos Creator
通过菜单 扩展 → 扩展管理器 确认插件已启用
通过菜单 面板 → Node Editor 打开编辑器

界面介绍

工具栏 - 位于顶部，包含新建、打开、保存、撤销、重做等操作
变量面板 - 位于左上角，用于定义和管理蓝图变量
画布区域 - 主区域，用于放置和连接节点
节点菜单 - 右键点击画布空白处打开，按分类列出所有可用节点

画布操作

操作	方式
平移画布	鼠标中键拖拽 / Alt + 左键拖拽
缩放画布	鼠标滚轮
打开节点菜单	右键点击空白处
框选多个节点	在空白处拖拽
追加框选	Ctrl + 拖拽
删除选中	Delete 键

节点操作

添加节点

从节点面板拖拽 - 将节点从左侧面板拖到画布
右键菜单 - 右键点击画布空白处，选择节点

连接节点

从输出引脚拖拽到输入引脚
兼容类型的引脚会高亮显示
松开鼠标完成连接

引脚类型说明：

引脚颜色	类型	说明
白色 ▶	Exec	执行流程（控制执行顺序）
青色 ◆	Entity	实体引用
紫色 ◆	Component	组件引用
浅蓝 ◆	String	字符串
绿色 ◆	Number	数值
红色 ◆	Boolean	布尔值
灰色 ◆	Any	任意类型

删除连接

点击连接线选中，按 Delete 键删除。

节点类型详解

事件节点 (Event)

事件节点是蓝图的入口点，当特定事件发生时触发执行。

节点	触发时机	输出
Event BeginPlay	蓝图开始运行时	Exec, Self (实体)
Event Tick	每帧执行	Exec, Delta Time
Event EndPlay	蓝图停止时	Exec

示例：游戏开始时打印消息

Event BeginPlay

Self

Exec

Message "游戏开始!"

实体节点 (Entity)

操作 ECS 实体的节点。

节点	功能	输入	输出
Get Self	获取当前实体	-	Entity
Create Entity	创建新实体	Exec, Name	Exec, Entity
Destroy Entity	销毁实体	Exec, Entity	Exec
Find Entity By Name	按名称查找	Name	Entity
Find Entities By Tag	按标签查找	Tag	Entity[]
Is Valid	检查实体有效性	Entity	Boolean
Get/Set Entity Name	获取/设置名称	Entity	String
Set Active	设置激活状态	Exec, Entity, Active	Exec

示例：创建新实体

Event BeginPlay

Create Entity

Exec

Name "Bullet"

Exec

Entity

Add Transform

Exec

Entity

组件节点 (Component)

访问和操作 ECS 组件。

节点	功能
Has Component	检查实体是否有指定组件
Get Component	获取组件实例
Add Component	添加组件到实体
Remove Component	移除组件
Get/Set Property	获取/设置组件属性

示例：修改 Transform 组件

Get Self

Entity

Get Component

Entity

Transform

Set Property

Exec

Target

x 100

流程控制节点 (Flow)

控制执行流程的节点。

Branch (分支)

条件判断，类似 if/else。

Branch

Exec

Condition

True

False

DoSomething

Exec

DoOtherThing

Exec

Sequence (序列)

按顺序执行多个分支。

Sequence

Exec

Then 0

Then 1

Then 2

Step 1

Exec

Step 2

Exec

Step 3

Exec

For Loop (循环)

循环执行指定次数。

For Loop

Exec

First Index 0

Last Index 10

Loop Body

Index

Completed

每次迭代执行

Exec

循环结束后执行

Exec

For Each (遍历)

遍历数组元素。

While Loop (条件循环)

当条件为真时持续循环。

Do Once (单次执行)

只执行一次，之后跳过。

Flip Flop (交替执行)

每次执行时交替触发 A 和 B 输出。

Gate (门)

可通过 Open/Close/Toggle 控制是否允许执行通过。

时间节点 (Time)

节点	功能	输出类型
Delay	延迟指定时间后继续执行	Exec
Get Delta Time	获取帧间隔时间	Number
Get Time	获取运行总时间	Number

示例：延迟 2 秒后执行

Event BeginPlay

Delay

Exec

Duration 2.0

Done

Exec

Msg "2秒后执行"

数学节点 (Math)

节点	功能
Add / Subtract / Multiply / Divide	四则运算
Abs	绝对值
Clamp	限制在范围内
Lerp	线性插值
Min / Max	最小/最大值
Random Range	随机数
Sin / Cos / Tan	三角函数

调试节点 (Debug)

节点	功能
Print	输出到控制台

变量系统

变量用于在蓝图中存储和共享数据。

创建变量

在变量面板点击 + 按钮
输入变量名称
选择变量类型
设置默认值（可选）

使用变量

拖拽到画布 - 创建 Get 或 Set 节点
Get 节点 - 读取变量值
Set 节点 - 写入变量值

变量类型

类型	说明	默认值
Boolean	布尔值	false
Number	数值	0
String	字符串	""
Entity	实体引用	null
Vector2	二维向量	(0, 0)
Vector3	三维向量	(0, 0, 0)

变量节点错误状态

如果删除了一个变量，但画布上还有引用该变量的节点：

节点会显示 红色边框 和 警告图标
需要重新创建变量或删除这些节点

节点分组

可以将多个节点组织到一个可视化组框中，便于整理复杂蓝图。

创建组

框选或 Ctrl+点击选中多个节点（至少 2 个）
右键点击选中的节点
选择 创建分组
组框会自动包裹所有选中的节点

组操作

操作	方式
移动组	拖拽组框头部，所有节点一起移动
取消分组	右键点击组框 → 取消分组

特性

动态大小：组框会自动调整大小以包裹所有节点
独立移动：可以单独移动组内的节点，组框会自动调整
仅编辑器：组是纯视觉组织，不影响运行时逻辑

快捷键

快捷键	功能
`Ctrl + S`	保存蓝图
`Ctrl + Z`	撤销
`Ctrl + Shift + Z`	重做
`Ctrl + C`	复制选中节点
`Ctrl + X`	剪切选中节点
`Ctrl + V`	粘贴节点
`Delete`	删除选中项
`Ctrl + A`	全选

保存与加载

保存蓝图

点击工具栏保存按钮
选择保存位置（必须保存在 assets/resources 目录下，否则 Cocos Creator 无法动态加载）
文件扩展名为 .blueprint.json

重要提示：蓝图文件必须放在 resources 目录下，游戏运行时才能通过 cc.resources.load() 加载。

加载蓝图

点击工具栏打开按钮
选择 .blueprint.json 文件

蓝图文件格式

蓝图保存为 JSON 格式，可与 @esengine/blueprint 运行时兼容：

{
  "version": 1,
  "type": "blueprint",
  "metadata": {
    "name": "PlayerController",
    "description": "玩家控制逻辑"
  },
  "variables": [],
  "nodes": [],
  "connections": []
}

实战示例

示例 1：移动控制

实现每帧移动实体：

Event Tick

Delta Time

Multiply

B (Speed) 100

Result

Set Property

Exec

Target

示例 2：生命值系统

受伤后检查死亡逻辑。Event OnDamage 是一个自定义事件节点，可以通过代码 vm.triggerCustomEvent('OnDamage', { damage: 50 }) 触发：

示例 3：延迟生成

每 2 秒生成一个敌人：

Event BeginPlay

Do N Times

Exec

N 10

Loop Body

Index

Completed

Delay

Exec

Duration 2.0

Done

Create Entity

Exec

Name "Enemy"

Entity

常见问题

Q: 节点无法连接？

检查引脚类型是否匹配。执行引脚（白色）只能连接执行引脚，数据引脚需要类型兼容。

Q: 蓝图不执行？

确保实体添加了 BlueprintComponent
确保场景添加了 BlueprintSystem
检查 autoStart 是否为 true
若脚本是普通 Cocos 组件（cc.Component，非 ECS 组件），改用 BlueprintRunner，见运行时集成

Q: 如何调试？

使用 Print 节点输出变量值到控制台。

下一步

ECS 节点参考 - 完整节点列表
自定义节点 - 创建自定义节点
运行时集成 - 蓝图虚拟机 API
实际示例 - 更多游戏逻辑示例