常见问题

想了解一下 Galacean Effects Studio 如何使用？

参考 用户文档。

如何快速预览动画？

https://www.galacean.com/effects/preview/

直接将导出的产物 ZIP 拖入上面的页面

播放尺寸不对怎么办？

参考 屏幕规则 。

播放太糊了怎么办？

参考 分辨率比率 ，将 pixelRatio 调大。

播放太卡、加载太忙、内存占用过高 怎么办？

参考 优化相关章节，包括 设计优化、加载优化、内存优化。

播放有黑边怎么办？

让设计同学在工程中有黑边的图片进行去黑边处理，如依然无法解决，请反馈解决。

发布失败了怎么办？

最常见的问题是图片资源过大，请参考 设计优化 章节进行处理。

Galacean Effects 和 Lottie 有什么区别？

相比于 Lottie，Galacean Effects 具有更多的功能和效果，如粒子、三维模型、Spine、特效等。同时相同的图层动画，Galacean Effects 在资源大小、内存占用上均有优势。Galacean Effects 也支持 Lottie 文件的导入。

Galacean Effects 会支持矢量动画或者形状补间动画吗？

中短期内不会支持。

运行时渲染不一致？

大部分情况下，渲染不一致都是由于使用的 Effects Runtime 版本不正确，永远使用最新的正式版本是正确的选择。当然你也可以用 Studio 的预览页面，在出问题的手机上预览观察动画是否正确。

播放常见报错

Container size overflowed...

手机端画布不允许宽高超过 2048，否则会导致页面崩溃。

• 如果是手机页面，删除 pixelRatio 参数，Player 会自动计算合适的 pixelRatio
• 如果确定为 PC 页面，请在创建 Player 时增加 env 参数

new Player({
  ...,
  container,
  env: 'PC'
});

export function getPixelRatio(): number {
  if (typeof screen === 'object' && typeof document === 'object') {
    const viewportWidth = Math.max(document.documentElement.clientWidth, window.innerWidth || 0);
    const screenWidth = screen.width;
    const viewportScale = screenWidth / viewportWidth;

    return Math.min(2 * viewportScale, 2);
  }
  
  return 1;
}

Container is not an HTMLElement

container 为 null 时，无法创建 Player，请检查元素是不是存在。如果是 React 的 ref 钩子里面，请检查 ref 是不是为 null。

Invalid container size...

container 没有在 DOM 中，如果 container 没有被添加到 DOM 中，clientWidth 和 clientHeight 为 0，这时 Player 无法创建，请保证 container 的宽高不为 0。

请确保在调用 player.play() 之前，container 被添加到 DOM 中，并且 container 的 CSS display 属性不为 none。

DPI overflowed...

一般是 DPI 过高，画布尺寸比屏幕像素更多，例如 750 宽度的手机，画布比 750 更高。这样会带来严重的性能衰退，这个时候需要缩小 DPI，需要减小 pixelRatio：

new Player({
  ...,
  container,
  pixelRatio: 1
});

WebGL not support

过老的机器是无法使用 WebGL 的，虽然这些机器已经不足万分之一，但如果你的 UV 达到了千万级别，这部分用户绝对数量还是不少。这种情况下需要降级：

player
  .loadScene(json)
  .catch(ex => {
  	// 因为不支持 WebGL 或者网络失败，走降级逻辑
  });


// 可以传特定参数，模拟 WebGL 失败
new Player({
  container,
  // 必触发 WebGL not support
  renderFramework: 'debug-disable' 
});

Never use destroyed player again

如果调用了player.dispose()，这个 player 就不能再使用了，请不要调用任何函数，如果出现此报错，检查一下 player 的创建和销毁逻辑。

Current running player count...

我们不鼓励多个 Player 同时播放，请调用player.pause()，请保证其他的 Player 是暂停状态。

Chrome 规定，当超过 8 个 WebGL 实例时，最早创建的 WebGL 会被销毁（也可能是被压栈页面的 WebGL），WebGL 被销毁后，播放器也会被强制销毁。当 Player 不可见的时候，请及时销毁：player.dispose()。

如果是常驻动画，当弹窗动画出现时，请调用 player.pause()，暂停被遮挡的常驻动画。

The plugin xx not found

插件未注册，需要在 Player 引入后引入相应的插件包，官方提供的插件如下：

• Spine : @galacean/effects-plugin-spine
• 陀螺仪：@galacean/effects-plugin-orientation-transformer
• 3D：@galacean/effects-plugin-model
• 多媒体（音视频）：@galacean/effects-plugin-multimedia
• 富文本：@galacean/effects-plugin-rich-text
• 降级插件：@galacean/effects-plugin-downgrade
• 性能检测：@galacean/effects-plugin-stats

Create player with different WebGL version

已存在旧 Player 和新建 Player 使用的 WebGL 版本不同。Galacean Effects 会缓存正在使用的 Player，每次新建的时候会检查是不是存在不同 WebGL 版本的 Player，同一设备不应该有不同 WebGL 版本的 Player 存在。考虑以下解决方案：

1. 及时销毁播放完不再使用的 Player
2. 通过 renderFramework 指定使用相同的 WebGL 版本创建 Player

Item duration can\'t be less than 0

每个元素都有自己的生命时长，小于或等于 0 的元素，会有一些不可预知的渲染效果，如果出现这种问题，请检查编辑器导出的 JSON 数据。

ValueType: 21\/22 is not supported

请开发升级到 @galacean/effects 到 1.4.1 及以上版本，若无法升级，请在编辑器发布 JSON / 导出 ZIP 时选择 2.3 版本。

TypeError: Cannot read properties of null (reading 'pipelineContext')

不要在 loadScene 的时候误执行 player.dispose()，如以下使用会触发该报错：

let player: Player | null = new Player({
  container,
  onError: err => {
    console.error(err);
  },
});

setTimeout(() => {
  player?.dispose();
  player = null;
  throw new Error('timeout');
}, 300);

await player.loadScene(jsons, { autoplay: false });

player?.play();