Boost Mini‑Program Animations with Galacean Effects: A Taro 3.x Guide

Background

In the Guming mini‑program's Qixi card‑collecting activity, users collect role cards and unlock lottery draws. To increase emotional value and immersion, the business wants a ritualistic animation when cards are merged, such as rotation, particle scattering, and romantic effects, aiming to extend user stay time and participation.

Pure CSS cannot achieve such complex animation; Lottie is often used but cannot handle particle effects well, and the mini‑program must support three platforms (WeChat, Douyin, Alipay).

About Galacean Effects

Galacean Effects (GE) is an online animation solution focused on mobile, jointly created by Ant Group’s Creative Design Center and Experience Technology Department. It consists of a Studio editor ( https://www.galacean.com/effects/dashboard ) and a Player ( https://www.npmjs.com/package/@galacean/effects ).

The Player parses and plays animation assets exported from the editor, ensuring consistent visual results and reducing communication cost between designers and developers.

Designers can use built‑in templates, layer animation, particle animation, 3D animation, Spine skeletal animation, and interaction settings. The editor also supports project management, multi‑person collaboration, and version saving.

After publishing, resources are automatically audited, compressed and ready for the Player, which uses WebGL/OpenGL to render high‑performance particle, 3D and Spine effects.

Installation

# Install the Galacean Effects mini‑program adapter
npm i @galacean/appx-adapter --save
# Install Galacean Effects
npm i @galacean/effects --save

Adapter Export

Thanks to Taro’s native multi‑platform support, export the appropriate module for each platform and import it in the animation component.

├── ge
│   ├── index.alipay.ts
│   ├── index.ts
│   ├── index.tt.ts
│   └── index.weapp.ts
└── index.tsx

export { registerCanvas } from "@galacean/appx-adapter/weapp";
export { Player } from "@galacean/effects/weapp";

Quick Start

1. Prepare animation JSON

{
  "playerVersion": {"web":"2.5.3","native":"0.0.1.202311221223"},
  "images": Array[4],
  "fonts": Array[0],
  "version":"3.3",
  "shapes": Array[0],
  "plugins": Array[0],
  "type":"ge",
  "compositions": Array[1],
  "components": Array[25],
  "geometries": Array[0],
  "materials": Array[0],
  "items": Array[27],
  "shaders": [],
  "bins": Array[1],
  "textures": Array[4],
  "animations": [],
  "miscs": Array[142],
  "compositionId":"17"
}

The JSON is exported from the editor; resource paths are relative and must be converted to absolute paths in code.

Make sure the playerVersion in the JSON matches the installed @galacean/effects version.

2. Set animation container

<Canvas type="webgl" id="J-webglCanvas" style={{width:"100%",height:"100%"}}></Canvas>

3. Create Player

import { View, Canvas } from "@tarojs/components";
import { useEffect, useRef } from "react";
import Taro from "@tarojs/taro";
import { registerCanvas, Player } from "./ge";

const playerRef = useRef<Player | null>(null);

useEffect(() => {
  initAndPlay();
  return () => {
    playerRef.current?.dispose();
  };
}, []);

const initAndPlay = async () => {
  const query = Taro.createSelectorQuery();
  const nodeCanvas = await new Promise(resolve => {
    query.select("#J-webglCanvas").node().exec(res => {
      resolve(res[0].node);
    });
  });
  const canvas = await registerCanvas({ id: nodeCanvas });
  playerRef.current = new Player({ canvas, renderFramework: "webgl" });
  playerRef.current.loadScene("https://g.gumingnc.com/u/Hw7lZMp/EA.json");
};

The above code reproduces the UI‑designed animation in the mini‑program.

Loading Optimization

The first‑frame delay consists of network request & initial processing and GPU shader compilation. The console output shows loadTime, compileTime, and firstFrameTime.

playerRef.current
  .loadScene("https://g.gumingnc.com/u/Hw7lZMp/EA.json")
  .then(composition => console.log(composition.statistic));
{
  "loadStart": 1760429624085,
  "loadTime": 753,
  "compileTime": 31,
  "firstFrameTime": 811
}

Most of the delay comes from downloading resources, especially on poor networks. A timeout (default 10 s) can trigger fallback logic.

Default timeout is 10 seconds

// onError handles timeout and fallback
playerRef.current = new Player({
  canvas,
  renderFramework: "webgl",
  onError: error => { console.log(error); }
});
await player.loadScene(json, { timeout: 1 });

A better approach is to download the animation package at app launch, unzip it locally, and load the animation from the local file system, eliminating network latency.

Core Idea

Download animation zip package on mini‑program start.

const geMap = [{ name: "qixi", url: "https://g.gumingnc.com/u/Pxil6Fp/6w.zip" }];
const targetPath = `${Taro.env.USER_DATA_PATH!}/animation`;
const fs = Taro.getFileSystemManager();
...
Taro.downloadFile({ url, success: res => {
  fs.unzip({ zipFilePath: res.tempFilePath, targetPath: `${targetPath}/name`, success: () => { /* update index.json */ } });
}});

After unzipping, rewrite resource URLs in the JSON to absolute paths and, for binary files, read them as ArrayBuffer on real devices.

// Adjust image and bin URLs to absolute paths
file.images = file.images.map(item => ({
  ...item,
  url: item.url.replace("./", `${targetPath}/${animationName}/qixi/`),
  webp: item.webp.replace("./", `${targetPath}/${animationName}/qixi/`)
}));
file.bins = file.bins.map(item => ({
  ...item,
  url: item.url.replace("./", `${targetPath}/${animationName}/qixi/`)
}));
if (Taro.getSystemInfoSync().platform.toLowerCase() !== "devtools") {
  const bins = file.bins.map(item => fs.readFileSync(item.url));
  file.bins = bins;
}
playerRef.current.loadScene(file, { autoplay: true, timeout: 1 });

Using an offline package reduces first‑frame time dramatically (e.g., total loadTime from 753 ms to 35 ms, firstFrameTime from 811 ms to 75 ms).

{
  "loadStart": 1760537905401,
  "loadTime": 35,
  "compileTime": 22,
  "firstFrameTime": 75
}

Conclusion

Galacean Effects provides a powerful, WebGL‑based animation framework for mobile front‑end development. Designers can quickly create rich effects in the visual editor, and developers can integrate them with minimal effort, greatly improving collaboration efficiency and animation quality.