docs(blueprint): add editor user guide with download link
- Add Chinese and English editor guide for Cocos Creator blueprint plugin - Add download link to GitHub Release in blueprint index pages - Add editor guide to sidebar navigation - Clarify blueprint files must be saved in resources directory
This commit is contained in:
yhh
@@ -232,6 +232,7 @@ export default defineConfig({
|
|||||||
translations: { en: 'Blueprint' },
|
translations: { en: 'Blueprint' },
|
||||||
items: [
|
items: [
|
||||||
{ label: '概述', slug: 'modules/blueprint', translations: { en: 'Overview' } },
|
{ label: '概述', slug: 'modules/blueprint', translations: { en: 'Overview' } },
|
||||||
|
{ label: '编辑器使用指南', slug: 'modules/blueprint/editor-guide', translations: { en: 'Editor Guide' } },
|
||||||
{ label: '虚拟机 API', slug: 'modules/blueprint/vm', translations: { en: 'VM API' } },
|
{ label: '虚拟机 API', slug: 'modules/blueprint/vm', translations: { en: 'VM API' } },
|
||||||
{ label: '自定义节点', slug: 'modules/blueprint/custom-nodes', translations: { en: 'Custom Nodes' } },
|
{ label: '自定义节点', slug: 'modules/blueprint/custom-nodes', translations: { en: 'Custom Nodes' } },
|
||||||
{ label: '内置节点', slug: 'modules/blueprint/nodes', translations: { en: 'Built-in Nodes' } },
|
{ label: '内置节点', slug: 'modules/blueprint/nodes', translations: { en: 'Built-in Nodes' } },
|
||||||
|
|||||||
388
docs/src/content/docs/en/modules/blueprint/editor-guide.md
Normal file
388
docs/src/content/docs/en/modules/blueprint/editor-guide.md
Normal file
@@ -0,0 +1,388 @@
|
|||||||
|
---
|
||||||
|
title: "Blueprint Editor User Guide"
|
||||||
|
description: "Complete guide for using the Cocos Creator Blueprint Visual Scripting Editor"
|
||||||
|
---
|
||||||
|
|
||||||
|
This guide covers how to use the Blueprint Visual Scripting Editor in Cocos Creator.
|
||||||
|
|
||||||
|
## Download & Installation
|
||||||
|
|
||||||
|
### Download
|
||||||
|
|
||||||
|
Download the latest version from GitHub Release:
|
||||||
|
|
||||||
|
**[Download Cocos Node Editor v1.0.0](https://github.com/esengine/esengine/releases/tag/cocos-node-editor-v1.0.0)**
|
||||||
|
|
||||||
|
### Installation Steps
|
||||||
|
|
||||||
|
1. Extract `cocos-node-editor.zip` to your project's `extensions` directory:
|
||||||
|
|
||||||
|
```
|
||||||
|
your-project/
|
||||||
|
├── assets/
|
||||||
|
├── extensions/
|
||||||
|
│ └── cocos-node-editor/ ← Extract here
|
||||||
|
└── ...
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Restart Cocos Creator
|
||||||
|
|
||||||
|
3. Confirm the plugin is enabled via **Extensions → Extension Manager**
|
||||||
|
|
||||||
|
4. Open the editor via **Panel → Node Editor**
|
||||||
|
|
||||||
|
## Interface Overview
|
||||||
|
|
||||||
|
- **Toolbar** - Located at the top, contains New, Open, Save, Undo, Redo operations
|
||||||
|
- **Node Panel** - Located on the left, lists all available nodes by category (Event, Entity, Component, Flow Control, etc.)
|
||||||
|
- **Canvas Area** - Main central area for placing and connecting nodes
|
||||||
|
- **Variables Panel** - Located at the bottom, for defining and managing blueprint variables
|
||||||
|
|
||||||
|
## Canvas Operations
|
||||||
|
|
||||||
|
| Operation | Method |
|
||||||
|
|-----------|--------|
|
||||||
|
| Pan canvas | Middle-click drag / Alt + Left-click drag |
|
||||||
|
| Zoom canvas | Mouse wheel |
|
||||||
|
| Open node menu | Right-click on empty space |
|
||||||
|
| Box select nodes | Drag on empty canvas |
|
||||||
|
| Additive select | Ctrl + Drag |
|
||||||
|
| Delete selected | Delete key |
|
||||||
|
|
||||||
|
## Node Operations
|
||||||
|
|
||||||
|
### Adding Nodes
|
||||||
|
|
||||||
|
1. **Drag from Node Panel** - Drag nodes from the left panel onto the canvas
|
||||||
|
2. **Right-click Menu** - Right-click on empty canvas space to select nodes
|
||||||
|
|
||||||
|
### Connecting Nodes
|
||||||
|
|
||||||
|
1. Drag from an output pin to an input pin
|
||||||
|
2. Compatible pins will highlight
|
||||||
|
3. Release to complete the connection
|
||||||
|
|
||||||
|
**Pin Type Reference:**
|
||||||
|
|
||||||
|
| Pin Color | Type | Description |
|
||||||
|
|-----------|------|-------------|
|
||||||
|
| White ▶ | Exec | Execution flow (controls order) |
|
||||||
|
| Cyan ◆ | Entity | Entity reference |
|
||||||
|
| Purple ◆ | Component | Component reference |
|
||||||
|
| Light Blue ◆ | String | String value |
|
||||||
|
| Green ◆ | Number | Numeric value |
|
||||||
|
| Red ◆ | Boolean | Boolean value |
|
||||||
|
| Gray ◆ | Any | Any type |
|
||||||
|
|
||||||
|
### Deleting Connections
|
||||||
|
|
||||||
|
Click a connection line to select it, then press Delete.
|
||||||
|
|
||||||
|
## Node Types Reference
|
||||||
|
|
||||||
|
### Event Nodes
|
||||||
|
|
||||||
|
Event nodes are entry points for blueprint execution, triggered when specific events occur.
|
||||||
|
|
||||||
|
| Node | Trigger | Outputs |
|
||||||
|
|------|---------|---------|
|
||||||
|
| **Event BeginPlay** | When blueprint starts | Exec, Self (Entity) |
|
||||||
|
| **Event Tick** | Every frame | Exec, Delta Time |
|
||||||
|
| **Event EndPlay** | When blueprint stops | Exec |
|
||||||
|
|
||||||
|
**Example: Print message on game start**
|
||||||
|
```
|
||||||
|
[Event BeginPlay] ──Exec──→ [Print]
|
||||||
|
└─ Message: "Game Started!"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Entity Nodes
|
||||||
|
|
||||||
|
Nodes for operating on ECS entities.
|
||||||
|
|
||||||
|
| Node | Function | Inputs | Outputs |
|
||||||
|
|------|----------|--------|---------|
|
||||||
|
| **Get Self** | Get current entity | - | Entity |
|
||||||
|
| **Create Entity** | Create new entity | Exec, Name | Exec, Entity |
|
||||||
|
| **Destroy Entity** | Destroy entity | Exec, Entity | Exec |
|
||||||
|
| **Find Entity By Name** | Find by name | Name | Entity |
|
||||||
|
| **Find Entities By Tag** | Find by tag | Tag | Entity[] |
|
||||||
|
| **Is Valid** | Check entity validity | Entity | Boolean |
|
||||||
|
| **Get/Set Entity Name** | Get/Set name | Entity | String |
|
||||||
|
| **Set Active** | Set active state | Exec, Entity, Active | Exec |
|
||||||
|
|
||||||
|
**Example: Create new entity**
|
||||||
|
```
|
||||||
|
[Event BeginPlay] ──→ [Create Entity] ──→ [Add Component]
|
||||||
|
└─ Name: "Bullet" └─ Type: Transform
|
||||||
|
```
|
||||||
|
|
||||||
|
### Component Nodes
|
||||||
|
|
||||||
|
Access and manipulate ECS components.
|
||||||
|
|
||||||
|
| Node | Function |
|
||||||
|
|------|----------|
|
||||||
|
| **Has Component** | Check if entity has component |
|
||||||
|
| **Get Component** | Get component instance |
|
||||||
|
| **Add Component** | Add component to entity |
|
||||||
|
| **Remove Component** | Remove component |
|
||||||
|
| **Get/Set Property** | Get/Set component property |
|
||||||
|
|
||||||
|
**Example: Modify Transform component**
|
||||||
|
```
|
||||||
|
[Get Self] ─Entity─→ [Get Component: Transform] ─Component─→ [Set Property]
|
||||||
|
├─ Property: x
|
||||||
|
└─ Value: 100
|
||||||
|
```
|
||||||
|
|
||||||
|
### Flow Control Nodes
|
||||||
|
|
||||||
|
Nodes that control execution flow.
|
||||||
|
|
||||||
|
#### Branch
|
||||||
|
|
||||||
|
Conditional branching, similar to if/else.
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─ True ──→ [DoSomething]
|
||||||
|
[Branch]─┤
|
||||||
|
└─ False ─→ [DoOtherThing]
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Sequence
|
||||||
|
|
||||||
|
Execute multiple branches in order.
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─ Then 0 ──→ [Step1]
|
||||||
|
[Sequence]─┼─ Then 1 ──→ [Step2]
|
||||||
|
└─ Then 2 ──→ [Step3]
|
||||||
|
```
|
||||||
|
|
||||||
|
#### For Loop
|
||||||
|
|
||||||
|
Execute a specified number of times.
|
||||||
|
|
||||||
|
```
|
||||||
|
[For Loop] ─Loop Body─→ [Execute each iteration]
|
||||||
|
│
|
||||||
|
└─ Completed ────→ [Execute after loop ends]
|
||||||
|
```
|
||||||
|
|
||||||
|
| Input | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| First Index | Starting index |
|
||||||
|
| Last Index | Ending index |
|
||||||
|
|
||||||
|
| Output | Description |
|
||||||
|
|--------|-------------|
|
||||||
|
| Loop Body | Execute each iteration |
|
||||||
|
| Index | Current index |
|
||||||
|
| Completed | Execute after loop ends |
|
||||||
|
|
||||||
|
#### For Each
|
||||||
|
|
||||||
|
Iterate over array elements.
|
||||||
|
|
||||||
|
#### While Loop
|
||||||
|
|
||||||
|
Loop while condition is true.
|
||||||
|
|
||||||
|
#### Do Once
|
||||||
|
|
||||||
|
Execute only once, skip afterwards.
|
||||||
|
|
||||||
|
#### Flip Flop
|
||||||
|
|
||||||
|
Alternate between A and B outputs each execution.
|
||||||
|
|
||||||
|
#### Gate
|
||||||
|
|
||||||
|
Control whether execution passes through via Open/Close/Toggle.
|
||||||
|
|
||||||
|
### Time Nodes
|
||||||
|
|
||||||
|
| Node | Function | Output Type |
|
||||||
|
|------|----------|-------------|
|
||||||
|
| **Delay** | Delay execution by specified time | Exec |
|
||||||
|
| **Get Delta Time** | Get frame delta time | Number |
|
||||||
|
| **Get Time** | Get total runtime | Number |
|
||||||
|
|
||||||
|
**Example: Execute after 2 second delay**
|
||||||
|
```
|
||||||
|
[Event BeginPlay] ──→ [Delay] ──→ [Print]
|
||||||
|
└─ Duration: 2.0 └─ "Executed after 2s"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Math Nodes
|
||||||
|
|
||||||
|
| Node | Function |
|
||||||
|
|------|----------|
|
||||||
|
| **Add / Subtract / Multiply / Divide** | Arithmetic operations |
|
||||||
|
| **Abs** | Absolute value |
|
||||||
|
| **Clamp** | Clamp to range |
|
||||||
|
| **Lerp** | Linear interpolation |
|
||||||
|
| **Min / Max** | Minimum/Maximum value |
|
||||||
|
| **Random Range** | Random number |
|
||||||
|
| **Sin / Cos / Tan** | Trigonometric functions |
|
||||||
|
|
||||||
|
### Debug Nodes
|
||||||
|
|
||||||
|
| Node | Function |
|
||||||
|
|------|----------|
|
||||||
|
| **Print** | Output to console |
|
||||||
|
|
||||||
|
## Variable System
|
||||||
|
|
||||||
|
Variables store and share data within a blueprint.
|
||||||
|
|
||||||
|
### Creating Variables
|
||||||
|
|
||||||
|
1. Click the **+** button in the Variables panel
|
||||||
|
2. Enter variable name
|
||||||
|
3. Select variable type
|
||||||
|
4. Set default value (optional)
|
||||||
|
|
||||||
|
### Using Variables
|
||||||
|
|
||||||
|
- **Drag to canvas** - Creates Get or Set node
|
||||||
|
- **Get Node** - Read variable value
|
||||||
|
- **Set Node** - Write variable value
|
||||||
|
|
||||||
|
### Variable Types
|
||||||
|
|
||||||
|
| Type | Description | Default |
|
||||||
|
|------|-------------|---------|
|
||||||
|
| Boolean | Boolean value | false |
|
||||||
|
| Number | Numeric value | 0 |
|
||||||
|
| String | String value | "" |
|
||||||
|
| Entity | Entity reference | null |
|
||||||
|
| Vector2 | 2D vector | (0, 0) |
|
||||||
|
| Vector3 | 3D vector | (0, 0, 0) |
|
||||||
|
|
||||||
|
### Variable Node Error State
|
||||||
|
|
||||||
|
If you delete a variable but nodes still reference it:
|
||||||
|
- Nodes display a **red border** and **warning icon**
|
||||||
|
- You need to recreate the variable or delete these nodes
|
||||||
|
|
||||||
|
## Keyboard Shortcuts
|
||||||
|
|
||||||
|
| Shortcut | Function |
|
||||||
|
|----------|----------|
|
||||||
|
| `Ctrl + S` | Save blueprint |
|
||||||
|
| `Ctrl + Z` | Undo |
|
||||||
|
| `Ctrl + Shift + Z` | Redo |
|
||||||
|
| `Ctrl + C` | Copy selected nodes |
|
||||||
|
| `Ctrl + X` | Cut selected nodes |
|
||||||
|
| `Ctrl + V` | Paste nodes |
|
||||||
|
| `Delete` | Delete selected items |
|
||||||
|
| `Ctrl + A` | Select all |
|
||||||
|
|
||||||
|
## Save & Load
|
||||||
|
|
||||||
|
### Saving Blueprints
|
||||||
|
|
||||||
|
1. Click the **Save** button in the toolbar
|
||||||
|
2. Choose save location (**must be saved in `assets/resources` directory**, otherwise Cocos Creator cannot load dynamically)
|
||||||
|
3. File extension is `.blueprint.json`
|
||||||
|
|
||||||
|
> **Important**: Blueprint files must be placed in the `resources` directory for runtime loading via `cc.resources.load()`.
|
||||||
|
|
||||||
|
### Loading Blueprints
|
||||||
|
|
||||||
|
1. Click the **Open** button in the toolbar
|
||||||
|
2. Select a `.blueprint.json` file
|
||||||
|
|
||||||
|
### Blueprint File Format
|
||||||
|
|
||||||
|
Blueprints are saved as JSON, compatible with `@esengine/blueprint` runtime:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": 1,
|
||||||
|
"type": "blueprint",
|
||||||
|
"metadata": {
|
||||||
|
"name": "PlayerController",
|
||||||
|
"description": "Player control logic"
|
||||||
|
},
|
||||||
|
"variables": [],
|
||||||
|
"nodes": [],
|
||||||
|
"connections": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Practical Examples
|
||||||
|
|
||||||
|
### Example 1: Movement Control
|
||||||
|
|
||||||
|
Move entity every frame:
|
||||||
|
|
||||||
|
```
|
||||||
|
[Event Tick] ─Exec─→ [Get Self] ─Entity─→ [Get Component: Transform]
|
||||||
|
│
|
||||||
|
[Get Delta Time] ▼
|
||||||
|
│ [Set Property: x]
|
||||||
|
│ │
|
||||||
|
[Multiply] ◄──────────────┘
|
||||||
|
│
|
||||||
|
└─ Speed: 100
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example 2: Health System
|
||||||
|
|
||||||
|
Check death after taking damage:
|
||||||
|
|
||||||
|
```
|
||||||
|
[On Damage Event] ─→ [Get Component: Health] ─→ [Get Property: current]
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[Subtract]
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[Set Property: current]
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ True ─→ [Destroy Self]
|
||||||
|
[Branch]─┤
|
||||||
|
└─ False ─→ (continue)
|
||||||
|
▲
|
||||||
|
│
|
||||||
|
[Less Or Equal]
|
||||||
|
│
|
||||||
|
current <= 0
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example 3: Delayed Spawning
|
||||||
|
|
||||||
|
Spawn an enemy every 2 seconds:
|
||||||
|
|
||||||
|
```
|
||||||
|
[Event BeginPlay] ─→ [Do N Times] ─Loop─→ [Delay: 2.0] ─→ [Create Entity: Enemy]
|
||||||
|
│
|
||||||
|
└─ N: 10
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Q: Nodes won't connect?
|
||||||
|
|
||||||
|
Check if pin types are compatible. Execution pins (white) can only connect to execution pins. Data pins need matching types.
|
||||||
|
|
||||||
|
### Q: Blueprint not executing?
|
||||||
|
|
||||||
|
1. Ensure entity has `BlueprintComponent` attached
|
||||||
|
2. Ensure scene has `BlueprintSystem` added
|
||||||
|
3. Check if `autoStart` is `true`
|
||||||
|
|
||||||
|
### Q: How to debug?
|
||||||
|
|
||||||
|
Use **Print** nodes to output variable values to the console.
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
- [ECS Node Reference](./nodes) - Complete node list
|
||||||
|
- [Custom Nodes](./custom-nodes) - Create custom nodes
|
||||||
|
- [Runtime Integration](./vm) - Blueprint VM API
|
||||||
|
- [Examples](./examples) - More game logic examples
|
||||||
@@ -5,7 +5,15 @@ description: "Visual scripting system deeply integrated with ECS framework"
|
|||||||
|
|
||||||
`@esengine/blueprint` provides a visual scripting system deeply integrated with the ECS framework, supporting node-based programming to control entity behavior.
|
`@esengine/blueprint` provides a visual scripting system deeply integrated with the ECS framework, supporting node-based programming to control entity behavior.
|
||||||
|
|
||||||
## Installation
|
## Editor Download
|
||||||
|
|
||||||
|
Blueprint Editor Plugin for Cocos Creator:
|
||||||
|
|
||||||
|
**[Download Cocos Node Editor v1.0.0](https://github.com/esengine/esengine/releases/tag/cocos-node-editor-v1.0.0)**
|
||||||
|
|
||||||
|
For detailed usage instructions, see [Editor User Guide](./editor-guide).
|
||||||
|
|
||||||
|
## Runtime Installation
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install @esengine/blueprint
|
npm install @esengine/blueprint
|
||||||
@@ -144,6 +152,7 @@ interface BlueprintAsset {
|
|||||||
|
|
||||||
## Documentation Navigation
|
## Documentation Navigation
|
||||||
|
|
||||||
|
- [Editor User Guide](./editor-guide) - Cocos Creator Blueprint Editor tutorial
|
||||||
- [Virtual Machine API](./vm) - BlueprintVM and ECS integration
|
- [Virtual Machine API](./vm) - BlueprintVM and ECS integration
|
||||||
- [ECS Node Reference](./nodes) - Built-in ECS operation nodes
|
- [ECS Node Reference](./nodes) - Built-in ECS operation nodes
|
||||||
- [Custom Nodes](./custom-nodes) - Create custom ECS nodes
|
- [Custom Nodes](./custom-nodes) - Create custom ECS nodes
|
||||||
|
|||||||
388
docs/src/content/docs/modules/blueprint/editor-guide.md
Normal file
388
docs/src/content/docs/modules/blueprint/editor-guide.md
Normal file
@@ -0,0 +1,388 @@
|
|||||||
|
---
|
||||||
|
title: "蓝图编辑器使用指南"
|
||||||
|
description: "Cocos Creator 蓝图可视化脚本编辑器完整使用教程"
|
||||||
|
---
|
||||||
|
|
||||||
|
本指南介绍如何在 Cocos Creator 中使用蓝图可视化脚本编辑器。
|
||||||
|
|
||||||
|
## 下载与安装
|
||||||
|
|
||||||
|
### 下载
|
||||||
|
|
||||||
|
从 GitHub Release 下载最新版本：
|
||||||
|
|
||||||
|
**[下载 Cocos Node Editor v1.0.0](https://github.com/esengine/esengine/releases/tag/cocos-node-editor-v1.0.0)**
|
||||||
|
|
||||||
|
### 安装步骤
|
||||||
|
|
||||||
|
1. 解压 `cocos-node-editor.zip` 到项目的 `extensions` 目录：
|
||||||
|
|
||||||
|
```
|
||||||
|
your-project/
|
||||||
|
├── assets/
|
||||||
|
├── extensions/
|
||||||
|
│ └── cocos-node-editor/ ← 解压到这里
|
||||||
|
└── ...
|
||||||
|
```
|
||||||
|
|
||||||
|
2. 重启 Cocos Creator
|
||||||
|
|
||||||
|
3. 通过菜单 **扩展 → 扩展管理器** 确认插件已启用
|
||||||
|
|
||||||
|
4. 通过菜单 **面板 → Node Editor** 打开编辑器
|
||||||
|
|
||||||
|
## 界面介绍
|
||||||
|
|
||||||
|
- **工具栏** - 位于顶部，包含新建、打开、保存、撤销、重做等操作
|
||||||
|
- **节点面板** - 位于左侧，按分类列出所有可用节点（事件、实体、组件、流程控制等）
|
||||||
|
- **画布区域** - 中间主区域，用于放置和连接节点
|
||||||
|
- **变量面板** - 位于底部，用于定义和管理蓝图变量
|
||||||
|
|
||||||
|
## 画布操作
|
||||||
|
|
||||||
|
| 操作 | 方式 |
|
||||||
|
|------|------|
|
||||||
|
| 平移画布 | 鼠标中键拖拽 / Alt + 左键拖拽 |
|
||||||
|
| 缩放画布 | 鼠标滚轮 |
|
||||||
|
| 打开节点菜单 | 右键点击空白处 |
|
||||||
|
| 框选多个节点 | 在空白处拖拽 |
|
||||||
|
| 追加框选 | Ctrl + 拖拽 |
|
||||||
|
| 删除选中 | Delete 键 |
|
||||||
|
|
||||||
|
## 节点操作
|
||||||
|
|
||||||
|
### 添加节点
|
||||||
|
|
||||||
|
1. **从节点面板拖拽** - 将节点从左侧面板拖到画布
|
||||||
|
2. **右键菜单** - 右键点击画布空白处，选择节点
|
||||||
|
|
||||||
|
### 连接节点
|
||||||
|
|
||||||
|
1. 从输出引脚拖拽到输入引脚
|
||||||
|
2. 兼容类型的引脚会高亮显示
|
||||||
|
3. 松开鼠标完成连接
|
||||||
|
|
||||||
|
**引脚类型说明：**
|
||||||
|
|
||||||
|
| 引脚颜色 | 类型 | 说明 |
|
||||||
|
|---------|------|------|
|
||||||
|
| 白色 ▶ | Exec | 执行流程（控制执行顺序） |
|
||||||
|
| 青色 ◆ | Entity | 实体引用 |
|
||||||
|
| 紫色 ◆ | Component | 组件引用 |
|
||||||
|
| 浅蓝 ◆ | String | 字符串 |
|
||||||
|
| 绿色 ◆ | Number | 数值 |
|
||||||
|
| 红色 ◆ | Boolean | 布尔值 |
|
||||||
|
| 灰色 ◆ | Any | 任意类型 |
|
||||||
|
|
||||||
|
### 删除连接
|
||||||
|
|
||||||
|
点击连接线选中，按 Delete 键删除。
|
||||||
|
|
||||||
|
## 节点类型详解
|
||||||
|
|
||||||
|
### 事件节点 (Event)
|
||||||
|
|
||||||
|
事件节点是蓝图的入口点，当特定事件发生时触发执行。
|
||||||
|
|
||||||
|
| 节点 | 触发时机 | 输出 |
|
||||||
|
|------|---------|------|
|
||||||
|
| **Event BeginPlay** | 蓝图开始运行时 | Exec, Self (实体) |
|
||||||
|
| **Event Tick** | 每帧执行 | Exec, Delta Time |
|
||||||
|
| **Event EndPlay** | 蓝图停止时 | Exec |
|
||||||
|
|
||||||
|
**示例：游戏开始时打印消息**
|
||||||
|
```
|
||||||
|
[Event BeginPlay] ──Exec──→ [Print]
|
||||||
|
└─ 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] ──→ [Add Component]
|
||||||
|
└─ Name: "Bullet" └─ Type: Transform
|
||||||
|
```
|
||||||
|
|
||||||
|
### 组件节点 (Component)
|
||||||
|
|
||||||
|
访问和操作 ECS 组件。
|
||||||
|
|
||||||
|
| 节点 | 功能 |
|
||||||
|
|------|------|
|
||||||
|
| **Has Component** | 检查实体是否有指定组件 |
|
||||||
|
| **Get Component** | 获取组件实例 |
|
||||||
|
| **Add Component** | 添加组件到实体 |
|
||||||
|
| **Remove Component** | 移除组件 |
|
||||||
|
| **Get/Set Property** | 获取/设置组件属性 |
|
||||||
|
|
||||||
|
**示例：修改 Transform 组件**
|
||||||
|
```
|
||||||
|
[Get Self] ─Entity─→ [Get Component: Transform] ─Component─→ [Set Property]
|
||||||
|
├─ Property: x
|
||||||
|
└─ Value: 100
|
||||||
|
```
|
||||||
|
|
||||||
|
### 流程控制节点 (Flow)
|
||||||
|
|
||||||
|
控制执行流程的节点。
|
||||||
|
|
||||||
|
#### Branch (分支)
|
||||||
|
|
||||||
|
条件判断，类似 if/else。
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─ True ──→ [DoSomething]
|
||||||
|
[Branch]─┤
|
||||||
|
└─ False ─→ [DoOtherThing]
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Sequence (序列)
|
||||||
|
|
||||||
|
按顺序执行多个分支。
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─ Then 0 ──→ [Step1]
|
||||||
|
[Sequence]─┼─ Then 1 ──→ [Step2]
|
||||||
|
└─ Then 2 ──→ [Step3]
|
||||||
|
```
|
||||||
|
|
||||||
|
#### For Loop (循环)
|
||||||
|
|
||||||
|
循环执行指定次数。
|
||||||
|
|
||||||
|
```
|
||||||
|
[For Loop] ─Loop Body─→ [每次迭代执行]
|
||||||
|
│
|
||||||
|
└─ Completed ────→ [循环结束后执行]
|
||||||
|
```
|
||||||
|
|
||||||
|
| 输入 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| First Index | 起始索引 |
|
||||||
|
| Last Index | 结束索引 |
|
||||||
|
|
||||||
|
| 输出 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| Loop Body | 每次迭代执行 |
|
||||||
|
| Index | 当前索引 |
|
||||||
|
| Completed | 循环结束后执行 |
|
||||||
|
|
||||||
|
#### 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] ──→ [Print]
|
||||||
|
└─ Duration: 2.0 └─ "2秒后执行"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 数学节点 (Math)
|
||||||
|
|
||||||
|
| 节点 | 功能 |
|
||||||
|
|------|------|
|
||||||
|
| **Add / Subtract / Multiply / Divide** | 四则运算 |
|
||||||
|
| **Abs** | 绝对值 |
|
||||||
|
| **Clamp** | 限制在范围内 |
|
||||||
|
| **Lerp** | 线性插值 |
|
||||||
|
| **Min / Max** | 最小/最大值 |
|
||||||
|
| **Random Range** | 随机数 |
|
||||||
|
| **Sin / Cos / Tan** | 三角函数 |
|
||||||
|
|
||||||
|
### 调试节点 (Debug)
|
||||||
|
|
||||||
|
| 节点 | 功能 |
|
||||||
|
|------|------|
|
||||||
|
| **Print** | 输出到控制台 |
|
||||||
|
|
||||||
|
## 变量系统
|
||||||
|
|
||||||
|
变量用于在蓝图中存储和共享数据。
|
||||||
|
|
||||||
|
### 创建变量
|
||||||
|
|
||||||
|
1. 在变量面板点击 **+** 按钮
|
||||||
|
2. 输入变量名称
|
||||||
|
3. 选择变量类型
|
||||||
|
4. 设置默认值（可选）
|
||||||
|
|
||||||
|
### 使用变量
|
||||||
|
|
||||||
|
- **拖拽到画布** - 创建 Get 或 Set 节点
|
||||||
|
- **Get 节点** - 读取变量值
|
||||||
|
- **Set 节点** - 写入变量值
|
||||||
|
|
||||||
|
### 变量类型
|
||||||
|
|
||||||
|
| 类型 | 说明 | 默认值 |
|
||||||
|
|------|------|--------|
|
||||||
|
| Boolean | 布尔值 | false |
|
||||||
|
| Number | 数值 | 0 |
|
||||||
|
| String | 字符串 | "" |
|
||||||
|
| Entity | 实体引用 | null |
|
||||||
|
| Vector2 | 二维向量 | (0, 0) |
|
||||||
|
| Vector3 | 三维向量 | (0, 0, 0) |
|
||||||
|
|
||||||
|
### 变量节点错误状态
|
||||||
|
|
||||||
|
如果删除了一个变量，但画布上还有引用该变量的节点：
|
||||||
|
- 节点会显示 **红色边框** 和 **警告图标**
|
||||||
|
- 需要重新创建变量或删除这些节点
|
||||||
|
|
||||||
|
## 快捷键
|
||||||
|
|
||||||
|
| 快捷键 | 功能 |
|
||||||
|
|--------|------|
|
||||||
|
| `Ctrl + S` | 保存蓝图 |
|
||||||
|
| `Ctrl + Z` | 撤销 |
|
||||||
|
| `Ctrl + Shift + Z` | 重做 |
|
||||||
|
| `Ctrl + C` | 复制选中节点 |
|
||||||
|
| `Ctrl + X` | 剪切选中节点 |
|
||||||
|
| `Ctrl + V` | 粘贴节点 |
|
||||||
|
| `Delete` | 删除选中项 |
|
||||||
|
| `Ctrl + A` | 全选 |
|
||||||
|
|
||||||
|
## 保存与加载
|
||||||
|
|
||||||
|
### 保存蓝图
|
||||||
|
|
||||||
|
1. 点击工具栏 **保存** 按钮
|
||||||
|
2. 选择保存位置（**必须保存在 `assets/resources` 目录下**，否则 Cocos Creator 无法动态加载）
|
||||||
|
3. 文件扩展名为 `.blueprint.json`
|
||||||
|
|
||||||
|
> **重要提示**：蓝图文件必须放在 `resources` 目录下，游戏运行时才能通过 `cc.resources.load()` 加载。
|
||||||
|
|
||||||
|
### 加载蓝图
|
||||||
|
|
||||||
|
1. 点击工具栏 **打开** 按钮
|
||||||
|
2. 选择 `.blueprint.json` 文件
|
||||||
|
|
||||||
|
### 蓝图文件格式
|
||||||
|
|
||||||
|
蓝图保存为 JSON 格式，可与 `@esengine/blueprint` 运行时兼容：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": 1,
|
||||||
|
"type": "blueprint",
|
||||||
|
"metadata": {
|
||||||
|
"name": "PlayerController",
|
||||||
|
"description": "玩家控制逻辑"
|
||||||
|
},
|
||||||
|
"variables": [],
|
||||||
|
"nodes": [],
|
||||||
|
"connections": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 实战示例
|
||||||
|
|
||||||
|
### 示例 1：移动控制
|
||||||
|
|
||||||
|
实现每帧移动实体：
|
||||||
|
|
||||||
|
```
|
||||||
|
[Event Tick] ─Exec─→ [Get Self] ─Entity─→ [Get Component: Transform]
|
||||||
|
│
|
||||||
|
[Get Delta Time] ▼
|
||||||
|
│ [Set Property: x]
|
||||||
|
│ │
|
||||||
|
[Multiply] ◄──────────────┘
|
||||||
|
│
|
||||||
|
└─ Speed: 100
|
||||||
|
```
|
||||||
|
|
||||||
|
### 示例 2：生命值系统
|
||||||
|
|
||||||
|
受伤后检查死亡：
|
||||||
|
|
||||||
|
```
|
||||||
|
[On Damage Event] ─→ [Get Component: Health] ─→ [Get Property: current]
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[Subtract]
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[Set Property: current]
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ True ─→ [Destroy Self]
|
||||||
|
[Branch]─┤
|
||||||
|
└─ False ─→ (继续)
|
||||||
|
▲
|
||||||
|
│
|
||||||
|
[Less Or Equal]
|
||||||
|
│
|
||||||
|
current <= 0
|
||||||
|
```
|
||||||
|
|
||||||
|
### 示例 3：延迟生成
|
||||||
|
|
||||||
|
每 2 秒生成一个敌人：
|
||||||
|
|
||||||
|
```
|
||||||
|
[Event BeginPlay] ─→ [Do N Times] ─Loop─→ [Delay: 2.0] ─→ [Create Entity: Enemy]
|
||||||
|
│
|
||||||
|
└─ N: 10
|
||||||
|
```
|
||||||
|
|
||||||
|
## 常见问题
|
||||||
|
|
||||||
|
### Q: 节点无法连接？
|
||||||
|
|
||||||
|
检查引脚类型是否匹配。执行引脚（白色）只能连接执行引脚，数据引脚需要类型兼容。
|
||||||
|
|
||||||
|
### Q: 蓝图不执行？
|
||||||
|
|
||||||
|
1. 确保实体添加了 `BlueprintComponent`
|
||||||
|
2. 确保场景添加了 `BlueprintSystem`
|
||||||
|
3. 检查 `autoStart` 是否为 `true`
|
||||||
|
|
||||||
|
### Q: 如何调试？
|
||||||
|
|
||||||
|
使用 **Print** 节点输出变量值到控制台。
|
||||||
|
|
||||||
|
## 下一步
|
||||||
|
|
||||||
|
- [ECS 节点参考](./nodes) - 完整节点列表
|
||||||
|
- [自定义节点](./custom-nodes) - 创建自定义节点
|
||||||
|
- [运行时集成](./vm) - 蓝图虚拟机 API
|
||||||
|
- [实际示例](./examples) - 更多游戏逻辑示例
|
||||||
@@ -5,7 +5,15 @@ description: "与 ECS 框架深度集成的可视化脚本系统"
|
|||||||
|
|
||||||
`@esengine/blueprint` 提供与 ECS 框架深度集成的可视化脚本系统，支持通过节点式编程控制实体行为。
|
`@esengine/blueprint` 提供与 ECS 框架深度集成的可视化脚本系统，支持通过节点式编程控制实体行为。
|
||||||
|
|
||||||
## 安装
|
## 编辑器下载
|
||||||
|
|
||||||
|
Cocos Creator 蓝图编辑器插件：
|
||||||
|
|
||||||
|
**[下载 Cocos Node Editor v1.0.0](https://github.com/esengine/esengine/releases/tag/cocos-node-editor-v1.0.0)**
|
||||||
|
|
||||||
|
详细使用教程请参考 [编辑器使用指南](./editor-guide)。
|
||||||
|
|
||||||
|
## 安装运行时
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install @esengine/blueprint
|
npm install @esengine/blueprint
|
||||||
@@ -144,6 +152,7 @@ interface BlueprintAsset {
|
|||||||
|
|
||||||
## 文档导航
|
## 文档导航
|
||||||
|
|
||||||
|
- [编辑器使用指南](./editor-guide) - Cocos Creator 蓝图编辑器教程
|
||||||
- [虚拟机 API](./vm) - BlueprintVM 与 ECS 集成
|
- [虚拟机 API](./vm) - BlueprintVM 与 ECS 集成
|
||||||
- [ECS 节点参考](./nodes) - 内置 ECS 操作节点
|
- [ECS 节点参考](./nodes) - 内置 ECS 操作节点
|
||||||
- [自定义节点](./custom-nodes) - 创建自定义 ECS 节点
|
- [自定义节点](./custom-nodes) - 创建自定义 ECS 节点
|
||||||
|
|||||||
Reference in New Issue
Block a user