refactor: reorganize package structure and decouple framework packages (#338)

* refactor: reorganize package structure and decouple framework packages ## Package Structure Reorganization - Reorganized 55 packages into categorized subdirectories: - packages/framework/ - Generic framework (Laya/Cocos compatible) - packages/engine/ - ESEngine core modules - packages/rendering/ - Rendering modules (WASM dependent) - packages/physics/ - Physics modules - packages/streaming/ - World streaming - packages/network-ext/ - Network extensions - packages/editor/ - Editor framework and plugins - packages/rust/ - Rust WASM engine - packages/tools/ - Build tools and SDK ## Framework Package Decoupling - Decoupled behavior-tree and blueprint packages from ESEngine dependencies - Created abstracted interfaces (IBTAssetManager, IBehaviorTreeAssetContent) - ESEngine-specific code moved to esengine/ subpath exports - Framework packages now usable with Cocos/Laya without ESEngine ## CI Configuration - Updated CI to only type-check and lint framework packages - Added type-check:framework and lint:framework scripts ## Breaking Changes - Package import paths changed due to directory reorganization - ESEngine integrations now use subpath imports (e.g., '@esengine/behavior-tree/esengine') * fix: update es-engine file path after directory reorganization * docs: update README to focus on framework over engine * ci: only build framework packages, remove Rust/WASM dependencies * fix: remove esengine subpath from behavior-tree and blueprint builds ESEngine integration code will only be available in full engine builds. Framework packages are now purely engine-agnostic. * fix: move network-protocols to framework, build both in CI * fix: update workflow paths from packages/core to packages/framework/core * fix: exclude esengine folder from type-check in behavior-tree and blueprint * fix: update network tsconfig references to new paths * fix: add test:ci:framework to only test framework packages in CI * fix: only build core and math npm packages in CI * fix: exclude test files from CodeQL and fix string escaping security issue
2025-12-26 14:50:35 +08:00
parent a84ff902e4
commit 155411e743
1936 changed files with 4147 additions and 11578 deletions
--- a/README_CN.md
+++ b/README_CN.md
@@ -5,7 +5,7 @@
 </h1>

 <p align="center">
-  <strong>跨平台 2D 游戏引擎</strong>
+  <strong>TypeScript 模块化游戏框架</strong>
 </p>

 <p align="center">
@@ -23,55 +23,35 @@
 <p align="center">
  <a href="https://esengine.cn/">文档</a> ·
  <a href="https://esengine.cn/api/README">API 参考</a> ·
-  <a href="https://github.com/esengine/esengine/releases">下载编辑器</a> ·
  <a href="./examples/">示例</a>
 </p>

 ---

-> **只需要 ECS？** 核心 ECS 框架 [`@esengine/ecs-framework`](./packages/core/) 可独立使用，支持 Cocos Creator、Laya 或任何 JS 引擎。[查看 ECS 文档](./packages/core/README_CN.md)
+## ESEngine 是什么？

-## 概述
+ESEngine 是一套**引擎无关的游戏开发模块**，可与 Cocos Creator、Laya、Phaser、PixiJS 等任何 JavaScript 游戏引擎配合使用。

-ESEngine 是一款基于现代 Web 技术从零构建的跨平台 2D 游戏引擎。它提供完整的工具集，让开发者专注于游戏创作而非基础设施搭建。
-
-一套代码即可导出到 Web 浏览器、微信小游戏等多个平台。
-
-## 核心特性
-
-| 特性 | 描述 |
-|-----|------|
-| **ECS 架构** | 数据驱动的实体-组件-系统模式，提供灵活且缓存友好的游戏逻辑 |
-| **高性能渲染** | Rust/WebAssembly 2D 渲染器，支持自动精灵批处理和 WebGL 2.0 |
-| **可视化编辑器** | 基于 Tauri 的跨平台桌面编辑器，支持场景管理和资源工作流 |
-| **模块化设计** | 按需引入，每个功能都是独立的包 |
-| **多平台导出** | 一套代码部署到 Web、微信小游戏等平台 |
-| **物理集成** | 基于 Rapier 的 2D 物理，支持编辑器可视化 |
-| **可视化脚本** | 行为树和蓝图系统，适合策划使用 |
-
-## 技术栈
-
- **运行时**: TypeScript, Rust, WebAssembly
- **渲染器**: WebGL 2.0, WGPU (计划中)
- **编辑器**: Tauri, React, Zustand
- **物理**: Rapier2D
- **构建**: pnpm, Turborepo, Rollup
-
-## 许可证
-
-ESEngine **完全免费开源**，采用 [MIT 协议](LICENSE)。无版税，无附加条件。
-
-## 安装
-
-### npm
+核心是一个高性能的 **ECS（实体-组件-系统）** 框架，配套 AI、网络、物理等可选模块。

 ```bash
 npm install @esengine/ecs-framework
 ```

-### 编辑器
+## 功能模块

-从 [Releases](https://github.com/esengine/esengine/releases) 页面下载预编译版本（支持 Windows、macOS）。
+| 模块 | 描述 | 需要渲染引擎 |
+|------|------|:----------:|
+| **ECS 核心** | 实体-组件-系统框架，支持响应式查询 | 否 |
+| **行为树** | AI 行为树，支持可视化编辑 | 否 |
+| **蓝图** | 可视化脚本系统 | 否 |
+| **状态机** | 有限状态机 | 否 |
+| **定时器** | 定时器和冷却系统 | 否 |
+| **空间索引** | 空间查询（四叉树、网格） | 否 |
+| **寻路** | A* 和导航网格寻路 | 否 |
+| **网络** | 客户端/服务端网络通信 (TSRPC) | 否 |
+
+> 所有框架模块都可以独立使用，无需依赖特定渲染引擎。

 ## 快速开始

@@ -81,6 +61,7 @@ import {
    Matcher, Time, ECSComponent, ECSSystem
 } from '@esengine/ecs-framework';

+// 定义组件（纯数据）
@ECSComponent('Position')
 class Position extends Component {
    x = 0;
@@ -93,6 +74,7 @@ class Velocity extends Component {
    dy = 0;
 }

+// 定义系统（逻辑）
@ECSSystem('Movement')
 class MovementSystem extends EntitySystem {
    constructor() {
@@ -120,7 +102,7 @@ player.addComponent(new Velocity());

 Core.setScene(scene);

-// 游戏循环
+// 集成到你的游戏循环
 function gameLoop(currentTime: number) {
    Core.update(currentTime / 1000);
    requestAnimationFrame(gameLoop);
@@ -128,109 +110,126 @@ function gameLoop(currentTime: number) {
 requestAnimationFrame(gameLoop);
 ```

-## 模块
+## 与其他引擎配合使用

-ESEngine 采用 Monorepo 组织，包含 50+ 个模块化包。按需引入即可。
+ESEngine 的框架模块设计为可与你喜欢的渲染引擎配合使用：

-### 核心安装
+### 与 Cocos Creator 配合

-```bash
-npm install @esengine/ecs-framework  # ECS 核心（可独立使用）
-npm install @esengine/engine-core    # 完整引擎模块系统
+```typescript
+import { Component as CCComponent, _decorator } from 'cc';
+import { Core, Scene, Matcher, EntitySystem } from '@esengine/ecs-framework';
+import { BehaviorTreeExecutionSystem } from '@esengine/behavior-tree';
+
+const { ccclass } = _decorator;
+
+@ccclass('GameManager')
+export class GameManager extends CCComponent {
+    private ecsScene!: Scene;
+
+    start() {
+        Core.create();
+        this.ecsScene = new Scene();
+
+        // 添加 ECS 系统
+        this.ecsScene.addSystem(new BehaviorTreeExecutionSystem());
+        this.ecsScene.addSystem(new MyGameSystem());
+
+        Core.setScene(this.ecsScene);
+    }
+
+    update(dt: number) {
+        Core.update(dt);
+    }
+}
 ```

-### 常用模块
+### 与 Laya 配合
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import { FSMSystem } from '@esengine/fsm';
+
+class Main {
+    constructor() {
+        Core.create();
+        const scene = new Scene();
+        scene.addSystem(new FSMSystem());
+        Core.setScene(scene);
+
+        Laya.timer.frameLoop(1, this, this.update);
+    }
+
+    update() {
+        Core.update(Laya.timer.delta / 1000);
+    }
+}
+```
+
+## 包列表
+
+### 框架包（引擎无关）
+
+这些包**零渲染依赖**，可与任何引擎配合使用：
+
+```bash
+npm install @esengine/ecs-framework      # ECS 核心
+npm install @esengine/behavior-tree      # AI 行为树
+npm install @esengine/blueprint          # 可视化脚本
+npm install @esengine/fsm                # 状态机
+npm install @esengine/timer              # 定时器和冷却
+npm install @esengine/spatial            # 空间索引
+npm install @esengine/pathfinding        # 寻路
+npm install @esengine/network            # 网络
+```
+
+### ESEngine 运行时（可选）
+
+如果你需要完整的引擎解决方案：

 | 分类 | 包名 |
 |------|------|
-| **渲染** | `sprite`, `tilemap`, `particle`, `mesh-3d`, `fairygui` |
+| **核心** | `engine-core`, `asset-system`, `material-system` |
+| **渲染** | `sprite`, `tilemap`, `particle`, `camera`, `mesh-3d` |
 | **物理** | `physics-rapier2d` |
-| **AI 逻辑** | `behavior-tree`, `blueprint` |
-| **网络** | `network`, `network-server` |
 | **平台** | `platform-web`, `platform-wechat` |

-<details>
-<summary><b>查看全部 50+ 个包</b></summary>
+### 编辑器（可选）

-#### 核心
- `@esengine/ecs-framework` - ECS 框架核心
- `@esengine/math` - 向量、矩阵工具
- `@esengine/engine` - Rust/WASM 渲染器
- `@esengine/engine-core` - 模块生命周期
+基于 Tauri 构建的可视化编辑器：

-#### 运行时
- `@esengine/sprite` - 2D 精灵和动画
- `@esengine/tilemap` - 瓦片地图
- `@esengine/particle` - 粒子特效
- `@esengine/physics-rapier2d` - 2D 物理
- `@esengine/behavior-tree` - AI 行为树
- `@esengine/blueprint` - 可视化脚本
- `@esengine/camera` - 相机系统
- `@esengine/audio` - 音频播放
- `@esengine/fairygui` - FairyGUI 集成
- `@esengine/mesh-3d` - 3D 模型 (FBX/GLTF/OBJ)
- `@esengine/material-system` - 材质和着色器
- `@esengine/asset-system` - 资源管理
- `@esengine/world-streaming` - 大世界流式加载
+- 从 [Releases](https://github.com/esengine/esengine/releases) 下载
+- 支持行为树编辑、Tilemap 绘制、可视化脚本

-#### 网络
- `@esengine/network` - 客户端 (TSRPC)
- `@esengine/network-server` - 服务端运行时
- `@esengine/network-protocols` - 共享协议
+## 项目结构

-#### 编辑器扩展
-所有运行时模块都有对应的 `-editor` 包用于可视化编辑。
-
-#### 平台
- `@esengine/platform-common` - 平台抽象层
- `@esengine/platform-web` - Web 运行时
- `@esengine/platform-wechat` - 微信小游戏
-
-</details>
-
-## 编辑器
-
-ESEngine 编辑器是基于 Tauri 和 React 构建的跨平台桌面应用。
-
-### 功能
-
- 场景层级和实体管理
- 组件检视器，支持自定义属性编辑器
- 资源浏览器，支持拖放
- Tilemap 编辑器，支持绘制和填充工具
- 行为树可视化编辑器
- 蓝图可视化脚本
- 材质和着色器编辑
- 内置性能分析器
- 多语言支持（英文、中文）
-
-### 截图
-
-![ESEngine Editor](screenshots/main_screetshot.png)
-
-## 平台支持
-
-| 平台 | 运行时 | 编辑器 |
-|------|:------:|:------:|
-| Web 浏览器 | ✓ | - |
-| Windows | - | ✓ |
-| macOS | - | ✓ |
-| 微信小游戏 | 开发中 | - |
-| Playable 可玩广告 | 计划中 | - |
-| Android | 计划中 | - |
-| iOS | 计划中 | - |
+```
+esengine/
+├── packages/
+│   ├── framework/          # 引擎无关模块（可发布到 NPM）
+│   │   ├── core/          # ECS 框架
+│   │   ├── math/          # 数学工具
+│   │   ├── behavior-tree/ # AI 行为树
+│   │   ├── blueprint/     # 可视化脚本
+│   │   ├── fsm/           # 有限状态机
+│   │   ├── timer/         # 定时器系统
+│   │   ├── spatial/       # 空间查询
+│   │   ├── pathfinding/   # 寻路
+│   │   ├── procgen/       # 程序化生成
+│   │   └── network/       # 网络
+│   │
+│   ├── engine/            # ESEngine 运行时
+│   ├── rendering/         # 渲染模块
+│   ├── physics/           # 物理模块
+│   ├── editor/            # 可视化编辑器
+│   └── rust/              # WASM 渲染器
+│
+├── docs/                   # 文档
+└── examples/               # 示例
+```

 ## 从源码构建

-### 前置要求
-
- Node.js 18+
- pnpm 10+
- Rust 工具链（用于 WASM 渲染器）
- wasm-pack
-
-### 安装
-
 ```bash
 git clone https://github.com/esengine/esengine.git
 cd esengine
@@ -238,55 +237,29 @@ cd esengine
 pnpm install
 pnpm build

-# 可选：构建 WASM 渲染器
-pnpm build:wasm
+# 框架包类型检查
+pnpm type-check:framework
+
+# 运行测试
+pnpm test
 ```

-### 运行编辑器
-
-```bash
-cd packages/editor-app
-pnpm tauri:dev
-```
-
-### 项目结构
-
-```
-esengine/
-├── packages/
-│   ├── core/                    # ECS 框架 (@esengine/ecs-framework)
-│   ├── math/                    # 数学库 (@esengine/math)
-│   ├── engine-core/             # 引擎生命周期管理
-│   ├── sprite/                  # 2D 精灵渲染
-│   ├── tilemap/                 # Tilemap 系统
-│   ├── physics-rapier2d/        # 物理引擎
-│   ├── behavior-tree/           # AI 行为树
-│   ├── editor-app/              # 桌面编辑器 (Tauri)
-│   └── ...                      # 其他模块
-├── docs/                        # 文档源码
-├── examples/                    # 示例项目
-├── scripts/                     # 构建工具
-└── thirdparty/                  # 第三方依赖
-```
-
-> **寻找 ECS 源码？** ECS 框架位于 `packages/core/`
-
 ## 文档

- [快速入门](https://esengine.cn/guide/getting-started.html)
- [架构指南](https://esengine.cn/guide/)
+- [ECS 框架指南](./packages/framework/core/README.md)
+- [行为树指南](./packages/framework/behavior-tree/README.md)
 - [API 参考](https://esengine.cn/api/README)

 ## 社区

- [Discord](https://discord.gg/gCAgzXFW) - 国际社区
 - [QQ 交流群](https://jq.qq.com/?_wv=1027&k=29w1Nud6) - 中文社区
+- [Discord](https://discord.gg/gCAgzXFW) - 国际社区
 - [GitHub Issues](https://github.com/esengine/esengine/issues) - Bug 反馈和功能建议
 - [GitHub Discussions](https://github.com/esengine/esengine/discussions) - 问题和想法

 ## 贡献

-欢迎贡献代码。提交 PR 前请阅读贡献指南。
+欢迎贡献代码！提交 PR 前请阅读贡献指南。

 1. Fork 仓库
 2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
@@ -296,10 +269,10 @@ esengine/

 ## 许可证

-ESEngine 基于 [MIT 协议](LICENSE) 开源。
+ESEngine 基于 [MIT 协议](LICENSE) 开源，个人和商业使用均免费。

 ---

 <p align="center">
-  由 ESEngine 团队用 ❤️ 打造
+  由 ESEngine 社区用心打造
 </p>