ParticleEmitter3D QML Type | Qt Quick 3D | Qt 6.10.3
Description: Emitter for logical particles.

- Qt 6.10
- Qt Quick 3D
- QML Types
- QtQuick3D.Particles3D
- ParticleEmitter3D
- Qt Quick 3D | Commercial or GPLv3

# ParticleEmitter3D QML Type

Emitter for logical particles. More...

Import Statement: | `import QtQuick3D.Particles3D`
Since: | Qt 6.2
Inherits: | Node
Inherited By: | TrailEmitter3D

- List of all members, including inherited members

## Properties

- EmitMode : enumeration `(since 6.10)`
- depthBias : real
- emitBursts : List<EmitBurst3D>
- emitMode : EmitMode `(since 6.10)`
- emitRate : real
- enabled : bool
- lifeSpan : int
- lifeSpanVariation : int
- particle : Particle3D
- particleEndScale : real
- particleEndScaleVariation : real
- particleRotation : vector3d
- particleRotationVariation : vector3d
- particleRotationVelocity : vector3d
- particleRotationVelocityVariation : vector3d
- particleScale : real
- particleScaleVariation : real
- reversed : bool `(since 6.10)`
- shape : ParticleAbstractShape3D
- system : ParticleSystem3D
- velocity : Direction3D

## Methods

- vector3d burst(int count)
- vector3d burst(int count, int duration)
- vector3d burst(int count, int duration, vector3d position)

## Detailed Description

This element emits logical particles into the ParticleSystem3D, with the given starting attributes.

At least one emitter is required to have particles in the ParticleSystem3D. There are a few different ways to control the emitting amount:

- Set the emitRate which controls how many particles per second get emitted continuously.
- Add EmitBurst3D elements into emitBursts property to emit bursts declaratively.
- Call any of the burst() methods to emit bursts immediately.

## Property Documentation

EmitMode : enumeration `[since 6.10]`

Defines the emit mode of the emitter with shape.

Constant | Description
--- | ---
`ParticleEmitter3D.Default` | Default emit behavior.
`ParticleEmitter3D.SurfaceNormal` | The particles are emitted along the surface normal. Requires a particle shape. If the emitter is a trail emitter, the surface normal is inherited from the followed particle.
`ParticleEmitter3D.SurfaceReflected` | The particles are emitted along the reflection of the velocity vector and the surface normal. If the emitter is a trail emitter, the surface normal and the velocity are inherited from the followed particle. Requires particle shape.

This property was introduced in Qt 6.10.

depthBias : real

Holds the depth bias of the emitter. Depth bias is added to the object distance from camera when sorting objects. This can be used to force rendering order between objects close to each other, that might otherwise be rendered in different order in different frames. Negative values cause the sorting value to move closer to the camera while positive values move it further from the camera.

emitBursts : List<EmitBurst3D>

This property takes a list of EmitBurst3D elements, to declaratively define bursts. If the burst starting time, amount, and duration are known beforehand, it is better to use this property than e.g. calling burst() with a Timer.

For example, to emit 100 particles at the beginning, and 50 particles at 2 seconds:

     ParticleEmitter3D {
         emitBursts: [
             EmitBurst3D {
                 time: 0
                 amount: 100
             },
             EmitBurst3D {
                 time: 2000
                 amount: 50
             }
         ]
     }

See also burst().

emitMode : EmitMode `[default: ParticleEmitter3D.Default, since 6.10]`

This property defines the emit mode of the emitter with shape.

This property was introduced in Qt 6.10.

emitRate : real

This property defines the constant emitting rate in particles per second. For example, if the emitRate is 120 and system animates at 60 frames per second, 2 new particles are emitted at every frame.

The default value is `0`.

enabled : bool

If enabled is set to `false`, this emitter will not emit any particles. Usually this is used to conditionally turn an emitter on or off. If you want to continue emitting burst, keep emitRate at 0 instead of toggling this to `false`.

The default value is `true`.

lifeSpan : int

This property defines the lifespan of a single particle in milliseconds.

The default value is `1000`.

See also lifeSpanVariation.

lifeSpanVariation : int

