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
This commit is contained in:
YHH
GitHub
215
packages/tools/build-config/README.md
Normal file
215
packages/tools/build-config/README.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# @esengine/build-config
|
||||
|
||||
ES Engine 统一构建配置包，提供标准化的 Vite 配置预设和共享插件。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 创建新包
|
||||
|
||||
使用脚手架工具快速创建新包：
|
||||
|
||||
```bash
|
||||
# 交互式创建
|
||||
node scripts/create-package.mjs
|
||||
|
||||
# 或指定参数
|
||||
node scripts/create-package.mjs my-plugin --type plugin
|
||||
```
|
||||
|
||||
### 包类型
|
||||
|
||||
| 类型 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `runtime-only` | 纯运行时库，不含编辑器代码 | core, math, components |
|
||||
| `plugin` | 插件包，同时有 runtime 和 editor 入口 | ui, tilemap, behavior-tree |
|
||||
| `editor-only` | 纯编辑器包，仅用于编辑器 | editor-core, node-editor |
|
||||
|
||||
## 使用预设
|
||||
|
||||
### 1. runtime-only（纯运行时包）
|
||||
|
||||
```typescript
|
||||
// vite.config.ts
|
||||
import { runtimeOnlyPreset } from '@esengine/build-config/presets';
|
||||
|
||||
export default runtimeOnlyPreset({
|
||||
root: __dirname
|
||||
});
|
||||
```
|
||||
|
||||
目录结构：
|
||||
```
|
||||
packages/my-lib/
|
||||
├── src/
|
||||
│ └── index.ts # 主入口
|
||||
├── vite.config.ts
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### 2. plugin（插件包）
|
||||
|
||||
```typescript
|
||||
// vite.config.ts
|
||||
import { pluginPreset } from '@esengine/build-config/presets';
|
||||
|
||||
export default pluginPreset({
|
||||
root: __dirname,
|
||||
hasCSS: true // 如果有 CSS 文件
|
||||
});
|
||||
```
|
||||
|
||||
目录结构：
|
||||
```
|
||||
packages/my-plugin/
|
||||
├── src/
|
||||
│ ├── index.ts # 主入口（导出全部）
|
||||
│ ├── runtime.ts # 运行时入口（不含 React!）
|
||||
│ ├── MyRuntimeModule.ts
|
||||
│ └── editor/
|
||||
│ ├── index.ts # 编辑器模块
|
||||
│ └── MyPlugin.ts
|
||||
├── plugin.json # 插件描述文件
|
||||
├── vite.config.ts
|
||||
└── package.json
|
||||
```
|
||||
|
||||
生成的 exports：
|
||||
```json
|
||||
{
|
||||
".": "./dist/index.js",
|
||||
"./runtime": "./dist/runtime.js",
|
||||
"./editor": "./dist/editor/index.js",
|
||||
"./plugin.json": "./plugin.json"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. editor-only（纯编辑器包）
|
||||
|
||||
```typescript
|
||||
// vite.config.ts
|
||||
import { editorOnlyPreset } from '@esengine/build-config/presets';
|
||||
|
||||
export default editorOnlyPreset({
|
||||
root: __dirname,
|
||||
hasReact: true,
|
||||
hasCSS: true
|
||||
});
|
||||
```
|
||||
|
||||
## 共享插件
|
||||
|
||||
### CSS 注入插件
|
||||
|
||||
将 CSS 内联到 JS 中，避免单独的 CSS 文件：
|
||||
|
||||
```typescript
|
||||
import { cssInjectPlugin } from '@esengine/build-config/plugins';
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [cssInjectPlugin()]
|
||||
});
|
||||
```
|
||||
|
||||
### 阻止编辑器代码泄漏
|
||||
|
||||
在运行时构建中检测并阻止编辑器代码被打包：
|
||||
|
||||
```typescript
|
||||
import { blockEditorPlugin } from '@esengine/build-config/plugins';
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [
|
||||
blockEditorPlugin({ bIsRuntimeBuild: true })
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
## Runtime vs Editor 分离规则
|
||||
|
||||
### ✅ runtime.ts 中可以：
|
||||
- 导入 @esengine/ecs-framework
|
||||
- 导入 @esengine/ecs-components
|
||||
- 导入其他包的 `/runtime` 路径
|
||||
|
||||
### ❌ runtime.ts 中不能：
|
||||
- 导入 `react`、`react-dom`
|
||||
- 导入 `@esengine/editor-core`
|
||||
- 导入 `lucide-react` 等 UI 库
|
||||
- 导入任何包的 `/editor` 路径
|
||||
|
||||
### 示例
|
||||
|
||||
```typescript
|
||||
// ✅ 正确
|
||||
import { Core } from '@esengine/ecs-framework';
|
||||
import { UIRuntimeModule } from '@esengine/ui/runtime';
|
||||
|
||||
// ❌ 错误 - 会把编辑器代码打包进来
|
||||
import { UIPlugin } from '@esengine/ui'; // 主入口包含编辑器
|
||||
import { UIPlugin } from '@esengine/ui/editor'; // 直接导入编辑器
|
||||
import React from 'react'; // React 不应在运行时
|
||||
```
|
||||
|
||||
## 迁移现有包
|
||||
|
||||
### 从 Rollup 迁移到 Vite 预设
|
||||
|
||||
1. 安装依赖：
|
||||
```bash
|
||||
pnpm add -D @esengine/build-config vite vite-plugin-dts
|
||||
```
|
||||
|
||||
2. 替换 `rollup.config.js` 为 `vite.config.ts`：
|
||||
```typescript
|
||||
import { pluginPreset } from '@esengine/build-config/presets';
|
||||
|
||||
export default pluginPreset({
|
||||
root: __dirname,
|
||||
hasCSS: true
|
||||
});
|
||||
```
|
||||
|
||||
3. 更新 `package.json` 的 scripts：
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"build": "vite build",
|
||||
"build:watch": "vite build --watch"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. 删除旧的 rollup 配置和依赖。
|
||||
|
||||
## API 参考
|
||||
|
||||
### runtimeOnlyPreset(options)
|
||||
|
||||
| 选项 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| root | string | - | 包根目录（必填） |
|
||||
| entry | string | 'src/index.ts' | 入口文件 |
|
||||
| external | (string\|RegExp)[] | [] | 额外的外部依赖 |
|
||||
| viteConfig | Partial<UserConfig> | {} | 额外的 Vite 配置 |
|
||||
|
||||
### pluginPreset(options)
|
||||
|
||||
| 选项 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| root | string | - | 包根目录（必填） |
|
||||
| entries.main | string | 'src/index.ts' | 主入口 |
|
||||
| entries.runtime | string | 'src/runtime.ts' | 运行时入口 |
|
||||
| entries.editor | string | 'src/editor/index.ts' | 编辑器入口 |
|
||||
| hasCSS | boolean | false | 是否包含 CSS |
|
||||
| hasPluginJson | boolean | true | 是否导出 plugin.json |
|
||||
| external | (string\|RegExp)[] | [] | 额外的外部依赖 |
|
||||
|
||||
### editorOnlyPreset(options)
|
||||
|
||||
| 选项 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| root | string | - | 包根目录（必填） |
|
||||
| entry | string | 'src/index.ts' | 入口文件 |
|
||||
| hasReact | boolean | true | 是否包含 React |
|
||||
| hasCSS | boolean | false | 是否包含 CSS |
|
||||
| external | (string\|RegExp)[] | [] | 额外的外部依赖 |
|
||||
Reference in New Issue
Block a user