# 使用说明

# 概述

一、工作原理

• worker任务代码事先写在 worker 文件夹内，并由 worker 入口文件引用，最后以自定义的任务名来注册任务;
• 通过引擎来驱动，根据任务文件的路径来创建任务，并创建交互数据块，最后向 worker 发送任务信息;
• worker收到后开始跑任务，任务内容中更新交互数据块内的共享内存（通过wx.createSharedArrayBuffer()来创建）;
• 引擎每帧末会对交互数据块进行处理，获取 worker 的返回数据并更新输入数据。这个过程称为引擎的任务回调，任务回调进行时，worker一定不会正在跑该任务。
• 引擎通过和 worker 的通信来控制 worker 跑任务的时序，以及控制 worker 暂停、终止任务等行为。

二、相关类介绍

详细 API 请参考[workerAPI]

# 实例步骤

# 一、worker侧配置

1. 建立 worker 文件夹

   微信小游戏的 worker 只能用指定的文件夹内的代码，所以在项目内 assets 下任意位置建立一个 worker 专用文件夹。
   (例)建立assets/Scripts/worker文件夹
   

2. 指定 worker 文件夹

   在方案工具内的资源管理器里对该文件夹点击右键，选择"设置为 worker 文件夹"

   指定为 worker 文件夹后，会发现文件夹内多了一些文件，请不要手动修改这些文件。

3. 添加 worker 任务

   现在可以新建第一个 worker 任务了。
   在 worker 文件夹下新建脚本文件myJob.ts，
   
   输入以下代码：

   import { Job } from "engine-worker-env";
   
   export default class MyJob extends Job {
       protected init() {
           // customize init
       }
   
       protected update() {
           // real work
       }
   }
   

   任务的内容先省略，后面再回来填充。

# 二、引擎侧配置

这里默认您已经知道引擎如何使用了(包括如何写引擎脚本等)，如果您还不会使用引擎制作简易游戏，请先返回之前的文档进行学习。

1. 在需要的地方启动 worker 任务

   假如我们想要 worker 执行一个最简单的任务：每帧将一个值加1。
   在想要启动 worker 任务的时候，执行以下代码：

   // 定义引擎和 worker 进行交互的数据块
   const data = {
       num: wx.createSharedArrayBuffer(4);
   };
   const numView = new Float32Array(data.num.buffer);
   numView[0] = 0;
   
   // game.createWorkerJob的第一个参数对应 myJob.ts 的路径
   const job = game.createWorkerJob("myJob", data);
   
   // job.start()里定义了每帧 worker 任务结束之后引擎的任务回调
   job.start(() => { console.log(numView); });
   

   接下来只要去myJob.ts里完善任务内容就可以了。

2. 完善任务内容

   修改myJob.ts：

   import { Job } from "engine-worker-env";
   
   export default class MyJob extends Job {
       private numView: Float32Array;
   
       protected init() {
           // this.data就是引擎传递过来的交互数据块
           this.numView = new Float32Array(this.data.num.buffer);
       }
   
       protected update() {
           this.numView[0] = this.numView[0] + 1;
       }
   }
   

# 三、预览和构建

1. 预览

   在 IDE 里选择场景并预览之后，就能在控制台看到打印出来不断递增的数字了。

2. 构建
   先点击构建Npm。
   

   然后正常构建项目即可。
   

# 注意事项

• 在 worker 环境里只能访问 game.json 里指定的 worker 文件夹里的文件，不能 require 外面的脚本；同样也不能访问引擎的 npm 包，如果有需要的话请在 worker 文件夹里重新npm install一个；

• 在 worker 环境里不能访问引擎内的资源，想要访问引擎内资源只能在引擎侧的任务回调里，将引擎内资源手动序列化后填充至交互数据块内（在 worker 内访问部分引擎资源的功能计划作为新特性在未来加入）。

• 在引擎创建任务并启动之后，worker可能会在1~3帧之后才收到，所以引擎的任务回调可能会空跑几帧。关于 worker 有没有进行第一次任务，可以通过 WorkerJob 类的状态来判断，具体方法请参考[API]。

• 由于每个 job 拥有单独的通信开销，所以尽量不要建太多job。