feat(core): GPU instancing auto-batching

docs/en/graphics/material/examples/shaderlab-05-advance.mdx

@@ -190,7 +190,6 @@ gl_FragColor = vec4(lighting, 1.0);
 
 The engine provides a rich set of built-in variables that can be used directly, such as transformation matrix variables:
 ```glsl
-mat4 renderer_LocalMat;    // Local transformation matrix
 mat4 renderer_ModelMat;    // Model matrix
 mat4 renderer_MVMat;       // Model-view matrix
 mat4 renderer_MVPMat;      // MVP matrix

docs/en/graphics/material/shaderAPI.mdx

@@ -27,7 +27,6 @@ vec4 fog(vec4 color, vec3 positionVS);
 Provides system variables for model space, view space, world space, and camera coordinates:
 
 ```glsl
-mat4 renderer_LocalMat;
 mat4 renderer_ModelMat;
 mat4 camera_ViewMat;
 mat4 camera_ProjMat;

docs/en/graphics/material/variables.mdx

@@ -25,7 +25,6 @@ Below are the engine's built-in variables for reference when writing Shaders:
 
 | Name              | Type | Description                  |
 | :---------------- | :--- | :--------------------------- |
-| renderer_LocalMat | mat4 | Model local coordinate matrix |
 | renderer_ModelMat | mat4 | Model world coordinate matrix |
 | renderer_MVMat    | mat4 | Model view matrix            |
 | renderer_MVPMat   | mat4 | Model view projection matrix |

docs/zh/graphics/material/examples/shaderlab-05-advance.mdx

