• Graphic of Code Basics Series on Particle Effects Part 1 848px

Code Basics – Add Particle Effects in Your Game – Part 1

posted in: Tutorial | 4


If you have been kicking around with 2D games, one of the coolest types of visual effects that you can add is Particle Effects.

If you want to simulate Fire, Smoke, Explosions, Sparks, Fog or other effects, then adding Particle Effects in your game is probably exactly what you are looking for.


As always, I will show you the ropes to adding particle effects in your game with the easy to use cross-platform development tool – Corona SDK.


So what do Particle Effects look like ?


Take a look at these two quick examples of Particle Effects that I coded and then loaded on my Android phone. The first is simply using a rocket image and attaching a fire type particle effect to the base of the rocket. Once you tap the screen, the rocket shoots up to the location of the tap along with the fire type particle effect streaming out from the bottom of the rocket.



The second video below shows a fountain type Particle Effect. Tapping anywhere on the screen generates the particles and a gravitational effect pulls the particles back toward the ground much like a lawn sprinkler does with water.




Pretty cool effects, right?!


Particle Effects in Corona SDK: A History


Particle Candy


As I mentioned previously I first discovered Corona SDK back in 2013 while looking for a cross platform development tool to create apps. Back then one of the best know tools for 2D game developers coding in Lua was a particle engine called Particle Candy by X-pressive.com.


Particle Candy website pic 600px



In many cases Particle Candy may still be a great choice even today to add Particle Effects in your game. The only friction point is that Particle Candy is a paid product with no trial available so you’ll have to pay for the library to get started.




Prior to 2013, if you were creating a game in Corona SDK you either used Particle Candy or created your own custom solution to add particle effects in your game. Then in 2013, a community member named Caleb from Gymbyl Coding released a free and open source particle effects library called CBEffects (or just CBE).


CBEffects website pic 600px


The library itself is very solid and provides many awesome particle features. An interesting side note about CBEffects is that its creator was only 13 years old at the time of its release.


In fact, I used the CBEffects library to create the two particle effects shown in the above videos from my Android phone. If you are using CBEffects and want to support Caleb I encourage you to check out his Github page where you can make a donation if you wish via Paypal to support the library.


Corona SDK Built-in Particle Support – display.newEmitter()


Both Particle Candy and CBEffects mentioned above are dedicated Lua modules that you add into your project. However, in March 2014 Corona SDK announced built-in particle effect support with the particle design tool called Particle Designer 2.0.


Corona Particle Designer Annoucement 700px


This announcement by Corona SDK for built-in support of all effects which are created with and exported from Particle Designer 2.0 provided an alternative work flow to getting particle effects in your game. The workflow for Particle Candy or CBEffects is that you add the library to your project (or an empty project), then use either the pre-canned emitters / effects to generate effects or alter some variables in a trial/error manner, then reload the project to see if the effect was what you wanted to achieve.


The workflow with the Corona SDK built-in methodology is slightly different. First you use a GUI tool like Particle Designer 2.0 where you design the particle graphically outside of your project. Once you are happy with the particle effect that you have designed, you export the particle design as a .json and .png file which you can then load into your project. As described in Ed Maurina’s post on the various Corona Particle Tools and Data Formats, the Lua code to load a Particle Designer 2.0 effect into your project would look something like this –



To re-iterate, there are three basic steps with the Corona SDK built-in methodology for adding particles in your game –

  • Create the particle effect in a Emitter Authoring Tool (the GUI… such as Particle Designer 2.0)
  • When happy with the particle effect, export it from the Emitter Authoring Tool (the GUI)
  • Open and decode the file that was previously exported with an Emitter Loader and pass it to the built-in Corona SDK API call display.newEmitter()


There was quite a lot of excitement within the Corona SDK community at the time during the built-in particle support announcement. However, there was one caveat with the announcement… Particle Designer was a Mac-only tool. Although a great paid product, being Mac-only, many Windows users were out of luck (at least initially). However, within a few weeks a community member called Mike Wilson created a custom Emitter Loader that could be used for free in conjunction with a free online Emitter Authoring Tool from OnebyOneDesign.com.


For a comprehensive overview of the various Particle GUI tools and loaders available I encourage you to check out Ed Maurina’s post titled Corona Particle Tools and Data Formats.


