插件开发

一般通过脚本组件的方式就可以实现大部分逻辑，涉及引擎级别或者业务级别的通用能力，可以使用插件的形式进行开发，插件主要是由 Component 和 System 组成。

Eva.js 的渲染是基于 PixiJS 的，一般 Img/Sprite/Spine 等插件实际上是创建了 Pixi 的渲染对象，像 Stats/EvaX/Transition 等插件不依赖 Pixi。不管是哪种插件都是输出 Component 和 System 给引擎使用，但是开发方案有一些不同，接下来我会先讲解最简单的插件开发方法。

我们提供了一个插件模板，可以点击 Use this Template 直接使用模版进行开发，里面带了必要的脚手架。

基础

开发

读到这里，相信大家已经对 Eva.js 有所了解并且知道如何在项目中使用了，下面是一个插件的简单的使用方法。

  1. import { Demo, DemoSystem } from './tutorials/lib'
  2. const game = new Game({
  3.   systems: [new DemoSystem()]
  4. })
  5. const go = new GameObject()
  6. go.addComponent(new Demo())
  7. game.scene.addChild(go)

我们可以看到，插件是由 Component 和 System 组成的，并且一个插件中不一定只包含一个 Component。

所以，开发插件需要实现暴露给用户使用的 Component 和 System。

插件运行逻辑

组件（Component）可以赋予游戏对象能力，我们将一些配置和属性记录在组件上。 系统（System）用来读取组件上面的数据，实现组件对应的能力。

当系统被添加到游戏实例上后，系统在它所需关心的组件在添加、移除、属性变化时，做一系列对应的操作，即可实现一些功能。

例如在 Img 插件中，当 Img 被添加到游戏对象上时，System 内会创建一个 Pixi 的 Sprite 对象，挂载到 GameObject 对应的 Pixi Container上，当 Img 组件的 resource 发生变化时，System 会去修改对应 Sprite 上面的 texture。

接下来，我会讲解如何设计一个组件，以及 System 是如何监听组件变化的。

构建与发布规范

开发实践

下面以 @eva/plugin-a11y 插件为例，对 Eva.js 插件开发做一个详细的介绍。

@eva/plugin-a11y 用于为游戏对象添加无障碍的能力。在 DOM 开发中，无障碍阅读器是可以阅读到 HTML 元素内容的，目前在 Canvas 里的绘制元素无法实现无障碍化的能力，@eva/plugin-a11y 插件通过定位游戏对象的位置，自动化地添加辅助 DOM，使得游戏对象能被无障碍阅读器聚焦，让游戏拥有无障碍功能。

首先设计 Component，既需要赋予游戏对象的能力。

使用案例

  1. import { A11y, A11ySystem } from '@eva/plugin-a11y'
  3. const game = new Game({
  4.   systems: [new A11ySystem()]
  5. })
  7. const go = new GameObject()
  9. go.addComponent(new A11y({
  10.   hint: '所需朗读的内容'
  11. }))
  13. game.scene.addChild(go)

Component 设计

  • 确定组件名称: A11y
  • 设计组件参数:
    • hint 需要朗读的内容
  1. import { Component } from '@eva/eva.js'
  2. export default class A11y extends Component {
  3.   static componentName: string = 'A11y' // 这里是Component的名称，用于 System 监听变化
  5.   /**
  6.    * 无障碍标签朗读内容
  7.    */
  8.   public hint: string
  10.   /**
  11.    * 初始化方法，构造函数的参数会传递到这里
  12.    */
  13.   init(param = {hint: ''}) {
  14.     const { hint } = param
  15.     this.hint = hint
  16.   }
  17. }

System 设计

  • 确定要监听的组件，以及需要监听哪些参数的变化
  • 确定系统名字
  • 根据组件变化实现逻辑

Step1 确定要监听的组件以及参数

  1. import { System, decorators } from '@eva/eva.js'
  3. @decorators.componentObserver({
  4.   A11y: ['hint'] // 监听 A11y 组件的 hint 属性变化
  5. })
  6. class A11ySystem extends System {
  8. }

在上面的代码中，我们将需要监听变化的组件名称和监听属性传入 @decorators.componentObserver 中，以便创建监听。

如果只需要监听组件添加移除可以不填写具体的属性，例如

  1. @decorators.componentObserver({
  2.   A11y: [] // 监听 A11y 组件的 hint 属性变化
  3. })

如果监听的属性不是直接挂载到组件对象上的，还有一级嵌套

例如监听组件 A 的 style 属性下的 size 属性