This property defines the lifespan variation of a single particle in milliseconds.

For example, to emit particles which will exist between 3 and 4 seconds:

     ParticleEmitter3D {
         ...
         lifeSpan: 3500
         lifeSpanVariation: 500
     }

The default value is `0`.

See also lifeSpan.

particle : Particle3D

This property defines the logical particle which this emitter emits. Emitter must have a particle defined, or it doesn't emit anything. Particle can be either SpriteParticle3D or ModelParticle3D.

particleEndScale : real

This property defines the scale multiplier of the particles at the end of particle lifeSpan. To have variation in the particle end sizes, use particleEndScaleVariation. When the value is negative, end scale is the same as the particleScale, so scale doesn't change during the particle lifeSpan.

The default value is `-1.0`.

See also particleScale and particleScaleVariation.

particleEndScaleVariation : real

This property defines the scale variation of the particles in the end. When the value is negative, particleScaleVariation is used also for the end scale. For example, to emit particles which start at scale 0.5 - 1.5 and end at scale 1.0 - 5.0:

     ParticleEmitter3D {
         ...
         particleScale: 1.0
         particleScaleVariation: 0.5
         particleEndScale: 3.0
         particleEndScaleVariation: 2.0
     }

The default value is `-1.0`.

See also particleEndScale.

particleRotation : vector3d

This property defines the rotation of the particles in the beginning. Rotation is defined as degrees in euler angles.

See also particleRotationVariation.

particleRotationVariation : vector3d

This property defines the rotation variation of the particles in the beginning. Rotation variation is defined as degrees in euler angles.

For example, to emit particles in fully random rotations:

     ParticleEmitter3D {
         ...
         particleRotationVariation: Qt.vector3d(180, 180, 180)
     }

See also particleRotation.

particleRotationVelocity : vector3d

This property defines the rotation velocity of the particles in the beginning. Rotation velocity is defined as degrees per second in euler angles.

See also particleRotationVelocityVariation.

particleRotationVelocityVariation : vector3d

This property defines the rotation velocity variation of the particles. Rotation velocity variation is defined as degrees per second in euler angles.

For example, to emit particles in random rotations which have random rotation velocity between -100 and 100 degrees per second into any directions:

     ParticleEmitter3D {
         ...
         particleRotationVariation: Qt.vector3d(180, 180, 180)
         particleRotationVelocityVariation: Qt.vector3d(100, 100, 100)
     }

See also particleRotationVelocity.

particleScale : real

This property defines the scale multiplier of the particles at the beginning. To have variation in the particle sizes, use particleScaleVariation.

The default value is `1.0`.

See also particleEndScale and particleScaleVariation.

particleScaleVariation : real

This property defines the scale variation of the particles. For example, to emit particles at scale 0.5 - 1.5:

     ParticleEmitter3D {
         ...
         particleScale: 1.0
         particleScaleVariation: 0.5
     }

The default value is `0.0`.

See also particleScale and particleEndScaleVariation.

reversed : bool `[default: false, since 6.10]`

This property reverses the particle time i.e. emitted particles are run from the end time to the start time.

This property was introduced in Qt 6.10.

shape : ParticleAbstractShape3D

This property defines optional shape for the emitting area. It can be either ParticleShape3D or ParticleModelShape3D. Shape is scaled, positioned and rotated based on the emitter node properties. When the Shape fill property is set to false, emitting happens only from the surface of the shape.

When the shape is not defined, emitting is done from the center point of the emitter node.

system : ParticleSystem3D

This property defines the ParticleSystem3D for the emitter. If system is direct parent of the emitter, this property does not need to be defined.

velocity : Direction3D

This property can be used to set a starting velocity for emitted particles. If velocity is not set, particles start motionless and velocity comes from affectors if they are used.

## Method Documentation

vector3d burst(int count)

This method emits count amount of particles from this emitter immediately.

vector3d burst(int count, int duration)

This method emits count amount of particles from this emitter during the next duration milliseconds.

vector3d burst(int count, int duration, vector3d position)

This method emits count amount of particles from this emitter during the next duration milliseconds. The particles are emitted as if the emitter was at position but all other properties are the same.