Galacean Engine: a TypeScript runtime for web 2D and 3D, with or without the editor

What Galacean Engine is for, and who ends up using it

Galacean Engine targets interactive content that runs in a browser or inside a WeChat minigame. The README describes it as a real-time interactive engine for web and mobile, built around a component system, with 2D and 3D graphics, animation, physics, GUI and input listed as the feature areas. The runtime is written in TypeScript, so the logic you write against it is TypeScript too, and the engine ships as an npm package named @galacean/engine.

The audience splits in two. One group works through the hosted Editor at galacean.antgroup.com/editor, where scenes are assembled visually and exported to a platform. The other group skips the editor and drives the runtime directly from code. The README states a preference for the editor route, calling it a streamlined workflow that lets artists build scenes while developers write custom logic. That preference is worth taking at face value: the repository you are reading is the runtime and its documentation, not the editor, and the editor is not part of this repository's source tree.

If your project is a marketing page with a spinning product model, or a small game that has to load quickly on a phone, the pure-code path is the one that matters, because it keeps the dependency graph to what you import.

Component architecture and the data flow from canvas to frame

The engine is organised around entities and components. The README example shows the shape clearly: WebGLEngine.create takes a canvas and returns an engine instance, the engine exposes a sceneManager whose activeScene is the scene you populate, and scene.createRootEntity creates the top of a hierarchy. Children are added with createChild, and behaviour is attached by calling addComponent on an entity.

Rendering follows from that hierarchy. A MeshRenderer component holds a mesh and a material; the README example assigns a BlinnPhongMaterial and a sphere produced by PrimitiveMesh.createSphere. A Camera component on another entity defines the view, and a DirectLight component with an intensity and a rotation defines the lighting. Calling engine.run starts the loop. The canvas is sized through engine.canvas.resizeByClientSize rather than by CSS alone, which is the detail that trips people up when the first render comes out stretched.

Assets come in through glTF, which the repository description names alongside WebGL as the foundation. That means geometry, materials and animation authored in a DCC tool are expected to arrive as glTF rather than through a bespoke format. The engine does not ship a scene file format of its own in this repository; scenes are built in code or produced by the editor.

Installing @galacean/engine and rendering a first sphere

The README gives one install command for the pure-code path. It requires a package manager and a bundler or dev server capable of handling TypeScript; the repository's own examples directory uses Vite, but the README does not prescribe one for consumers.

npm install @galacean/engine

The package is scoped, so the import specifier is @galacean/engine, not galacean. The README's scene example is the shortest complete program it offers, and it is worth running unchanged before adapting it:

import { BlinnPhongMaterial, Camera, DirectLight, MeshRenderer, WebGLEngine, PrimitiveMesh } from "@galacean/engine";

const engine = await WebGLEngine.create({ canvas: "canvas-id" });
engine.canvas.resizeByClientSize();

const scene = engine.sceneManager.activeScene;
const rootEntity = scene.createRootEntity("Root");

const lightEntity = rootEntity.createChild("Light");
const directLight = lightEntity.addComponent(DirectLight);
lightEntity.transform.setRotation(-45, -45, 0);
directLight.intensity = 0.4;

const cameraEntity = rootEntity.createChild("Camera");
cameraEntity.addComponent(Camera);
cameraEntity.transform.setPosition(0, 0, 12);

const meshEntity = rootEntity.createChild("Sphere");
const meshRenderer = meshEntity.addComponent(MeshRenderer);
const material = new BlinnPhongMaterial(engine);
meshRenderer.setMaterial(material);
meshRenderer.mesh = PrimitiveMesh.createSphere(engine, 1);

engine.run();

The string passed to WebGLEngine.create is the id of an existing canvas element in your HTML, so a page needs something like a canvas with that id before this script runs. What you should see is a lit sphere against the scene background, framed by the camera twelve units back on the z axis. If the canvas has no explicit size, resizeByClientSize derives it from the element's client box, so give the canvas CSS dimensions first.

