Particle Emitters

A ParticleEmitter is an instance that emits 2D images (particles) that look and behave for the duration of their lifetime according to the particle emitter's set properties. You can customize a particle emitter's properties to create special effects like fire, smoke, and sparks.

Particle Emission

You can either parent a particle emitter to an Attachment or an object of the BasePart class. When you parent a particle emitter to an object of the BasePart class, the particles generate and emit based on their parent part's size. For example, a part with a small area compacts particles while a part with a large area spreads particles out:

In addition, the EmissionDirection property determines the face of the part that will emit particles. When you change this property, you consequently change the particle emission direction as well. By default, this property is the top of the part, but you can change it to any face. The following video shows the emission direction changing from the Top face to the Left face to the Front face:

Creating a Particle Emitter

To create a particle emitter on a given part:

  1. In the Explorer window, hover over the part and click the ⊕ button. A contextual menu displays.
  2. From the menu, insert a ParticleEmitter. The particle emitter immediately emits particles within the part's area.

Customizing Particles

You can change the properties of particle emitters to create interesting visual effects such as glowing portals, green billowing smoke, or vibrant explosions.

Texture

The Texture property renders the image that each particle displays. By default, particle emitters have particles with a white sparkle texture, but you can change it to any texture to achieve interesting effects. The following video shows three similar particle emitters with different set textures:

When you are creating a texture to use as a particle, consider these best practices:

  • Use images in .png format with a background that is transparent. If your texture is grayscale with no alpha channel, try setting the particle emitter's LightEmission property to 1 to hide the darker regions.
  • Blur the edges of your image to get a more polished, continuous effect.
  • Make your image grayscale to give yourself full control over the final color of the particle with the Color property.

To insert an image into a particle emitter:

  1. In the menu bar, navigate to the View tab and select Toolbox. The Toolbox window displays.

    1. If you want to insert an image that you have previously imported, click on the Inventory tab.
    2. If you want to insert an image from another creator, click on the Marketplace tab.
  2. Right-click on the image you want to insert into a particle emitter. A pop-up menu displays.

  3. Select Copy Asset ID.

  4. In the Explorer window, select the ParticleEmitter.

  5. In the Properties window, paste the asset id into the Texture property.

Lifetime

The Lifetime property sets the lifetime of a particle in seconds. You can set this property either as a consistent value or provide a minimum and maximum range from which a random lifetime will be chosen for each particle. The maximum lifetime a particle can have is 20 seconds.

Color

The Color property tints the particle's texture to either a specific hue or a ColorSequence data type. A color sequence changes a particle's color across its lifetime.

Constant Color

To set particles to a specific hue:

  1. In the Explorer window, select the ParticleEmitter.

  2. In the Properties window, select the Color property. You can either:

    1. Click on the color square to open the Colors pop-up window and select a color.
    2. Input three numbers into the RGB color value field.
    Similar particle emitters with different colored particles

Color Sequence

To set a particle emitter's color sequence:

  1. In the Explorer window, select the ParticleEmitter.

  2. In the Properties window, select the Color property.

  3. Click the ... button. A color sequence pop-up displays. By default, the color sequence is all white.

    Each triangle on the bottom axis of the color sequence is a keypoint that determines the color value of the property at that point of the particle's lifetime.

  4. Click the keypoint at the start of the color sequence, then click the small square next to Color to open the Colors pop-up window.

  5. Select the color that you want particles to be at the start of their lifetime.

  6. If you want particles to change their color near the end of their lifetime, click the keypoint at the end of the color sequence, then click the small square next to Color to open the Colors pop-up window to select a color.

  7. If applicable, you can:

    • Add another keypoint by clicking anywhere on the graph.
    • Make a color change sooner or later within the gradient by dragging an existing keypoint to a new position. color to change sooner or later within the gradient.
    • Delete a keypoint by selecting it and clicking the Delete button.
    • Reset the sequence by clicking the Reset button.

Size

The Size property sets the stud size of each particle either as a consistent size or a NumberSequence. A number sequence changes a particle's size across its lifetime; it starts at 0, the start of emitting, and ends at 1, the lifetime of a particle.

Constant Size

To set particles to a specific size:

  1. In the Explorer window, select the ParticleEmitter.
  2. In the Properties window, select the Size property.
  3. Input the stud size that you want each particle to be.

Size Sequence

To set a particle emitter's number sequence:

  1. In the Explorer window, select the ParticleEmitter.

  2. In the Properties window, select the Size property.

  3. Click the button. A number sequence pop-up displays. By default, the graph is a straight line and a particle remains the same size throughout its lifetime.

    Each square at the start and end of the number sequence is a keypoint that determines the size value of the property at that point of the particle's lifetime.

  4. Perform one of the following actions:

    • To change the size at a point, click on a keypoint and either drag it up or down, or enter a value in the Value field.
    • To insert new keypoints, click on any point in the graph.
    • To delete a keypoint, select the keypoint, then the Delete button.
    • To add a random range for size, click on any keypoint and drag the envelope lines up or down. At that time, particles generate at a random size between the pink envelope.

Transparency

The Transparency property sets the opacity of each particle either as a consistent opacity or a NumberSequence. A number sequence changes a particle's opacity across its lifetime; it can range anywhere from 0 (totally opaque) to 1 (fully clear). For details on how to set particles to either a specific opacity or to a number sequence, follow the instructions in customizing Size.

