feat(particle): support custom particle shaders with custom data

e2e/case/particleRenderer-customShader.ts

@@ -0,0 +1,136 @@
+/**
+ * @title Particle Custom Shader
+ * @category Particle
+ */
+import {
+  BoxShape,
+  Camera,
+  Color,
+  Entity,
+  Logger,
+  ParticleCompositeCurve,
+  ParticleCompositeGradient,
+  ParticleMaterial,
+  ParticleRenderer,
+  Shader,
+  Vector3,
+  WebGLEngine
+} from "@galacean/engine";
+import { ShaderCompiler } from "@galacean/engine-shader-compiler";
+import { initScreenshot, updateForE2E } from "./.mockForE2E";
+
+const shaderCompiler = new ShaderCompiler();
+
+// Custom particle shader: declares the customData uniforms the TS side uploads
+// (suffix tables live on addCurve / addGradient TSDoc) and consumes them
+// directly to drive per-particle color tint and x-offset.
+const customParticleShaderSource = `Shader "Test/ParticleCustom" {
+  SubShader "Default" {
+    Pass "Forward Pass" {
+      Tags { pipelineStage = "Forward" }
+
+      RenderQueueType renderQueueType;
+      BlendFactor sourceColorBlendFactor;
+      BlendFactor destinationColorBlendFactor;
+      BlendFactor sourceAlphaBlendFactor;
+      BlendFactor destinationAlphaBlendFactor;
+      CullMode rasterStateCullMode;
+      Bool blendEnabled;
+      Bool depthWriteEnabled;
+
+      BlendState = {
+        Enabled = blendEnabled;
+        SourceColorBlendFactor = sourceColorBlendFactor;
+        DestinationColorBlendFactor = destinationColorBlendFactor;
+        SourceAlphaBlendFactor = sourceAlphaBlendFactor;
+        DestinationAlphaBlendFactor = destinationAlphaBlendFactor;
+      }
+      DepthState = { WriteEnabled = depthWriteEnabled; }
+      RasterState = { CullMode = rasterStateCullMode; }
+      RenderQueueType = renderQueueType;
+
+      VertexShader = vert;
+      FragmentShader = frag;
+
+      #include "ShaderLibrary/Particle/ParticleVert.glsl"
+
+      // Uniforms uploaded by CustomDataModule:
+      //   addCurve("OffsetX", Constant)    → renderer_OffsetXMaxConst
+      //   addGradient("Tint", Constant)    → renderer_TintMaxConst
+      float renderer_OffsetXMaxConst;
+      vec4 renderer_TintMaxConst;
+
+      Varyings vert(Attributes attr) {
+          Varyings v;
+          float age = renderer_CurrentTime - attr.a_DirectionTime.w;
+          float normalizedAge = age / attr.a_ShapePositionStartLifeTime.w;
+          if (normalizedAge >= 0.0 && normalizedAge < 1.0) {
+              vec3 center = computeParticleCenter(attr, age, normalizedAge, v);
+              center.x += renderer_OffsetXMaxConst;
+              gl_Position = camera_ProjMat * camera_ViewMat * vec4(center, 1.0);
+              v.v_Color = computeParticleColor(attr, attr.a_StartColor, normalizedAge);
+              v.v_Color.rgb *= renderer_TintMaxConst.rgb;
+          } else {
+              gl_Position = vec4(2.0, 2.0, 2.0, 1.0);
+          }
+          return v;
+      }
+
+      void frag(Varyings v) {
+          gl_FragColor = v.v_Color;
+      }
+    }
+  }
+}`;
+
+Logger.enable();
+WebGLEngine.create({ canvas: "canvas", shaderCompiler }).then((engine) => {
+  engine.canvas.resizeByClientSize();
+
+  const scene = engine.sceneManager.activeScene;
+  const rootEntity = scene.createRootEntity();
+  scene.background.solidColor = new Color(0.05, 0.05, 0.05, 1);
+
+  const cameraEntity = rootEntity.createChild("camera");
+  cameraEntity.transform.position = new Vector3(0, 0, 6);
+  const camera = cameraEntity.addComponent(Camera);
+  camera.fieldOfView = 60;
+
+  // Build the particle detached from the scene so the `ParticleRenderer`
+  // `_onEnable` lifecycle hook does not fire until the generator + custom
+  // shader are fully configured.
+  const particleEntity = new Entity(engine, "CustomParticle");
+  const particleRenderer = particleEntity.addComponent(ParticleRenderer);
+
+  const customShader = Shader.create(customParticleShaderSource);
+  const material = new ParticleMaterial(engine, customShader);
+  material.baseColor = new Color(1, 1, 1, 1);
+  particleRenderer.setMaterial(material);
+
+  const generator = particleRenderer.generator;
+  generator.useAutoRandomSeed = false;
+
+  const { main, emission, customData } = generator;
+  main.duration = 5;
+  main.startLifetime.constant = 1.5;
+  main.startSpeed.constant = 0.5;
+  main.startSize.constant = 0.3;
+  main.startColor.constant = new Color(1, 1, 1, 1);
+
+  emission.rateOverTime.constant = 30;
+  const box = new BoxShape();
+  box.size = new Vector3(2, 1, 0);
+  emission.shape = box;
+
+  // Register named custom streams. The uniform names the shader reads above
+  // (`renderer_TintMaxConst`, `renderer_OffsetXMaxConst`) follow the
+  // `renderer_<name><suffix>` convention documented on addCurve/addGradient.
+  customData.enabled = true;
+  customData.addGradient("Tint", new ParticleCompositeGradient(new Color(1, 0.3, 0.1, 1)));
+  customData.addCurve("OffsetX", new ParticleCompositeCurve(0.5));
+
+  rootEntity.addChild(particleEntity);
+
+  updateForE2E(engine, 500);
+  initScreenshot(engine, camera);
+});

