docs(blueprint): fix Cocos editor integration guide (#444)
* 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
GitHub
11
.changeset/math-blueprint-nodes.md
Normal file
11
.changeset/math-blueprint-nodes.md
Normal 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)
|
||||||
@@ -110,89 +110,22 @@ Blueprints are saved as `.blueprint.json` files, fully compatible with runtime:
|
|||||||
|
|
||||||
## Running Blueprints in Game
|
## 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
|
```typescript
|
||||||
import { Component, ECSComponent, Property, Serialize } from '@esengine/ecs-framework';
|
import { BlueprintSystem } from '@esengine/blueprint';
|
||||||
import type { BlueprintAsset } from '@esengine/blueprint';
|
|
||||||
|
|
||||||
@ECSComponent('Blueprint')
|
// Add blueprint system during scene initialization
|
||||||
export class BlueprintComponent extends Component {
|
scene.addSystem(new BlueprintSystem());
|
||||||
@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;
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. Create Blueprint Execution System
|
### 2. Load Blueprint and Add to Entity
|
||||||
|
|
||||||
```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
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import { resources, JsonAsset } from 'cc';
|
import { resources, JsonAsset } from 'cc';
|
||||||
import { validateBlueprintAsset } from '@esengine/blueprint';
|
import { BlueprintComponent, validateBlueprintAsset, BlueprintAsset } from '@esengine/blueprint';
|
||||||
|
|
||||||
// Load blueprint asset
|
// Load blueprint asset
|
||||||
async function loadBlueprint(path: string): Promise<BlueprintAsset | null> {
|
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
|
| Property | Type | Description |
|
||||||
// During scene initialization
|
|----------|------|-------------|
|
||||||
scene.addSystem(new BlueprintExecutionSystem());
|
| `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
|
## Creating Custom Nodes
|
||||||
|
|
||||||
|
|||||||
@@ -110,89 +110,22 @@ npm install
|
|||||||
|
|
||||||
## 在游戏中运行蓝图
|
## 在游戏中运行蓝图
|
||||||
|
|
||||||
使用 ECS 系统方式管理和执行蓝图。
|
`@esengine/blueprint` 包已提供完整的 ECS 集成，包括 `BlueprintComponent` 和 `BlueprintSystem`，可以直接使用。
|
||||||
|
|
||||||
### 1. 定义蓝图组件
|
### 1. 添加蓝图系统到场景
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import { Component, ECSComponent, Property, Serialize } from '@esengine/ecs-framework';
|
import { BlueprintSystem } from '@esengine/blueprint';
|
||||||
import type { BlueprintAsset } from '@esengine/blueprint';
|
|
||||||
|
|
||||||
@ECSComponent('Blueprint')
|
// 在场景初始化时添加蓝图系统
|
||||||
export class BlueprintComponent extends Component {
|
scene.addSystem(new BlueprintSystem());
|
||||||
@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;
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. 创建蓝图执行系统
|
### 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. 加载蓝图并添加到实体
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import { resources, JsonAsset } from 'cc';
|
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> {
|
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()` | 清理蓝图资源 |
|
||||||
|
|
||||||
## 创建自定义节点
|
## 创建自定义节点
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user