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

posted in: Tutorial | 2

 

In Part 1 of this tutorial series on adding particle effects in your game using Corona SDK, we used the free and open source library CBEffects to make a cool rocket blast off effect. By simply adding a decent background image, your game would look similar to this –

 

Final Screen Shot of CBEffect Particle Game 640px

 

In Part 2 of this tutorial series we’ll use an external GUI tool, export the particle effect and then load it into our game using the built-in display.newEmitter() function that was introduced to Corona SDK in 2014.




External GUI Particle Design

 

As described quite thoroughly in the post Corona Particle Tools and Data Formats, the workflow to use the Corona built-in display.newEmitter() function starts with you designing your particle effects using an external GUI particle design tool (or emitter authoring tool). These GUI particle design tools allow you to create, edit, export, and import particle emitter data.

 

Three great options for GUI particle design tools include –

 

Particle Designer 2.0 (by 71 Squared)

 

Screenshot of 71 Squared Particle Editor 700px

 

 

Particle Editor for Corona SDK (by Roaming Gamer)

 

Screenshot of RoamingGamer Particle Editor 700px

 

 

Online Particle Editor (by OnebyOneDesign)

 

Screenshot of OnebyOne Design Particle Editor 700px

 

 

For this session we’ll be using the Free online particle editor by OnebyOneDesign.com, but I encourage you to check out the Roaming Gamer’s Particle Editor tool that allows you to create and edit particles on Windows, Mac and your mobile devices. If you are exclusively a Mac user, you might also want to check out the feature rich Particle Designer 2.0 by 71Squared.com.

 

Let’s get started !

 




 

Setup your Project

 

We will be re-using most of the code that we created in the previous tutorial Code Basics – Add Particle Effects in Your Game – Part 1.

The easiest way to continue on here is to create a copy of our previous Corona SDK project. Alternatively, if you are starting here just create a new Corona SDK projects titled “Basic Particles 2”, then go back to Code Basics – Add Particle Effects in Your Game – Part 1 and copy the main.lua code at the end of the tutorial into your main.lua project file. Additionally, ensure your config.lua file is the same as that shown in the previous Part 1 tutorial.

 

After you make a copy of the previous “Basic Particles” project or simply create a new project, rename the project directory “Basic Particles 2” as shown below –

 

Basic Particle 2 Project Directory 700px

 

 

The content within your “Basic Particles 2” project directory should look the same as shown below. Note: I removed the CBE folder that was used in Code Basics – Add Particle Effects in Your Game – Part 1.

 

Basic Particle 2 Content Directory 700px

 

 

Open up “main.lua” in Sublime Text (or whatever text editor you use) and the code should look like the following – [Note: The previous code and references to the CBE library have been removed below]

 

 

With the code above, if you launch the app using the Corona Simulator you should see the basic touchable app that launches the rockets without any particle effect goodness. It will look like the following –

 

 

Design Your Particle Effects

 

Now that we have the basic game play ready, head over to the Particle Editor at OnebyOneDesign.com where we will design our rocket particle effect.

 

Entry screen OnebyOneDesign.com PE 700px

 

Rocket Exhaust Particle Design

 

We will change the settings of the online particle editor to look like a white-hot pink fire ball to emulate our rocket exhaust once it fires up. It should look similar to the following screen shot –

 

Our Design on OnebyOneDesign.com PE 700px

 

Ensure that your particle parameters are set to the following values

 

Particle Properties –

ParameterValue
Emitter TypeGravity
Max Particles300
Lifespan 0.5
Lifespan Variance1.9
Start Size50
Start Size Variance10.3
Finish Size2.6
Finish Size Variance5.0
Emitter Angle0.0
Angle Variance10.0
Start Rot.0.0
Start Rot. Var.0.0
End Rot.0.0
End Rot. Var.0.0

 

Particle Behaviour –
ParameterValue
X Variance0.0
Y Variance0.0
Speed300
Speed Variance0.0
Gravity X0.0
Gravity Y300
Tan. Acc.0.0
Tan. Acc. Var.0.0
Rad. Acc.0.0
Rad. Acc. Var.0.0

 

Note: The Rotational (Radial Emitter) properties are not applicable in this case.

 

Particle Colour-
StartValue
Red0.7
Green0.2
Blue0.2
Alpha0.9
FinishValue
Red1.0
Green0.3
Blue0.0
Alpha0.0

 

Note: Set all the Particle Colour Variance properties to Zero.

 

