ParticleEmitter

UT2003 :: Object >> ParticleEmitter (Package: Engine)

Subclasses of this class are used within Emitter actors. The settings are pretty complex and require a fair amount of trial and error to get used to. Some examples can be found in our ParticleEmitter cookbook.

Properties

Acceleration Group

vector Acceleration: Vector which determines the acceleration of the particles in any of the three planes

Collision Group

Settings for collisions with world geometry. See /Collision.

Color Group

rangevector ColorMultiplierRange: Used to randomize the color of the particles. X corresponds to red, Y corresponds to Green and Z corresponds to blue. A value of 1 preserves the color of the original textures. To make everything darker, for example, set 0.5 for all values.
array<ParticleColorScale> ColorScale: Used to change the color of a particle over time. You set both a color you want it to be, and the relative time at which you want it to be that color. It will fade from whatever color it is to the color you want it to be over the interval you specify. The time is relative, so 0.5 would be half the particles lifespan.
float ColorScaleRepeats: How many times to repeat the color scales. Example, if you have a color scale that changes it to black at 0.5 time(half its lifespan), with color repeats it will be black by the time its half way done living. With one repeat, it will be black at 1/4 of its lifespan, normal at 1/2, and black again at 3/4ths of its lifespan.
bool UseColorScale: Must be true for ColorScales and ColorScaleRepeats to have any effect on the particles.

Fading Group

bool FadeIn: If true, it will fade the particle in
float FadeInEndTime: If FadeIn is true, this is the time at which the particle will have completly faded in and is 100% visible. This is NOT relative. 0.5 is 1/2 a second, not 1/2 of the particles lifespan.
plane FadeInFactor: Specifies how much each component of the particle colors should be faded. 1 means start at 0 while e.g. 0.5 means start at half the normal value. X,Y,Z correspond to R,G,B and W corresponds to the alpha value.
bool FadeOut: If true, the particle will fade out.
plane FadeOutFactor: Specifies how much each component of the particle colors should be faded. 1 means end at 0 while e.g. 0.5 means end at half the normal value. X,Y,Z correspond to R,G,B and W corresponds to the alpha value.
float FadeOutStartTime: If Fadeout is true, this is the absolute time at which the particle will start fading out. Fading out overrules fading in, so if a particle is not yet faded in and starts fading out, it will start at full color values.

Force Group

bool UseActorForces: Whether the particles can be affected by Actor forces.
Note: Setting this to True can cause a huge performance hit and will only work when physics details are set high enough.

General Group

EParticleCoordinateSystem CoordinateSystem: Determines how the settings in the location section are calculated. See /Enums.
EParticleEffectAxis EffectAxis
int MaxParticles (const): Maximum number of particles that this ParticleEmitter can have at a time.
bool ResetAfterChange: Determines if this emitter reset after a change has been made to its properties. It currently has no effect. (emitter resets no matter what if you make a change)

Local Group

bool AutoDestroy: Determines if this emitter will destroy itself once all particles are gone.
bool AutoReset: Determines if this emitter will reset itself after a specified amount of time.
range AutoResetTimeRange: The time delay for auto-resets.
bool Disabled: If true, this emitter wont emit anything. Typically used along with TriggerDisabled=true to create a trigger-toggled emitter that starts inactive and only begins emitting once the trigger Event occurs. Also used during testing to disable certain emitters within an emitter system.
bool DisableFogging: Determines if particles are affected by distance fog.
string Name: A name for this ParticleEmitter
bool RespawnDeadParticles: Determines if dead particles (i.e. particles that have exceeded their lifespan or maximum collisions) should be respawned.

Location Group

Spawn location of the particles. See /Location.

Mass Group

range StartMassRange

MeshSpawning Group

vector MeshNormal
range MeshNormalThresholdRange
rangevector MeshScaleRange: This determines the size scale of an emitted mesh, similar to DrawScale3D for actors. It takes each axis independantly, so setting a good range can result in a lot of different shapes on the same mesh.
EParticleMeshSpawning MeshSpawning
StaticMesh MeshSpawningStaticMesh: A StaticMesh, whose vertices should be used as possible start location offsets. The ParticleMeshes static mesh package provides some useful StaticMeshes for this.
bool SpawnOnlyInDirectionOfNormal
bool UniformMeshScale: If this is true, the settings in meshscalerange are no longer used for each axis independantly. Instead, the mesh will be scaled along all axis using the x values.
bool UniformVelocityScale
bool UseColorFromMesh
bool VelocityFromMesh
rangevector VelocityScaleRange

Rendering Group

bool AcceptsProjectors
int AlphaRef
bool AlphaTest
bool ZTest
bool ZWrite

Revolution Group

Revolution moves all particles around a central point or area. This might be useful for vortex-like particle effects.

rangevector RevolutionCenterOffsetRange: The range of where the center of revolution for this particle will be
array<ParticleRevolutionScale> RevolutionScale
float RevolutionScaleRepeats
rangevector RevolutionsPerSecondRange: Determines how many times the particle will orbit the center per second, it takes each axis independantly.
bool UseRevolution: If true, the particles will orbit a center point.
bool UseRevolutionScale: Whether the RevolutionScale settings should be used.