The Transparency property is one of the most vital properties of a particle emitter. Fading particles near the start and/or end of their lifetime avoids a popping in/out effect and provides a more realistic effect.

Static transparency vs. fading in/out

Rate

The Rate property sets the number of particles that emit per second. A single particle emitter can create up to 500 particles per second. For best performance, keep the particle rate as low as possible. Experiment with the size of the particle texture, the size of particles, and other properties to minimize the number of particles while still achieving the desired visual effect.

SpreadAngle

The SpreadAngle property has an X and a Y value which determine the range of angles from which a particle can emit. The range is calculated from both sides around the axes; for example, a value of (45, 0) emits particles from to 45° away from the EmissionDirection across the X axis.

X axis spread angle of 0° vs. 45°

Shape

The Shape property sets the shape of the particle emitter to either a Box, Sphere, Cylinder, or Disc.

Box
Sphere
Cylinder
Disc

After you select a shape for your particle emitter, you can experiment with the ShapeStyle, ShapeInOut, and ShapePartial properties to further customize particle emission.

ShapeStyle

The ShapeStyle property sets the emission type to either:

  • Volume - Particles emit anywhere within the shape.
  • Surface - Particles only emit from the outside of the shape.
Cylinder + Volume
Cylinder + Surface

ShapeInOut

The ShapeInOut property sets the emission to:

  • Outward - Particles emit away from the shape.
  • Inward - Particles emit toward the shape.
  • InAndOut - Particles randomly behave as both Inward and Outward.

ShapePartial

The ShapePartial property is a factor you can use to determine cylinder, disc, and sphere shapes.

For cylinders, ShapePartial multiplies the radius of the cylinder on the side of its EmissionDirection.

ShapePartial = 0.5
ShapePartial = 0

For discs, ShapePartial inversely multiplies the inner radius of the disc.

ShapePartial = 0.5
ShapePartial = 0.1

For spheres, ShapePartial multiplies the hemispherical angle.

ShapePartial = 1
ShapePartial = 0.5

Flipbook

Particle flipbook textures let you animate a particle's texture over its lifetime. The following video shows a flipbook that loops over the four particles in its texture.

To use particle flipbooks, the texture must be a square with dimensions of 8×8, 16×16, 32×32, 64×64, 128×128, 256×256, 512×512, or 1024×1024. If the texture isn't a square with one of these dimensions, then you can't set flipbook's properties in the Properties window. The flipbook texture can have a frame layout of 2×2, 4×4, or 8×8. For example, the following 1024×1024 image has an 8×8 layout, so it's suitable for a 64-frame animation.

Sample texture for particle flipbooks

When you create a flipbook texture, include spacing between each of the particle frames. Mip filtering issues might lead to needing larger spacing. The previous image has transparent spacing around each particle frame in the flipbook particle texture.

Features with custom textures such as flipbooks cost memory to render. If you use many flipbooks with other features that use high memory, then clients automatically deactivate flipbooks when they are low on memory, which is likely for older mobile phones. To reduce the memory usage of flipbooks, use fewer unique animated particle effects or choose a texture of smaller resolution when possible. Reusing textures costs less memory than using unique textures.

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.

FlipbookLayout

The FlipbookLayout property determines the layout of the texture. It can be any value of the 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. The property can be any value of the 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.

Other Properties

To further customize particles, consider these additional particle emitter properties:

Property Description
Acceleration Determines by how much the velocity of particles changes per second. You can use this property to create effects such as particles being affected by gravity or wind.
Drag Determines the rate in seconds that particles lose half their speed.
Rotation Determines the angle of rotation for newly-emitted particles. Single numbers create particles at that angle, while two numbers (minimum, maximum) set a random rotation for each particle.
RotSpeed Determines the angular speed in degrees per second for particles. This can be a single number or a number range for a randomized speed. Negative values cause particles to rotate counter-clockwise.
Speed Determines the initial speed of particle movement, measured in studs per second. This can be a single number or a number range for a randomized speed. Negative values cause particles to move in reverse.
ZOffset Determines how many studs toward the camera that particles are rendered, allowing for multiple particle emitters to layer properly. The apparent size of the particles are not changed.

For a complete list of emitter properties, see the ParticleEmitter API reference.

Creating Explosions

You can create explosions by pairing a particle emitter with a LocalScript that triggers a burst of particles when a user steps on an object.

To create an explosion:

  1. Create a particle emitter and rename it to Explosion.

  2. Customize the particles to the following listed properties:

    • Texture - rbxassetid://6101261905
    • Drag - 10
    • Lifetime - 0.2, 0.6
    • Speed - 20, 40
    • SpreadAngle - 180, 180
  3. Under the parent object of the particle emitter, insert a LocalScript object:

    1. Hover over the part and click the ⊕ button. A contextual menu displays.
    2. From the menu, insert a LocalScript.
  4. Copy and paste the following code sample which checks if a user has touched the parent object of the particle emitter. When it detects the user, 100 particles emit and the user's health drops to 0.


    1local trapObject = script.Parent
    2local particleEmitter = trapObject:FindFirstChild("Explosion")
    3
    4local EMIT_AMOUNT= 100
    5
    6local function killPlayer(otherPart)
    7 local character = otherPart.Parent
    8 local humanoid = character:FindFirstChildWhichIsA("Humanoid")
    9
    10 if humanoid then
    11 humanoid.Health = 0
    12 particleEmitter:Emit(EMIT_AMOUNT)
    13 end
    14end
    15
    16trapObject.Touched:Connect(killPlayer)
    17