蓝图可视化脚本 (Blueprint)

@esengine/blueprint 提供与 ECS 框架深度集成的可视化脚本系统，支持通过节点式编程控制实体行为。

编辑器下载

Cocos Creator 蓝图编辑器插件（免费）：

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

安装运行时

npm install @esengine/blueprint

核心特性

ECS 深度集成 - 内置 Entity、Component 操作节点
组件自动节点生成 - 使用装饰器标记组件，自动生成 Get/Set/Call 节点
运行时蓝图执行 - 高效的虚拟机执行蓝图逻辑

快速开始

1. 添加蓝图系统

import { Scene, Core } from '@esengine/ecs-framework';
import { BlueprintSystem } from '@esengine/blueprint';

// 创建场景并添加蓝图系统
const scene = new Scene();
scene.addSystem(new BlueprintSystem());

// 设置场景
Core.setScene(scene);

2. 为实体添加蓝图

import { BlueprintComponent } from '@esengine/blueprint';

// 创建实体
const player = scene.createEntity('Player');

// 添加蓝图组件
const blueprint = new BlueprintComponent();
blueprint.blueprintAsset = await loadBlueprintAsset('player.blueprint.json');
blueprint.autoStart = true;
player.addComponent(blueprint);

3. 标记组件（自动生成蓝图节点）

import {
    BlueprintExpose,
    BlueprintProperty,
    BlueprintMethod
} from '@esengine/blueprint';
import { Component, ECSComponent } from '@esengine/ecs-framework';

@ECSComponent('Health')
@BlueprintExpose({ displayName: '生命值', category: 'gameplay' })
export class HealthComponent extends Component {
    @BlueprintProperty({ displayName: '当前生命值', type: 'float' })
    current: number = 100;

    @BlueprintProperty({ displayName: '最大生命值', type: 'float' })
    max: number = 100;

    @BlueprintMethod({
        displayName: '治疗',
        params: [{ name: 'amount', type: 'float' }]
    })
    heal(amount: number): void {
        this.current = Math.min(this.current + amount, this.max);
    }

    @BlueprintMethod({ displayName: '受伤' })
    takeDamage(amount: number): boolean {
        this.current -= amount;
        return this.current <= 0;
    }
}

标记后，蓝图编辑器中会自动出现以下节点：

Get Health - 获取 Health 组件
Get 当前生命值 - 获取 current 属性
Set 当前生命值 - 设置 current 属性
治疗 - 调用 heal 方法
受伤 - 调用 takeDamage 方法

ECS 集成架构

┌─────────────────────────────────────────────────────────────┐
│                         Core.update()                        │
│                              ↓                               │
│                    Scene.updateSystems()                     │
│                              ↓                               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                  BlueprintSystem                       │  │
│  │                                                        │  │
│  │  Matcher.all(BlueprintComponent)                       │  │
│  │                       ↓                                │  │
│  │  process(entities) → blueprint.tick() for each entity  │  │
│  │                       ↓                                │  │
│  │              BlueprintVM.tick(dt)                      │  │
│  │                       ↓                                │  │
│  │         Execute Event/ECS/Flow Nodes                   │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

节点类型

类别	说明	颜色
`event`	事件节点（BeginPlay, Tick, EndPlay）	红色
`entity`	ECS 实体操作	蓝色
`component`	ECS 组件访问	青色
`flow`	流程控制（Branch, Sequence, Loop）	灰色
`math`	数学运算	绿色
`time`	时间工具（Delay, GetDeltaTime）	青色
`debug`	调试工具（Print）	灰色

蓝图资产结构

蓝图保存为 .blueprint.json 文件：

interface BlueprintAsset {
    version: number;
    type: 'blueprint';
    metadata: {
        name: string;
        description?: string;
    };
    variables: BlueprintVariable[];
    nodes: BlueprintNode[];
    connections: BlueprintConnection[];
}

文档导航

编辑器使用指南 - Cocos Creator 蓝图编辑器教程
虚拟机 API - BlueprintVM 与 ECS 集成
ECS 节点参考 - 内置 ECS 操作节点
自定义节点 - 创建自定义 ECS 节点
蓝图组合 - 片段复用
实际示例 - ECS 游戏逻辑示例