ECS 节点参考

本文档提供蓝图系统所有内置节点的完整参考，包含可视化示例。

引脚类型说明

执行流 (Exec)

实体 (Entity)

组件 (Component)

数值 (Float)

字符串 (String)

布尔 (Boolean)

事件节点

生命周期事件

生命周期事件，作为蓝图执行的入口点：

节点	说明	输出
EventBeginPlay	蓝图启动时触发	Exec, Self (Entity)
EventTick	每帧触发	Exec, Delta Time
EventEndPlay	蓝图停止时触发	Exec

自定义事件

自定义事件节点允许你定义自己的事件，通过代码触发蓝图逻辑。

节点	说明	输出
EventCustom	自定义事件，通过代码触发	Exec, 自定义参数

创建自定义事件：

在蓝图编辑器中创建自定义事件节点时，需要设置：

• 事件名称 (eventName)：用于代码中触发事件
• 输出参数：事件传递的数据，如 damage、amount 等

通过代码触发自定义事件：

// 获取实体的蓝图组件
const blueprint = entity.getComponent(BlueprintComponent);

// 触发自定义事件，传递参数
blueprint.vm?.triggerCustomEvent('OnDamage', {
    damage: 50,
    source: attackerEntity
});

// 触发无参数事件
blueprint.vm?.triggerCustomEvent('OnPickup');

蓝图中接收事件数据：

自定义事件节点会将传递的参数作为输出引脚暴露：

Event OnDamage

Self

Damage

Print

Exec

Msg

常用自定义事件示例：

事件名	用途	参数示例
OnDamage	受到伤害	{ damage: number, source: Entity }
OnHeal	治疗	{ amount: number }
OnCollision	碰撞检测	{ other: Entity, point: Vector2 }
OnPickup	拾取物品	{ item: Entity }
OnInteract	交互	{ player: Entity }
OnDeath	死亡	{ killer: Entity }

示例：游戏初始化

Event BeginPlay

Self

Print

Exec

Message "游戏开始!"

示例：每帧移动

Event Tick

Delta Time

Multiply

A

B 100

Result

Set Property

Exec

Target

x

实体节点 (Entity)

操作 ECS 实体：

节点	说明	类型
Get Self	获取拥有此蓝图的实体	纯节点
Create Entity	在场景中创建新实体	执行节点
Destroy Entity	销毁指定实体	执行节点
Destroy Self	销毁自身实体	执行节点
Is Valid	检查实体是否有效	纯节点
Get Entity Name	获取实体名称	纯节点
Set Entity Name	设置实体名称	执行节点
Find Entity By Name	按名称查找实体	纯节点
Find Entities By Tag	按标签查找所有实体	纯节点

示例：创建子弹

Event BeginPlay

Self

Create Entity

Exec

Exec

Entity

Add Transform

Exec

Entity

组件节点 (Component)

读写组件属性：

节点	说明	类型
Get Component	从实体获取指定类型组件	纯节点
Has Component	检查实体是否拥有指定组件	纯节点
Add Component	为实体添加组件	执行节点
Remove Component	从实体移除组件	执行节点
Get Property	获取组件属性值	纯节点
Set Property	设置组件属性值	执行节点

示例：修改位置

Get Self

Entity

Get Component

Entity

Transform

Get Property

Target

x

流程控制节点

控制蓝图执行流程：

节点	说明
Branch	条件分支（if/else）
Sequence	按顺序执行多个分支
For Loop	指定次数循环
For Each	遍历数组元素
While Loop	条件循环
Do Once	仅执行一次
Flip Flop	交替执行 A/B
Gate	门控开关

示例：条件分支

Condition

Exec

Result

Branch

Exec

Cond

True

False

Print

Exec

Msg "是"

Print

Exec

Msg "否"

示例：For 循环

Event BeginPlay

For Loop

Exec

First 0

Last 10

Body

Index

Done

时间节点

节点	说明	输出
Delay	延迟执行指定秒数	Exec
Get Delta Time	获取帧间隔时间	Float
Get Time	获取运行总时间	Float

示例：延迟执行

Event BeginPlay

Delay

Exec

Duration 2.0

Done

Print

Exec

Msg "2秒后"

数学节点

基础运算

节点	说明	输入	输出
Add	加法	A, B	A + B
Subtract	减法	A, B	A - B
Multiply	乘法	A, B	A × B
Divide	除法	A, B	A / B
Modulo	取模	A, B	A % B

数学函数

节点	说明	输入	输出
Abs	绝对值	Value	|Value|
Sqrt	平方根	Value	√Value
Pow	幂运算	Base, Exp	Base^Exp
Floor	向下取整	Value	⌊Value⌋
Ceil	向上取整	Value	⌈Value⌉
Round	四舍五入	Value	round(Value)
Clamp	区间钳制	Value, Min, Max	min(max(V, Min), Max)
Lerp	线性插值	A, B, Alpha	A + (B-A) × Alpha
Min	取最小值	A, B	min(A, B)
Max	取最大值	A, B	max(A, B)

三角函数

节点	说明
Sin	正弦
Cos	余弦
Tan	正切
Asin	反正弦
Acos	反余弦
Atan	反正切
Atan2	二参数反正切

随机数

节点	说明	输入	输出
Random	随机浮点数 [0, 1)	-	Float
Random Range	范围内随机数	Min, Max	Float
Random Int	随机整数	Min, Max	Int

比较节点

节点	说明	输出
Equal	A == B	Boolean
Not Equal	A != B	Boolean
Greater	A > B	Boolean
Greater Or Equal	A >= B	Boolean
Less	A < B	Boolean
Less Or Equal	A <= B	Boolean

扩展数学节点

Vector2、Fixed32、FixedVector2、Color 等高级数学节点由 @esengine/ecs-framework-math 模块提供。

详见：数学库蓝图节点

示例：钳制数值

Random Range

Min 0

Max 100

Result

Clamp

Value

Min 20

Max 80

Result

变量节点

蓝图定义的变量会自动生成 Get 和 Set 节点：

节点	说明	类型
Get <变量名>	读取变量值	纯节点
Set <变量名>	设置变量值	执行节点

调试节点

节点	说明
Print	输出消息到控制台

相关文档

• 数学库蓝图节点 - Vector2、Fixed32、Color 等数学节点
• 蓝图编辑器指南 - 学习如何使用编辑器
• 自定义节点 - 创建自定义节点
• 蓝图虚拟机 - 运行时 API