Merge pull request #445 from esengine/changeset-release/master

chore: release packages
Merge branch 'master' into changeset-release/master
2026-01-06 11:32:03 +08:00 · 2026-01-06 11:28:27 +08:00 · 2026-01-06 11:27:18 +08:00 · 2026-01-06 11:25:43 +08:00 · 2026-01-06 03:11:07 +00:00 · 2026-01-06 11:09:18 +08:00
12 changed files with 109 additions and 205 deletions
--- a/docs/src/content/docs/en/modules/blueprint/cocos-editor.md
+++ b/docs/src/content/docs/en/modules/blueprint/cocos-editor.md
@@ -7,37 +7,26 @@ This document explains how to install and use the blueprint visual scripting edi

 ## Installation

-### 1. Copy Extension to Project
+### 1. Download Extension

-Copy the `cocos-node-editor` extension to your Cocos Creator project's `extensions` directory:
+Download the `cocos-node-editor.zip` extension package from the release page.

-```
-your-project/
-├── assets/
-├── extensions/
-│   └── cocos-node-editor/    # Blueprint editor extension
-└── ...
-```
-
-### 2. Install Dependencies
-
-Install dependencies in the extension directory:
-
-```bash
-cd extensions/cocos-node-editor
-npm install
-```
-
-### 3. Enable Extension
+### 2. Import Extension

 1. Open Cocos Creator
 2. Go to **Extensions → Extension Manager**
-3. Find `cocos-node-editor` and enable it
+3. Click the **Import Extension** button
+4. Select the downloaded `cocos-node-editor.zip` file
+5. Enable the extension after importing

 ## Opening the Blueprint Editor

 Open the blueprint editor panel via menu **Panel → Node Editor**.

+### First Launch - Install Dependencies
+
+When opening the panel for the first time, the plugin will check if `@esengine/blueprint` is installed in your project. If not installed, it will display **"Missing required dependencies"** prompt. Click the **"Install Dependencies"** button to install automatically.
+
 ## Editor Interface

 ### Toolbar
@@ -110,89 +99,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 +149,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

--- a/docs/src/content/docs/modules/blueprint/cocos-editor.md
+++ b/docs/src/content/docs/modules/blueprint/cocos-editor.md
@@ -7,37 +7,26 @@ description: "在 Cocos Creator 中使用蓝图可视化脚本系统"

 ## 安装扩展

-### 1. 复制扩展到项目
+### 1. 下载扩展

-将 `cocos-node-editor` 扩展复制到你的 Cocos Creator 项目的 `extensions` 目录：
+从发布页面下载 `cocos-node-editor.zip` 扩展包。

-```
-your-project/
-├── assets/
-├── extensions/
-│   └── cocos-node-editor/    # 蓝图编辑器扩展
-└── ...
-```
-
-### 2. 安装依赖
-
-在扩展目录中安装依赖：
-
-```bash
-cd extensions/cocos-node-editor
-npm install
-```
-
-### 3. 启用扩展
+### 2. 导入扩展

 1. 打开 Cocos Creator
 2. 进入 **扩展 → 扩展管理器**
-3. 找到 `cocos-node-editor` 并启用
+3. 点击 **导入扩展包** 按钮
+4. 选择下载的 `cocos-node-editor.zip` 文件
+5. 导入后启用扩展

 ## 打开蓝图编辑器

 通过菜单 **面板 → Node Editor** 打开蓝图编辑器面板。

+### 首次打开 - 安装依赖
+
+首次打开面板时，插件会检测项目中是否安装了 `@esengine/blueprint` 依赖包。如果未安装，会显示 **"缺少必要的依赖包"** 提示，点击 **"安装依赖"** 按钮即可自动安装。
+
 ## 编辑器界面

 ### 工具栏
