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.
Échantillons de code
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 = attachment
Résumé
Propriétés
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.
Méthodes
Clears all particles that have been emitted.
Emits a given number of particles.
Évènements
Propriétés
Acceleration
The Acceleration property determines how the Speed of particles changes over their lifetime. It is defined using a Vector3 to determine the acceleration on the global X/Y/Z axes and is measured in studs per second squared. When changed, this property affects all particles emitted by the emitter, both current and future.
Acceleration will slow particles down if the vector points in the opposite EmissionDirection in which they are emitted. Otherwise, it will speed them up.
Color
The Color property determines the color of all active particles over their individual lifetimes. The color applies to the Texture when rendering and it uses the texture alpha along with the emitter's Transparency. If an emitter has a LightEmission value that's greater than 0, darker colors make particles appear more transparent.
Changing this property affects all particles emitted by the emitter, both current and future.
When this property uses a gradient ColorSequence, a particle's present color is determined by linearly interpolating on the sequence using the particle's age and its 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.
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 Speed and any velocity inherited from the parent from VelocityInheritance. Setting this property to a negative value will cause particles' velocities to grow exponentially.
EmissionDirection
The EmissionDirection property determines the face (Enum.NormalId) of the parent object that particles emit from. A negative Speed means particles emit in the opposite direction. SpreadAngle further varies the emission direction.
If you add a ParticleEmitter to an Attachment, which has a direction, you can rotate the attachment itself (Attachment.Orientation) instead of using this property.
Enabled
The Enabled property determines if particles emit from the emitter. Setting this to false stops further particles from spawning, but any existing particles remain active 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 to clear all particles from a disabled emitter, call Clear(). Then, if desired, call Emit() on the emitter to 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 flipbook, with a maximum of 30 frames per second.
FlipbookIncompatible
The error message to display if the Texture is incompatible for a flipbook. The flipbook texture must be of pixel dimensions 8×8, 16×16, 32×32, 64×64, 128×128, 256×256, 512×512, or 1024×1024.
FlipbookLayout
The FlipbookLayout property determines the layout of the texture. It can be any value of the Enum.ParticleFlipbookLayout enum:
- None – Disable flipbook features and use the texture as a single static texture over the particle's lifetime.
- Grid2x2 – 2×2 frames for a 4-frame animation.
- Grid4x4 – 4×4 frames for a 16-frame animation.
- Grid8x8 – 8×8 frames for a 64-frame animation.
FlipbookMode
The FlipbookMode property determines the type of the flipbook animation. It can be any value of the Enum.ParticleFlipbookMode enum:
- 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 for newly emitted particles. Lifetimes are stored on a per-particle basis, so if this value is changed, existing particles will stay active until their randomly chosen lifetime ends. A lifetime of 0 will prevent particles from emitting at all.
LightEmission
The LightEmission property determines the blending of the Texture colors with the colors behind them. A value of 0 uses normal blending mode while a value of 1 uses additive blending. When changed, this property instantly affects all particles owned by the emitter, both current and future.
This property should not be confused with LightInfluence which determines how particles are affected by environmental light.
This property does not cause particles to light the environment around them. To accomplish that, consider using a PointLight.
LightInfluence
The LightInfluence property determines how much environmental light affects the color of individual particles when they render. It must be in the range of 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); 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.
LocalTransparencyModifier
LockedToPart
The LockedToPart property determines if particles "stick" to the emission source (the Attachment or BasePart to which the ParticleEmitter is parented). If true, active particles will move in lock step if the parent object moves.
Alternatively, consider using the VelocityInheritance property with a value of 1 which may be more appropriate for some effects.
Orientation
The Orientation property determines which orientation mode to use for an emitter's particle geometry.
Orientation | Particle Behavior |
---|---|
FacingCamera | Standard camera-facing billboard quad; default behavior. |
FacingCameraWorldUp | Facing the camera, but rotating only on the vertical upward world Y axis. |
VelocityParallel | Aligned parallel to their direction of movement. |
VelocityPerpendicular | Aligned perpendicular to their direction movement. |
Rate
The Rate property determines how many particles are emitted per second while the emitter is Enabled. It is the inverse of frequency, meaning that a rate of 5 emits a particle every 0.2 seconds. When changed, this property has no affect on any active particles.
RotSpeed
The RotSpeed property determines a random range of angular speeds for newly emitted particles, measured in degrees per second. A random angular speed is chosen upon emission, so changing this property doesn't affect active particles. This property, along with Rotation, affects the angle of the rendered particle image.
Particles with very high angular speeds can appear to rotate slower or not at all, since the angle of rotation is synchronized with the software render speed. For example, if particles rotate at exactly 360 degrees every frame, there will be no apparent change in rotation.
Rotation
The Rotation property determines the range of rotations in degrees for newly emitted particles, measured in degrees. Positive values are in the clockwise direction. This property is commonly set to [0, 360] to provide a completely random rotation to new particles. RotSpeed also influences the rotation of a particle over its lifetime.
Changes to this value only affect new particles; existing particles maintain the rotation at which they were originally emitted.
The Shape property sets the shape of the emitter to either a box, sphere, cylinder, or disc. After you make a selection, you can adjust the ShapeStyle, ShapeInOut, and ShapePartial properties to further customize particle emission. For visual examples, see here.
ShapeInOut
Sets whether particles emit outward only, inward only, or in both directions. For visual examples, see here.
ShapePartial
Depending on the Shape value, this property performs a different action:
For cylinders, it specifies the top radius proportion. A value of 0 means the top of the cylinder has zero radius, making it a cone. A value of 1 means the cylinder has no deformation.
For discs, it specifies the inner radius proportion. A value of 0 means the disc is fully closed (circle/ellipse), while a value of 1 means emission only occurs on the outermost rim of the disc. Values between 0 and 1 emit from an annulus with a certain thickness.
For spheres, it specifies the hemispherical angle over which particles emit. A value of 1 means particles emit from the entire sphere; a value of 0.5 means particles emit from a half-dome; a value of 0 means particles only emit from a single point at the north pole.
For visual examples, see here.
ShapeStyle
Sets particle emission to either volumetric or surface-only emission. For visual examples, see here.
Size
The Size property determines the world size of all active particles over their individual lifetimes. This property represents the dimensions of the square Texture for each particle. It is a NumberSequence that works similarly to Transparency.
A particle's present size is determined by linearly interpolating on this sequence using the particle's age and its 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 non-zero envelope value, a random value in the envelope range is chosen for each keypoint for each particle when it emits.
Speed
The Speed property determines a random range of velocities (minimum to maximum) at which new particles will emit, measured in studs per second. Each particle's velocity is chosen upon emission and it applies in the EmissionDirection. Negative values cause particles to travel in reverse.
Note that changing Speed does not affect active particles and they retain whatever speed they already have. However, Acceleration, Drag, and VelocityInheritance can be used to affect the speed of active particles over their lifetime.
SpreadAngle
The SpreadAngle property determines the random angles at which a particle may be emitted. For example, if the EmissionDirection is Top (+Y), this Vector2 describes the size of the random angle spread on the X/Z axes, in degrees.
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.
Squash
Allows for non-uniform scaling of particles, curve-controlled over their lifetime. Values greater than 0 cause particles to both shrink horizontally and grow vertically, while values less than 0 cause particles to both grow horizontally and shrink vertically.
Texture
The Texture property determines the image rendered on particles. This image is influenced by Color, Transparency, LightInfluence, and LightEmission. Textures with transparent backgrounds work best for particles.
TimeScale
A value between 0 and 1 that controls the speed of the particle effect. At 1, it runs at normal speed; at 0.5 it runs at half speed; at 0 it freezes in time.
Transparency
The Transparency property determines the transparency of all active particles over their individual lifetimes. It works similar to Size in how it affects particles over time. In terms of rendering, a value of 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 sequence using the particle's age and its 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 non-zero envelope value, a random value in the envelope range is chosen for each keypoint for each particle when it emits.
VelocityInheritance
The VelocityInheritance property determines how much of the parent part's Velocity is inherited by particles when they are emitted. A value of 0 means that no velocity is inherited, while a value of 1 means the particle will have the exact same speed as the parent BasePart.
When used in conjunction with Drag, a particle emitter can appear to "shed" particles from a moving part.
WindAffectsDrag
If true, emitted particles follow the Workspace.GlobalWind vector. Only applies if the Drag property is greater than 0.
ZOffset
The ZOffset property determines the forward-backward render position of particles, in studs, without changing their size on the screen. When changed, this property affects both current and future particles. Note that this property accepts fractional values; it is not like GuiObject.ZIndex (an integer).
Positive values 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.
Méthodes
Clear
The Clear method instantly clears all existing particles that have been emitted by the ParticleEmitter through its natural emission (non-zero Rate on an Enabled emitter) or via Emit().
Retours
Échantillons de code
local emitter = script.Parent
while true do
emitter:Clear()
emitter:Emit(10)
task.wait(2)
end
Emit
The Emit method will cause the ParticleEmitter to instantly emit the given number of particles.
Paramètres
The number of particles to emit.
Retours
Échantillons de code
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 = false
local emitter = script.Parent
while true do
emitter:Clear()
emitter:Emit(10)
task.wait(2)
end