ParticleEmitter

Show Deprecated

A ParticleEmitter is a special object that emits customizable 2D billboard particles into the world. To emit and render particles, it must be parented to a BasePart or an Attachment within such a part. When parented to a BasePart, particles spawn randomly within the part's bounding box or shape; when parented to an Attachment, particles spawn from the attachment's position.

Particles emit automatically when the emitter is Enabled with a non-zero Rate, or manually when the Emit method is called. With a non-zero Speed, particles are set in motion outwards and/or inwards, depending on the ShapeInOut property.

By default, particles face the camera, but the Orientation can be modified to respect the particle velocity instead.

During the Lifetime of the particles, they can change appearance according to the Color and Size. Their motion can change over time according to the Drag and Acceleration properties, and they can also move as their parent moves when they are LockedToPart or have a non-zero VelocityInheritance.

Roblox provides several pre-made particle effect objects of Fire, Smoke and Sparkles. They behave similarly to a ParticleEmitter but lack the control methods of Emit and Clear. An Explosion also creates particles, but provides minimal control with regards to how the effect looks.

To learn more about creating and customizing particle emitters, see Particle Emitters.

Code Samples

Creating a Particle Emitter from Scratch

1local emitter = Instance.new("ParticleEmitter")
2-- Number of particles = Rate * Lifetime
3emitter.Rate = 5 -- Particles per second
4emitter.Lifetime = NumberRange.new(1, 1) -- How long the particles should be alive (min, max)
5emitter.Enabled = true
6
7-- Visual properties
8emitter.Texture = "rbxassetid://1266170131" -- A transparent image of a white ring
9-- For Color, build a ColorSequence using ColorSequenceKeypoint
10local colorKeypoints = {
11 -- API: ColorSequenceKeypoint.new(time, color)
12 ColorSequenceKeypoint.new(0, Color3.new(1, 1, 1)), -- At t=0, White
13 ColorSequenceKeypoint.new(0.5, Color3.new(1, 0.5, 0)), -- At t=.5, Orange
14 ColorSequenceKeypoint.new(1, Color3.new(1, 0, 0)), -- At t=1, Red
15}
16emitter.Color = ColorSequence.new(colorKeypoints)
17local numberKeypoints = {
18 -- API: NumberSequenceKeypoint.new(time, size, envelop)
19 NumberSequenceKeypoint.new(0, 1), -- At t=0, fully transparent
20 NumberSequenceKeypoint.new(0.1, 0), -- At t=.1, fully opaque
21 NumberSequenceKeypoint.new(0.5, 0.25), -- At t=.5, mostly opaque
22 NumberSequenceKeypoint.new(1, 1), -- At t=1, fully transparent
23}
24emitter.Transparency = NumberSequence.new(numberKeypoints)
25emitter.LightEmission = 1 -- When particles overlap, multiply their color to be brighter
26emitter.LightInfluence = 0 -- Don't be affected by world lighting
27
28-- Speed properties
29emitter.EmissionDirection = Enum.NormalId.Front -- Emit forwards
30emitter.Speed = NumberRange.new(0, 0) -- Speed of zero
31emitter.Drag = 0 -- Apply no drag to particle motion
32emitter.VelocitySpread = NumberRange.new(0, 0)
33emitter.VelocityInheritance = 0 -- Don't inherit parent velocity
34emitter.Acceleration = Vector3.new(0, 0, 0)
35emitter.LockedToPart = false -- Don't lock the particles to the parent
36emitter.SpreadAngle = Vector2.new(0, 0) -- No spread angle on either axis
37
38-- Simulation properties
39local numberKeypoints2 = {
40 NumberSequenceKeypoint.new(0, 0), -- At t=0, size of 0
41 NumberSequenceKeypoint.new(1, 10), -- At t=1, size of 10
42}
43emitter.Size = NumberSequence.new(numberKeypoints2)
44emitter.ZOffset = -1 -- Render slightly behind the actual position
45emitter.Rotation = NumberRange.new(0, 360) -- Start at random rotation
46emitter.RotSpeed = NumberRange.new(0) -- Do not rotate during simulation
47
48-- Create an attachment so particles emit from the exact same spot (concentric rings)
49local attachment = Instance.new("Attachment")
50attachment.Position = Vector3.new(0, 5, 0) -- Move the attachment upwards a little
51attachment.Parent = script.Parent
52emitter.Parent = attachment