Rotation

Rotation rotates the particle itself around its center.

bool DampRotation: Whether collision should affect a particle's rotation.
rangevector RotationDampingFactorRange: How collision affects the particle's rotation.
vector RotationNormal: The normal used when UseRotationFrom is set to PTRS_Normal.
rotator RotationOffset
vector SpinCCWorCW: The chance that particles will spin clockwise. 0 will make all particles spin counterclockwise, 0.7 will give a 70% chance that particles spin clockwise and a 30% chance for spinning counterclockwise.
bool SpinParticles: Whether particles should spin.
rangevector SpinsPerSecondRange: The range that determines how fast the particles will spin. X, Y and Z correspond to Pitch, Yaw and Roll.
rangevector StartSpinRange: Specifies the initial rotation of the particles. Again, X, Y and Z correspond to Pitch, Yaw and Roll.
EParticleRotationSource UseRotationFrom: What to base the rotation on. See /Enums.

Size

array<ParticleTimeScale> SizeScale
float SizeScaleRepeats
rangevector StartSizeRange
bool UniformSize
bool UseRegularSizeScale
bool UseSizeScale

Skeletalmesh

range RelativeBoneIndexRange
Actor SkeletalMeshActor
vector SkeletalScale
ESkelLocationUpdate UseSkeletalLocationAs

Sound

EParticleCollisionSound CollisionSound
range CollisionSoundIndex
range CollisionSoundProbability
array<ParticleSound> Sounds
EParticleCollisionSound SpawningSound
range SpawningSoundIndex
range SpawningSoundProbability

Spawning

bool AutomaticInitialSpawning: Automatically determines a particle spawn rate based on the particle lifetime and the maximum number of particles allowed so that the maximum number of particles is reached exactly when the first particle's lifetime is up. ParticlesPerSecond must be 0 for this to work.
float InitialParticlesPerSecond: The initial particle spawn rate until the point when the maximum number of particles is reached.
float ParticlesPerSecond: The particle spawn rate after the initial warmup phase reached the maximum number of particles.

Texture

bool BlendBetweenSubdivisions
EParticleDrawStyle DrawStyle
int SubdivisionEnd
array<float> SubdivisionScale
int SubdivisionStart
Texture Texture
int TextureUSubdivisions
int TextureVSubdivisions
bool UseRandomSubdivision
bool UseSubdivisionScale

Tick

float MinSquaredVelocity: The minimum velocity a particle may have before it gets inactive. This is essential for colliding particles that are supposed to stay idle on ground. The number should be in squared uu/s, ie if you want to set it to 50 uu/s, enter 2500 (50*50) instead.
float SecondsBeforeInactive: The amount of time that has to pass when the emitter is out of view before particle calculation is paused. Set this to 0.0 to disable the pausing effect, e.g. for Emitter-based weapon effects like explosions, tracers, sparks, etc.

Time

range InitialDelayRange: Determines how long before this emitter will become active
range InitialTimeRange: The initial particle age. For obvious reasons this should be lower than LifetimeRange. You might be able to create interesting effects in combination with the various scales parameters if you have a particle with e.g. LifetimeRange 4 seconds and InitialTimeRange 3 seconds. Effectively the particle will have 1 second left, but it already starts at 75% of its entire lifetime.
range LifetimeRange: Determines the lifespan of the particles that this emitter emits.

Trigger

bool ResetOnTrigger: Whether this ParticleEmitter should be reset when it's triggered. When the ParticleEmitter is reset, all its particles are removed and it starts spawning according to its initial spawn parameters. (initial delay, initial particles per second, etc.)
float SpawnOnTriggerPPS
range SpawnOnTriggerRange: When triggered, this ParticleEmitter should spawn SpawnOnTriggerRange.Min to SpawnOnTriggerRange.Max particles, with a spawn rate of SpawnOnTriggerPPS particles per second.
bool TriggerDisabled: If true allows the emitter to be toggled on/off by the Event named in the Emitter system's Event>Tag. As the Tag belongs to the entire emitter system sub-emitters can only respond to the one Event, albeit in different ways. By default the initial status of emitters is active, and will be toggled off upon first firing of the Event, but setting Local>bDisabled=true will disable emitter at start and wait for Event to turn on. Always set this to false if you want to use the other trigger options or if you don't want the ParticleEmitter's regular particle spawning to be affected by triggering.

Velocity

int AddVelocityFromOtherEmitter
rangevector AddVelocityMultiplierRange
EParticleVelocityDirection GetVelocityDirectionFrom
vector MaxAbsVelocity
range StartVelocityRadialRange
rangevector StartVelocityRange
bool UseVelocityScale
rangevector VelocityLossRange
array<ParticleVelocityScale> VelocityScale
float VelocityScaleRepeats

Warmup

