在微信小程序/小游戏中使用

基本使用

1、安装依赖

# 安装 Galacean Effects 的小程序/小游戏适配器
$ npm i @galacean/appx-adapter --save
# 安装 Galacean Effects
$ npm i @galacean/effects --save

2、在小程序中使用

<view style="width: 100vw; height: 100vh; background-color: black;">
  <canvas type="webgl"
          id="J-webglCanvas"
          style="width: 100%; height: 100%;">
  </canvas>
</view>

import { registerCanvas } from '@galacean/appx-adapter/weapp';
import { Player } from '@galacean/effects/weapp';

// 1. 使用 adapter 方法注册 canvas
// 第一种方式（推荐）：通过 ID 注册 canvas
const canvas = await registerCanvas({ id: '#J-webglCanvas' });
// 第二种方式 通过 Canvas 对象注册
const query = wx.createSelectorQuery();
const nodeCanvas = await new Promise(resolve => {
  query
    .select('#J-webglCanvas')
    .node()
    .exec(res => {
      resolve(res[0].node);
    });
});
const canvas = await registerCanvas({ id: nodeCanvas });

// 2. 通过创建的 canvas 对象实例化一个 Galacean Effects 播放器
const player = new Player({
  transparentBackground: true,
  canvas,
  pixelRatio: 2,
  renderFramework: 'webgl',
});

// 3. 加载资源并执行播放
await this.player.loadScene('url');

交互

如果需要响应点击、拖拽等交互，需要通过同层组件进行 UI 事件响应和转发。若遇到 iOS 上无法触发的问题，可以查阅：事件 | 微信开放文档 解决。

<view >
  <canvas  
    type="webgl" 
    id="J-webglCanvas" 
    style="width: 100%; height: 100%;" 
    disable-scroll="{{ true }}"
    bind:touchcancel="touchCancel" 
    bind:touchend="touchEnd" 
    bind:touchmove="touchMove" 
    bind:touchstart="touchStart">
  </canvas>
</view>

import {
  dispatchTouchStart,
  dispatchTouchMove,
  dispatchTouchEnd,
  dispatchTouchCancel,
} from '@galacean/appx-adapter/weapp';

Page({
  touchEnd(e) {
    dispatchTouchEnd(e);
  },
  touchStart(e) {
    dispatchTouchStart(e);
  },
  touchMove(e) {
    dispatchTouchMove(e);
  },
  touchcancel(e) {
    dispatchTouchCancel(e);
  },
});

插件使用

小程序中支持 GE 的 Spine、3D 模型插件，使用时需要安装下方对应的依赖：

$ npm i @galacean/effects-plugin-spine --save
$ npm i @galacean/effects-plugin-model --save

Spine

需要额外引入 Spine 插件包：

import { Player } from '@galacean/effects/weapp';
import '@galacean/effects-plugin-spine/weapp';

3D 模型

需要额外 3D 模型插件包：

import { Player } from '@galacean/effects/weapp';
import '@galacean/effects-plugin-model/weapp';

基于原生 js/ts 模版的小程序

1、获取依赖 lib

根据 demo 项目 main 分支的提示构建好 mp-weapp-galacean-effects.js 文件。

2、在小程序中使用

<view style="width: 100vw; height: 100vh; background-color: black">
  <canvas type="webgl"
          id="J-webglCanvas"
          style="width: 100%; height: 100%;">
  </canvas>
</view>

// 1. 引入 mp-weapp-galacean-effects.js 文件，~/libs 根据项目有所不同
import { adapter, Player } from '~/libs/mp-weapp-galacean-effects';

// 2. 使用 adapter 方法注册 canvas
const canvas = await adapter.registerCanvas({ id: '#J-webglCanvas' });
// 通过 Canvas 对象注册的方式见上面。

// 3. 通过创建的 canvas 对象实例化一个 Galacean Effects 播放器
const player = new Player({
  canvas,
  renderFramework: 'webgl',
});

// 4. 加载资源并执行播放
await this.player.loadScene('url');

通过 uni-app 使用

1、安装依赖

# 安装 Galacean Effects 的小程序/小游戏适配器
$ npm i @galacean/appx-adapter --save
# 安装 Galacean Effects
$ npm i @galacean/effects --save

2、使用示例

参考以下 Vue + Setup 语法 + Composition API + Typescript 技术栈的使用方式，按实际技术栈改写：

<template>
<view style="width: 100vw; height: 100vh;">
    <canvas
        type="webgl"
        id="J-webglCanvas"
        style="width: 100%; height: 100%; background-color: rgba(0, 0, 0, 0.6);"
        disable-scroll="{{ true }}">
    </canvas>
</view>
</template>

<script setup lang="ts">
import { onMounted, onBeforeUnmount } from 'vue';
import { registerCanvas } from '@galacean/appx-adapter/weapp';
import { Player } from '@galacean/effects/weapp';

let player: Player = null;

onMounted(async () => {
    try {
        // 1. 使用 adapter 方法注册 canvas
        const canvas = await registerCanvas({ id: '#J-webglCanvas' });
        // 2. 通过创建的 canvas 对象实例化一个 Galacean Effects 播放器
        player = new Player({
            canvas,
            renderFramework: 'webgl',
        });

        // 3. 加载资源并执行播放
        await player.loadScene('url');
    } catch (e) {
        console.error(`biz error: ${e}`);
    }
})

onBeforeUnmount(() => {
    player?.dispose();
})
</script>

<style>
/* 你的样式 */
</style>

关于自定义字体

由于微信小程序自定义字体的实现与 H5 不同，默认不支持 Galacean Effects 中使用自定义字体的文本特效，如果有自定义文本的特殊需求，可以按照以下方式实现。

1、在导出的 .json 文件中找到 fonts 字段

2、通过微信小程序相关接口手动接入字体

wx.loadFontFace({
  family: 'f_1_000_WYUE_MFJianHei-Regular',
  source: 'url("xxx")',
  scopes: ['webview', 'native'],
  success: (res) => {
    // 加载成功
    console.log(res.status);
  },
  fail: function(res) {
    // 加载失败
    console.log(res);
  },
  complete: function(res) {
    console.log(res.status);
  }
});

效果展示

常见问题

1、资源预加载报 timeout

由于小程序下 Image 对象是由 canvas.createImage 创建的，所以在 AssetManager.loadScene 之前要完成 canvas 的注册（即：registerCanvas），如下：

async onReady () {
  try {
    // 一定要在 assetManager.loadScene 之前完成注册
    const canvas = await registerCanvas({ id: '#J-webglCanvas' });
    const assetManager = new AssetManager();
    const scene = await assetManager.loadScene(json);
    
    this.player = new Player({
      canvas,
      renderFramework: 'webgl',
    });
    await this.player.loadScene(scene, { autoplay: false });
  } catch (e) {
    console.error(`biz error: ${e}`);
  }
},
handlePlay () {
  this.player?.play();
},

附：

• adapter 源码：https://github.com/galacean/appx-adapter