e2e/config.ts

@@ -448,6 +448,12 @@ export const E2E_CONFIG = {
       caseFileName: "particleRenderer-burst-cycles",
       threshold: 0,
       diffPercentage: 0.2
+    },
+    customShader: {
+      category: "Particle",
+      caseFileName: "particleRenderer-customShader",
+      threshold: 0,
+      diffPercentage: 0
     }
   },
   PostProcess: {

packages/core/src/particle/ParticleGenerator.ts

@@ -25,6 +25,7 @@ import { ParticleSimulationSpace } from "./enums/ParticleSimulationSpace";
 import { ParticleStopMode } from "./enums/ParticleStopMode";
 import { ParticleFeedbackVertexAttribute } from "./enums/attributes/ParticleFeedbackVertexAttribute";
 import { ColorOverLifetimeModule } from "./modules/ColorOverLifetimeModule";
+import { CustomDataModule } from "./modules/CustomDataModule";
 import { EmissionModule } from "./modules/EmissionModule";
 import { ForceOverLifetimeModule } from "./modules/ForceOverLifetimeModule";
 import { LimitVelocityOverLifetimeModule } from "./modules/LimitVelocityOverLifetimeModule";
@@ -87,6 +88,9 @@ export class ParticleGenerator {
   /** Noise module. */
   @deepClone
   readonly noise: NoiseModule;
+  /** Custom data module — two per-particle vec4 streams readable from a custom shader. */
+  @deepClone
+  readonly customData: CustomDataModule;
 
   /** @internal */
   _currentParticleCount = 0;
@@ -195,6 +199,7 @@ export class ParticleGenerator {
     this.sizeOverLifetime = new SizeOverLifetimeModule(this);
     this.limitVelocityOverLifetime = new LimitVelocityOverLifetimeModule(this);
     this.noise = new NoiseModule(this);
+    this.customData = new CustomDataModule(this);
 
     this.emission.enabled = true;
   }
@@ -619,6 +624,7 @@ export class ParticleGenerator {
     this.rotationOverLifetime._updateShaderData(shaderData);
     this.colorOverLifetime._updateShaderData(shaderData);
     this.noise._updateShaderData(shaderData);
+    this.customData._updateShaderData(shaderData);
   }
 
   /**

packages/core/src/particle/ParticleMaterial.ts

@@ -9,16 +9,17 @@ export class ParticleMaterial extends EffectMaterial {
   /**
    * Create a particle material instance.
    * @param engine - Engine to which the material belongs
+   * @param shader - Shader used by the material
    */
-  constructor(engine: Engine) {
-    super(engine, Shader.find("Effect/Particle"));
+  constructor(engine: Engine, shader: Shader = Shader.find("Effect/Particle")) {
+    super(engine, shader);
   }
 
   /**
    * @inheritdoc
    */
   override clone(): ParticleMaterial {
-    const dest = new ParticleMaterial(this._engine);
+    const dest = new ParticleMaterial(this._engine, this.shader);
     this._cloneToAndModifyName(dest);
     return dest;
   }

packages/core/src/particle/index.ts

@@ -9,6 +9,7 @@ export { ParticleSimulationSpace } from "./enums/ParticleSimulationSpace";
 export { ParticleStopMode } from "./enums/ParticleStopMode";
 export { Burst } from "./modules/Burst";
 export { ColorOverLifetimeModule } from "./modules/ColorOverLifetimeModule";
+export { CustomDataModule } from "./modules/CustomDataModule";
 export { EmissionModule } from "./modules/EmissionModule";
 export { MainModule } from "./modules/MainModule";
 export { ParticleCompositeCurve } from "./modules/ParticleCompositeCurve";