@@ -193,7 +193,6 @@ void frag() {
 
 引擎提供了丰富的内置变量，直接声明使用即可，比如变换矩阵相关变量：
 ```glsl
-mat4 renderer_LocalMat;    // 本地变换矩阵
 mat4 renderer_ModelMat;    // 模型矩阵
 mat4 renderer_MVMat;       // 模型视图矩阵
 mat4 renderer_MVPMat;      // MVP矩阵

docs/zh/graphics/material/shaderAPI.mdx

@@ -29,7 +29,6 @@ vec4 fog(vec4 color, vec3 positionVS);
 提供了模型空间、视图空间、世界空间、相机坐标等[系统变量](/docs/graphics/material/variables/):
 
 ```glsl
-mat4 renderer_LocalMat;
 mat4 renderer_ModelMat;
 mat4 camera_ViewMat;
 mat4 camera_ProjMat;

docs/zh/graphics/material/variables.mdx

@@ -25,7 +25,6 @@ Shader 代码中会经常用到内置变量，一种是**逐顶点**的 `attribu
 
 | 名字               | 类型 | 解释               |
 | :----------------- | :--- | ------------------ |
-| renderer_LocalMat  | mat4 | 模型本地坐标系矩阵 |
 | renderer_ModelMat  | mat4 | 模型世界坐标系矩阵 |
 | renderer_MVMat     | mat4 | 模型视口矩阵       |
 | renderer_MVPMat    | mat4 | 模型视口投影矩阵   |

e2e/case/gpu-instancing-auto-batch.ts

@@ -0,0 +1,68 @@
+/**
+ * @title GPU Instancing Auto Batch
+ * @category Mesh
+ */
+import {
+  AmbientLight,
+  AssetType,
+  Camera,
+  Color,
+  DirectLight,
+  GLTFResource,
+  Logger,
+  Vector3,
+  WebGLEngine
+} from "@galacean/engine";
+import { initScreenshot, updateForE2E } from "./.mockForE2E";
+
+Logger.enable();
+WebGLEngine.create({ canvas: "canvas" }).then(async (engine) => {
+  engine.canvas.resizeByClientSize(2);
+
+  const scene = engine.sceneManager.activeScene;
+  const rootEntity = scene.createRootEntity("Root");
+
+  // Camera
+  const cameraEntity = rootEntity.createChild("Camera");
+  cameraEntity.transform.setPosition(0, 10, 80);
+  cameraEntity.transform.lookAt(new Vector3(0, 0, 0));
+  const camera = cameraEntity.addComponent(Camera);
+  camera.farClipPlane = 300;
+
+  // Light
+  const lightEntity = rootEntity.createChild("Light");
+  lightEntity.transform.setRotation(-45, -45, 0);
+  lightEntity.addComponent(DirectLight).color = new Color(1, 1, 1, 1);
+
+  // Load Duck model and ambient light
+  const [glTF, ambientLight] = await Promise.all([
+    engine.resourceManager.load<GLTFResource>({
+      url: "https://gw.alipayobjects.com/os/bmw-prod/6cb8f543-285c-491a-8cfd-57a1160dc9ab.glb",
+      type: AssetType.GLTF
+    }),
+    engine.resourceManager.load<AmbientLight>({
+      url: "https://mdn.alipayobjects.com/oasis_be/afts/file/A*eRJ8QKzf5zAAAAAAgBAAAAgAekp5AQ/ambient.ambLight",
+      type: AssetType.AmbientLight
+    })
+  ]);
+  scene.ambientLight = ambientLight;
+
+  // Clone ducks with fixed seed positions for deterministic output
+  const count = 500;
+  const spread = 50;
+  for (let i = 0; i < count; i++) {
+    const duck = glTF.instantiateSceneRoot();
+    // Use deterministic positions based on index
+    const t = i / count;
+    duck.transform.setPosition(
+      Math.sin(t * 137.5) * spread * 0.5,
+      Math.cos(t * 97.3) * spread * 0.5,
+      Math.sin(t * 59.1) * spread * 0.5
+    );
+    duck.transform.setRotation(t * 360, t * 720, t * 1080);
+    rootEntity.addChild(duck);
+  }
+
+  updateForE2E(engine);
+  initScreenshot(engine, camera);
+});

e2e/case/gpu-instancing-custom-data.ts

@@ -0,0 +1,100 @@
+/**
+ * @title GPU Instancing Custom Data
+ * @category Mesh
+ */
+import {
+  Camera,
+  Color,
+  DirectLight,
+  Logger,
+  Material,
+  MeshRenderer,
+  PrimitiveMesh,
+  Shader,
+  ShaderProperty,
+  Vector3,
+  Vector4,
+  WebGLEngine
+} from "@galacean/engine";
+import { initScreenshot, updateForE2E } from "./.mockForE2E";
+
+Logger.enable();
+
+// Custom shader: uses renderer_CustomColor (per-instance) for fragment output
+Shader.create(
+  "CustomInstanceShader",
+  `
+  #include <transform_declare>
+  attribute vec3 POSITION;
+  attribute vec3 NORMAL;
+
+  varying vec3 v_normal;
+
+  void main() {
+    gl_Position = renderer_MVPMat * vec4(POSITION, 1.0);
+    v_normal = normalize((renderer_NormalMat * vec4(NORMAL, 0.0)).xyz);
+  }
+  `,
+  `
+  uniform vec4 renderer_CustomColor;
+
+  varying vec3 v_normal;
+
+  void main() {
+    vec3 lightDir = normalize(vec3(1.0, 1.0, 1.0));
+    float NdotL = max(dot(v_normal, lightDir), 0.2);
+    gl_FragColor = vec4(renderer_CustomColor.rgb * NdotL, 1.0);
+  }
+  `
+);
+
+WebGLEngine.create({ canvas: "canvas" }).then((engine) => {
+  engine.canvas.resizeByClientSize(2);
+
+  const scene = engine.sceneManager.activeScene;
+  const rootEntity = scene.createRootEntity("Root");
+
+  // Camera
+  const cameraEntity = rootEntity.createChild("Camera");
+  cameraEntity.transform.setPosition(0, 10, 80);
+  cameraEntity.transform.lookAt(new Vector3(0, 0, 0));
+  const camera = cameraEntity.addComponent(Camera);
+  camera.farClipPlane = 300;
+
+  // Light
+  const lightEntity = rootEntity.createChild("Light");
+  lightEntity.transform.setRotation(-45, -45, 0);
+  lightEntity.addComponent(DirectLight).color = new Color(1, 1, 1, 1);
+
+  // Shared mesh and material
+  const mesh = PrimitiveMesh.createCuboid(engine, 1, 1, 1);
+  const material = new Material(engine, Shader.find("CustomInstanceShader"));
+  const customColorProperty = ShaderProperty.getByName("renderer_CustomColor");
+
+  // Create cubes with deterministic positions and colors
+  const count = 500;
+  const spread = 50;
+  for (let i = 0; i < count; i++) {
+    const entity = rootEntity.createChild("Cube" + i);
+    const t = i / count;
+    entity.transform.setPosition(
+      Math.sin(t * 137.5) * spread * 0.5,
+      Math.cos(t * 97.3) * spread * 0.5,
+      Math.sin(t * 59.1) * spread * 0.5
+    );
+    entity.transform.setRotation(t * 360, t * 720, t * 1080);
+
+    const renderer = entity.addComponent(MeshRenderer);
+    renderer.mesh = mesh;
+    renderer.setMaterial(material);
+
+    // Deterministic colors based on index
+    renderer.shaderData.setVector4(
+      customColorProperty,
+      new Vector4(Math.sin(t * 6.28) * 0.5 + 0.5, Math.cos(t * 4.71) * 0.5 + 0.5, Math.sin(t * 3.14) * 0.5 + 0.5, 1.0)
+    );
+  }
+
+  updateForE2E(engine);
+  initScreenshot(engine, camera);
+});

e2e/config.ts

@@ -135,7 +135,7 @@ export const E2E_CONFIG = {
       category: "Material",
       caseFileName: "material-pbr",
       threshold: 0,
-      diffPercentage: 0.0080
+      diffPercentage: 0.008
     },
     shaderLab: {
       category: "Material",
@@ -464,6 +464,20 @@ export const E2E_CONFIG = {
       diffPercentage: 0.03
     }
   },
+  GPUInstancing: {
+    autoBatch: {
+      category: "GPUInstancing",
+      caseFileName: "gpu-instancing-auto-batch",
+      threshold: 0,
+      diffPercentage: 0.00126
+    },
+    customData: {
+      category: "GPUInstancing",
+      caseFileName: "gpu-instancing-custom-data",
+      threshold: 0,
+      diffPercentage: 0
+    }
+  },
   SpriteMask: {
     CustomStencil: {
       category: "SpriteMask",

examples/package.json

@@ -22,6 +22,7 @@
     "@galacean/engine-shader": "workspace:*",
     "@galacean/engine-shaderlab": "workspace:*",
     "@galacean/engine-toolkit": "latest",
+    "@galacean/engine-toolkit-stats": "latest",
     "@galacean/engine-ui": "workspace:*"
   },
   "devDependencies": {