Next, in this tutorial I will show you how to add particle effects in your game with Corona SDK by using two different methodologies (both are Free).


  • First, in Part 1 of this tutorial series we’ll use the free and open source library CBEffects
  • Then, in Part 2 of this tutorial series we’ll try an external GUI tool, export the particle effect and then load it into our game using the built-in Corona display.newEmitter() call


Creating the Basic Game


First we will make a basic game to demonstrate how to add particle effects in your game.


For the setup of the game play we will assume we are targeting a smart phone such as the iPhone. The only real difference for us is the aspect ratio (screen height divided by screen width) changes from 1.5 (iPhone 4/4S) to 1.78 (iPhone 5/5C/5S/6). We will layout our content area for the iPhone 4/4S and set this up in the config.lua file below.


The basic game play will be the following –

  • A rocket image will be positioned just off the left side of the screen. The vertical position that the rocket starts at can vary randomly between the top and bottom of the screen.
  • The rocket image will then move from left to right.
  • When you touch the image, it will emit a particle effect and launch itself upwards.


Download and Install Corona SDK –


If you haven’t installed Corona yet, go ahead and head over to https://coronalabs.com. Click on the “Download” button in the top right hand side of the page. You will need to register, accept the terms/conditions and you’ll be able to download the SDK for either Windows or Mac. I recommend you check out “Corona SDK System Requirements” and “Installing Corona SDK” for your O/S within Corona University.

Use or choose your favourite text editor, I will be using Sublime Text 3 since Corona has their plugin “Corona Editor” available with Sublime Text that features code completion for the API, debugging options and other handy features.


If you want a guided tour of the installation process, check out this video –



Create a New Project in Corona SDK –


Note: The operating system used in this tutorial is Windows 8. If you are using Mac OSX, screen shots and windows will look slightly different but the same principles and Lua code will apply.


Open up Corona SDK, and create a New Project –


Basic Particle Project New Proj 1 700px


When the New Project window comes up –


  • For Application Name: Call it something like “Basic Particles”
  • For Project Folder: Select a location on your computer where you want to store the project (or leave it as the default location)
  • For Project Template: Leave the radio button selected as “Blank”
  • Leave the Upright Screen Size to “Phone Preset”
  • Leave the Default Orientation radio button as “Upright”


Basic Particle Project New Proj 2 700px


Hit the OK button in the New Project window above and the window for your new project should launch (otherwise just navigate to the Project Folder location, like that shown in the New Project window above) –


Basic Particle Project Window View


Take particular note of the two files that I have highlighted in the above project folder view:


  • config.lua
  • main.lua


Edit the ‘config.lua’ file –


Think of the “config.lua” file as basically the file that holds specific settings like target device resolution, content scaling, dynamic image placement, etc. It sounds complicated but for now just copy the code below into your project “config.lua” file.

Although we are targeting an iPhone sized smart phone for this demo app, we will change part of the “config.lua” file to handle multiple screen sizes and resolutions using the Simple Content Scaling methodology. We will assume for this simple example that the demo app is used in Portrait mode only, with Letterbox type scaling. From the original post on modernizing the “config.lua” file, open the “config.lua” file in Sublime Text (or whatever text editor you use) and ensure the content of this file in your project folder has the following settings –



You will notice the values 640 and 960 used above. This sets up the content area that you are designing your app towards to be the same as the iPhone 4/4S with a content area that is 960 pixels high and 640 pixels wide.


Once you have entered the code above into your “config.lua” file, Save the “config.lua” file.

In this simple demo, we will only be experimenting with a single page application along with the inclusion of Particle Effects. Corona handles multi-screen applications (which most real apps have) and the interconnectivity of these screens in your game or app with the Composer library. For now, just know that it exists… as we won’t deal with Composer in this demo.


Edit the ‘main.lua’ file –


Open up “main.lua” in Sublime Text (or whatever text editor you use).


Screen shot of Sublime Text search 700px


Basic Particle Project Main.lua 1 700px


If you are using Sublime Text, then make sure you navigate to View->Syntax and ensure that the syntax option for Corona SDK Lua is selected.


Basic Particle Project Main.lua 2 700px


The main reason for selecting the Corona SDK Lua syntax option is that when you are typing out your code, it will present you with auto-complete options from the Corona SDK API that makes life a little bit easier.


Download this rocket image and add it to your Project files (at the same level as your main.lua file) –


