esengine/packages/tools/worker-generator/README.md

@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:

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

   // 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