@@ -110,89 +99,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 +149,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()` | 清理蓝图资源 |

 ## 创建自定义节点

--- a/packages/framework/math/CHANGELOG.md
+++ b/packages/framework/math/CHANGELOG.md
@@ -1,5 +1,16 @@
 # @esengine/ecs-framework-math

+## 2.10.0
+
+### Minor Changes
+
+- [#444](https://github.com/esengine/esengine/pull/444) [`fa593a3`](https://github.com/esengine/esengine/commit/fa593a3c69292207800750f8106f418465cb7c0f) Thanks [@esengine](https://github.com/esengine)! - 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)
+
 ## 2.9.0

 ### Minor Changes
--- a/packages/framework/math/package.json
+++ b/packages/framework/math/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@esengine/ecs-framework-math",
-  "version": "2.9.0",
+  "version": "2.10.0",
  "description": "ECS框架2D数学库 - 提供向量、矩阵、几何形状和碰撞检测功能",
  "main": "bin/index.js",
  "types": "bin/index.d.ts",
--- a/packages/framework/network/CHANGELOG.md
+++ b/packages/framework/network/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @esengine/network

+## 12.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`fa593a3`](https://github.com/esengine/esengine/commit/fa593a3c69292207800750f8106f418465cb7c0f)]:
+    - @esengine/ecs-framework-math@2.10.0
+
 ## 11.0.0

 ### Patch Changes
--- a/packages/framework/network/package.json
+++ b/packages/framework/network/package.json
@@ -1,6 +1,6 @@
 {
    "name": "@esengine/network",
-    "version": "11.0.0",
+    "version": "12.0.0",
    "description": "Network synchronization for multiplayer games",
    "esengine": {
        "plugin": true,
--- a/packages/framework/pathfinding/CHANGELOG.md
+++ b/packages/framework/pathfinding/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @esengine/pathfinding

+## 11.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`fa593a3`](https://github.com/esengine/esengine/commit/fa593a3c69292207800750f8106f418465cb7c0f)]:
+    - @esengine/ecs-framework-math@2.10.0
+
 ## 10.0.0

 ### Patch Changes
--- a/packages/framework/pathfinding/package.json
+++ b/packages/framework/pathfinding/package.json
@@ -1,6 +1,6 @@
 {
    "name": "@esengine/pathfinding",
-    "version": "10.0.0",
+    "version": "11.0.0",
    "description": "寻路系统 | Pathfinding System - A*, Grid, NavMesh",
    "type": "module",
    "main": "./dist/index.js",
--- a/packages/framework/spatial/CHANGELOG.md
+++ b/packages/framework/spatial/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @esengine/spatial

+## 11.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`fa593a3`](https://github.com/esengine/esengine/commit/fa593a3c69292207800750f8106f418465cb7c0f)]:
+    - @esengine/ecs-framework-math@2.10.0
+
 ## 10.0.0

 ### Patch Changes
--- a/packages/framework/spatial/package.json
+++ b/packages/framework/spatial/package.json
@@ -1,6 +1,6 @@
 {
    "name": "@esengine/spatial",
-    "version": "10.0.0",
+    "version": "11.0.0",
    "description": "Spatial query and indexing system for ECS Framework / ECS 框架的空间查询和索引系统",
    "type": "module",
    "main": "./dist/index.js",
--- a/packages/tools/demos/CHANGELOG.md
+++ b/packages/tools/demos/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @esengine/demos

+## 1.0.17
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/pathfinding@11.0.0
+    - @esengine/spatial@11.0.0
+
 ## 1.0.16

 ### Patch Changes
--- a/packages/tools/demos/package.json
+++ b/packages/tools/demos/package.json
@@ -1,6 +1,6 @@
 {
    "name": "@esengine/demos",
-    "version": "1.0.16",
+    "version": "1.0.17",
    "private": true,
    "description": "Demo tests for ESEngine modules documentation",
    "type": "module",
Author	SHA1	Message	Date
YHH	7caa69a22e	Merge pull request #445 from esengine/changeset-release/master chore: release packages	2026-01-06 11:32:03 +08:00
YHH	5a5daf7565	Merge branch 'master' into changeset-release/master	2026-01-06 11:28:27 +08:00
YHH	3415737fcc	Merge pull request #446 from esengine/fix/cocos-editor-install-docs docs(blueprint): fix Cocos extension installation instructions	2026-01-06 11:27:18 +08:00
yhh	876312deb2	docs(blueprint): fix Cocos extension installation instructions - Change from manual copy to zip import via Extension Manager - Add first-launch dependency installation flow description - Plugin auto-detects and prompts to install @esengine/blueprint	2026-01-06 11:25:43 +08:00
github-actions[bot]	a790fc9e92	chore: release packages	2026-01-06 03:11:07 +00:00
YHH	fa593a3c69	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	2026-01-06 11:09:18 +08:00