galacean · cptbtptpbcptdtptp · Jan 26, 2026 · Jan 26, 2026 · Jan 27, 2026 · Jan 27, 2026
diff --git a/.eslintrc.js b/.eslintrc.js
diff --git a/.github/HOW_TO_CONTRIBUTE.md b/.github/HOW_TO_CONTRIBUTE.md
@@ -31,9 +31,9 @@ The following is a set of guidelines for contributing to Galacean. Please spend
 
 <br />To set up for contributing code, you will take a few steps:<br />
 
-1. Ensure you have node.js installed. You can download Node.js from [nodejs.org](https://nodejs.org/en/) and make sure your Node.js is later than `12`. Use `node -v` to check your Node.js version.
+1. Ensure you have node.js installed. You can download Node.js from [nodejs.org](https://nodejs.org/en/) and make sure your Node.js is later than `20.19`. Use `node -v` to check your Node.js version.
 1. Fork the Galacean repository.
-1. Run `npm run bootstrap` in your cloned folder to install all the dependencies for Galacean.
+1. Run `pnpm install` and `pnpm build` in your cloned folder to install all the dependencies for Galacean.
 
 
 
@@ -46,9 +46,9 @@ The following is a set of guidelines for contributing to Galacean. Please spend
 <br />You can test your change by the following ways:<br />
 
 - Clone the Galacean playground repository and write a demo for your change.
-- Write an uint test in the Galacean repository and run `npm run test` to execute the uint test.
+- Write an unit test in the Galacean repository and run `pnpm test` to execute the unit test.
 
-- [Write an e2e test](https://github.com/galacean/runtime/wiki/How-to-write-an-e2e-Test-for-runtime) in the Galacean repository and run `npm run e2e` to execute the e2e test.
+- [Write an e2e test](https://github.com/galacean/engine/wiki/How-to-write-an-e2e-Test-for-runtime) in the Galacean repository and run `pnpm e2e` to execute the e2e test.
 
 
 
@@ -137,7 +137,7 @@ git pull --ff upstream master
 
 - All features or bug fixes **must be tested** by one or more specs (unit-tests).
 - All public API methods **must be documented**.
-- We use Prettier as an automatic code formatter. Run `npm run prettier` after making any changes to the code.
+- We use Prettier as an automatic code formatter. Run `pnpm format` to format your code, and `pnpm lint` to check code quality, after making any changes to the code.
 
 
 

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -28,6 +28,9 @@ jobs:
       - name: Lint
         run: pnpm run lint
 
+      - name: Format check
+        run: pnpm run format:check
+
   build:
     runs-on: ${{ matrix.os }}
 

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -51,6 +51,11 @@ jobs:
         if: ${{ github.event.inputs.build_official_preload == '' || github.event.inputs.build_official_preload == 'true' }}
         run: ./scripts/build-official-preload.js
 
+      - name: Verify npm auth
+        run: npm whoami
+        env: 
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
       - name: Release engine packages and Sync to CDN
         uses: galacean/publish@main
         if: success() || failure()

diff --git a/.gitignore b/.gitignore
@@ -26,6 +26,7 @@ stats.html
 tsconfig.tsbuildinfo
 api
 docs/api
+docs/plans
 yarn.lock
 e2e/videos/*
 e2e/screenshots/*
@@ -47,3 +48,6 @@ CLAUDE.md
 # For bison generated files used by ShaderLab
 *.tab.c
 *.output
+
+# Local-only test assets (third-party game art, not for redistribution)
+examples/public/spine/
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Galacean Engine
 
-<a href="https://www.npmjs.com/package/@galacean/engine"><img src="https://img.shields.io/npm/v/@galacean/engine"/></a>
+[![npm-version](https://img.shields.io/npm/v/@galacean/engine)](https://www.npmjs.com/package/@galacean/engine)
 ![npm-size](https://img.shields.io/bundlephobia/minzip/@galacean/engine)
 ![npm-download](https://img.shields.io/npm/dm/@galacean/engine)
 [![codecov](https://codecov.io/gh/galacean/engine/branch/main/graph/badge.svg?token=KR2UBKE3OX)](https://codecov.io/gh/galacean/engine)
@@ -22,12 +22,13 @@
 ## Usage
 
 ### Using Editor
-We recommend using [**Editor**](https://galacean.antgroup.com/editor)  for a streamlined workflow that enables seamless integration between artists and developers. Its intuitive visual tools allow artists to quickly create scenes and enable developers to write custom logic, with convenient platform export. You can even create projects based on pre-built case templates.
 
-![image](https://github.com/user-attachments/assets/18f63fef-696c-4f9f-b44a-d8b7af481a3e)
+We recommend using [**Editor**](https://galacean.antgroup.com/editor) for a streamlined workflow that enables seamless integration between artists and developers. Its intuitive visual tools allow artists to quickly create scenes and enable developers to write custom logic, with convenient platform export. You can even create projects based on pre-built case templates.
 
+![image](https://github.com/user-attachments/assets/18f63fef-696c-4f9f-b44a-d8b7af481a3e)
 
 ### Using Pure Code
+
 If you want to build your project using pure code via runtime, install the engine from npm:
 
 ```sh
@@ -73,7 +74,7 @@ engine.run();
 
 This repository contains the runtime's source code and documentation. Everyone is welcome to contribute—whether you find a bug, have a feature request, or want to tackle a task from our roadmap, please get in touch.
 
-Make sure to read the [Contributing Guide](.github/HOW_TO_CONTRIBUTE.md) / [贡献指南](https://github.com/galacean/engine/wiki/%E5%A6%82%E4%BD%95%E4%B8%8E%E6%88%91%E4%BB%AC%E5%85%B1%E5%BB%BA-Oasis-%E5%BC%80%E6%BA%90%E4%BA%92%E5%8A%A8%E5%BC%95%E6%93%8E) before submitting changes.
+Make sure to read the [Contributing Guide](.github/HOW_TO_CONTRIBUTE.md) before submitting changes.
 
 ## Clone
 
@@ -91,7 +92,7 @@ git clone git@github.com:galacean/engine.git
 
 Prerequisites:
 
-- [Node.js v15.0.0+](https://nodejs.org/en/) and NPM (Install by official website)
+- [Node.js v20.19.0+](https://nodejs.org/en/) (Install by official website)
 - [PNPM](https://pnpm.io/) (Install globally by `npm install -g pnpm`)
 
 In the folder where you have cloned the repository, install the build dependencies using pnpm:
@@ -100,10 +101,10 @@ In the folder where you have cloned the repository, install the build dependenci
 pnpm install
 ```
 
-Then, to build the source, using npm:
+Then, to build the source, using pnpm:
 
 ```sh
-npm run b:all
+pnpm run b:all
 ```
 
 ## Links

diff --git a/docs/en/animation/animator.mdx b/docs/en/animation/animator.mdx
@@ -113,11 +113,20 @@ animator.speed = 0;
 animator.speed = 1;
 ```
 
-If you only want to pause a specific `AnimatorState` , you can do so by setting its speed to 0.
+If you only want to pause a specific `AnimatorState` on this Animator instance, set the per-instance speed to 0.
 
 ```typescript
 const state = animator.findAnimatorState("xxx");
+if (!state) {
+  // State not found in any layer
+  return;
+}
+
+// Pause only this Animator instance's playback of the state.
 state.speed = 0;
+
+// To resume later, write any non-zero value:
+// state.speed = 1;
 ```
 
 ### Transition to Specified Animation State
@@ -130,26 +139,34 @@ animator.crossFade("OtherStateName", 0.3);
 
 ### Get Current Playing Animation State
 
-You can use the [getCurrentAnimatorState](/apis/core/#Animator-getCurrentAnimatorState) method to get the currently playing `AnimatorState` . The parameter is the index `layerIndex` of the `AnimatorControllerLayer` where the `AnimatorState` is located. For details, see the [API documentation](/apis/core/#Animator-getCurrentAnimatorState). After obtaining it, you can set the properties of the `AnimatorState` , such as changing the default loop playback to play once.
+[getCurrentAnimatorState](/apis/core/#Animator-getCurrentAnimatorState) returns the playing `AnimatorStateInstance` on a given layer, or `null` when the layer is missing or nothing is playing.
 
 ```typescript
-const currentState = animator.getCurrentAnimatorState(0);
-// Play once
-currentState.wrapMode = WrapMode.Once;
-// Loop playback
-currentState.wrapMode = WrapMode.Loop;
+const current = animator.getCurrentAnimatorState(0);
+if (current) {
+  current.speed = 0.5;
+}
 ```
 
 ### Get Animation State
 
-You can use the [findAnimatorState](/apis/core/#Animator-findAnimatorState) method to get the specified `AnimatorState` . After obtaining it, you can set the properties of the  `AnimatorState` , such as changing the default loop playback to play once.
+[findAnimatorState](/apis/core/#Animator-findAnimatorState) returns the per-Animator `AnimatorStateInstance` (`AnimatorStateInstance | null`). Writes only affect this Animator; the shared `AnimatorState` on the controller is untouched. Same pattern as `Renderer.getInstanceMaterial`.
+
+- `speed`, `wrapMode` are per-instance overrideable; unwritten reads return the shared default.
+- `name`, `clip`, `clipStartTime`, `clipEndTime` read through to the shared asset.
+
+To mutate the shared asset (broadcasts to every Animator), go through the controller path:
 
 ```typescript
 const state = animator.findAnimatorState("xxx");
-// Play once
+if (!state) return;
+
+// Per-instance overrides.
+state.speed = 0.5;
 state.wrapMode = WrapMode.Once;
-// Loop playback
-state.wrapMode = WrapMode.Loop;
+
+// Broadcast to every Animator using this controller.
+animator.animatorController.layers[0].stateMachine.findStateByName("xxx").clip = otherClip;
 ```
 
 ### Animation Culling

diff --git a/docs/en/assets/load.mdx b/docs/en/assets/load.mdx
@@ -77,7 +77,7 @@ this.engine.resourceManager.load("https://a.png");
 // 加载 base64
 this.engine.resourceManager.load<GLTFResource>({
   url: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
-  type: AssetType.Texture2D,
+  type: AssetType.Texture,
 });
 
 // 加载编辑器虚拟路径下的资源

diff --git a/docs/en/basics/overview.mdx b/docs/en/basics/overview.mdx
@@ -33,14 +33,12 @@ Includes the following sub-packages:
 | Package | Description | Related Documentation |
 | :-- | :-- | --- |
 | [@galacean/engine](https://www.npmjs.com/package/@galacean/engine) | Core architecture logic and core functionalities | [API](/apis/galacean) |
-| [@galacean/engine-physics-lite](https://www.npmjs.com/package/@galacean/engine-physics-lite) | Lightweight physics engine | [Doc](/en/docs/physics/overall) |
 | [@galacean/engine-physics-physx](https://www.npmjs.com/package/@galacean/engine-physics-physx) | Full-featured physics engine | [Doc](/en/docs/physics/overall) |
-| [@galacean/engine-shaderlab](https://www.npmjs.com/package/@galacean/engine-shaderlab) | Galacean Shader compiler | [Doc](/en/docs/graphics/material/shader) |
+| [@galacean/engine-shader-compiler](https://www.npmjs.com/package/@galacean/engine-shader-compiler) | Galacean Shader compiler | [Doc](/en/docs/graphics/material/shader) |
 | [@galacean/engine-xr](https://www.npmjs.com/package/@galacean/engine-xr) | XR logic package | [Doc](/en/docs/xr/overall) |
 | [@galacean/engine-xr-webxr](https://www.npmjs.com/package/@galacean/engine-xr-webxr) | WebXR backend | [Doc](/en/docs/xr/overall) |
 | [@galacean/engine-ui](https://www.npmjs.com/package/@galacean/engine-ui) | UI | [Doc](/en/docs/UI/overall) |
 
-
 You can install it via [NPM](https://docs.npmjs.com/):
 
 ```bash
@@ -88,9 +86,8 @@ For some functional modules that require additional compatibility considerations
 | Module | Compatibility Considerations | Specific Documentation |
 | :-- | :-- | :-- |
 | [Mouse and Touch](/en/docs/input) | [PointerEvent](https://caniuse.com/?search=PointerEvent) | For compatibility, please refer to [polyfill-pointer-event](https://github.com/galacean/polyfill-pointer-event) |
-| [PhysX](/en/docs/physics/overall) | [WebAssembly](https://caniuse.com/?search=wasm) | In environments that do not support WebAssembly, it will degrade to the JS version, with slightly lower performance and performance compared to the WebAssembly version |
+| [PhysX](/en/docs/physics/overall) | [WebAssembly](https://caniuse.com/?search=wasm) | PhysX requires WebAssembly; `Auto` runtime mode only selects between SIMD and non-SIMD WebAssembly builds |
 
 ## Open Source Collaboration
 
 **Galacean** is eager to collaborate with you to build an interactive engine. All development processes, including [planning](https://github.com/galacean/engine/projects?query=is%3Aopen), [milestones](https://github.com/galacean/engine/milestones), and [architecture design](https://github.com/galacean/engine/wiki/Physical-system-design), are publicly available in GitHub's project management. You can participate in the construction of the engine by [creating an issue](https://docs.github.com/zh/issues/tracking-your-work-with-issues/creating-an-issue) and [submitting a PR](https://docs.github.com/zh/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). If you have any questions or need help, you can join the DingTalk group or seek help in the [discussion area](https://github.com/orgs/galacean/discussions).
-```
diff --git a/docs/en/core/color.mdx b/docs/en/core/color.mdx
@@ -53,10 +53,10 @@ When uploading textures in the editor, the sRGB toggle is enabled by default. If
 [Loading textures](/en/docs/assets/load) uses the sRGB color space by default. If linear space is required, you can disable the sRGB setting via parameters:
 
 ```ts showLineNumbers {7}
-// Load textures using Texture2DLoader
+// Load textures using TextureLoader
 engine.resourceManager
   .load<Texture2D>({
-    type: AssetType.Texture2D,
+    type: AssetType.Texture,
     url: "https://***.png",
     params: {
       isSRGBColorSpace: false // Disable sRGB, use linear space, e.g., for normal maps

diff --git a/docs/en/graphics/background/sky.mdx b/docs/en/graphics/background/sky.mdx
@@ -34,31 +34,6 @@ Finally, follow the path **[Hierarchy Panel](/en/docs/interface/hierarchy)** ->
 
 <Image src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*rqvsSpkGJ6UAAAAAAAAAAAAADhuCAQ/original" />
 
-### Code to Set Skybox
-
-```typescript
-// 创建天空盒纹理
-const textureCube = await engine.resourceManager.load<TextureCube>({
-  urls: [
-    "px - right 图片 url",
-    "nx - left 图片 url",
-    "py - top 图片 url",
-    "ny - bottom 图片 url",
-    "pz - front 图片 url",
-    "nz - back 图片 url",
-  ],
-  type: AssetType.TextureCube,
-});
-// 创建天空盒材质
-const skyMaterial = new SkyBoxMaterial(engine);
-skyMaterial.texture = textureCube;
-// 设置天空盒
-const background = scene.background;
-background.mode = BackgroundMode.Sky;
-background.sky.material = skyMaterial;
-background.sky.mesh = PrimitiveMesh.createCuboid(engine, 2, 2, 2);
-```
-
 ## Setting Procedural Sky
 
 Procedural sky is the default background in 3D projects in the editor. You can also follow the path **[Hierarchy Panel](/en/docs/interface/hierarchy)** -> **Select Scene** -> **[Inspector Panel](/en/docs/interface/inspector)** -> **Background section** -> **Set Mode to Sky** -> **Select the built-in SkyMat material** -> **Set Mesh to the built-in Sphere**

diff --git a/docs/en/graphics/background/texture.mdx b/docs/en/graphics/background/texture.mdx
@@ -24,7 +24,7 @@ background.mode = BackgroundMode.Texture;
 // 将一张 2D 纹理设置为背景纹理
 background.texture = await engine.resourceManager.load<Texture2D>({
   url: "XXX.jpg",
-  type: AssetType.Texture2D,
+  type: AssetType.Texture,
 });
 // 设置填充模式为铺满
 background.textureFillMode = BackgroundTextureFillMode.Fill;

diff --git a/docs/en/graphics/light/ambient.mdx b/docs/en/graphics/light/ambient.mdx
@@ -32,12 +32,12 @@ In addition to real-time computed direct light sources, we generally need to pre
 
 ## Script Usage
 
-After obtaining the URL of the baked product through the [baking tutorial](/en/docs/graphics/light/bake/), load and parse it through the engine's EnvLoader:
+After obtaining the URL of the baked product through the [baking tutorial](/en/docs/graphics/light/bake/), load and parse it through the engine's AmbientLightLoader:
 
 ```typescript
 engine.resourceManager
   .load<AmbientLight>({
-    type: AssetType.Env,
+    type: AssetType.AmbientLight,
     url: "https://gw.alipayobjects.com/os/bmw-prod/89c54544-1184-45a1-b0f5-c0b17e5c3e68.bin"
   })
   .then((ambientLight) => {
@@ -49,7 +49,5 @@ engine.resourceManager
 
     // 预滤波环境贴图（ambientLight.specularTexture）还可以作为场景的背景
     // skyMaterial.texture = ambientLight.specularTexture;
-    // 由于烘焙产物的颜色编码方式是 RGBM，因此作为背景时需要将解码设置为 textureDecodeRGBM
-    // skyMaterial.textureDecodeRGBM = true;
   });
 ```
diff --git a/docs/en/graphics/material/baseUse.mdx b/docs/en/graphics/material/baseUse.mdx
@@ -36,7 +36,7 @@ You can select materials in the editor and switch shaders to observe real-time r
 
 <Image src="https://gw.alipayobjects.com/zos/OasisHub/cd87c11a-7a68-4cde-a19a-40cff943e878/2025-02-10%25252017.05.33.gif" />
 
-Each shader has different rendering effects and application scenarios. For more details, refer to [Built-in Shader Tutorial](/en/docs/graphics/material/builtinShaders/pbr/) and [Custom Shader Tutorial](/en/docs/graphics/material/examples/shaderlab-01-basic-shader).
+Each shader has different rendering effects and application scenarios. For more details, refer to [Built-in Shader Tutorial](/en/docs/graphics/material/builtinShaders/pbr/) and [Custom Shader Tutorial](/en/docs/graphics/material/examples/shader-01-basic-shader).
 
 ## Creating Custom Shaders
 If built-in shaders cannot meet your needs, we can create a custom shader. In the editor asset panel, create a new Shader and choose PBR template or Unlit template:
@@ -54,7 +54,7 @@ The editor will automatically help us create the Shader file and [UIScript](/en/
 />
 
 <Callout type="info">
-For specific shader content writing, you can quickly get started with [Custom Shader Tutorial](/en/docs/graphics/material/examples/shaderlab-01-basic-shader).
+For specific shader content writing, you can quickly get started with [Custom Shader Tutorial](/en/docs/graphics/material/examples/shader-01-basic-shader).
 </Callout>
 
 ## Shader Data Transfer
@@ -72,13 +72,13 @@ Pass "Forward" {
     mat4 renderer_MVPMat;
 
     // Through including code fragments
-    #include "Transform.glsl"
+    #include "Common/Transform.glsl"
 }
 ...
 ```
 
 ## Next Steps
-- [Custom Shader](/en/docs/graphics/material/examples/shaderlab-01-basic-shader) - Start your shader creation journey from scratch
+- [Custom Shader](/en/docs/graphics/material/examples/shader-01-basic-shader) - Start your shader creation journey from scratch
 - [Shader Syntax Deep Learning](/en/docs/graphics/material/shader) - Complete syntax reference
 - [Shader Built-in Variables Reference](/en/docs/graphics/material/variables) - All built-in variables provided by the engine
 - [Shader Built-in API Reference](/en/docs/graphics/material/shaderAPI) - All Shader APIs provided by the engine

diff --git a/docs/en/graphics/material/examples/_meta.json b/docs/en/graphics/material/examples/_meta.json
@@ -1,8 +1,8 @@
 {
-  "shaderlab-01-basic-shader": "Basic Shader Syntax",
-  "shaderlab-02-render-state": "Render State Control",
-  "shaderlab-03-ui-script": "UIScript System",
-  "shaderlab-04-multi-pass": "Multi-Pass Rendering",
-  "shaderlab-05-advance": "Advanced Features & Code Reuse"
+  "shader-01-basic-shader": "Basic Shader Syntax",
+  "shader-02-render-state": "Render State Control",
+  "shader-03-ui-script": "UIScript System",
+  "shader-04-multi-pass": "Multi-Pass Rendering",
+  "shader-05-advance": "Advanced Features & Code Reuse"
 }
 
diff --git a/...al/examples/shaderlab-01-basic-shader.mdx → ...erial/examples/shader-01-basic-shader.mdx b/...al/examples/shaderlab-01-basic-shader.mdx → ...erial/examples/shader-01-basic-shader.mdx
@@ -2,8 +2,8 @@
 title: Basic Shader Syntax
 ---
 
-This tutorial will introduce the basic syntax of ShaderLab using a simple texture rendering shader. Through this basic example, you will learn:
-- The basic structure of ShaderLab
+This tutorial will introduce the basic syntax of Galacean Shader using a simple texture rendering shader. Through this basic example, you will learn:
+- The basic structure of Galacean Shader
 - How to declare variables and structures
 - Basic vertex shader transformations
 - Texture sampling in fragment shaders
@@ -15,7 +15,7 @@ src="https://mdn.alipayobjects.com/huamei_dmxymu/afts/img/A*Ykx2T7IuiAIAAAAAT0AA
 
 ## Shader Structure
 
-ShaderLab uses a three-level nested structure: `Shader` → `SubShader` → `Pass`
+Galacean Shader uses a three-level nested structure: `Shader` → `SubShader` → `Pass`
 
 ```glsl
 Shader "Tutorial/01-BasicShader" {
@@ -205,4 +205,4 @@ This shader will:
 4. Multiply the texture color with the base color to get the final color
 
 
-Go to [Playground](/examples/shaderlab-01-basic-shader)
+Go to [Playground](/examples/shader-01-basic-shader)