ParticleEmitter

Show deprecated

A ParticleEmitter allows for the creation of particle systems. It is a special effect object that emits customizable 2D billboard particles into the world. On Roblox, a particle is a square 2D image, like a BillboardGui or SurfaceGui with an ImageLabel.

To emit and render particles, a ParticleEmitter must be parented to a BasePart (such as a Part) or an Attachment within such a part. Particles are emit automatically when the emitter is ParticleEmitter/Enabled|Enabled with a non-zero ParticleEmitter/Rate|Rate, or manually when the ParticleEmitter/Emit|Emit method is called. The starting positions of particles are determined by the ParticleEmitter/Shape|Shape and ParticleEmitter/ShapePartial|ShapePartial properties as well as the parent BasePart/Size. By default, particles spawn randomly in the bounding box of the parent part, although this can be configured to be on a specific surface by the emitter’s ParticleEmitter/ShapeStyle|ShapeStyle and ParticleEmitter/EmissionDirection|EmissionDirection. With a non-zero ParticleEmitter/Speed|Speed, particles are set in motion outwards and/or inwards, depending on the ParticleEmitter/ShapeInOut|ShapeInOut property. The direction can be randomized with ParticleEmitter/SpreadAngle|SpreadAngle. By default, particles face the camera, but the ParticleEmitter/Orientation|Orientation can be modified to respect the particle velocity instead.

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

Roblox provides several pre-made particle effect objects - Fire, Smoke and Sparkles. They behave similarly to a ParticleEmitter, but they are not as customizable. They also lack the particle-controlling methods (ParticleEmitter/Emit|Emit and ParticleEmitter/Clear|Clear). An Explosion also creates particles, but provides little-to-no control with regards to how the effect looks.

Properties





	


Vector3


                      
                        Acceleration

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





	


float


                      
                        Brightness





	


ColorSequence


                      
                        Color

Determines the color of all particles emit over their individual lifetimes





	


float


                      
                        Drag

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





	
		
	


NormalId


                      
                        EmissionDirection

Determines the face towards which particles will be emit





	


bool


                      
                        Enabled

Determines whether particles ought to be emit





	


NumberRange


                      
                        FlipbookFramerate





	


string


                      
                        FlipbookIncompatible





	


ParticleFlipbookLayout


                      
                        FlipbookLayout





	


ParticleFlipbookMode


                      
                        FlipbookMode





	


bool


                      
                        FlipbookStartRandom





	


NumberRange


                      
                        Lifetime

Defines a random range of ages for newly emit particles





	


float


                      
                        LightEmission

Determines how much particles’ colors are blended with the colors behind them





	


float


                      
                        LightInfluence

Determines how much particles are influenced by the the environment light





	


bool


                      
                        LockedToPart

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





	
		
	


ParticleOrientation


                      
                        Orientation

Specifies how to orient particles





	


float


                      
                        Rate

Determines the number of particles emit per second





	


NumberRange


                      
                        RotSpeed

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





	


NumberRange


                      
                        Rotation

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





	


ParticleEmitterShape


                      
                        Shape





	


ParticleEmitterShapeInOut


                      
                        ShapeInOut





	


float


                      
                        ShapePartial





	


ParticleEmitterShapeStyle


                      
                        ShapeStyle





	


NumberSequence


                      
                        Size

Determines the world size over individual particles’ lifetimes





	


NumberRange


                      
                        Speed

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





	


Vector2


                      
                        SpreadAngle

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





	


NumberSequence


                      
                        Squash





	


Content


                      
                        Texture

Determines the image rendered on particle billboards





	


float


                      
                        TimeScale





	


NumberSequence


                      
                        Transparency

Determines the transparency of particles over their individual lifetimes





	


float


                      
                        VelocityInheritance

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





	


float


                      
                        VelocitySpread


                     
                        [NotReplicated]


                     
                         [Deprecated]

Determines how offset a particle can be fired from the local emitter direction of its parent





	


float


                      
                        ZOffset

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

Inherited from Instance: Show Hide





	


bool


                    
                      Archivable

Determines if an Instance can be cloned using /Instance/Clone or saved to file.





	


