使用说明

概述

一、工作原理

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

二、相关类介绍

环境 类名 功能
引擎 engine.Game 游戏类,通过game.createWorkerJob()来创建任务
引擎 engine.WorkerJob 任务类,创建任务后获得该实例,可以控制任务启动停止等行为
worker Job 抽象类,代表一个任务的原型
<!-- 引擎 engine.Worker
<!-- worker EngineWorker

详细API请参考[workerAPI]

实例步骤

一、worker侧配置

  1. 建立worker文件夹

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

  2. 指定worker文件夹

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

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

  3. 添加worker任务

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

    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。
    构建npm

    然后正常构建项目即可。
    构建

注意事项

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

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

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

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