Particle Tut Rocket Image 140x160px


Initially we won’t do too much exciting, we will simply localise helper variables that we will commonly use, load the rocket image, then place it at the center of the screen and rotate it for a left-to-right flight direction. Type out the follow code below in your main.lua file –


Launch the Corona Simulator. Within the Corona Simulator ensure you have selected View -> View As -> iPhone 4. Your project should look something like this –


Step 1 of Basic Game Setup. Rocket image load.



Next, we want rockets to appear from off the left side of the screen on a prescribed interval, say every 2 seconds. So let’s make a function that will be called every 2 seconds, creating a new rocket that will transition from the left to the right of the screen.


To do this we create a new local function called createNewRocket(). We place our previous code that created and positioned the rocket inside this function. Additionally, within this new createNewRocket() function we add a call to the Corona SDK method transition.to() that will move the newly created rocket object from the left to the right of the screen over a 3 second interval. We will start the rocket at 200 pixels off the left side of the screen, at a random y location limited to between the top and bottom of the screen. When the rocket reaches its destination 200 pixels beyond the right side of the screen, we call an internal clean up function called rocketCleanUp() to remove the display object and free up the memory it occupied.

To start the app off, we create the 1st rocket object and start it moving with the initial call to createNewRocket() on Line 39. 

Then on Line 40, we use the Corona method timer.performWithDelay() to call that createNewRocket() function every 2 seconds (2000 milliseconds). The third parameter of timer.performWithDelay() is passed a 0 which indicates that this function should run forever within the app (passing -1 also does the same thing).


With the code above, your app should now behave like the following (except the vertical position will vary)-



Next, we want to add a touch event listener to each rocket image that is created in our new function createNewRocket(). This allows each rocket to sense when it has been touched. In this instance we will simply use the Corona SDK Tap Event. The Tap Event is much simpler than the Touch Event that I described in an earlier post. The Tap Event does not have states and simply generates a hit event when the user touches the display object.


To indicate that the touch event listener is working, we will simply print the statement “You tapped the rocket” in the console.


Your code should now look something like this –



With the code above, your app should now behave like the following (notice I slowed down the across screen transition to 4000 milliseconds)-



We have completed 2 of the 3 functions for the basic game setup prior to seeing how we add in particle effects. Next, let’s build out the rocketTapped() function that is the listener function that receives the Tap Event every time we touch a rocket. We want the following sequence of events to happen –

  • When a rocket is tapped by the user the code within local function rocketTapped(event) is run
  • On line 29, local obj = event.target creates a local variable called “obj” that points to the rocket object that was touched
  • On line 30, local obj_touch_x = event.target.x creates a local variable called “obj_touch_x” that indicates the screen x location when the tap occurred.
  • On line 31, we do the same for the screen y location when the tap occurred.
  • On line 34, we cancel the transition that was moving the rocket image from the left to the right side of the screen.
  • On line 36, we remove the Tap Event listener from the object.
  • On line 39, we rotate the rocket image randomly between 30 to 80 degrees in preparation of the blast off effect.
  • The lines between 40-60 use some standard trigonometry to prepare the blast off effect.
  • On line 63, we launch the rocket image into the blast off effect using another call to transition.to()
  • Once the transition finishes, the onComplete parameter passes the object “obj” to the rocketCleanUp() function to remove the display object and free up the memory it occupied.


Your code should look like the following –


With the code above, your app should now behave like the following –



Woo hoo! Congrats! You have made the basic game and we are now ready to add some Particle Effects.


Add Particle Effects in Your Game with CBEffects


First off, head over to the Gymbyl Coding Github page to download the CBEffects particle library. The latest version at the time of this writing is CBE 3.2.


CBEffects library Github page image 700px



Click on the “Download ZIP” button on the right side of the Github page as shown in the image above. Save the file “CBEffects-master.zip” to any location on your computer and then un-zip / extract the files by right-clicking on the .zip file and selecting Extract All.. as shown below (or use 7-Zip if you have it installed). 


Unzipping the CBEffect Library 700px


The extracted folder structure should look something similar to that below. We will actually only need to include the folder titled CBE in our own project, but for now I recommend you copy the entire CBEffects-master folder as shown below (we will place a copy in our working directory).


TheCBEffect Library 700px