Summary

Properties

Determines the global-axis acceleration of all alive particles, measured in studs per second squared.

Determines the color of all particles emit over their individual lifetimes.

Determines the rate at which particles will lose half their speed through exponential decay.

Determines the face towards which particles will be emit.

Determines whether particles ought to be emit.

Determines how fast the flipbook texture animates in frames per second.

The error message to display if the Texture is incompatible for a flipbook. The texture must be a 1024×1024 image.

Indicates the layout of the texture. Must be None, TwoByTwo, FourByFour, or EightByEight.

Specifies the type of the flipbook animation. Must be Loop, OneShot, PingPong, or Random.

Determines whether the animation starts at a random frame chosen per particle instead of always starting at frame zero.

Defines a random range of ages for newly emit particles.

Determines how much particles' colors are blended with the colors behind them.

Determines how much particles are influenced by the the environment light.

Determines whether the particles rigidly move with the part they're being emitted from.

Specifies how to orient particles.

Determines the number of particles emit per second.

Determines the range of angular speeds emitted particles, measured in degrees per second.

Determines the range of rotations in degrees for a newly emit particles.

Determines the world size over individual particles' lifetimes.

Determines the random range of speeds a new particle will have when emit, measured in studs per second.

Determines the angles at which particles may be randomly emit, measured in degrees.

Determines the image rendered on particle billboards.

Value between 0-1 that controls the speed of the particle effect.

Determines the transparency of particles over their individual lifetimes.

Determines how much of the parent's velocity is inherited by particles when emitted.

Determines the forward-backward render position of particles; used to control what particles render on top/bottom.

Events

Methods

Clear(): nil  

Clears all particles that have been emit.

Emit(particleCount: number): nil  

Emits a given number of particles.

FastForward(numFrames: number): nil  


Properties

Acceleration

The Acceleration property determines how particles ParticleEmitter.Speed changes over the particle's lifetime. It is defined using a Vector3 to determine the acceleration on the global X/Y/Z axes. It is measured in studs per second squared. When changed, this property affects all particles emit by the emitter, both current and future particles.

Acceleration will slow particles down if the vector points in the opposite ParticleEmitter.EmissionDirection in which particles are emitted. Otherwise, it will speed them up. You can use ParticleEmitter.Drag to slow particles down no matter what direction they travel.

Acceleration is most often used to apply a gravity effect to particles (try a value of (0, -3, 0) for this). You can also use small values on the X/Z axes to make it look like particles are being blown away by wind. If you emit a bubble particle downwards, you could use an acceleration of (0, 5, 0) to cause the bubbles to decelerate and then float back upwards.

The Color property determines the color of all particles active in an emitter's system. The color is applied to the ParticleEmitter.Texture when rendering, and uses the texture alpha along with the ParticleEmitter.Transparency. If a particle has a ParticleEmitter.LightEmission of greater than 0, darker colors will make particles appear more transparent.

Note that the default ParticleEmitter.Lifetime is 5 to 10 seconds, so some particles next to each other have small variations in color due to the variations in individual particle lifetime.

A particle's present color is determined by linearly interpolating on this ColorSequence using the particle's age and the particle's total lifetime. For example, if a particle spawned 2 seconds ago and has a 4 second lifetime, the color will be whatever is 50% of the way through the ColorSequence.

Changing this property applies changes to all particles present in the system. This is because the color of a particle is determined using its present lifetime and this ColorSequence (the ColorSequence when the particle was emit is not stored on a per-particle basis).

Drag

The Drag property determines the rate in seconds at which individual particles will lose half their speed via exponential decay.

Drag is applied by scaling the expected velocity (from ParticleEmitter.Speed and any velocity inherited from the parent from ParticleEmitter.VelocityInheritance) by the following formula: 2 ^ (elapsedTime * -drag), where elapsedTime is the time since the particle was emit. Consequently, setting Drag to a negative value will cause particles' velocities to grow exponentially.

Warning: if Drag is set to a sufficiently negative value, this can cause all particles emit by the emitter to completely disappear. Be careful when setting this property lower than -100.

EmissionDirection

The EmissionDirection property determines the face (NormalId) of the parent object towards which particles will be emit. By default, this is the top (+Y) direction. A negative ParticleEmitter.Speed will emit in the opposite direction. ParticleEmitter.SpreadAngle will further vary the emission direction. If a ParticleEmitter is added to an Attachment, which has a direction, the the Attachment itself can be rotated (Attachment.Orientation) instead of using this property.

