Files

YHH dfd0dfc7f9 feat(worker): 添加微信小游戏 Worker 支持和 Worker Generator CLI (#297 )

* 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 进行安全可靠的代码转换
- 移除所有可能导致回溯的正则表达式

2025-12-08 17:02:11 +08:00

3.5 KiB

Raw Blame History

@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

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:

@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

# 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)

{
  "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:

Worker files - JavaScript files containing the extracted workerProcess logic
worker-mapping.json - Mapping of class names to Worker file paths

Example output:

workers/
├── physics-worker.js
└── worker-mapping.json

Important Notes

Pure Functions: Your workerProcess must be a pure function - it cannot use this or external variables

// 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;
  });
}

Re-run after changes: Run the generator again after modifying workerProcess
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

3.5 KiB Raw Blame History