# effects-runtime is the web half of the Galacean Effects pipeline

> galacean/effects-runtime is a TypeScript package that loads and renders animation effects authored in the Galacean Effects editor, exposing layer and particle animation data to a game engine. It is a renderer, not an editor, and its Spine support carries a separate licence that users must satisfy themselves.

**galacean/effects-runtime** — It can load and render cool animation effects

- Repository: https://github.com/galacean/effects-runtime
- Website: https://www.galacean.com/effects/
- Stars: 750 · Forks: 36
- Language: TypeScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/galacean-effects-runtime

## The editor authors the scene, the runtime only renders it

Galacean Effects is a two half pipeline and this repository is one half of it. The description is short: it can load and render cool animation effects. The scene file it consumes, a demo.json in the example, is produced by the Galacean Effects editor hosted at galacean.com/effects, and the README points there for it. So the runtime is for teams that already have authored effects and want them on screen inside a web product, not for teams that want to produce effects in the first place. The second half of the description tells you what the runtime is for inside an engine. The APIs provided by effects-core allow your engine to quickly access animation data such as layer and particle animation, which is the interesting part for a game engine: the runtime is not a black box that renders a file, it exposes the structure of the animation so engine code can read it and react to it.

## The Player API is three calls and one container element

The runtime installs as an ordinary npm package:

```bash
npm install @galacean/effects
```

The pnpm equivalent is:

```bash
pnpm add @galacean/effects
```

In the page, the runtime needs a container element to draw into:

```html
<div id="J-Container"></div>
```

Then a Player is instantiated against that element and pointed at a scene file:

```ts
import { Player } from '@galacean/effects';

// 1. Instantiate a player
const player = new Player({
  container: document.getElementById('J-Container'),
});

// 2. Load and play the animation resource
player.loadScene('./demo.json');
```

That is the entire documented usage path, and it is worth sitting with how little it asks of you. There is no configuration file, no asset pipeline step and no lifecycle to wire up beyond the container. The scene file is fetched at runtime from a path you choose, so it can sit next to your other static assets or behind a CDN. What you give up for that simplicity is visible too: the README documents one construction option and one load call, and says nothing about pause, seek, event callbacks or teardown, so a project that needs to control playback precisely will have to look at the API documentation rather than the README.

## A pnpm monorepo with three families of packages

The repository root is a monorepo named monorepo-root and marked private, with a pnpm-workspace.yaml and a pnpm-lock.yaml at the top. Inside it are three package directories: packages, plugin-packages and web-packages, and the build script filters over them separately, building packages first and then the plugins. The web-packages family is where the editor facing pieces live, the plugin-packages family holds optional integrations such as the Spine plugin, and packages holds the runtime itself. The scripts show the split explicitly, with build:main running the filter over the packages directory and build:plugins doing the same for the plugin directory, and a publish step that pushes only those two families with pnpm -r publish. The docs site is built from the same sources through a build:docs script that runs the build and then typedoc, with typedoc.base.json and typedoc.json at the root. The test suite lives in its own package under the @galacean/effects-test name and is run with pnpm --filter.

## The pipeline is guarded by hooks, linting and a publish tag

Several details show how seriously the release process is treated. There is a preinstall script that runs npx only-allow pnpm followed by a script that fetches binaries, so an npm install of the monorepo is refused outright and the FlatBuffers compiler binaries are staged automatically. A prepare script installs husky and runs the build:fbs step across the packages, which is the schema compilation step. Formatting and linting run through eslint with separate fix scripts, commit messages are checked with commitlint through commitlint.config.js, and staged files are handled by lint-staged through .lintstagedrc.json. Publishing supports three channels: a normal publish, an alpha publish tagged alpha, and a beta publish tagged beta, and the alpha and beta paths deliberately pass no-git-checks so a release can be cut from a working tree that is not clean. Version numbers are bumped by a script under scripts/, and the changelog is produced by another script that fetches from origin first. Type checking runs through a project references build over tsconfig.check.json, with separate base, external and check configurations.

## Spine support arrives with its own licence conditions