Paste a copy of the CBEffects-master folder at the same level as our project that we created in this tutorial (the one I called Basic Particles).


Placing the CBEffect Library in working dir 700px


CBEffects include a demo app, that will show you many of the features included in the library. Launch the CBEffects demo app by opening Sublime Text or the Corona Simulator. Navigate inside the CBEffects-master folder and open the main.lua file included with it.


The demo app should look like this –


CBEffects demo app 600 px


If you click on the individual text objects in the CBEffect demo app it will launch a sample effect. To learn more about that sample effect, in the lower right hand side there is a text button called “Show Academic Section”. Note: If the text appears very small when you launch the demo app, resize the simulator by going to View -> Zoom In.


Now that you know where to experiment with CBEffects by using the demo app included with it, its time to add the library into the basic game that we created earlier.


Copy the CBE Folder into the root level of your Basic Particle Project


As mentioned before, the only folder that we need to add into our project is the CBE folder that was included in the entire CBEffects-master download from Github.

Copy the CBE folder across to your project and place it at the same level as main.lua (often called the root of your project). Your folder structure should look similar to this –


CBE in Basic Particles Project 700px


If you closed down the project we created earlier, open up “main.lua” in Sublime Text (or whatever text editor you use).

The easiest way to start using the CBEffects particle library is to use one of the built-in “presets”.

At the top of our code we first add in the CBEffects particle library by declaring require(“CBE.CBE”). To see a listing of the Preset particle effects available, on the next line we type in CBE.listPresets(). Run your project with the Corona Simulator and you should see a listing of the presets available in the console like shown below.


CBE Presets in Console 600px


Within Sublime Textif you enable the menu option in Corona Editor -> Show Build Panel you will also see the console output within the editor as shown below. 


CBE Presets in Sublime 700px


Since we are dealing with a rocket in our basic game, the “burn” preset will be appropriate. We first need to define a new particle effect in our project. A particle effect in CBEffects lingo is called a “vent“. In other particle systems the particle effect is called an “emitter“.


You create a particle effect “vent” by calling the CBE.newVent() function and pass in a table of parameters. To load a preset, the code would simply look like this (where we load the “burn” preset) –



Now, let’s add this line of code to our project and then position the particle effect “vent” near the bottom of the screen in the center.


[Note: I was initially caught off guard by a slight change that occurred from CBE Library version 3.1 to CBE Library version 3.2. Specifically the position parameters ‘x’ and ‘y’ have been renamed to ’emitX’ and ’emitY’ in version 3.2.]


Your code should now look like this –



With the code above, your app should now behave like the following –



However, we don’t want the particle effect to just live statically in an arbitrary position on the screen. Specifically we want the particle effect to appear only when the rocket image is tapped, and it should transition along with the rocket image into its launch off the screen. Also, we need to orientate the “burn” preset so that the flame is angled downwards.


The code below accomplishes this, and I will describe the additions / changes here –

  • On lines 51-61, we move the creation of the new Particle Effect “vent” to within the rocketTapped() function
  • We pass some physics properties to override the preset default values. The gravityY parameter ensures the particles fall downward.
  • On lines 63-65, we position the new Particle Effect “vent” at the same location as the tapped rocket image
  • On line 68, we ensure the rocket image is positioned over top of the particle effect
  • On line 71, we start the particle effect
  • On line 95, we start a parallel transition.to() to move the particle effect “vent” in conjunction with the rocket launch image.
  • When the particle effect “vent” finishes, we make a call with the onComplete parameter to the clean-up function ventCleanUp()



With the code above, your app should now behave like the following –



If you made it this far and understood the step-by-step process to create Particle Effects in your game with the help of the CBEffects library, Great Job!


You could add a nice background, create a points system, apply some UI buttons/controls, wrap it in a scene management system like Composer and you’ve got a basic children’s game that could be published.


Final Screen Shot of CBEffect Particle Game 640px



Up Next: Part 2 with Particle GUI Tools


Join us next time for Part 2 of this tutorial series where we’ll use an external GUI tool, export the particle effect and then load it into our game using the built-in Corona display.newEmitter() call.


4 Responses

    • Randal

      Hi Jon, thanks for your feedback and I’m glad you enjoyed the article. Part 2, using the Corona SDK built-in “display.newEmitter()” should be live within a few days. Cheers mate!

Leave a Reply