From db67a02f0ed715523d2f8b79f26401bc683fa395 Mon Sep 17 00:00:00 2001 From: ChenMo Date: Fri, 17 Apr 2026 14:58:35 +0800 Subject: [PATCH] refactor(particle): rename ParticleScaleMode enums for clarity (#2970) * refactor(particle): rename ParticleScaleMode enums for clarity (cherry picked from commit 00942cc808bc7d3f32d5e23fb0c44f14854886c7) --- docs/en/graphics/particle/renderer-main-module.mdx | 6 +++--- docs/zh/graphics/particle/renderer-main-module.mdx | 6 +++--- e2e/case/particleRenderer-fire.ts | 8 ++++---- packages/core/src/particle/enums/ParticleScaleMode.ts | 10 +++++----- packages/core/src/particle/modules/MainModule.ts | 6 +++--- 5 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/en/graphics/particle/renderer-main-module.mdx b/docs/en/graphics/particle/renderer-main-module.mdx index 4e3888fea..ea6d2c8e5 100644 --- a/docs/en/graphics/particle/renderer-main-module.mdx +++ b/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. \ No newline at end of file +- **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. \ No newline at end of file diff --git a/docs/zh/graphics/particle/renderer-main-module.mdx b/docs/zh/graphics/particle/renderer-main-module.mdx index b551210dc..1faa4e8be 100644 --- a/docs/zh/graphics/particle/renderer-main-module.mdx +++ b/docs/zh/graphics/particle/renderer-main-module.mdx @@ -44,6 +44,6 @@ label: Graphics/Particle scalingMode 有以下几种模式： -- **Local**：粒子会继承粒子生成器的局部变换，即粒子的变换是在生成器的本地坐标系中进行的 -- **World**：粒子会继承粒子生成器的全局变换，即粒子的变换是在世界坐标系中进行的 -- **Hierarchy**：粒子会继承整个变换层级中的变换，即粒子会考虑到生成器的父级及更上级的变换 +- **World**：使用世界缩放（包含所有父级变换）来缩放粒子的发射位置和大小 +- **Local**：仅使用自身 Transform 的缩放来缩放粒子的发射位置和大小，忽略父级缩放 +- **Shape**：仅缩放发射形状区域，粒子本身的大小不受影响 diff --git a/e2e/case/particleRenderer-fire.ts b/e2e/case/particleRenderer-fire.ts index 6344f7bba..52a0c7afd 100644 --- a/e2e/case/particleRenderer-fire.ts +++ b/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; diff --git a/packages/core/src/particle/enums/ParticleScaleMode.ts b/packages/core/src/particle/enums/ParticleScaleMode.ts index 0f780ef94..b3ec3a3fe 100644 --- a/packages/core/src/particle/enums/ParticleScaleMode.ts +++ b/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 } diff --git a/packages/core/src/particle/modules/MainModule.ts b/packages/core/src/particle/modules/MainModule.ts index 9318cbdb4..d17c156d9 100644 --- a/packages/core/src/particle/modules/MainModule.ts +++ b/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;