CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(blueprint): fix Cocos editor integration guide (#444)

Browse Source 
* feat(math): add blueprint nodes for math library

- Add Vector2 blueprint nodes (Make, Break, arithmetic, Length, Normalize, Dot, Cross, Distance, Lerp, Rotate, FromAngle)
- Add Fixed32 blueprint nodes (conversions, arithmetic, math functions, comparison)
- Add FixedVector2 blueprint nodes (Make, Break, arithmetic, vector operations)
- Add Color blueprint nodes (Make, Break, conversions, color manipulation, constants)
- Add documentation with visual examples for all math blueprint nodes
- Update sidebar navigation to include math module

* fix(ci): adjust build order - blueprint before math

math package now depends on blueprint, so blueprint must be built first

* docs(blueprint): fix Cocos editor integration guide

- Remove redundant component/system implementations
- Users should use BlueprintComponent and BlueprintSystem from @esengine/blueprint
- Add BlueprintComponent properties and methods reference table
This commit is contained in:
YHH
2026-01-06 11:09:18 +08:00
committed by GitHub
parent e7d95dfdaf
commit fa593a3c69
3 changed files with 55 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.changeset/math-blueprint-nodes.md Normal file
View File

@@ -0,0 +1,11 @@
---
"@esengine/ecs-framework-math": minor
---
feat(math): add blueprint nodes for math library
- Add Vector2 blueprint nodes (Make, Break, Add, Sub, Mul, Length, Normalize, Dot, Cross, Distance, Lerp, Rotate, FromAngle)
- Add Fixed32 blueprint nodes (FromFloat, FromInt, ToFloat, ToInt, arithmetic operations, Abs, Sqrt, Floor, Ceil, Round, Sign, Min, Max, Clamp, Lerp)
- Add FixedVector2 blueprint nodes (Make, Break, Add, Sub, Mul, Negate, Length, Normalize, Dot, Cross, Distance, Lerp)
- Add Color blueprint nodes (Make, Break, FromHex, ToHex, FromHSL, ToHSL, Lerp, Lighten, Darken, Saturate, Desaturate, Invert, Grayscale, Luminance, constants)
- Add documentation for math blueprint nodes (Chinese and English)

101
docs/src/content/docs/en/modules/blueprint/cocos-editor.md
View File

@@ -110,89 +110,22 @@ Blueprints are saved as `.blueprint.json` files, fully compatible with runtime:
## Running Blueprints in Game
Use ECS system to manage and execute blueprints.
The `@esengine/blueprint` package provides complete ECS integration, including `BlueprintComponent` and `BlueprintSystem` ready to use.
### 1. Define Blueprint Component
### 1. Add Blueprint System to Scene
```typescript
import { Component, ECSComponent, Property, Serialize } from '@esengine/ecs-framework';
import type { BlueprintAsset } from '@esengine/blueprint';
import { BlueprintSystem } from '@esengine/blueprint';
@ECSComponent('Blueprint')
export class BlueprintComponent extends Component {
@Serialize()
@Property({ type: 'asset', label: 'Blueprint Asset' })
blueprintPath: string = '';
@Serialize()
@Property({ type: 'boolean', label: 'Auto Start' })
autoStart: boolean = true;
// Runtime data (not serialized)
blueprintAsset: BlueprintAsset | null = null;
vm: BlueprintVM | null = null;
isStarted: boolean = false;
}
// Add blueprint system during scene initialization
scene.addSystem(new BlueprintSystem());
```
### 2. Create Blueprint Execution System
```typescript
import { EntitySystem, Matcher, Entity } from '@esengine/ecs-framework';
import {
BlueprintVM,
validateBlueprintAsset
} from '@esengine/blueprint';
import { BlueprintComponent } from './BlueprintComponent';
export class BlueprintExecutionSystem extends EntitySystem {
constructor() {
super(Matcher.empty().all(BlueprintComponent));
}
protected override process(entities: readonly Entity[]): void {
const dt = Time.deltaTime;
for (const entity of entities) {
const bp = entity.getComponent(BlueprintComponent)!;
// Skip entities without blueprint asset
if (!bp.blueprintAsset) continue;
// Initialize VM
if (!bp.vm) {
bp.vm = new BlueprintVM(bp.blueprintAsset, entity, this.scene!);
}
// Auto start
if (bp.autoStart && !bp.isStarted) {
bp.vm.start();
bp.isStarted = true;
}
// Update blueprint
if (bp.isStarted) {
bp.vm.tick(dt);
}
}
}
protected override onRemoved(entity: Entity): void {
const bp = entity.getComponent(BlueprintComponent);
if (bp?.vm && bp.isStarted) {
bp.vm.stop();
bp.vm = null;
bp.isStarted = false;
}
}
}
```
### 3. Load Blueprint and Add to Entity
### 2. Load Blueprint and Add to Entity
```typescript
import { resources, JsonAsset } from 'cc';
import { validateBlueprintAsset } from '@esengine/blueprint';
import { BlueprintComponent, validateBlueprintAsset, BlueprintAsset } from '@esengine/blueprint';
// Load blueprint asset
async function loadBlueprint(path: string): Promise<BlueprintAsset | null> {
@@ -227,12 +160,22 @@ async function createBlueprintEntity(scene: IScene, blueprintPath: string): Prom
}
```
### 4. Register System to Scene
### BlueprintComponent Properties
```typescript
// During scene initialization
scene.addSystem(new BlueprintExecutionSystem());
```
| Property | Type | Description |
|----------|------|-------------|
| `blueprintAsset` | `BlueprintAsset \| null` | Blueprint asset data |
| `blueprintPath` | `string` | Blueprint asset path (for serialization) |
| `autoStart` | `boolean` | Auto-start execution (default `true`) |
| `debug` | `boolean` | Enable debug mode |
### BlueprintComponent Methods
| Method | Description |
|--------|-------------|
| `start()` | Manually start blueprint execution |
| `stop()` | Stop blueprint execution |
| `cleanup()` | Cleanup blueprint resources |
## Creating Custom Nodes

101
docs/src/content/docs/modules/blueprint/cocos-editor.md
View File

@@ -110,89 +110,22 @@ npm install
## 在游戏中运行蓝图
使用 ECS 系统方式管理和执行蓝图。
`@esengine/blueprint` 包已提供完整的 ECS 集成，包括 `BlueprintComponent` 和 `BlueprintSystem`，可以直接使用。
### 1. 定义蓝图组件
### 1. 添加蓝图系统到场景
```typescript
import { Component, ECSComponent, Property, Serialize } from '@esengine/ecs-framework';
import type { BlueprintAsset } from '@esengine/blueprint';
import { BlueprintSystem } from '@esengine/blueprint';
@ECSComponent('Blueprint')
export class BlueprintComponent extends Component {
@Serialize()
@Property({ type: 'asset', label: 'Blueprint Asset' })
blueprintPath: string = '';
@Serialize()
@Property({ type: 'boolean', label: 'Auto Start' })
autoStart: boolean = true;
// 运行时数据（不序列化）
blueprintAsset: BlueprintAsset | null = null;
vm: BlueprintVM | null = null;
isStarted: boolean = false;
}
// 在场景初始化时添加蓝图系统
scene.addSystem(new BlueprintSystem());
```
### 2. 创建蓝图执行系统
```typescript
import { EntitySystem, Matcher, Entity } from '@esengine/ecs-framework';
import {
BlueprintVM,
validateBlueprintAsset
} from '@esengine/blueprint';
import { BlueprintComponent } from './BlueprintComponent';
export class BlueprintExecutionSystem extends EntitySystem {
constructor() {
super(Matcher.empty().all(BlueprintComponent));
}
protected override process(entities: readonly Entity[]): void {
const dt = Time.deltaTime;
for (const entity of entities) {
const bp = entity.getComponent(BlueprintComponent)!;
// 跳过没有蓝图资产的实体
if (!bp.blueprintAsset) continue;
// 初始化 VM
if (!bp.vm) {
bp.vm = new BlueprintVM(bp.blueprintAsset, entity, this.scene!);
}
// 自动启动
if (bp.autoStart && !bp.isStarted) {
bp.vm.start();
bp.isStarted = true;
}
// 更新蓝图
if (bp.isStarted) {
bp.vm.tick(dt);
}
}
}
protected override onRemoved(entity: Entity): void {
const bp = entity.getComponent(BlueprintComponent);
if (bp?.vm && bp.isStarted) {
bp.vm.stop();
bp.vm = null;
bp.isStarted = false;
}
}
}
```
### 3. 加载蓝图并添加到实体
### 2. 加载蓝图并添加到实体
```typescript
import { resources, JsonAsset } from 'cc';
import { validateBlueprintAsset } from '@esengine/blueprint';
import { BlueprintComponent, validateBlueprintAsset, BlueprintAsset } from '@esengine/blueprint';
// 加载蓝图资产
async function loadBlueprint(path: string): Promise<BlueprintAsset | null> {
@@ -227,12 +160,22 @@ async function createBlueprintEntity(scene: IScene, blueprintPath: string): Prom
}
```
### 4. 注册系统到场景
### BlueprintComponent 属性
```typescript
// 在场景初始化时
scene.addSystem(new BlueprintExecutionSystem());
```
| 属性 | 类型 | 说明 |
|------|------|------|
| `blueprintAsset` | `BlueprintAsset \| null` | 蓝图资产数据 |
| `blueprintPath` | `string` | 蓝图资产路径（用于序列化） |
| `autoStart` | `boolean` | 是否自动开始执行（默认 `true`） |
| `debug` | `boolean` | 是否启用调试模式 |
### BlueprintComponent 方法
| 方法 | 说明 |
|------|------|
| `start()` | 手动开始执行蓝图 |
| `stop()` | 停止蓝图执行 |
| `cleanup()` | 清理蓝图资源 |
## 创建自定义节点