可以这样写：

  1. @decorators.componentObserver({
  2.   A: [{
  3.     prop: ['style', 'size']
  4.   }]
  5. })

如果想要深度监听 style 属性，可以这样写

  1. @decorators.componentObserver({
  2.   A: [{
  3.     prop: ['style'],
  4.     deep: true
  5.   }]
  6. })

如果想监听多个组件变化，可以这样写

  1. @decorators.componentObserver({
  2.   A: [{
  3.     prop: ['style'],
  4.     deep: true
  5.   }]
  6.   B: ['props']
  7. })

Step2 设置系统名字

给 System 设置名字

  1. import { System, decorators } from '@eva/eva.js'
  3. @decorators.componentObserver({
  4.   A11y: ['hint'] // 监听 A11y 组件的 hint 属性变化
  5. })
  6. class A11ySystem extends System {
  7.   static systemName = 'A11ySystem';
  8. }

Step3 根据组件变化实现逻辑

在此之前，我们做了一些监听配置，那么我们如何拿到对应的变化呢？

我们知道 System 有 update 生命周期，我们在生命周期中可以获取到当前帧 Component 的变化。

  1. import { System, decorators, ComponentChanged } from '@eva/eva.js'
  3. @decorators.componentObserver({
  4.   A11y: ['hint'] // 监听 A11y 组件的 hint 属性变化
  5. })
  6. class A11ySystem extends System {
  7.   static systemName = 'A11ySystem';
  8.   private elemMap = new Map()
  9.   update () {
  10.     const changes: ComponentChanged[] = this.componentObserver.clear() // 获取当前帧所有需要监听的组件大变化，并且进行清理
  11.     for (const changed of changes) {
  12.         switch (changed.type) {
  13.           case OBSERVER_TYPE.ADD:
  14.             this.add(changed);
  15.             break;
  16.           case OBSERVER_TYPE.CHANGE:
  17.             this.change(changed)
  18.             break;
  19.           case OBSERVER_TYPE.REMOVE:
  20.             this.remove(changed);
  21.             break;
  22.         }
  23.       }
  24.   }
  25.   add(changed) {
  26.     if (changed.componentName === 'A11y') { // 如果有多个Component的话需要分开处理
  27.       const component = changed.component as A11y
  28.       const elem = document.createElement('div')
  29.       elem.setAttribute('aria-label', component.hint);
  30.       this.elemMap.set(component, elem)
  31.       document.body.append(elem) // 添加到body上
  32.     }
  33.   }
  34.   remove(changed) {
  35.     if (changed.componentName === 'A11y') { // 如果有多个Component的话需要分开处理
  36.       const component = changed.component as A11y
  37.       const elem = this.elemMap.get(component)
  38.       elem.remove() // 移除elem
  39.     }
  40.   }
  41.   change(changed) {
  42.     if (changed.componentName === 'A11y') { // 如果有多个Component的话需要分开处理
  43.       if (changed.prop?.prop[0] === 'hint'){ //如果有多个监听属性需要分开处理
  44.         const component = changed.component as A11y
  45.         elem.setAttribute('aria-label', component.hint);
  46.       }
  47.     }
  48.   }
  49. }

ComponentChanged 对应的类型是这样的，可以参考，不需要在代码里实现

  1. export interface PureObserverProp {
  2.   deep: boolean;
  3.   prop: string[];
  4. }
  6. export enum ObserverType {
  7.   ADD = 'ADD',
  8.   REMOVE = 'REMOVE',
  9.   CHANGE = 'CHANGE',
  10. }
  12. export interface ComponentChanged {
  13.   type: ObserverType;
  14.   component: Component;
  15.   componentName: string;
  16.   prop?: PureObserverProp;
  17.   gameObject?: GameObject;
  18.   systemName?: string;
  19. }

现在我们把DOM创建好，并且放到了 body 上面，按照能力来讲，我们已经完成了具体的功能，因为屏幕阅读器已经可以阅读游戏中的元素了，但是看起来目前欠缺一些内容，例如：无法通过触发 DOM 点击事件来触发游戏里面的点击，DOM 的没有宽高和定位。

如果想实现这些功能，就要去在当前组件下拿到别的组件去实现功能了，如果想触发点击事件，需要判断 Event 组件是否安装，如果安装的话，可以根据 Event 上绑定的事件，触发对应的事件。如果想获取宽高位置的话，可以获取游戏对象的 Transform 组件