string


                    
                      ClassName


                       
                          [ReadOnly]


                       
                          [NotReplicated]

A read-only string representing the class this Instance belongs to

int


                    
                      DataCost


                       
                          [Hidden]


                       
                          [ReadOnly]


                       
                          [NotReplicated]


                       
                         [Deprecated]

The cost of saving the instance using data persistence.





	


string


                    
                      Name

A non-unique identifier of the Instance





	
		
	


Instance


                    
                      Parent


                       
                          [NotReplicated]

Determines the hierarchical parent of the Instance





	


bool


                    
                      RobloxLocked


                       
                          [Hidden]

A deprecated property that used to protect CoreGui objects





	


int64


                    
                      SourceAssetId


                       
                          [Hidden]


                       
                          [NotReplicated]





	


bool


                    
                      archivable


                       
                          [Hidden]


                       
                          [NotReplicated]


                       
                         [Deprecated]





	


string


                    
                      className


                       
                          [ReadOnly]


                       
                          [NotReplicated]


                       
                         [Deprecated]

Functions






void

Clears all particles that have been emit






void


                      
                        Emit
                        
                          (
                          
                            
                              
                              
                              




int

                              particleCount
                            
                            
                          
                          )

Emits a given number of particles

Inherited from Instance: Show Hide






void


                        
                          ClearAllChildren
                          
                            (
                            
                            )

This function destroys all of an Instance’s children.






Instance

Create a copy of an object and all its descendants, ignoring objects that are not Instance/Archivable|Archivable






void

Sets the Instance/Parent property to nil, locks the Instance/Parent property, disconnects all connections, and calls Destroy on all children.






Instance


                        
                          FindFirstAncestor
                          
                            (
                            
                              
                                
                                
                                




string

                                name
                              
                              
                            
                            )

Returns the first ancestor of the Instance whose Instance/Name is equal to the given name.






Instance


                        
                          FindFirstAncestorOfClass
                          
                            (
                            
                              
                                
                                
                                




string

                                className
                              
                              
                            
                            )

Returns the first ancestor of the Instance whose Instance/ClassName is equal to the given className.






Instance


                        
                          FindFirstAncestorWhichIsA
                          
                            (
                            
                              
                                
                                
                                




string

                                className
                              
                              
                            
                            )

Returns the first ancestor of the Instance for whom Instance/IsA returns true for the given className.






Instance


                        
                          FindFirstChild
                          
                            (
                            
                              
                                
                                
                                




string

                                name
                              
                              
                                ,
                              
                            
                              
                                
                                
                                




bool

                                recursive
                              
                              
                            
                            )

Returns the first child of the Instance found with the given name.






Instance


                        
                          FindFirstChildOfClass
                          
                            (
                            
                              
                                
                                
                                




string

                                className
                              
                              
                            
                            )

Returns the first child of the Instance whose Instance/ClassName|ClassName is equal to the given className.






Instance


                        
                          FindFirstChildWhichIsA
                          
                            (
                            
                              
                                
                                
                                




string

                                className
                              
                              
                                ,
                              
                            
                              
                                
                                
                                




bool

                                recursive
                              
                              
                            
                            )

Returns the first child of the Instance for whom Instance/IsA returns true for the given className.






Instance


                        
                          FindFirstDescendant
                          
                            (
                            
                              
                                
                                
                                




string

                                name
                              
                              
                            
                            )

Returns the first descendant found with the given Instance/Name.






Actor

Returns the Actor associated with the Instance, usually the first Actor ancestor






Variant


                        
                          GetAttribute
                          
                            (
                            
                              
                                
                                
                                




string

                                attribute
                              
                              
                            
                            )

Returns the attribute which has been assigned to the given name






RBXScriptSignal


                        
                          GetAttributeChangedSignal
                          
                            (
                            
                              
                                
                                
                                




string

                                attribute
                              
                              
                            
                            )

Returns an event that fires when the given attribute changes






Dictionary


                        
                          GetAttributes
                          
                            (
                            
                            )

Returns a dictionary of string → variant pairs for each of the Instance|Instance’s attributes






Objects


                        
                          GetChildren
                          
                            (
                            
                            )

Returns an array containing all of the Instance’s children.






