ParticleEmitter2D is an object that emits customizable 2D images (particles) from a UI object, useful for simulating interface effects like sparkles, bursts, and glows.
You can parent a ParticleEmitter2D to any GuiObject, such as a Frame, ImageLabel, or TextButton inside a ScreenGui, SurfaceGui, or BillboardGui. Particles render above the parent's strokes and inset shadows.
Use the Enabled and Rate properties for continuous emission, or call Emit() to create a one-off burst of particles.
Customize particles
By experimenting with the following properties, you can customize a particle's visual appearance to make unique UI elements like button sparkles, loading effects, and celebratory bursts.
Texture
The TextureContent property sets the image that each particle displays. It accepts an asset URI and works together with color, transparency, and blending to determine the particle's final appearance.
Color
The Color property tints each particle's texture to either a specific hue, or to a gradient ColorSequence across its lifetime.
Size
The Size property sets each particle's size as a NumberSequence across its lifetime, measured in offset units. The sequence value represents half of the particle's rendered size.
Transparency
The Transparency property sets each particle's opacity as a NumberSequence across its lifetime. Fading particles near the start and/or end of their lifetime avoids a popping in/out effect.
Lifetime
The Lifetime property sets the lifetime of a particle in seconds. Provide a minimum and maximum range to randomize each particle's lifetime.
Motion
Particles emit at a set speed (or random range of speeds) and optionally accelerate or slow down over the course of their lifetime.
- Speed sets a random range of velocities, in offset units per second, at which new particles emit.
- Acceleration determines how much a particle's velocity changes per second.
- Drag determines the rate at which particles lose speed, slowing them down gradually over their lifetime.
Rotation
Particles emit at a set rotation (or random range of rotations) and optionally spin either clockwise or counter‑clockwise.
- Rotation determines the angle, in degrees, of newly-emitted particles.
- RotSpeed determines the angular speed, in degrees per second, at which particles rotate. Positive values rotate clockwise.
Emission
Use the following properties to control where and in which direction particles emit:
- EmissionAngle sets the base direction particles travel.
- SpreadAngle sets the range of angles, in degrees, around the emission angle from which a particle can emit.
- EmissionOffset and EmissionSpread adjust the position and size of the emission region relative to the parent GuiObject.
Squash
The Squash property allows for non-uniform scaling of particles, curve-controlled over their lifetime.
Lighting & blending
Particles can appear to emit light, take on environmental light from the 3D world, and blend with the colors behind them.
- LightInfluence determines how much environmental light affects a particle's color. It only applies when the emitter's parent GuiObject renders in the 3D world, meaning a SurfaceGui, or a BillboardGui that doesn't have AlwaysOnTop enabled.
- Blend determines how a particle's texture colors blend with the colors behind them. A value of 0 uses normal blending, while a value of 1 uses additive blending, which can make particles appear to glow.
Flipbooks
Particle flipbook textures let you animate a particle's texture over its lifetime:
- FlipbookLayout sets the texture's frame layout, using the Enum.ParticleFlipbookLayout enum.
- FlipbookMode sets the animation type, using the Enum.ParticleFlipbookMode enum.
- FlipbookFramerate sets how fast the flipbook animates, in frames per second.
- FlipbookStartRandom determines whether each particle begins at a random frame instead of always starting at the first frame.
- FlipbookBlendFrames determines whether frames crossfade into each other during playback.
Other properties
| Property | Description |
|---|---|
| Enabled | 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 or the Clear() method is called. When disabled, the Emit() method can be called to emit a one-off burst of particles. |
| LockedToParent | Determines if particles "stick" to the parent GuiObject instead of remaining at their emission position. |
| TimeScale | A value between 0 and 1 that controls the speed of the particle effect. |
| ZIndex | Determines the render order of particles relative to other UI objects. |