dfd0dfc7f9
* feat(worker): 添加微信小游戏 Worker 支持和 Worker Generator CLI - 新增 @esengine/worker-generator 包，用于从 WorkerEntitySystem 生成 Worker 文件 - WorkerEntitySystem 添加 workerScriptPath 配置项，支持预编译 Worker 脚本 - CLI 工具支持 --wechat 模式，自动转换 ES6+ 为 ES5 语法 - 修复微信小游戏 Worker 消息格式差异（res 直接是数据，无需 .data） - 更新中英文文档，添加微信小游戏支持章节 * docs: 更新 changelog，添加 v2.3.1 说明并标注 v2.3.0 为废弃 * fix: 修复 CI 检查问题 - 移除 cli.ts 中未使用的 toKebabCase 函数 - 修复 generator.ts 中正则表达式的 ReDoS 风险（使用 [ \t] 替代 \s*） - 更新 changelog 版本号（2.3.1 -> 2.3.2） * docs: 移除未发布版本的 changelog 条目 * fix(worker-generator): 使用 TypeScript 编译器替代手写正则进行 ES5 转换 - 修复 CodeQL 检测的 ReDoS 安全问题 - 使用 ts.transpileModule 进行安全可靠的代码转换 - 移除所有可能导致回溯的正则表达式
138 lines
3.5 KiB
Markdown
138 lines
3.5 KiB
Markdown
# @esengine/worker-generator
|
|
|
|
CLI tool to generate Worker files from `WorkerEntitySystem` classes for WeChat Mini Game and other platforms that don't support dynamic Worker scripts.
|
|
|
|
## Why This Tool?
|
|
|
|
WeChat Mini Game has strict Worker limitations:
|
|
- Cannot create Workers from Blob URLs or dynamic scripts
|
|
- Worker scripts must be pre-compiled files in the code package
|
|
- Maximum 1 Worker allowed
|
|
|
|
This tool extracts your `workerProcess` method and generates compatible Worker files automatically.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install -D @esengine/worker-generator
|
|
# or
|
|
pnpm add -D @esengine/worker-generator
|
|
```
|
|
|
|
## Usage
|
|
|
|
### 1. Configure your WorkerEntitySystem
|
|
|
|
Add `workerScriptPath` to specify where the Worker file should be generated:
|
|
|
|
```typescript
|
|
@ECSSystem('Physics')
|
|
class PhysicsWorkerSystem extends WorkerEntitySystem<PhysicsData> {
|
|
constructor() {
|
|
super(Matcher.all(Position, Velocity), {
|
|
enableWorker: true,
|
|
workerScriptPath: 'workers/physics-worker.js', // Output path
|
|
systemConfig: {
|
|
gravity: 100,
|
|
friction: 0.95
|
|
}
|
|
});
|
|
}
|
|
|
|
protected workerProcess(
|
|
entities: PhysicsData[],
|
|
deltaTime: number,
|
|
config: any
|
|
): PhysicsData[] {
|
|
return entities.map(entity => {
|
|
entity.vy += config.gravity * deltaTime;
|
|
entity.x += entity.vx * deltaTime;
|
|
entity.y += entity.vy * deltaTime;
|
|
return entity;
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Run the Generator
|
|
|
|
```bash
|
|
# Basic usage
|
|
npx esengine-worker-gen --src ./src --wechat
|
|
|
|
# Full options
|
|
npx esengine-worker-gen \
|
|
--src ./src \ # Source directory to scan
|
|
--out ./workers \ # Default output directory (if no workerScriptPath)
|
|
--wechat \ # Generate WeChat Mini Game compatible code (ES5)
|
|
--mapping \ # Generate worker-mapping.json
|
|
--verbose # Verbose output
|
|
```
|
|
|
|
### 3. Configure game.json (WeChat Mini Game)
|
|
|
|
```json
|
|
{
|
|
"workers": "workers"
|
|
}
|
|
```
|
|
|
|
## CLI Options
|
|
|
|
| Option | Description | Default |
|
|
|--------|-------------|---------|
|
|
| `-s, --src <dir>` | Source directory to scan | `./src` |
|
|
| `-o, --out <dir>` | Output directory for Worker files | `./workers` |
|
|
| `-w, --wechat` | Generate WeChat Mini Game compatible code | `false` |
|
|
| `-m, --mapping` | Generate worker-mapping.json file | `true` |
|
|
| `-t, --tsconfig <path>` | Path to tsconfig.json | Auto-detect |
|
|
| `-v, --verbose` | Verbose output | `false` |
|
|
|
|
## Output
|
|
|
|
The tool generates:
|
|
|
|
1. **Worker files** - JavaScript files containing the extracted `workerProcess` logic
|
|
2. **worker-mapping.json** - Mapping of class names to Worker file paths
|
|
|
|
Example output:
|
|
```
|
|
workers/
|
|
├── physics-worker.js
|
|
└── worker-mapping.json
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
1. **Pure Functions**: Your `workerProcess` must be a pure function - it cannot use `this` or external variables
|
|
|
|
```typescript
|
|
// Correct
|
|
protected workerProcess(entities, deltaTime, config) {
|
|
return entities.map(e => {
|
|
e.y += config.gravity * deltaTime; // Use config parameter
|
|
return e;
|
|
});
|
|
}
|
|
|
|
// Wrong
|
|
protected workerProcess(entities, deltaTime, config) {
|
|
return entities.map(e => {
|
|
e.y += this.gravity * deltaTime; // Cannot access this!
|
|
return e;
|
|
});
|
|
}
|
|
```
|
|
|
|
2. **Re-run after changes**: Run the generator again after modifying `workerProcess`
|
|
|
|
3. **ES5 Conversion**: When using `--wechat`, the tool converts:
|
|
- Arrow functions → regular functions
|
|
- `const`/`let` → `var`
|
|
- Spread operator → `Object.assign`
|
|
- Template literals → string concatenation
|
|
|
|
## License
|
|
|
|
MIT
|