Once your parameters are set and you are happy with your particle design, click on the “Export Particle” button and you will be prompted to Save a file called “particle.zip”. Save this .zip file to the root level of your Basic Particles 2 project folder as shown below –

 

Export Rocket Particle 700px

 

Un-zip / extract the files by right-clicking on the .zip file and selecting Extract All.. or use 7-Zip if you have it installed. There will be two files in the extracted .zip folder –

 

  • particle.pex
  • texture.png

 

Create a new folder within your Basic Particles 2 project called “emitters“. Move the “particle.pex” file and “texture.png” file to this new emitters folder. Rename the “particle.pex” file to “rocket_exhaust.pex”. Your project structure should look like the below screen shot –

 

Screenshot of emitters folder 700px

 

 

Once you have done this you can delete or archive / move the .zip file that was exported from the online particle editor.

 

Rocket Igniter Particle Design

 

In addition to our rocket exhaust particle effect, we will also create a rocket ignition explosion particle effect that we will activate just before our rocket starts up. It will look similar to this –

 

Explode Design on OnebyOneDesign.com PE 700px

 

For the explosion effect, ensure that your particle parameters are set to the following values

 

Particle Properties –

ParameterValue
Emitter TypeGravity
Max Particles300
Lifespan 0.2
Lifespan Variance0.6
Start Size11
Start Size Variance49.5
Finish Size30.5
Finish Size Variance5.0
Emitter Angle360
Angle Variance360
Start Rot.0.0
Start Rot. Var.0.0
End Rot.0.0
End Rot. Var.0.0
Particle Behaviour –
ParameterValue
X Variance0.0
Y Variance0.0
Speed430
Speed Variance72
Gravity X0.0
Gravity Y0.0
Tan. Acc.0.0
Tan. Acc. Var.0.0
Rad. Acc.0.0
Rad. Acc. Var.0.0

 

Note: The Rotational (Radial Emitter) properties are not applicable in this case.

 

Particle Colour-
StartValue
Red0.8
Green0.8
Blue0.0
Alpha0.5
FinishValue
Red1.0
Green0.0
Blue0.0
Alpha0.1

 

Note: Set all the Particle Colour Variance properties to Zero.

 

Similar to the previous particle exporting process, click on the “Export Particle” button and you will be prompted to Save a file called “particle.zip”. In the same manner as described previously, un-zip / extract the files. You only need to retain the “particle.pex” file in this case. Rename this file from “particle.pex” to “rocket_ignite.pex”, and then save it in the emitters folder created earlier.

 

Pex Loader Module: The Ponywolf Library

 

As described in Ed Maurina’s post on the various Corona Particle Tools and Data Formats, the format of the .pex files that we exported previously is commonly referred to as the Starling Format. Each of the .pex files is an XML-encoded Lua table in Starling Format 2.

 

With the .pex particle effect files we need to do some pre-processing to load them into a table that can be passed into the built-in Corona SDK function display.newEmitter( EmitterData ), where the argument EmitterData is effectively a table of parameters used to define the Emitter Object that gets created and returned when calling display.newEmitter().

 

To pre-process the .pex particle definition files in a format the can be consumed in Corona SDK, we will use the Ponywolf Pex4Corona library.

 

Note: There is an alternative to using the Ponywolf Pex4Corona library that involves using 3 library files (modules) that come in the EmitterBasic2 sample that is packaged with the Corona SDK installation files on your computer. They are located in the location as shown below. Despite this, I prefer only having to include 1 extra library file by using the Ponywolf Pex4Corona library.

 

Alternative to PonyWolf library 700px

 

 

First off, head over to the Ponywolf Github page to download the Pex4Corona particle loader library.

 

Screenshot of Pex4Corona PonyWolf library 700px

 

 

Click on the “Download ZIP” button on the right side of the Github page as shown in the image above. Save the file “pex4coronamaster.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). 

 

Extracting Pex4Corona PonyWolf library 700px

 

 

The extracted folder structure should look something similar to that below. We will actually only need to include the folder titled com in our own project, but you can look at the main.lua file that is included in “pex4coronamaster.zip” on how to use and call the pex loader module. (Note: We’ll go over usage of the library as we continue our Basic Particles 2 project below).

 

The COM folder in Pex4Corona PonyWolf library 700px

 

 

Copy the Ponywolf “com” Folder into the root level of your Basic Particle 2 Project

 