Warmup precalculates particle spawning and movement so when the emitter first comes into sight it looks like it has been running for some time already.

float RelativeWarmupTime: The time to precalculate, relative to the particle lifetime. 1.0 is the time corresponding to one particle's entire lifetime.
float WarmupTicksPerSecond: How many ticks per second to precalculate during warmup. Higher values can look better, but very high values might also freeze the game for a split-second while the emitter warms up when it comes into view for the first time.

Other Properties

These properties aren't visible in UnrealEd. All of them are transient, i.e. their value won't be saved when saving a game. Some of these properties represent scary internal stuff and probably shouldn't be touched.

int ActiveParticles: Currently active particles
bool AllParticlesDead: Whether all particles have died.
int BoneIndex
box BoundingBox
color Color
vector ColorMultiplier
int CurrentCollisionSoundIndex
int CurrentMeshSpawningIndex
int CurrentSpawningSoundIndex
int CurrentSpawnOnTrigger
int DeferredParticles
int Flags
vector GlobalOffset
int HitCount
bool Inactive
float InactiveTime
float InitialDelay
bool Initialized
int KillPending
float Mass
int MaxActiveParticles
float MaxLifetime
float MaxSizeScale
array<vector> MeshVertsAndNormals
vector OldLocation
vector OldMeshLocation
int OtherIndex
Emitter Owner: The Emitter actor this ParticleEmitter belongs to.
int ParticleIndex: Index into circular list of particles
array<Particle> Particles: Contains the data of all active particles. See /Structs for details about the Particle data type.
float PPSFraction: Used to keep track of fractional PPTick
int PS2Data
bool RealDisableFogging
vector RealExtentMultiplier
vector RealMeshNormal
vector RevolutionCenter
vector RevolutionsMultiplier
vector RevolutionsPerSecond
vector Size
vector SpinsPerSecond
vector StartLocation
vector StartSize
vector StartSpin
int Subdivision
float Time
float TimeTillReset
vector Velocity
vector VelocityMultiplier
bool WarmedUp

Enums

See /Enums.

Structs

See /Structs.

Methods

SpawnParticle (int Amount) [native]: Spawns a specified amount of particles.
Trigger ( ) [native]: Performs the action specified in the Trigger property group. This function is called by the parent Emitter actor's Trigger function.

Known Subclasses

Discussion

EricBlade: A couple things in the Trigger properties have me confused as heck, and if anyone knows the answer, I'd be happy to document them. TriggerDisabled is the big one. What does this do? So far, I have been unable to get an emitter to trigger without this set to True. Does this mean that TriggerDisabled is actually the negative of what it's name implies? Or does it mean that it will allow the Trigger to trigger a disabled emitter?

Wormbo: AFAIK TriggerDisabled means that triggering is disabled for this ParticleEmitter. It shoudln't be too hard to test that though: Make a SpriteEmitter that doesn't spawn any particles on its own. Set SpawnOnTriggerPPS and SpawnOnTriggerRange to some meaningful values and ResetOnTrigger to False. Match the parent Emitter's Tag with a touch Trigger's Event and test ingame with TriggerDisabled set to false and true.

EricBlade: I don't know if I'm doing something incorrectly, but the only way I have been able to get an emitter to trigger, is if I have: ResetOnTrigger=False, TriggerDisabled=True, and Disabled=True .. i've managed to get no farther than knowing if TriggerDisabled is it's own negative, or if that means it can trigger a disabled emitter on .. :-S New info.. UDN has this description: "This will toggle the disabledness of the emitter. If the emitter is currently disabled, triggering it will turn it back on. If the emitter is not disabled, triggering it will disable it." If that confuses anyone, what it seems like this indicates, is that you need to set TriggerDisabled=True if you want a Trigger to be able to trigger it ON from the OFF state. Otherwise, you can only trigger it to turn it off. Or something kind of like that.

Wormbo: TriggerDisable means triggering toggles the disabled state of the emitter.

EricBlade: As opposed to? I don't see anything else in the code that triggering the emitter could cause...

Wormbo: As opposed to "TriggerDisable makes the emitter ignore triggering." Refactor Me.

Solitaire: To recap: TriggerDisable is basically the same as a TriggerToggle state - when set true it allows an individual sub-emitter to be toggled on/off by a triggering Event matching the Emitter System actor's Event>Tag field. It defaults to initially on (turned off by first Event fired) but making Local>bDisabled=true reverses this (initially off, first firing turns it on). You need seperate Emitter actors if you want to trigger emitters by different events; but you can have several sub-emitters reacting to the same Event in different ways within one Emitter System actor (turning on, off, resetting or ignoring the Event) which is why the bDisabled and bTriggerDisabled functions belong to individual sub-emitters rather than just using regular fields such as Object>InitialState which would force all the emitters within the actor to do the same thing. And bResetOnTrigger can be used with bTriggerDisable (I know this from doing it!), all it does is restart a re-enabled emitter from scratch rather than have it reappear exactly as it was prior to being disabled.

Category Class (UT2003)
Category Class (UT2004)