Ren'Py Floating Dust Particles Script

When developing on one of my own visual novels, I wanted to make some scenes more alive by adding some floating dust particles to it. As I was developing on it, I thought it would be a cool thing to share it with you patrons as well in case there are those of you who would like to have something similar in your games.

So in this post you can download a dust particles script I made which you can of course use in both personal and commercial if you're a patron in the tier Supporter or higher! 😁

If you cant see the  preview .gif above, please turn off your adblocker for the time being.

You can download it here: Download
or by scrolling down to the bottom of the post and download the attachment.

Do keep reading as well as I go into how it works below.

The script isn't really intended to be used by a complete Ren'Py beginner as you'd need to know at least the basics of how to use Ren'py first.

It's always good to get familiar with how things work by doing tests and reading the Ren'Py documentation. How you end up using the particles in your game is up to you and how you structure your game, but the below information will be helpful to know about.

How it works

The way it works is by using the SpriteManager class in Ren'Py which is great for things like these as it is optimized to display a larger amount of sprites at once and still keep performance good. Granted you use it responsibly of course.

You can read all about SpriteManagers and Sprites in Ren'py in the official documentation: https://www.renpy.org/doc/html/sprites.html.

The example project contains an extra file called "dust_particles.rpy" where the functionality of the particles is added.

The file contains 4 Python functions. One creates the dust sprites for the SpriteManager to use, then the update function animates them. Then there's a delete function that removes the SpriteManager from the game when you're done using it.

To create and add the dust particles to the game, you'd first need to create the particle sprites by calling a function called "create_dust_particles" and supply the amount of particles to make. Then to show them, you add the "dust" SpriteManager to the label or screen it should show in.

Examples can be seen in the example project.

Images used and how to swap them for your own

The sprites uses dust particle images from a folder I've named "Particles" inside of the images folder of the project. You can replace these with your own using the same name or with different names. There's two different ones because the script picks one to use for each particle at random.

If you decide on re-naming the files you would need to change the filenames in the "dust_particles.rpy" file as well for each transform in the functions. They look like this:

t = Transform("Particles/dust-particle-%s.png" % rand_img, alpha = rand_alpha, zoom = rand_zoom, additive = 1.0)

You'd need to change the file path so the name matches. So if you'd name your particles dust-1.png and dust-2.png for example, then you'd change the transform to use that name:

t = Transform("Particles/dust-%s.png" % rand_img, alpha = rand_alpha, zoom = rand_zoom, additive = 1.0)

The %s is a placeholder for the randomly picked number stored in the "rand_img" variable.

Adding the files to your own project

You can include the "dust_particles.rpy" file into the project files of any project you have. To see examples of how to use it, you can have a look at the "script.rpy" script file where the dust SpriteManager displayable is added to a few labels.

Using the dust particles in screens and avoiding performance issues

If you have some screens in your game where you want the dust particles to show on top of, you can do this in various ways such as with the "add" or "use" statements. The important thing to remember when using this particle effect is to make sure the particles don't "stack" on top of each other several times.

For example, this is something you shouldn't do:

screen scene_1:

image "scene_1_background.png"

imagebutton idle "door_1.png" action Show("scene_2")

add dust

screen scene_2:

image "scene_2_background.png"

imagebutton idle "door_2.png" action Show("scene_3")

add dust

screen scene_3:

image "scene_3_background.png"

imagebutton idle "door_3.png" action Show("scene_1")

add dust

label start:

call screen scene_1

return

In the above example, we have three "scene" screens. In each of these we have a button that shows the next screen, and the dust SpriteManager. In the third screen the button leads back to the first screen.

The problem here is that each time you show a new screen, the previous one is still showing behind. That means when you reach scene_3, you will have three dust SpriteManagers showing at the same time. This will end up in some visual hiccups and will most likely eventually slow down performance when you add more screens using the particles.

Instead of the previous example, you'd want to make sure you hide the previous screen before switching to the next one. That way you will only show one dust SpriteManager at a time. So the action would look like:

action [Hide("scene_1"), Show("scene_2")]

for example.

When using labels, you can hide the dust particles with: hide expression dust when you're done with it, or by using the scene statement which will remove all previously shown displayables.

That's about it. I might update this post in the future.

Hope you'll enjoy it, and feel free to ask questions below if you're wondering something about it. 😊