Enabled

The Enabled property determines whether a ParticleEmitter should emit partciles according to its ParticleEmitter.Rate. Setting Enabled to false will halt further particles from spawning; any existing particles will remain until they expire. This property is useful when you have a pre-made particle effect that you want to remain disabled until you need it to emit particles.

If you want no particles to render, you should call ParticleEmitter:Clear() to clear any existing particles. You can use ParticleEmitter:Emit() on disabled ParticleEmitters and they will still emit and render particles.

FlipbookFramerate

The FlipbookFramerate property determines how fast the flipbook texture animates in frames per second. Like Lifetime, you can set a minimum and maximum range to randomize the framerate of the flip book, with a maximum of 30 frames per second.

FlipbookIncompatible

The error message to display if the Texture is incompatible for a flipbook. The texture must be a 1024×1024 image.

The FlipBookLayout property indicates the layout of the texture. It has the following options:

  • None – Disable flipbook features and use the texture as a single static texture over the particle's lifetime.
  • TwoByTwo – 2×2 frames for a 4-frame animation.
  • FourByFour – 4×4 frames for a 16-frame animation.
  • EightByEight – 8×8 frames for a 64-frame animation.

The FlipbookMode property specifies the type of the flipbook animation:

  • Loop – Continuously play through all frames, starting back at the first frame after playing the last.
  • OneShot – Play through the animation only once across the particle's lifetime. With this setting, the FlipbookFramerate property doesn't apply; instead, the framerate is determined by the particle's Lifetime divided evenly by the number of frames in the animation. OneShot animations are useful for clear non-repeating animations, such as an explosion that creates a puff of smoke and then fades out.
  • PingPong – Play from the first to the last frame, then in reverse from the last to the first, repeating throughout the Lifetime of the particle.
  • Random – Play the frames in a random order, blending/crossfading from one frame to the next. This can be useful for organic particle textures at low framerates, such as stars slowly twinkling between subtly different shapes.

FlipbookStartRandom

The FlipbookStartRandom property determines whether each particle begins at a random frame of the animation instead of always starting at the first frame. One use case is to enable this property and also set FlipbookFramerate to zero, causing each emitted particle to be a static frame chosen randomly from the flipbook texture.

Lifetime

The Lifetime property defines the maximum and minimum ages a newly emit particle will. When a particle is emit, a random lifetime is chosen uniformly. Lifetimes are stored on a per-particle basis, so if this value is changed, existing particles will stay "alive" until their randomly chosen lifetime is lived. The bounds for this property should be in the range [0, 20]. By default, ParticleEmitters will have a lifetime of 5 to 10 seconds. A lifetime of 0 will prevent particles from being emit in the first place.

it is important to pick a sensible Lifetime and ParticleEmitter.Rate so that you don't have too many particles being rendered at once. Long lifetimes and high emission rates are a quick way to cause performance issues. If you need many particles, pick a balance of lifetime and rate. To instantly remove any presently emit particles (perhaps ones with absurdly long lifetimes), you can call ParticleEmitter:Clear().

LightEmission

The LightEmission property determines the blending of the ParticleEmitter.Texture's colors with the colors behind them. It should be set on the range [0, 1]. A value of 0 uses normal blending modes, and a value of 1 will use additive blending. The value of the additive blending is determined by this property. When changed, this property instantly affects all particles owned by the emitter, both current and future particles.

When set to 1, only additive blending is used. As such, choosing a suitable ParticleEmitter.Texture is necessary. Below is an example texture that is suitable for such a ParticleEmitter.

This property should not be confused with ParticleEmitter.LightInfluence, which determines how particles are affected by environment light. This property does not cause particles to light the environment around them. To do that, consider using a PointLight.

LightInfluence

The LightInfluence property determines how much environment light affects the color of individual particles when they are rendered. It must be in the range [0, 1]; behavior of values outside of this range are not defined. At 0, particles are not influenced by light at all (they retain full brightness), and at 1 particles are fully influenced by light (in complete darkness, particles will be black).

By default, this value is 1 if inserted with Studio tools. If inserted using Instance.new(), it is 0.

LockedToPart

The LockedToPart property determines if particles will "stick" to the emission source (the Attachment or BasePart to which the ParticleEmitter is parented).