The Third-Party Notices section is the part to read before committing to a feature set. The project integrates Spine Runtimes for 2D skeletal animation support, and use of the plugin package @galacean/effects-plugin-spine is subject to the Spine Runtime License Agreement. The consequences are spelled out: each user must hold a valid Spine Editor licence, and Galacean Effects does not cover Spine licence fees, with users responsible for complying with the terms set by Esoteric Software. This is not a formality, because a Spine Editor licence is a per user purchase, and the plugin is bundled into a runtime that you distribute to your own users. So the cost model changes depending on whether you enable Spine support: without it the runtime is plain MIT, with it your users need licences you are not covering. If your project already standardises on Spine, this plugin removes the work of wiring the runtimes together; if it does not, the licensing may decide the question before the technical fit does.

## The runtime cannot author, and the native build lives in another repository

Two limits are worth being explicit about. The first is authoring. The runtime reads a scene file that the Galacean Effects editor produces, and the README has no way of creating one from code, so a team that wants effects but does not want to design them in that editor has to look elsewhere for the content pipeline. The second is platform. The topics cover 2D, 3D, animation, html5, javascript, webgl and webgl2, and the package is a web runtime, so this repository is the web side. There is a separate Native project at galacean/effects-native linked from the README, which is the path for non web targets, and choosing between them is a platform decision rather than a feature decision. The alternative to the whole pipeline, for reference, is running the Spine runtime on its own for 2D skeletal animation: that approach has no editor lock in, since you author in Spine directly, but it covers skeletal animation only and does not give you the layer and particle animation data the effects-core APIs expose.

## MIT licensed, with releases every few weeks

The licence is MIT, with a LICENSE file at the repository root and a Chinese translation of the changelog alongside the English one, plus a Chinese README. The release history shows a steady cadence. v2.10.1 was published on 2026-09-03, v2.10.3 on 2026-09-15 and v2.10.4 on 2026-10-12, and the repository is not archived with the last push on 2026-10-20. The version number itself sits in the two digit minor range, which tells you the project is past its early churn. Because the runtime and the plugin packages are published separately from the monorepo root, an upgrade means bumping the @galacean/effects dependency and reading the changelog between the two versions, and the presence of alpha and beta publication channels means you can also pin to a pre-release line when you want a fix before it reaches the stable channel.

## Conclusion

Adopt effects-runtime if your web project needs to play animation effects authored in the Galacean Effects editor and you want the engine to reach into layer and particle animation data, since the runtime is published as a normal npm package and the Player API is small. Do not adopt it expecting to author content, because the scene file it loads comes out of the editor, and check the Spine terms first if you plan to use the plugin package, since each user must hold a valid Spine Editor licence that Galacean does not pay for. Before integrating, confirm that your build targets a browser the runtime supports, verify the API documentation for the version you install, and read the CHANGELOG.md entries between your current version and the latest release.

## FAQ

### How do I install and use the Galacean Effects runtime?

Install the package with npm install @galacean/effects or pnpm add @galacean/effects, create a Player with a container element, and call player.loadScene with the path to the scene file. The scene file itself is produced by the Galacean Effects editor at galacean.com/effects.

### Can I use @galacean/effects-plugin-spine without a Spine licence?

No. The third-party notices state that use of the plugin is subject to the Spine Runtime License Agreement, that each user must hold a valid Spine Editor licence, and that Galacean Effects does not cover Spine licence fees.

### Does the effects runtime work outside the browser?

This repository is the web runtime, with topics covering html5, javascript, webgl and webgl2. A separate Native project is linked from the README at galacean/effects-native, and the native build is the route for platforms other than the browser.

### How do I contribute to effects-runtime?

The repository uses pnpm exclusively, enforced by a preinstall script that runs only-allow pnpm, and the development guide is at docs/developing.md. Linting runs through eslint, commit messages through commitlint, and staged changes through lint-staged with husky hooks.

### What licence is galacean/effects-runtime released under?

The runtime itself is MIT licensed, with a LICENSE file at the repository root. The Spine integration is the exception, since the plugin package is subject to Esoteric Software's Spine Runtime License Agreement on top of the project licence.

## Sources

- [galacean/effects-runtime on GitHub](https://github.com/galacean/effects-runtime)
- [License: MIT](https://github.com/galacean/effects-runtime/blob/main/LICENSE)
- [Project website](https://www.galacean.com/effects/)
- [README](https://github.com/galacean/effects-runtime/blob/main/README.md)
- [Releases](https://github.com/galacean/effects-runtime/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/galacean-effects-runtime