add AlignToDirection implement (#394)

* add AlignToDirection implement

* fix eslint

* fix max line error

* fix ParticleSpace world condition
This commit is contained in:
zxx43
2026-11-03 11:45:39 +08:00
committed by GitHub
parent b9f9e95b9b
commit a69be8d0a7
5 changed files with 234 additions and 16 deletions
+17 -14
View File
@@ -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<keyof typeof ParticleShapeType> = ['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<keyof typeof ParticleShapeType> = ['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<keyof typeof ParticleShapeType> = ['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<keyof typeof ParticleShapeType> = ['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<keyof typeof ParticleShapeType> = ['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<keyof typeof ParticleShapeType> = ['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<keyof typeof ParticleShapeType> = ['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<keyof typeof ParticleShapeType> = ['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<keyof typeof ParticleShapeType> = ['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<keyof typeof ParticleShapeType> = ['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) {
+22
View File
@@ -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.
@@ -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);
@@ -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);
+175
View File
@@ -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));
});
});