增加 Event 组件的监听，在上述 add remove 等方法里做对应操作即可。

  1. @decorators.componentObserver({
  2.   A11y: ['hint'] // 监听 A11y 组件的 hint 属性变化
  3.   Event: [] // Event 增加删除监听
  4. })
  5. class A11ySystem extends System {
  6. }

对于位置和宽高，可以在 A11y 组件被添加时拿到对应 GameObject 的 Transform，这里仅举个例子

  1. add(changed) {
  2.    if (changed.componentName === 'A11y') { // 如果有多个Component的话需要分开处理
  3.       const component = changed.component as A11y
  4.       const elem = document.createElement('div')
  5.       elem.setAttribute('aria-label', component.hint);
  6.       this.elemMap.set(component, elem)
  7.       document.body.append(elem) // 添加到body上
  10.       const transform = changed.gameObject.transform
  11.       elem.style.width = transform.size.width + 'px'
  12.       elem.style.height = transform.size.width + 'px'
  13.       elem.style.x = transform.position.x + 'px'
  14.       elem.style.y = transform.position.y + 'px'
  15.     }
  16. }

基于 PixiJS 的插件

以图片组件举例：

  1.   import {
  2.     GameObject,
  3.     decorators,
  4.     resource,
  5.     ComponentChanged,
  6.     RESOURCE_TYPE,
  7.     OBSERVER_TYPE,
  8.   } from '@eva/eva.js';
  9.   import {
  10.     RendererManager,
  11.     ContainerManager,
  12.     RendererSystem,
  13.     Renderer,
  14.   } from '@eva/plugin-renderer';
  16.   @decorators.componentObserver({
  17.     Img: [{prop: ['resource'], deep: false}],
  18.   })
  19.   export default class Img extends Renderer { // 基于 PixiJS 渲染的插件，我们的 System 需要继承于统一的一个 Renderer 类
  20.   rendererSystem: RendererSystem;
  21.   init() { // 在init中去获取 rendererSystem 以便后续添加 Pixi 对象，并且需要将当前系统注册到rendererManager中。
  22.     this.rendererSystem = this.game.getSystem(RendererSystem) as RendererSystem;
  23.     this.rendererSystem.rendererManager.register(this);
  24.   }
  25.   rendererUpdate(gameObject: GameObject) { // rendererUpdate 代替 Update 方法，因为update在 Renderer 类中已经实现
  26.     const {width, height} = gameObject.transform.size;
  27.     if (this.imgs[gameObject.id]) {
  28.       this.imgs[gameObject.id].sprite.width = width;
  29.       this.imgs[gameObject.id].sprite.height = height;
  30.     }
  31.   }
  33.   async componentChanged(changed: ComponentChanged) { // 在 Renderer 类中实现了 update 方法，并且将 Img 对应的组件变化传递给 componentChanged
  34.   if (changed.componentName === 'Img') {
  35.       const component: ImgComponent = changed.component as ImgComponent;
  36.       if (changed.type === OBSERVER_TYPE.ADD) {
  37.         const sprite = new Sprite(null);
  38.         resource.getResource(component.resource).then(({instance}) => {
  39.           if (!instance) {
  40.             console.error(
  41.               `GameObject:${changed.gameObject.name}'s Img resource load error`,
  42.             );
  43.           }
  44.           sprite.image = instance;
  45.         });
  46.         this.imgs[changed.gameObject.id] = sprite;
  47.         this.containerManager
  48.           .getContainer(changed.gameObject.id)
  49.           .addChildAt(sprite.sprite, 0); // 将创建的 Pixi 渲染对象放进 GameObject 对应的 Pixi 容器中
  50.       } else if (changed.type === OBSERVER_TYPE.CHANGE) {
  51.         const {instance} = await resource.getResource(component.resource);
  52.         if (!instance) {
  53.           console.error(
  54.             `GameObject:${changed.gameObject.name}'s Img resource load error`,
  55.           );
  56.         }
  57.         this.imgs[changed.gameObject.id].image = instance;
  58.       } else if (changed.type === OBSERVER_TYPE.REMOVE) {
  59.         const sprite = this.imgs[changed.gameObject.id];
  60.         this.containerManager
  61.           .getContainer(changed.gameObject.id)
  62.           .removeChild(sprite.sprite);
  63.         delete this.imgs[changed.gameObject.id];
  64.       }
  65.     }
  66.   }

生命周期

image.png

总结

通过 Component 和 System 的结合，我们可以实现各种各样的通用插件，在日常开发中，我们仅需要 CustomComponent 提供的能力开发游戏逻辑即可。