diff --git a/cocos/particle/emitter/shape-module.ts b/cocos/particle/emitter/shape-module.ts index a007c0125a..8a41dd230f 100644 --- a/cocos/particle/emitter/shape-module.ts +++ b/cocos/particle/emitter/shape-module.ts @@ -110,7 +110,7 @@ export default class ShapeModule { */ @displayOrder(6) @tooltip('i18n:shapeModule.arc') - @visible(function (this: ShapeModule) { + @visible(function selectArc (this: ShapeModule) { const subset: Array = ['Cone', 'Circle']; const enumName = getShapeTypeEnumName(this.shapeType); return subset.includes(enumName); @@ -131,7 +131,7 @@ export default class ShapeModule { */ @displayOrder(5) @tooltip('i18n:shapeModule.angle') - @visible(function (this: ShapeModule) { + @visible(function selectAngle (this: ShapeModule) { const subset: Array = ['Cone']; const enumName = getShapeTypeEnumName(this.shapeType); return subset.includes(enumName); @@ -208,7 +208,7 @@ export default class ShapeModule { @serializable @displayOrder(2) @tooltip('i18n:shapeModule.emitFrom') - @visible(function (this: ShapeModule) { + @visible(function selectEmitFrom (this: ShapeModule) { const subset: Array = ['Box', 'Cone', 'Sphere', 'Hemisphere']; const enumName = getShapeTypeEnumName(this.shapeType); return subset.includes(enumName); @@ -216,8 +216,8 @@ export default class ShapeModule { public emitFrom = ParticleEmitLocation.Volume; /** - * @en Align particle with particle direction. - * @zh 根据粒子的初始方向决定粒子的移动方向。 + * @en Align the particle's negative Z axis with its initial emission direction, then apply start rotation. + * @zh 将粒子的负 Z 轴对齐到初始发射方向,再叠加初始旋转。 */ @serializable @displayOrder(16) @@ -258,7 +258,7 @@ export default class ShapeModule { @serializable @displayOrder(3) @tooltip('i18n:shapeModule.radius') - @visible(function (this: ShapeModule) { + @visible(function selectRadius (this: ShapeModule) { const subset: Array = ['Circle', 'Cone', 'Sphere', 'Hemisphere']; const enumName = getShapeTypeEnumName(this.shapeType); return subset.includes(enumName); @@ -278,7 +278,7 @@ export default class ShapeModule { @serializable @displayOrder(4) @tooltip('i18n:shapeModule.radiusThickness') - @visible(function (this: ShapeModule) { + @visible(function selectRadiusThickness (this: ShapeModule) { const subset: Array = ['Circle', 'Cone', 'Sphere', 'Hemisphere']; const enumName = getShapeTypeEnumName(this.shapeType); return subset.includes(enumName); @@ -293,7 +293,7 @@ export default class ShapeModule { @serializable @displayOrder(7) @tooltip('i18n:shapeModule.arcMode') - @visible(function (this: ShapeModule) { + @visible(function selectArcMode (this: ShapeModule) { const subset: Array = ['Cone', 'Circle']; const enumName = getShapeTypeEnumName(this.shapeType); return subset.includes(enumName); @@ -304,11 +304,12 @@ export default class ShapeModule { * @en Control arc spread for Cone and circle shape. * @zh 控制可能产生粒子的弧周围的离散间隔。 */ - @visible(function noArc (this: ShapeModule) { return this.arcMode !== ParticleArcMode.Random; }) // Bug fix: Hide this input when arcMode is random + // Bug fix: Hide this input when arcMode is random + @visible(function noArc (this: ShapeModule) { return this.arcMode !== ParticleArcMode.Random; }) @serializable @displayOrder(9) @tooltip('i18n:shapeModule.arcSpread') - @visible(function (this: ShapeModule) { + @visible(function selectArcSpread (this: ShapeModule) { const subset: Array = ['Cone', 'Circle']; const enumName = getShapeTypeEnumName(this.shapeType); return subset.includes(enumName); @@ -319,13 +320,14 @@ export default class ShapeModule { * @en Emit speed around arc (available for Cone and Circle). * @zh 粒子沿圆周发射的速度。 */ + // Bug fix: Hide this input when arcMode is random @type(CurveRange) - @visible(function noArc (this: ShapeModule) { return this.arcMode !== ParticleArcMode.Random; }) // Bug fix: Hide this input when arcMode is random + @visible(function noArc (this: ShapeModule) { return this.arcMode !== ParticleArcMode.Random; }) @range([0, 1]) @serializable @displayOrder(10) @tooltip('i18n:shapeModule.arcSpeed') - @visible(function (this: ShapeModule) { + @visible(function selectArcSpeed (this: ShapeModule) { const subset: Array = ['Cone', 'Circle']; const enumName = getShapeTypeEnumName(this.shapeType); return subset.includes(enumName); @@ -340,7 +342,7 @@ export default class ShapeModule { @serializable @displayOrder(11) @tooltip('i18n:shapeModule.length') - @visible(function (this: ShapeModule) { + @visible(function selectCone (this: ShapeModule) { const subset: Array = ['Cone']; const enumName = getShapeTypeEnumName(this.shapeType); return subset.includes(enumName); @@ -354,7 +356,7 @@ export default class ShapeModule { @serializable @displayOrder(12) @tooltip('i18n:shapeModule.boxThickness') - @visible(function (this: ShapeModule) { + @visible(function selectBox (this: ShapeModule) { const subset: Array = ['Box']; const enumName = getShapeTypeEnumName(this.shapeType); return subset.includes(enumName); @@ -445,6 +447,7 @@ export default class ShapeModule { if (this.arcMode === ParticleArcMode.Random) { return randomRange(0, this._arc); } + /* eslint-disable-next-line max-len */ let angle = this.totalAngle + 2 * Math.PI * this.arcSpeed.evaluate(this.particleSystem!.time, 1)! * (this.particleSystem!.time - this.lastTime); this.totalAngle = angle; if (this.arcSpread !== 0) { diff --git a/cocos/particle/particle-system.ts b/cocos/particle/particle-system.ts index 234aea2b8a..dd27db7e2f 100644 --- a/cocos/particle/particle-system.ts +++ b/cocos/particle/particle-system.ts @@ -55,6 +55,9 @@ import { director, DirectorEvent } from '../game/director'; const _world_mat = new Mat4(); const _world_rol = new Quat(); +const _emitDirection = new Vec3(); +const _alignRotation = new Quat(); +const _startRotation = new Quat(); const superMaterials = Object.getOwnPropertyDescriptor(Renderer.prototype, 'sharedMaterials')!; @@ -1376,6 +1379,14 @@ export class ParticleSystem extends ModelRenderer { self._textureAnimationModule.init(particle); } + const alignToDirection = self._shapeModule?.enable && self._shapeModule.alignToDirection; + if (alignToDirection) { + Vec3.copy(_emitDirection, particle.velocity); + if (self._simulationSpace === ParticleSpace.World) { + Vec3.transformQuat(_emitDirection, _emitDirection, _world_rol); + } + } + const curveStartSpeed = self.startSpeed.evaluate(loopDelta, rand)!; Vec3.multiplyScalar(particle.velocity, particle.velocity, curveStartSpeed); @@ -1392,6 +1403,17 @@ export class ParticleSystem extends ModelRenderer { } else { particle.startEuler.set(0, 0, self.startRotationZ.evaluate(loopDelta, rand)); } + if (alignToDirection && _emitDirection.lengthSqr() > 0) { + // Align before applying start rotation, in simulation space. Use the + // shape direction so zero start speed still has a defined orientation. + Vec3.normalize(_emitDirection, _emitDirection); + Quat.rotationTo(_alignRotation, particleEmitZAxis, _emitDirection); + const r2d = 180 / Math.PI; + Quat.fromEuler(_startRotation, particle.startEuler.x * r2d, particle.startEuler.y * r2d, particle.startEuler.z * r2d); + Quat.multiply(_startRotation, _alignRotation, _startRotation); + Quat.toEuler(particle.startEuler, _startRotation); + particle.startEuler.multiplyScalar(1 / r2d); + } particle.rotation.set(particle.startEuler); // apply startSize. diff --git a/cocos/particle/renderer/particle-system-renderer-cpu.ts b/cocos/particle/renderer/particle-system-renderer-cpu.ts index d4eb6af86c..686d80d75e 100644 --- a/cocos/particle/renderer/particle-system-renderer-cpu.ts +++ b/cocos/particle/renderer/particle-system-renderer-cpu.ts @@ -336,7 +336,16 @@ export default class ParticleSystemRendererCPU extends ParticleSystemRendererBas return; } - if (this._alignSpace === ParticleAlignmentSpace.Local) { + const ps = this._particleSystem; + if (mode === ParticleRenderMode.Mesh && ps?._shapeModule?.enable && ps._shapeModule.alignToDirection) { + // Aligned particle rotations are already in simulation space. The mesh + // shader only needs the remaining simulation-to-world rotation. + if (ps.simulationSpace === ParticleSpace.Local) { + ps.node.getWorldRotation(_node_rot); + } else { + _node_rot.set(0, 0, 0, 1); + } + } else if (this._alignSpace === ParticleAlignmentSpace.Local) { this._particleSystem?.node.getRotation(_node_rot); } else if (this._alignSpace === ParticleAlignmentSpace.World) { this._particleSystem?.node.getWorldRotation(_node_rot); diff --git a/cocos/particle/renderer/particle-system-renderer-gpu.ts b/cocos/particle/renderer/particle-system-renderer-gpu.ts index 31b94503cd..5f6cd5fdbb 100644 --- a/cocos/particle/renderer/particle-system-renderer-gpu.ts +++ b/cocos/particle/renderer/particle-system-renderer-gpu.ts @@ -265,7 +265,16 @@ export default class ParticleSystemRendererGPU extends ParticleSystemRendererBas return; } - if (this._alignSpace === ParticleAlignmentSpace.Local) { + const ps = this._particleSystem; + if (mode === ParticleRenderMode.Mesh && ps?._shapeModule?.enable && ps._shapeModule.alignToDirection) { + // Aligned particle rotations are already in simulation space. The mesh + // shader only needs the remaining simulation-to-world rotation. + if (ps.simulationSpace === ParticleSpace.Local) { + ps.node.getWorldRotation(_node_rot); + } else { + _node_rot.set(0, 0, 0, 1); + } + } else if (this._alignSpace === ParticleAlignmentSpace.Local) { this._particleSystem?.node.getRotation(_node_rot); } else if (this._alignSpace === ParticleAlignmentSpace.World) { this._particleSystem?.node.getWorldRotation(_node_rot); diff --git a/tests/particle/align-to-direction.test.ts b/tests/particle/align-to-direction.test.ts new file mode 100644 index 0000000000..603f36986b --- /dev/null +++ b/tests/particle/align-to-direction.test.ts @@ -0,0 +1,175 @@ +import { Quat, Vec3 } from '../../cocos/core'; +import { Node, Scene } from '../../cocos/scene-graph'; +import { ParticleSystem } from '../../cocos/particle/particle-system'; +import { Particle } from '../../cocos/particle/particle'; +import { ParticleAlignmentSpace, ParticleRenderMode, ParticleShapeType, ParticleSpace } from '../../cocos/particle/enum'; +import RotationOvertimeModule from '../../cocos/particle/animator/rotation-overtime'; +import ShapeModule from '../../cocos/particle/emitter/shape-module'; +import ParticleSystemRendererCPU from '../../cocos/particle/renderer/particle-system-renderer-cpu'; +import ParticleSystemRendererGPU from '../../cocos/particle/renderer/particle-system-renderer-gpu'; +import ParticleSystemRenderer from '../../cocos/particle/renderer/particle-system-renderer-data'; +import { ParticleSystemRendererBase } from '../../cocos/particle/renderer/particle-system-renderer-base'; +import { Pass } from '../../cocos/render-scene'; + +const forward = new Vec3(0, 0, -1); + +function rotationOf(p: Particle): Quat { + return Quat.fromEuler(new Quat(), p.rotation.x * Particle.R2D, p.rotation.y * Particle.R2D, p.rotation.z * Particle.R2D); +} + +function expectRotation(actual: Quat, expected: Quat): void { + // Compare transformed basis vectors: q and -q represent the same rotation. + for (const axis of [Vec3.UNIT_X, Vec3.UNIT_Y, Vec3.UNIT_Z]) { + const a = Vec3.transformQuat(new Vec3(), axis, actual); + const b = Vec3.transformQuat(new Vec3(), axis, expected); + expect(a.x).toBeCloseTo(b.x, 5); + expect(a.y).toBeCloseTo(b.y, 5); + expect(a.z).toBeCloseTo(b.z, 5); + } +} + +function fixture() { + const ps = new ParticleSystem(); + ps.node = new Node(); + const p = new Particle(ps); + // Exercise the shared CPU/GPU emission path without allocating render resources. + ps.processor = { + getFreeParticle: () => p, + setNewParticle: jest.fn(), + getInfo: () => ({ renderMode: ParticleRenderMode.Mesh }), + updateMaterialParams: () => {}, + updateTrailMaterial: () => {}, + } as unknown as ParticleSystem['processor']; + const shape = new ShapeModule(); + ps.shapeModule = shape; + shape.onInit(ps); + shape.enable = true; + shape.alignToDirection = true; + shape.shapeType = ParticleShapeType.Box; + return { ps, p, shape }; +} + +describe('AlignToDirection', () => { + describe.each([ParticleSystemRendererCPU, ParticleSystemRendererGPU])('mesh renderer %p', (Renderer) => { + test.each([ + [ParticleSpace.Local, ParticleAlignmentSpace.Local], + [ParticleSpace.Local, ParticleAlignmentSpace.World], + [ParticleSpace.Local, ParticleAlignmentSpace.View], + [ParticleSpace.World, ParticleAlignmentSpace.Local], + [ParticleSpace.World, ParticleAlignmentSpace.World], + [ParticleSpace.World, ParticleAlignmentSpace.View], + ])('combines shader rotations in simulation space %s with alignment space %s', (space, alignment) => { + const { ps, p, shape } = fixture(); + const scene = new Scene(); + const parent = new Node(); + scene.addChild(parent); + parent.addChild(ps.node); + Object.defineProperty(ps.node, 'scene', { value: scene }); + parent.setRotationFromEuler(15, 25, 35); + ps.node.setRotationFromEuler(20, 50, 10); + // A rotated camera must not change a direction-aligned mesh. + Object.defineProperty(scene, 'renderScene', { value: { cameras: [{ + visibility: 0xffffffff, name: 'Editor Camera', forward: new Vec3(1, 0, 0), + }] } }); + ps.simulationSpace = space; + shape.rotation = new Vec3(30, 40, 0); + ps.emit(1, 0); + const info = new ParticleSystemRenderer(); + info.renderMode = ParticleRenderMode.Mesh; + const renderer = new Renderer(info); + // Initialize only the system reference; no GPU resources are needed. + ParticleSystemRendererBase.prototype.onInit.call(renderer, ps); + renderer.updateAlignSpace(alignment); + const uniform = new Quat(); + const pass = { setUniform: (_handle: number, value: Quat) => Quat.copy(uniform, value) } as unknown as Pass; + const check = () => { + renderer.updateRotation(pass); + // Match particle-vs-legacy.chunk: rotMat = nodeMat * rotMat. + const rendered = Quat.multiply(new Quat(), uniform, rotationOf(p)); + const actual = Vec3.transformQuat(new Vec3(), forward, rendered); + const expected = p.velocity.clone().normalize(); + if (space === ParticleSpace.Local) Vec3.transformQuat(expected, expected, ps.node.worldRotation); + expect(actual.x).toBeCloseTo(expected.x, 5); + expect(actual.y).toBeCloseTo(expected.y, 5); + expect(actual.z).toBeCloseTo(expected.z, 5); + }; + check(); + // Existing world particles remain fixed; local particles follow their parent. + parent.setRotationFromEuler(60, -35, 20); + ps.node.setRotationFromEuler(-10, 80, 30); + check(); + + // Disabling alignment restores the renderer's existing alignment-space behavior. + shape.alignToDirection = false; + renderer.updateRotation(pass); + const expected = alignment === ParticleAlignmentSpace.Local ? ps.node.rotation + : alignment === ParticleAlignmentSpace.World ? ps.node.worldRotation + : Quat.fromViewUp(new Quat(), new Vec3(1, 0, 0)); + expectRotation(uniform, expected); + }); + }); + + test.each([[0, 0, 0], [0, 180, 0], [90, 0, 0], [31, 47, 19]])('aligns with rotated shape (%s, %s, %s)', (x, y, z) => { + const { ps, p, shape } = fixture(); + shape.rotation = new Vec3(x, y, z); + ps.emit(1, 0); + const direction = Vec3.transformQuat(new Vec3(), forward, rotationOf(p)); + const velocity = p.velocity.clone().normalize(); + expect(direction.x).toBeCloseTo(velocity.x, 5); + expect(direction.y).toBeCloseTo(velocity.y, 5); + expect(direction.z).toBeCloseTo(velocity.z, 5); + }); + + test.each([ParticleSpace.Local, ParticleSpace.World])('composes start rotation in simulation space %s, even at zero speed', (space) => { + const { ps, p, shape } = fixture(); + ps.simulationSpace = space; + ps.node.setRotationFromEuler(20, 50, 10); + shape.rotation = new Vec3(30, 40, 0); + ps.startSpeed.constant = 0; + ps.startRotation3D = true; + ps.startRotationX.constant = 0.2; + ps.startRotationY.constant = 0.3; + ps.startRotationZ.constant = 0.4; + const direction = Vec3.transformQuat(new Vec3(), forward, Quat.fromEuler(new Quat(), 30, 40, 0)); + if (space === ParticleSpace.World) Vec3.transformQuat(direction, direction, ps.node.worldRotation); + const expected = Quat.rotationTo(new Quat(), forward, direction.normalize()); + Quat.multiply(expected, expected, Quat.fromEuler(new Quat(), 0.2 * Particle.R2D, 0.3 * Particle.R2D, 0.4 * Particle.R2D)); + ps.emit(1, 0); + expectRotation(rotationOf(p), expected); + expect(p.velocity.lengthSqr()).toBe(0); + + const module = new RotationOvertimeModule(); + module.z.constant = 0.6; + module.animate(p, 0.5); + Quat.multiply(expected, expected, Quat.fromEuler(new Quat(), 0, 0, 0.3 * Particle.R2D)); + const encoded = p.rotation.clone(); + const sign = encoded.x > Particle.INDENTIFY_NEG_QUAT * 0.5 ? -1 : 1; + if (sign < 0) encoded.x -= Particle.INDENTIFY_NEG_QUAT; + expectRotation(new Quat(encoded.x, encoded.y, encoded.z, sign * Math.sqrt(Math.abs(1 - encoded.lengthSqr()))), expected); + }); + + test.each(['alignment', 'shape'])('resets reused particles when %s is disabled', (disabled) => { + const { ps, p, shape } = fixture(); + shape.rotation = new Vec3(0, 90, 0); + ps.startRotationZ.constant = 0.4; + ps.emit(1, 0); + if (disabled === 'alignment') shape.alignToDirection = false; + else shape.enable = false; + ps.emit(1, 0); + expect(p.rotation).toEqual(new Vec3(0, 0, 0.4)); + expect(p.startRotated).toBe(false); + }); + + test('uses the final spherical direction and handles a degenerate direction', () => { + const { ps, p, shape } = fixture(); + shape.scale = Vec3.ZERO.clone(); + shape.position = new Vec3(3, 4, 0); + shape.sphericalDirectionAmount = 1; + ps.emit(1, 0); + expectRotation(rotationOf(p), Quat.rotationTo(new Quat(), forward, new Vec3(0.6, 0.8, 0))); + shape.position = Vec3.ZERO.clone(); + ps.startRotationZ.constant = 0.7; + ps.emit(1, 0); + expect(p.rotation).toEqual(new Vec3(0, 0, 0.7)); + }); +});