refactor(particle): rename ParticleScaleMode enums for clarity (#2970)

* refactor(particle): rename ParticleScaleMode enums for clarity

(cherry picked from commit 00942cc808)

docs/en/graphics/particle/renderer-main-module.mdx

@@ -44,6 +44,6 @@ You can debug each property in the provided example to better understand and con
 
 The scalingMode has the following options:
 
-- **Local**: Particles inherit the local transformation of the particle generator, meaning the particle transformation occurs in the generator's local coordinate system.
-- **World**: Particles inherit the global transformation of the particle generator, meaning the particle transformation occurs in the world coordinate system.
-- **Hierarchy**: Particles inherit transformations from the entire transformation hierarchy, meaning particles consider transformations of the generator's parent and higher-level transformations.
+- **World**: Scale particle emission position and size using the world scale, including all parent transforms.
+- **Local**: Scale particle emission position and size using only its own transform scale, ignoring parent scale.
+- **Shape**: Only scale the emission shape area, particles themselves are not affected.

docs/zh/graphics/particle/renderer-main-module.mdx

@@ -44,6 +44,6 @@ label: Graphics/Particle
 
 scalingMode 有以下几种模式：
 
-- **Local**：粒子会继承粒子生成器的局部变换，即粒子的变换是在生成器的本地坐标系中进行的
-- **World**：粒子会继承粒子生成器的全局变换，即粒子的变换是在世界坐标系中进行的
-- **Hierarchy**：粒子会继承整个变换层级中的变换，即粒子会考虑到生成器的父级及更上级的变换
+- **World**：使用世界缩放（包含所有父级变换）来缩放粒子的发射位置和大小
+- **Local**：仅使用自身 Transform 的缩放来缩放粒子的发射位置和大小，忽略父级缩放
+- **Shape**：仅缩放发射形状区域，粒子本身的大小不受影响

e2e/case/particleRenderer-fire.ts

@@ -44,7 +44,7 @@ WebGLEngine.create({
 
   // Create camera
   const cameraEntity = rootEntity.createChild("camera_entity");
-  cameraEntity.transform.position = new Vector3(-10, 1, 3);// -10 can test bounds transform
+  cameraEntity.transform.position = new Vector3(-10, 1, 3); // -10 can test bounds transform
   const camera = cameraEntity.addComponent(Camera);
   camera.fieldOfView = 60;
 
@@ -199,7 +199,7 @@ function createFireGlowParticle(fireEntity: Entity, texture: Texture2D): void {
 
   main.simulationSpace = ParticleSimulationSpace.World;
 
-  main.scalingMode = ParticleScaleMode.Hierarchy;
+  main.scalingMode = ParticleScaleMode.World;
 
   // Emission module
   emission.rateOverTime.constant = 20;
@@ -270,7 +270,7 @@ function createFireSmokeParticle(fireEntity: Entity, texture: Texture2D): void {
 
   main.simulationSpace = ParticleSimulationSpace.World;
 
-  main.scalingMode = ParticleScaleMode.Hierarchy;
+  main.scalingMode = ParticleScaleMode.World;
 
   // Emission module
   emission.rateOverTime.constant = 25;
@@ -353,7 +353,7 @@ function createFireEmbersParticle(fireEntity: Entity, texture: Texture2D): void
 
   main.simulationSpace = ParticleSimulationSpace.World;
 
-  main.scalingMode = ParticleScaleMode.Hierarchy;
+  main.scalingMode = ParticleScaleMode.World;
 
   // Emission module
   emission.rateOverTime.constant = 65;

packages/core/src/particle/enums/ParticleScaleMode.ts

@@ -2,10 +2,10 @@
  * Control how Particle Generator apply transform scale.
  */
 export enum ParticleScaleMode {
-  /** Scale the Particle Generator using the entire transform hierarchy. */
-  Hierarchy,
-  /** Scale the Particle Generator using only its own transform scale. (Ignores parent scale). */
+  /** Scale the Particle Generator using the world scale, including all parent transforms. */
+  World,
+  /** Scale the Particle Generator using only its own transform scale, ignoring parent scale. */
   Local,
-  /** Only apply transform scale to the shape component, which controls where particles are spawned, but does not affect their size or movement. */
-  World
+  /** Scale only the emitter shape positions; particle size and movement are unaffected. */
+  Shape
 }

packages/core/src/particle/modules/MainModule.ts

@@ -277,8 +277,8 @@ export class MainModule implements ICustomClone {
   _getPositionScale(): Vector3 {
     const transform = this._generator._renderer.entity.transform;
     switch (this.scalingMode) {
-      case ParticleScaleMode.Hierarchy:
       case ParticleScaleMode.World:
+      case ParticleScaleMode.Shape:
         return transform.lossyWorldScale;
       case ParticleScaleMode.Local:
         return transform.scale;
@@ -306,7 +306,7 @@ export class MainModule implements ICustomClone {
     }
 
     switch (this.scalingMode) {
-      case ParticleScaleMode.Hierarchy:
+      case ParticleScaleMode.World:
         var scale = transform.lossyWorldScale;
         shaderData.setVector3(MainModule._positionScale, scale);
         shaderData.setVector3(MainModule._sizeScale, scale);
@@ -316,7 +316,7 @@ export class MainModule implements ICustomClone {
         shaderData.setVector3(MainModule._positionScale, scale);
         shaderData.setVector3(MainModule._sizeScale, scale);
         break;
-      case ParticleScaleMode.World:
+      case ParticleScaleMode.Shape:
         shaderData.setVector3(MainModule._positionScale, transform.lossyWorldScale);
         shaderData.setVector3(MainModule._sizeScale, MainModule._vector3One);
         break;