The only folder that we need to add into our project is the com folder that was included in the entire pex4corona-master download from Github. The actual .pex loader module is called pex.lua.

Copy the com 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 –

 

Emitters and PonyWolf Library in Project 700px

 

Within your Basic Particles 2 project folder, you should have the following –

 

The com subfolder that contains –

  • pex.lua (located within com\ponywolf)

 

The emitters subfolder that contains –

  • rocket_ignite.pex
  • rocket_exhaust.pex
  • texture.png

 

Add Particle Effects in Your Game using “display.newEmitter()”

 

Now that we have –

 

  1. Designed and exported our particle effects into our project using an external GUI tool (in this case the Particle Editor at OnebyOneDesign.com)
  2. Included the .pex loader module into our project with the Ponywolf Pex4Corona library

 

…we are now ready to get back to our game and implement these particle effects !!

 

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

 

To start off with, we will load the pex data into a format that can be consumed by the built-in Corona SDK particle object display.newEmitter(). We will then position the two particle effects on the screen statically just to check they load similar to how they looked in the external GUI tool.

 

Your code should look like the following –

 

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

 

 

Next, let’s position and stage our particle effects so that the following happens –

  • When a rocket image is tapped, the rocket image should rotate to a launch angle and the rocket igniter particle effect (rocket_igniter.pex) should fire for about 100 milliseconds. We then stop that particle effect.
  • After the rocket igniter (100 millisecond duration), the rocket should launch and the rocket exhaust particle effect (rocket_exhaust.pex) should transition along with the rocket image into its launch off the screen.
  • When the rocket moves off screen, the transition finishes and we stop and clean up the rocket particle effects.

 

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

  • On lines 10-12, we require our Ponywolf pex loader module and use the pex.load() function to load our particle effect data into a Lua table format that can later be passed to the built-in Corona SDK display.newEmiiter() function.
  • On line 14, we hide the status bar at the top of the simulator.
  • On lines 22-28, we fill in our emitterCleanUp() function so that when an emitter display object is passed to its argument, we first ensure the particle emitter is stopped (if not already) and then remove the object and clean up its memory by making it nil.
  • On lines 56-59, within our rocketTapped() listener function when the rocket object is tapped we create an instance of the rocket exhaust particle effect with display.newEmitter( particleData1), passing in the particle data formatted on lines 10-12. We then programmatically change the “angle” property of the particle effect to orientate itself with the launch direction. We call the emitter stop() function so it is ready but not showing yet.
  • Similarly, on lines 61-62, we create and the stop() our rocker igniter particle effect with display.newEmitter(particleData2).
  • On lines 64-68, we position the two particle effect instances at the same location as the tapped rocket image object.
  • On line 71, we use the obj:toFront() call to ensure the rocket is in the top display group.
  • On line 105, we call myEmitter2:start() to show the rocket igniter particle effect.
  • On line 106, we use timer.performWithDelay() to call the local function doNextParticles() after 100ms of showing the rocket igniter particle effect.
  • On lines 93-103, we create the function doNextParticles() that stops the rocket igniter particle effect, starts the rocket exhaust particle effect and initiates our launch sequence with the calls to transition.to(). When the transitions are finished, the onComplete parameter is used to pass each object instance to its respective clean-up function to remove the display object and free up the memory.
  • For a description of the other code, go back and check out Part 1 of this tutorial series.

 

Note: For a listing of all emitter object parameters that are set and that can be changed at any time (like we did programmatically above), check out the Corona SDK documentation on the Emitter Object.

 

Your code should look like the following –

 

 

With the code above, your app should now behave like the following – (Note: In my version I added a nice little space background for extra impact ! )

 

 

If you made it this far and understood the step-by-step process of creating Particle Effects using the built-in Corona SDK display.newEmitter() function, Awesome Stuff!

 

If you want to change properties or colours of the rocket exhaust particle effect that we created, I recommend just tweaking the effect in the External GUI particle design tool and then changing the values manually in the project “rocket_exhaust.pex” file (rather than re-exporting and un-zipping from the External GUI particle design tool).

 

Once again…. you could easily expand upon this app to create a basic children’s game that could be published to the App Stores with a bit of polish.

 

If you are looking for a nice background and some artwork to expand upon your game so that it looks professional and polished, I recommend you check out – 99designs.com

(Click here for a  $25 discount to all mobile traffic)


 

 

 

 

2 Responses

Leave a Reply