feat(core): GPU instancing auto-batching

docs/en/graphics/material/examples/shader-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/shader-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/animator-customBlendShape.ts

@@ -32,7 +32,6 @@ WebGLEngine.create({ canvas: "canvas" }).then((engine) => {
   cameraEntity.transform.position = new Vector3(0, 0, 5);
   const camera = cameraEntity.addComponent(Camera);
 
-
   const meshEntity = rootEntity.createChild("meshEntity");
   const skinnedMeshRenderer = meshEntity.addComponent(SkinnedMeshRenderer);
   const modelMesh = new ModelMesh(engine);

e2e/case/gltf-blendshape.ts

@@ -54,4 +54,4 @@ WebGLEngine.create({ canvas: "canvas" }).then((engine) => {
 
       initScreenshot(engine, camera);
     });
-});
+});

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,112 @@
+/**
+ * @title GPU Instancing Custom Data
+ * @category Mesh
+ */
+import {
+  Camera,
+  Color,
+  DirectLight,
+  Logger,
+  Material,
+  MeshRenderer,
+  PrimitiveMesh,
+  Shader,
+  ShaderProperty,
+  Vector3,
+  Vector4,
+  WebGLEngine
+} from "@galacean/engine";
+import { ShaderCompiler } from "@galacean/engine-shader-compiler";
+import { initScreenshot, updateForE2E } from "./.mockForE2E";
+
+Logger.enable();
+
+const shaderCompiler = new ShaderCompiler();
+
+// Custom shader: uses renderer_CustomColor (per-instance) for fragment output
+const customInstanceShaderSource = `Shader "CustomInstanceShader" {
+  SubShader "Default" {
+    Pass "Forward" {
+      struct Attributes {
+        vec3 POSITION;
+        vec3 NORMAL;
+      };
+
+      struct Varyings {
+        vec3 v_normal;
+      };
+
+      mat4 renderer_MVPMat;
+      mat4 renderer_NormalMat;
+      vec4 renderer_CustomColor;
+
+      VertexShader = vert;
+      FragmentShader = frag;
+
+      Varyings vert(Attributes attr) {
+        Varyings v;
+        gl_Position = renderer_MVPMat * vec4(attr.POSITION, 1.0);
+        v.v_normal = normalize((renderer_NormalMat * vec4(attr.NORMAL, 0.0)).xyz);
+        return v;
+      }
+
+      vec4 frag(Varyings v) {
+        vec3 lightDir = normalize(vec3(1.0, 1.0, 1.0));
+        float NdotL = max(dot(v.v_normal, lightDir), 0.2);
+        return vec4(renderer_CustomColor.rgb * NdotL, 1.0);
+      }
+    }
+  }
+}`;
+
+WebGLEngine.create({ canvas: "canvas", shaderCompiler }).then((engine) => {
+  Shader.create(customInstanceShaderSource);
+  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/case/spriteMask-customStencil.ts

@@ -151,7 +151,15 @@ WebGLEngine.create({ canvas: "canvas", shaderCompiler: new ShaderCompiler() }).t
       // Create a sprite renderer that writes stencil.
       pos.set(0, 0, 0);
       scale.set(5, 5, 5);
-      const writeStencilSR = addSpriteRenderer(pos, scale, sprite, SpriteMaskInteraction.None, Layer.Layer0, Layer.Layer0, 0);
+      const writeStencilSR = addSpriteRenderer(
+        pos,
+        scale,
+        sprite,
+        SpriteMaskInteraction.None,
+        Layer.Layer0,
+        Layer.Layer0,
+        0
+      );
       const writeStencilMaterial = writeStencilSR.getInstanceMaterial();
       writeStencilMaterial.shader = customStencilShader;
       const writeStencilData = writeStencilMaterial.shaderData;
@@ -161,7 +169,15 @@ WebGLEngine.create({ canvas: "canvas", shaderCompiler: new ShaderCompiler() }).t
 
       // Create a sprite renderer that reads stencil.
       pos.set(3, 3, 0);
-      const readStencilSR = addSpriteRenderer(pos, scale, sprite, SpriteMaskInteraction.None, Layer.Layer0, Layer.Layer0, 1);
+      const readStencilSR = addSpriteRenderer(
+        pos,
+        scale,
+        sprite,
+        SpriteMaskInteraction.None,
+        Layer.Layer0,
+        Layer.Layer0,
+        1
+      );
       readStencilSR.color.set(1, 0, 0, 1);
       const readStencilMaterial = readStencilSR.getInstanceMaterial();
       readStencilMaterial.shader = customStencilShader;
@@ -173,7 +189,15 @@ WebGLEngine.create({ canvas: "canvas", shaderCompiler: new ShaderCompiler() }).t
 
       // Create a sprite renderer with mask interaction (does not need custom stencil).
       pos.set(5, -3, 0);
-      const maskSR = addSpriteRenderer(pos, scale, sprite, SpriteMaskInteraction.VisibleOutsideMask, Layer.Layer0, Layer.Layer0, 2);
+      const maskSR = addSpriteRenderer(
+        pos,
+        scale,
+        sprite,
+        SpriteMaskInteraction.VisibleOutsideMask,
+        Layer.Layer0,
+        Layer.Layer0,
+        2
+      );
       maskSR.color.set(0, 1, 0, 1);
 
       // Create a sprite mask.
@@ -183,7 +207,15 @@ WebGLEngine.create({ canvas: "canvas", shaderCompiler: new ShaderCompiler() }).t
       // Create another sprite renderer that reads stencil with a different comparison.
       pos.set(20, 10, 0);
       scale.set(3, 3, 3);
-      const readStencilSR2 = addSpriteRenderer(pos, scale, sprite, SpriteMaskInteraction.None, Layer.Layer0, Layer.Layer0, 4);
+      const readStencilSR2 = addSpriteRenderer(
+        pos,
+        scale,
+        sprite,
+        SpriteMaskInteraction.None,
+        Layer.Layer0,
+        Layer.Layer0,
+        4
+      );
       readStencilSR2.color.set(1, 0.5, 0.8, 1);
       const readStencilMaterial2 = readStencilSR2.getInstanceMaterial();
       readStencilMaterial2.shader = customStencilShader;