Below is an animation of two Parts being moved simultaneously in Studio. Inside each is a default ParticleEmitter; the background/left emitter has LockedToPart enabled so the column of particles moves as the part is moved. Contrast with the foreground/right emitter particles which stay in their world position.

Also consider using the ParticleEmitter.VelocityInheritance property set to 1, which may be more appropriate for some effects.

This property determines which orientation mode to use for an emitter's particle geometry:

FaceCamera: standard camera facing billboard quad, default behavior. FaceCameraWorldUp: face the camera, but rotating only on the vertical world-up Y-axis. VelocityParallel: align particles parallel to the direction of their movement. VelocityPerpendicular: align particles perpendicular to the direction of their movement.

Rate

The Rate property determines how many particles are ParticleEmitter:Emit() emit per second while the ParticleEmitter is ParticleEmitter.Enabled. It is the inverse of frequency - a Rate of 5 means that a particle will be emit every 1/5 = 0.2 seconds. When changed, this property will have no affect on any already emit particles.

it is important to pick a sensible ParticleEmitter.Lifetime and Rate so that you don't have too many particles being rendered at once. Long lifetimes and high emission rates are a quick way to cause performance issues. If you need many particles, pick a balance of lifetime and rate. To instantly remove any presently emit particles (perhaps ones with absurdly long lifetimes), you can call ParticleEmitter:Clear().

RotSpeed

The RotSpeed property determines a random range of angular speeds that newly emit particles will have. A random angular speed is chosen upon emission, so changing this property will not affect already emit particles. This property, along with ParticleEmitter.Rotation affect the angle of the rendered particle image. This property is a NumberRange measured in degrees per second.

Particles with very high angular speeds can appear to rotate slower or not at all - this is because the angle of rotation is synchronized with the software render speed. In other words, if the particle is rotating at exactly 360 degrees every frame, there will be no apparent change in rotation.

Rotation

The Rotation property determines the angle at which new particles are emit. It is a NumberRange measured in degrees. Positive values are in the clockwise direction. This property is often set to [0, 360] to provide a completely random rotation to new particles. ParticleEmitter.RotSpeed also influences the rotation of a particle over its lifetime. Finally, this property is useful for correcting any ParticleEmitter.Textures that aren't at the desired orientation.

Changes to this value only affect new particles; existing particles will maintain the rotation at which they were originally emitted.

The Size property determines the world size in studs of all active particles over their individual lifetimes. This property represents the dimensions of the square ParticleEmitter.Texture for each particle. It is a NumberSequence that works similar to ParticleEmitter.Transparency and ParticleEmitter.Color.

A particle's present size is determined by linearly interpolating on this NumberSequence using the particle's age and the particle's total lifetime. For example, if a particle spawned 2 seconds ago and has a 4 second lifetime, the size will be whatever is 50% of the way through the NumberSequence. For any NumberSequenceKeypoint with a nonzero envelope value, a random value in the envelope range is chosen for each keypoint for each particle when it spawns.

Changing this property applies changes to all particles present in the system. This is because the size of a particle is determined using its present lifetime and this NumberSequence (the Size at the time the particle was emit is not stored on a per-particle basis).

Design Note

When designing particle effects, size is probably the most important of all properties. Too large or too subtle can ruin a particle effect! The first thing you should do is decide how you want particles to enter and exit view - fade in/out, or grow/shrink from size 0? The choice is yours - start with a size NumberSequence from 0 to 3 or the reverse and go from there.

The Speed property determines the random range of velocities that newly emit particles may have. It is measured in studs per second using a NumberRange. The velocity is chosen upon emission, and is applied in the ParticleEmitter.EmissionDirection. Negative speed values will cause particles to travel in reverse.

ParticleEmitter.VelocityInheritance, ParticleEmitter.Acceleration and ParticleEmitter.Drag will affect a particle's speed over its lifetime. Changing Speed will not affect already existing particles - they will retain whatever speed they have already.

SpreadAngle

The SpreadAngle property determines the random angles that a particle may be emit. On emission, a random angle is selected uniformly using the range defined by SpreadAngle. For example, if the ParticleEmitter.EmissionDirection is Top (+Y), then this Vector2 describes the size of the random angle spread on the X/Z axes, in degrees. The particle is given a velocity based on the ParticleEmitter.Speed in the chosen direction.