Building the engine from source is a separate exercise and is not needed to consume the package. The README lists git-lfs, Node.js v15.0.0 or later, and pnpm as prerequisites, then pnpm install followed by npm run b:all. The root package.json enforces pnpm through a preinstall hook that runs only-allow pnpm, so npm install at the repository root will fail by design.

Where the runtime stops being the right tool

The most concrete limitation is versioning. The recent releases attached to this repository are v2.0.0-alpha.42, v2.0.0-alpha.41 and v2.0.0-alpha.38, published in August and July 2026. The root package.json in the repository reads version 1.6.13. Those two facts do not describe the same thing, and the README does not explain which line a new consumer receives from npm or what the migration path between them looks like. Anyone planning production work should resolve that question against the published package rather than against this page.

The second boundary is platform. The README lists HTML5 and WeChat minigame as the supported targets. There is no mention of native desktop, native mobile or server-side rendering anywhere in the README, so a team that needs a native build is looking at the wrong project. Likewise, the repository contains the runtime and its documentation; the editor referenced throughout the README is hosted elsewhere, so a team that wants the visual workflow is depending on a service outside this codebase, with whatever availability that implies.

Finally, physics is listed as a feature area but the README gives no configuration example, no backend name and no tuning guidance. Treat the physics claim as a capability statement rather than a documented workflow until you read the docs site.

How this differs from Babylon.js and Three.js

Babylon.js and Three.js occupy the same space: JavaScript rendering for the browser. The difference is where each puts the work. Three.js gives you a renderer and a scene graph and leaves physics, animation blending and UI to separate packages you choose yourself. Babylon.js bundles more, including its own editor and a documented physics abstraction, and it is distributed as a mature release line rather than an alpha.

Galacean Engine sits closer to the Babylon.js end of that spectrum in ambition, bundling graphics, animation, physics and GUI behind one component system, but it differs in two practical ways. It is written in TypeScript and expects TypeScript from you, and it pairs the runtime with a hosted editor rather than a downloadable one. If you want a runtime you can vendor, read end to end, and pair with libraries of your own choosing, Three.js is the lighter commitment. If you want a bundled feature set with a long release history, Babylon.js is the safer bet today. Galacean's case rests on the editor workflow and on the WeChat minigame target, which the other two do not advertise.

Maintenance, upgrades and what the MIT licence covers

The repository is not archived, and the last push was on 2026-09-20, so the runtime is being worked on. The release cadence visible in the published releases is roughly monthly across the alpha line, which is frequent enough that pinning an exact version in package.json is the sane default rather than relying on a caret range across alpha builds.

Upgrading carries a specific cost here. The engine is a component system, so a breaking change to a component's API or to the entity hierarchy propagates into every scene you have written. The README does not document a deprecation policy or a migration guide, and it does not document rollback. Budget for reading release notes before each bump.

The licence is MIT, stated in the README and present as a LICENSE file at the repository root. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice travel with the code. Two caveats worth checking yourself: the repository description says the engine is built on WebGL and glTF, both of which are open standards with their own specifications, and the editor is a separate hosted product whose terms are not in this repository. This is a description of the licence text, not legal advice.

Editorial conclusion

Adopt Galacean Engine if you are building a browser or WeChat minigame scene in TypeScript and want the runtime as an npm dependency rather than a downloaded editor project. Do not adopt it if you need a stable, non-alpha release line or if your team has no appetite for a framework whose visual tooling lives on a hosted site. Before committing, verify which version you are actually installing, since the repository root package.json reads 1.6.13 while the recent releases listed are v2.0.0-alpha builds, and confirm that the packages you need are covered by the MIT licence text in the LICENSE file rather than by the README summary.

Frequently asked questions

Official sources

1. galacean/engine on GitHub
2. License: MIT
3. Project website
4. README
5. Releases