string


                        
                          GetDebugId
                          
                            (
                            
                              
                                
                                
                                




int

                                scopeLength
                              
                              
                            
                            )


                            
                              [NotBrowsable]

Returns a coded string of the Instances DebugId used internally by Roblox.






Array


                        
                          GetDescendants
                          
                            (
                            
                            )


                            
                              [CustomLuaState]

Returns an array containing all of the descendants of the instance






string


                        
                          GetFullName
                          
                            (
                            
                            )

Returns a string describing the Instance’s ancestry.






RBXScriptSignal


                        
                          GetPropertyChangedSignal
                          
                            (
                            
                              
                                
                                
                                




string

                                property
                              
                              
                            
                            )

Get an event that fires when a given property of an object changes.






bool


                            
                              [CustomLuaState]

Returns true if an Instance’s class matches or inherits from a given class






bool


                        
                          IsAncestorOf
                          
                            (
                            
                              
                                
                                
                                




Instance

                                descendant
                              
                              
                            
                            )

Returns true if an Instance is an ancestor of the given descendant.






bool


                        
                          IsDescendantOf
                          
                            (
                            
                              
                                
                                
                                




Instance

                                ancestor
                              
                              
                            
                            )

Returns true if an Instance is a descendant of the given ancestor.






void


                            
                               [Deprecated]

Sets the object’s Parent to nil, and does the same for all its descendants.






void


                        
                          SetAttribute
                          
                            (
                            
                              
                                
                                
                                




string

                                attribute
                              
                              
                                ,
                              
                            
                              
                                
                                
                                




Variant

                                value
                              
                              
                            
                            )

Sets the attribute with the given name to the given value






Instance


                        
                          WaitForChild
                          
                            (
                            
                              
                                
                                
                                




string

                                childName
                              
                              
                                ,
                              
                            
                              
                                
                                
                                




double

                                timeOut
                              
                              
                            
                            )


                            
                              [CustomLuaState]


                            
                              [CanYield]

Returns the child of the Instance with the given name. If the child does not exist, it will yield the current thread until it does.






Objects


                            
                               [Deprecated]

Returns an array of the object’s children.






Instance


                            
                               [Deprecated]






void


                            
                               [Deprecated]






Instance


                        
                          findFirstChild
                          
                            (
                            
                              
                                
                                
                                




string

                                name
                              
                              
                                ,
                              
                            
                              
                                
                                
                                




bool

                                recursive
                              
                              
                            
                            )


                            
                               [Deprecated]






Objects


                        
                          getChildren
                          
                            (
                            
                            )


                            
                               [Deprecated]






bool


                            
                               [Deprecated]


                            
                              [CustomLuaState]






bool


                        
                          isDescendantOf
                          
                            (
                            
                              
                                
                                
                                




Instance

                                ancestor
                              
                              
                            
                            )


                            
                               [Deprecated]






void


                            
                               [Deprecated]

Events

Inherited from Instance: Show Hide






RBXScriptSignal


                        
                          AncestryChanged
                          
                          (
                            
                              
                                
                                
                                




Instance

                                child
                              
                              
                                ,
                              
                            
                              
                                
                                
                                




Instance

                                parent
                              
                              
                            
                          )

Fires when the Instance/Parent property of the object or one of its ancestors is changed.






RBXScriptSignal


                        
                          AttributeChanged
                          
                          (
                            
                              
                                
                                
                                




string

                                attribute
                              
                              
                            
                          )

Fires whenever an attribute is changed on the Instance






RBXScriptSignal

Fired immediately after a property of an object changes.






RBXScriptSignal

Fires after an object is parented to this Instance.






RBXScriptSignal


                        
                          ChildRemoved
                          
                          (
                            
                              
                                
                                
                                




Instance

                                child
                              
                              
                            
                          )

Fires after a child is removed from this Instance.






RBXScriptSignal


                        
                          DescendantAdded
                          
                          (
                            
                              
                                
                                
                                




Instance

                                descendant
                              
                              
                            
                          )

Fires after a descendant is added to the Instance






RBXScriptSignal


                        
                          DescendantRemoving
                          
                          (
                            
                              
                                
                                
                                




Instance

                                descendant
                              
                              
                            
                          )

