esengine/docs/src/content/docs/modules/blueprint/index.md

title, description

title	description
蓝图可视化脚本 (Blueprint)	与 ECS 框架深度集成的可视化脚本系统

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

编辑器下载

Cocos Creator 蓝图编辑器插件：

下载 Cocos Node Editor v1.0.0

详细使用教程请参考 编辑器使用指南。

安装运行时

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.bp');
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）	灰色

蓝图资产结构

蓝图保存为 .bp 文件：

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 游戏逻辑示例