ParticleEmitter
A ParticleEmitter is a special object that emits customizable 2D 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.
To learn more about creating and customizing particle emitters, see Particle Emitters.
Code Samples
This rather lengthy code sample shows how every property of a ParticleEmitter can be set, including NumberRange, NumberSequence and ColorSequence properties. Below is how the ParticleEmitter should look after every property is set. Try playing around with the different properties to customize how the effect looks!
local emitter = Instance.new("ParticleEmitter")
-- Number of particles = Rate * Lifetime
emitter.Rate = 5 -- Particles per second
emitter.Lifetime = NumberRange.new(1, 1) -- How long the particles should be alive (min, max)
emitter.Enabled = true
-- Visual properties
emitter.Texture = "rbxassetid://1266170131" -- A transparent image of a white ring
-- For Color, build a ColorSequence using ColorSequenceKeypoint
local colorKeypoints = {
-- API: ColorSequenceKeypoint.new(time, color)
ColorSequenceKeypoint.new(0, Color3.new(1, 1, 1)), -- At t=0, White
ColorSequenceKeypoint.new(0.5, Color3.new(1, 0.5, 0)), -- At t=.5, Orange
ColorSequenceKeypoint.new(1, Color3.new(1, 0, 0)), -- At t=1, Red
}
emitter.Color = ColorSequence.new(colorKeypoints)
local numberKeypoints = {
-- API: NumberSequenceKeypoint.new(time, size, envelop)
NumberSequenceKeypoint.new(0, 1), -- At t=0, fully transparent
NumberSequenceKeypoint.new(0.1, 0), -- At t=.1, fully opaque
NumberSequenceKeypoint.new(0.5, 0.25), -- At t=.5, mostly opaque
NumberSequenceKeypoint.new(1, 1), -- At t=1, fully transparent
}
emitter.Transparency = NumberSequence.new(numberKeypoints)
emitter.LightEmission = 1 -- When particles overlap, multiply their color to be brighter
emitter.LightInfluence = 0 -- Don't be affected by world lighting
-- Speed properties
emitter.EmissionDirection = Enum.NormalId.Front -- Emit forwards
emitter.Speed = NumberRange.new(0, 0) -- Speed of zero
emitter.Drag = 0 -- Apply no drag to particle motion
emitter.VelocitySpread = NumberRange.new(0, 0)
emitter.VelocityInheritance = 0 -- Don't inherit parent velocity
emitter.Acceleration = Vector3.new(0, 0, 0)
emitter.LockedToPart = false -- Don't lock the particles to the parent
emitter.SpreadAngle = Vector2.new(0, 0) -- No spread angle on either axis
-- Simulation properties
local numberKeypoints2 = {
NumberSequenceKeypoint.new(0, 0), -- At t=0, size of 0
NumberSequenceKeypoint.new(1, 10), -- At t=1, size of 10
}
emitter.Size = NumberSequence.new(numberKeypoints2)
emitter.ZOffset = -1 -- Render slightly behind the actual position
emitter.Rotation = NumberRange.new(0, 360) -- Start at random rotation
emitter.RotSpeed = NumberRange.new(0) -- Do not rotate during simulation
-- Create an attachment so particles emit from the exact same spot (concentric rings)
local attachment = Instance.new("Attachment")
attachment.Position = Vector3.new(0, 5, 0) -- Move the attachment upwards a little
attachment.Parent = script.Parent
emitter.Parent = attachmentSummary
Properties
Determines the global-axis acceleration of all active particles, measured in studs per second squared.
Scales the light emitted from the emitter when ParticleEmitter.LightInfluence is 0.
Determines the color of all active particles over their individual lifetimes.
Determines the rate at which particles will lose half their speed through exponential decay.
Determines the face of the object that particles emit from.
Determines if particles emit from the emitter.
Determines how fast the flipbook texture animates in frames per second.
The error message to display if the Texture is incompatible for a flipbook.
Determines the layout of the flipbook texture. Must be None, Grid2x2, Grid4x4, or Grid8x8.
Determines 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 emitted particles.
Determines how much particles' colors are blended with the colors behind them.
Determines how much particles are influenced by the environmental 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 emitted per second.
Determines the range of angular speeds of emitted particles, measured in degrees per second.
Determines the range of rotations in degrees for newly emitted particles.
Sets the shape of the emitter to either a box, sphere, cylinder, or disc.
Sets whether particles emit outward only, inward only, or in both directions.
Influences particle emission from cylinder, disc, sphere, and box shapes.
Sets particle emission to either volumetric or surface-only emission.
Determines the world size over individual particles' lifetimes.
Determines a random range of velocities (minimum to maximum) at which new particles will emit, measured in studs per second.
Determines the angles at which particles may be randomly emit, measured in degrees.
Allows for non-uniform scaling of particles, curve-controlled over their lifetime.
Determines the image rendered on particles.
Value between 0 and 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.
Whether emitted particles follow the Workspace.GlobalWind vector.
Determines the forward-backward render position of particles; used to control what particles render on top/bottom.
Methods
Clears all particles that have been emitted.
Emits a given number of particles.
Properties
Acceleration
Brightness
Color
Drag
EmissionDirection
Enabled
FlipbookFramerate
FlipbookIncompatible
FlipbookLayout
FlipbookMode
FlipbookStartRandom
Lifetime
LightEmission
LightInfluence
LocalTransparencyModifier
LockedToPart
Orientation
Rate
RotSpeed
Rotation
ShapeInOut
ShapePartial
ShapeStyle
Size
Speed
SpreadAngle
Squash
Texture
TimeScale
Transparency
VelocityInheritance
WindAffectsDrag
ZOffset
Methods
Clear
Returns
Code Samples
local emitter = script.Parent
while true do
emitter:Clear()
emitter:Emit(10)
task.wait(2)
endEmit
Parameters
Returns
Code Samples
local RunService = game:GetService("RunService")
local emitter = script.Parent
local part = emitter.Parent
local PARTICLES_PER_STUD = 3
local lastPosition = part.Position
local distance = 0
local function onStep()
local displacement = part.Position - lastPosition
distance = distance + displacement.magnitude
local n = math.floor(distance * PARTICLES_PER_STUD)
emitter:Emit(n)
distance = distance - n / PARTICLES_PER_STUD
lastPosition = part.Position
end
RunService.Stepped:Connect(onStep)
emitter.Enabled = falselocal emitter = script.Parent
while true do
emitter:Clear()
emitter:Emit(10)
task.wait(2)
end