Fires immediately before a descendant of the Instance is removed.






RBXScriptSignal

Fires immediately before the instance is destroyed via Instance/Destroy.






RBXScriptSignal


                        
                           [Deprecated]

Code Samples

Creating a Particle Emitter from Scratch

This rather lengthy code sample shows how every property of a ParticleEmitter can be set, including DataType/NumberRange, DataType/NumberSequence and DataType/ColorSequence properties. Below is how the ParticleEmitter should after every property is set. Try playing around with the different properties to customize how the effect looks!

The final product

			
			
				Creating a Particle Emitter from Scratch

			
			
			
				Expected Output
			
			
				Expand
				
			
		

			
			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(.5, Color3.new(1, .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(.1, 0);    -- At t=.1, fully opaque
	NumberSequenceKeypoint.new(.5, .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", script.Parent)
attachment.Position = Vector3.new(0, 5, 0) -- Move the attachment upwards a little
emitter.Parent = attachment
		

			When you run the code sample, you should see particles that look like the provided animation.
		

			
				
				Copy Code
			
			
				Light Theme
				
					
					
				
			
		

Fire Smoke

ParticleEmitter

ParticleEmitter

See also

Properties

Functions

Clear ( )

Emit ( int particleCount )

ClearAllChildren ( )

Clone ( )

Destroy ( )

FindFirstAncestor ( string name )

FindFirstAncestorOfClass ( string className )

FindFirstAncestorWhichIsA ( string className )

FindFirstChild ( string name , bool recursive )

FindFirstChildOfClass ( string className )

FindFirstChildWhichIsA ( string className , bool recursive )

FindFirstDescendant ( string name )

GetActor ( )

GetAttribute ( string attribute )

GetAttributeChangedSignal ( string attribute )

GetAttributes ( )

GetChildren ( )

GetDebugId ( int scopeLength )

GetDescendants ( )

GetFullName ( )

GetPropertyChangedSignal ( string property )

IsA ( string className )

IsAncestorOf ( Instance descendant )

IsDescendantOf ( Instance ancestor )

Remove ( )

SetAttribute ( string attribute , Variant value )

WaitForChild ( string childName , double timeOut )

children ( )

clone ( )

destroy ( )

findFirstChild ( string name , bool recursive )

getChildren ( )

isA ( string className )

isDescendantOf ( Instance ancestor )

remove ( )

Events

AncestryChanged ( Instance child , Instance parent )

AttributeChanged ( string attribute )

Changed ( string property )

ChildAdded ( Instance child )

ChildRemoved ( Instance child )

DescendantAdded ( Instance descendant )

DescendantRemoving ( Instance descendant )

Destroying ( )

childAdded ( Instance child )

Code Samples

Creating a Particle Emitter from Scratch

Emit ( `int` particleCount )

FindFirstAncestor ( `string` name )

FindFirstAncestorOfClass ( `string` className )

FindFirstAncestorWhichIsA ( `string` className )

FindFirstChild ( `string` name , `bool` recursive )

FindFirstChildOfClass ( `string` className )

FindFirstChildWhichIsA ( `string` className , `bool` recursive )

FindFirstDescendant ( `string` name )

GetAttribute ( `string` attribute )

GetAttributeChangedSignal ( `string` attribute )

GetDebugId ( `int` scopeLength )

GetPropertyChangedSignal ( `string` property )

IsA ( `string` className )

IsAncestorOf ( `Instance` descendant )

IsDescendantOf ( `Instance` ancestor )

SetAttribute ( `string` attribute , `Variant` value )

WaitForChild ( `string` childName , `double` timeOut )

findFirstChild ( `string` name , `bool` recursive )

isA ( `string` className )

isDescendantOf ( `Instance` ancestor )

AncestryChanged ( `Instance` child , `Instance` parent )

AttributeChanged ( `string` attribute )

Changed ( `string` property )

ChildAdded ( `Instance` child )

ChildRemoved ( `Instance` child )

DescendantAdded ( `Instance` descendant )

DescendantRemoving ( `Instance` descendant )

childAdded ( `Instance` child )