Setting one axis to 360 will cause particles to emit in all direction in a circle. Setting both to 360 will cause particles to emit in all directions in a sphere.

Texture

The Texture property determines the image rendered on particle billboards. The rendered image is influenced by ParticleEmitter.Color, ParticleEmitter.Transparency, ParticleEmitter.LightInfluence, and ParticleEmitter.LightEmission. Transparent textures work best for particles

TimeScale

A value between 0-1 than controls the speed of the particle effect. At 1 it runs at normal speed, at 0.5 it runs at half speed, and at 0 it freezes time.

Transparency

The Transparency property determines the transparency of all active particles over their individual lifetimes. It works similar to ParticleEmitter.Size in how it affects particles over time. In terms of rendering, it works like the BasePart.Transparency of a part on a scale of 0 to 1, where 0 is completely visible (opaque), and a value of 1 is completely invisible (not rendered at all).

A particle's present transparency is determined by linearly interpolating on this NumberSequence using the particle's age and the particle's total lifetime. For example, if a particle spawned 2 seconds ago and has a 4 second lifetime, the transparency will be whatever is 50% of the way through the NumberSequence. For any NumberSequenceKeypoint with a nonzero envelope value, a random value in the envelope range is chosen for each keypoint for each particle when it spawns.

Changing this property applies changes to all particles present in the system. This is because the transparency of a particle is determined using its present lifetime and this NumberSequence (the Transparency at the time the particle was emit is not stored on a per-particle basis).

VelocityInheritance

The VelocityInheritance property determines how much of the parent part's BasePart.Velocity is inherited by particles when they are emitted. A value of 0 means that no velocity is inherited, and a value of 1 means the particle will have the exact same speed as the parent BasePart.

When used in conjunction with ParticleEmitter.Drag, a particle emitter can make appear to be "shedding" particles from a moving part.

ZOffset

The ZOffset property determines the forward-backward (Z) render position of particles, in studs. they render at a modified ParticleEmitter.Size such that this property will not affect the screen size of particles. When changed, this property will affects all particles, both current and future particles. Note that this property accepts fractional values; it is not like GuiObject.ZIndex (an integer)

A practical use of ZOffset is for ParticleEmitters placed in players' characters: use it to define if particles should appear in front of or behind the character (use a value of +/- 2).

Positive values will move particles closer to the camera, and negative values move particles away. Sufficiently negative values can cause particles to render inside or behind the parent part.

Events

Methods

Clear

The Clear method will instantly destroy any existing particles that have been emit by the ParticleEmitter via its natural emission (nonzero ParticleEmitter.Rate on an ParticleEmitter.Enabled emitter) or via ParticleEmitter:Emit(). It is not possible to clear individual particles - all are deleted at once.

Sometimes it is desirable to clear particles before teleporting a character so that there are no lingering effects that might follow due to ParticleEmitter.LockedToPart.


Returns

Code Samples

ParticleEmitter Burst

1local emitter = script.Parent
2while true do
3 emitter:Clear()
4 emitter:Emit(10)
5 task.wait(2)
6end

Emit

The Emit method will cause the ParticleEmitter to emit the given number of particles similar to how ParticleEmitter.Rate does on ParticleEmitter.Enabled emitters. Be warned - this always emits exactly the number of particles even if Roblox' graphics settings are lower. Emitting too many particles can cause performance issues on lower-end hardware.

To clear any emit particles, use ParticleEmitter:Clear().

Parameters

particleCount: number

The number of particles to emit.

Default Value: "16"

Returns

Code Samples

Emit Particles Over Distance

1local RunService = game:GetService("RunService")
2
3local emitter = script.Parent
4local part = emitter.Parent
5
6local PARTICLES_PER_STUD = 3
7
8local lastPosition = part.Position
9local distance = 0
10local function onStep()
11 local displacement = part.Position - lastPosition
12 distance = distance + displacement.magnitude
13
14 local n = math.floor(distance * PARTICLES_PER_STUD)
15 emitter:Emit(n)
16 distance = distance - n / PARTICLES_PER_STUD
17 lastPosition = part.Position
18end
19
20RunService.Stepped:Connect(onStep)
21emitter.Enabled = false
ParticleEmitter Burst

1local emitter = script.Parent
2while true do
3 emitter:Clear()
4 emitter:Emit(10)
5 task.wait(2)
6end

FastForward

Roblox Script Security

Parameters

numFrames: number

Returns