A good particle system is important for games and we are pleased to announce support for Particle Designer 2.0, one of the best particle effects editors in the market.

Key Features

Particle Designer 2.0 offers cool features to mobile developers, including:

  • High Configurability — 48 properties allow you to create wildly unique effects.
  • Multiple Emitters — Support for multiple simultaneous particle systems.
  • Realtime Preview — Watch particles immediately morph to reflect your property changes.
  • Drag-and-Drop — Full drag-and-drop support for background and particle images.

Getting Started

particle-designer-1First, download Particle Designer 2.0. The application is Mac-only, however Corona supports all effects which are created with and exported from Particle Designer, so Windows users can download particle systems and easily implement them in a Corona project.

Once installed, load the Particle Designer application. If you’re not familiar with the product, you can read some basic tutorials located on the 71Squared website.

When you open the Particle Designer application, you’ll see a sample particle system running. In the left panel, you’ll see this system listed under Particle Systems. If you wish, click the “cloud” button in the upper-right region of the application window and select another system from the Shared Emitters library.

In the Settings panel on the right side, you can adjust a myriad of properties for the emitter and see the changes reflected interactively in the main window. This tutorial will not discuss how to design particle systems, but rather focus on how to implement them within a Corona project.

Exporting for Corona

Once you’re pleased with the particle system in Particle Designer, it’s time to export it to Corona. There are some very important steps associated with this, so please read this section thoroughly.

1. Rename the Particle System

By default, the particle system name is Untitled 1. Obviously this isn’t a useful descriptor, so click on the name and enter something more accurate:


2. Expand the Particle System Options

To use a particle system in Corona, you must set some specific options before export. Expand the panel by clicking the “gear” button next to Particle Systems:


3. Deselect the “Embed” Option

When exporting a particle system, Particle Designer can embed the emitter texture file inside the particle file, however Corona does not support this feature. So, deselect the Embed option now:


4. Select the “Flip Y” Option

In some frameworks, including Corona, the Y coordinate is flipped. Particle Designer will take this into consideration if you select the Flip Y option:


5. Enable or Disable “Grouped/Relative”

In Particle Designer, the generated particles can be either grouped/relative in respect to the emitter, or independent of the emitter. This option can be toggled via the Grouped/Relative option:


If grouped/relative is enabled, all particles are dependent on the emitter position. For example, if you move the emitter up 100 pixels within Corona, the existing particles will also move up 100 pixels.

If this option is disabled, the generated particles behave independently of the emitter. For instance, if you create an emitter in Corona and, sometime after it begins generating particles, you move the emitter to a new location, the existing particles will not move in relation to the emitter — instead, they will continue their transformations independently.

If you want to see the difference interactively, you can toggle this option and drag the system “handle” around in the center panel.

6. Adjust the Maximum Particles

In the right panel, notice the Maximum Particles slider. The amount of memory pre-allocated for an emitter is driven by this value and you should balance it between the best visual effect and the fewest amount of particles. If you increase this value to an unnecessarily large value, you can bloat the memory usage within an app.


7. Change the Export Settings

In the bottom region of the left panel, locate and click the Export Settings button:


In the popup panel, select JSON as the Export Type. Then, for Export Location, browse to some folder where you can test Particle Designer from within a Corona project. When finished, exit the popup panel.


8. Export!

When you’re all ready, click the Export button:


To confirm that the export was successful, check inside the folder that you selected for export. Two files should now exist which match the name of the particle system that you set in step 1, for example nebula.json and nebula.png. The .json file contains the particle system details — this will be decoded within Lua and passed to the emitter instance in Corona. The accompanying .png file is the texture file used by the emitter.

Displaying the Particle System

With these files generated, adding the particle system to a Corona project requires just two steps:

1. Decode the .json file into a Lua table that Corona can utilize. This is accomplished by opening the .json file using the file i/o library, reading its contents into a string, and converting it to a Lua table using json.decode():

-- Require the JSON library for decoding purposes
local json = require( "json" )

-- Read the exported Particle Designer file (JSON) into a string
local filePath = system.pathForFile( "nebula.json" )
local f = io.open( filePath, "r" )
local fileData = f:read( "*a" )

-- Decode the string
local emitterParams = json.decode( fileData )

2. Display the particle system in Corona using display.newEmitter():

local emitter = display.newEmitter( emitterParams )
emitter.x = display.contentCenterX
emitter.y = display.contentCenterY

Now, relaunch the Corona Simulator and you should see the particle effect running effectively the same as it does in Particle Designer!

Module-Based Decode

If you intend to use several particle effects in an app, it may be useful to construct a simple Lua module which accepts some parameters and returns the decoded information. The following example, particleDesigner.lua, accepts the .json file name and (optionally) the system directory where it’s located:

local particleDesigner = {}

local json = require( "json" )

function particleDesigner.newEmitter( fileName, baseDir )

   local filePath = system.pathForFile( fileName, baseDir )
   local f = io.open( filePath, "r" )
   local fileData = f:read( "*a" )

   local emitterParams = json.decode( fileData )
   local emitter = display.newEmitter( emitterParams )

   return emitter

return particleDesigner

With this module accessible within the main project folder and required within main.lua or the proper Composer scene file, displaying a particle system is now as simple as this:

local particleDesigner = require( "particleDesigner" )

local emitter = particleDesigner.newEmitter( "nebula.json" )
emitter.x = display.contentCenterX
emitter.y = display.contentCenterY

Subfolder Usage

This module-based approach can also be used if you export the .json and image file(s) to a subfolder within your main project folder, for example particleFX. In this case, the emitter instantiation may look like this:

local particleDesigner = require( "particleDesigner" )

local emitter = particleDesigner.newEmitter( "particleFX/nebula.json" )
emitter.x = display.contentCenterX
emitter.y = display.contentCenterY

Emitters on Physics Bodies

If you wish to “attach” an emitter to a physics object, this can be accomplished by creating a new display group, a display object, and a new emitter. With these objects created, insert both the object and emitter into the group and apply a new physics body to the group itself (not the object or the emitter):

--Create a display group and display object
local group = display.newGroup()
local obj = display.newCircle( 0, 0, 5 )

local emitter = particleDesigner.newEmitter( "nebula.json" )

--Insert object and emitter into group
group:insert( obj )
group:insert( emitter )

--Add physics body to group
physics.addBody( group, "dynamic", { density=1, friction=0, bounce=0.3, radius=5 } )

In Conclusion

Hopefully this tutorial illustrates how easy it is to visually design, test, and export spectacular particle effects using Particle Designer and, once exported, display them within a Corona app in just a few lines of code.

  1. Very nice, I will check this out!

    So far we used Particle Candy for our projects. Particle Candy is basically a lua library that helps you with all particle stuff, and is doing a good job.

    Now one question: Is the performance of the Particle Designer integration better than the Particle Candy library? Because you precompiled it into the SDK? Or is this lua code running in the background, too?

    Thanks & best,

    • Brent Sorrentino says:

      Hi Andreas,
      Particle Designer support is compiled into the core of Corona, so presumably you would see performance improvements by using it. However, performance in regards to particle systems is prone to many factors and you could potentially make any app slow to a crawl by over-use of particles. In addition, the performance may vary considerably between devices, GPUs, and more. So ultimately, it’s up to you which option you choose and implement. Particle Designer is now another choice for Corona developers.

  2. Hi.
    I’ve successfully added the particles to my game, but trying your approach with subfolders fails!?

    I copied the code from your post.

    I have this:
    particles = particleDesigner.newEmitter(“explosions/stars.json”) and I have the .json and .png in a folder called “explosion” in my resource directory along main.lua and all the other files.

    The emulator then tells me this:
    Bad argument #1 to ‘open’ (string expected, got nil)

    Any thoughts?


    • Brent Sorrentino says:

      Hi Frode,
      You type here “explosions” and then “explosion” (folder name missing the “s”). Is this how your code is, or just how you typed it here? I have this implementation working on my side.

      • Hi.
        Sorry, that was a type here. In the App they are the same “Explosion” both places.
        Hmmm….must have been something I did. It’s working now!?
        Sorry, my bad! I must say Particle Designer rules! :) Greate addition to Corona SDK.


    • Brent Sorrentino says:

      Hi Dean,
      Yes, dynamic image selection is built-in and I confirmed that it’s working. Of course, Particle Designer will not automatically export the different resolution versions for you, so you’ll need to create and add them to the project yourself.

      As for blend modes, I can’t guarantee what will/won’t work on the countless Android devices and countless associated GPUs. I urge you to test as much as possible on this front, if you want to experiment with different blending modes.

  3. Hi.
    If I stack 2 separate emitters on top of each other I see the “invisible area” around the emitter particle as a black box.
    The case I’m referring to is when I “win” in my game. I first add a “starburst” for removing an object, and then I add the “You won!” particle system on top of that.


  4. The grouped/relative feature doesn’t seem to work.

    The particles are relative to the emitter x/y regardless of if the system is set to group/relative.

        • Brent Sorrentino says:

          Hi Thomas,
          Yes, I think it’s possible by adding/editing the field “absolutePosition”, but I’m not sure which value makes it true or false. 1, 0, -1… you’ll have to test it out. And, although this may seem obvious, I’m NOT encouraging people to adjust their JSON files haphazardly to get the particle effects they want. You do this at your own risk and we can’t be responsible for the outcome. :)

          • Albert Yale says:

            Use true or false, as in:

            "absolutePosition": true,

            But it’s simpler to do after the JSON file has been loaded, and this data is passed to newEmitter(), like so:

            local emitterParams = particleDesigner.loadParams( filename )
            emitterParams.absolutePosition = true
            local emitter = display.newEmitter( emitterParams )
  5. This is awesome, thanks a lot.
    But how would I stop emitting particles without emitter:removeSelf()?
    When I emitter:removeSelf() every particle will be deleted instantly. But I would just love to just stop emitting particles, so the effect wears off naturally and THEN removing the emitter.

    • Brent Sorrentino says:

      Hi PhilipFuchs,
      We haven’t yet added support for this, but we’re pondering the best approach. The consideration thus far is a simple “.start()” and “.pause()” function, mimicking things like audio start/pause. However, we’re open to other suggestions… do you have an alternative need or suggestion along these lines?

      At this point, a potential solution (depending on your particle effect) is to fade the emitter out (alpha) and then remove it upon completion. I realize this won’t be perfectly effective for all emitters, but it may be suitable in some cases.

  6. so is particle designer free for pro and enterprise users or do we still need to buy it from the publisher? If we do have to pay extra for it then why is corona labs spending a good amount of time integrating/fixing/adding features to the sdk specifically for this particle designer when it would be nice if you guys focused more on fixing and adding things on what we’ve already paid for which is the corona sdk itself.

  7. Purchased Particle Designer 2 & trying out.

    a) How can I adjust some of the variables of the emitters at runtime like I do for Particle Candy? For example I need to speed up the output of particle as the player speed increases. So example changing: maximum particles, speed, lifespan

    b) How to turn off, than back on, an emitter

    • Albert Yale says:

      A start(), stop(), and pause(), have been added to EmitterObjects. As well as the ability to modify most JSON parameters. Please take a look at the EmitterBasic3 sample in the latest daily build, and the daily build documentation for EmitterObject.

  8. I have a problem with subfolders. I put the petals2.json and the petals2.png in a subfolder called particleFX/
    However corona only finds the .json file

    WARNING: Failed to find image (petals2.png)
    CAN’T find texture name: petals2

    The problem solves if I put the image in the main folder.

    So, only with the instruction local filePath = system.pathForFile(“particleFX/petals2.json”) Corona still tries to find the .png in the root folder and not in particleFX/ subfolder.

    • Brent Sorrentino says:

      Hi Pablo,
      I’m certain that I got this working. Did you follow the example that I show under “Subfolder Usage” in this tutorial?


      • Yes, I tried another time and I got the same error

        The “Subfolder Usage” is only this lines isn’t it?

        local particleDesigner = require( “particleDesigner” )

        local emitter = particleDesigner.newEmitter( “particleFX/nebula.json” )
        emitter.x = display.contentCenterX
        emitter.y = display.contentCenterY

        With that code It works only if the nebula.json is in particleFX and the nebula.png in the root folder

        • I’m using build 2014.2332, and I’m seeing the same issue. Subfolders are not supported.
          However I created a new function that fixes this issue in the meantime.

          local newEmitter = function(emitterFile, dir)
          dir = dir or system.ResourceDirectory

          local filePath = system.pathForFile(emitterFile, dir)
          local f = io.open(filePath, “r”)
          local fileData = f:read(“*a”)

          local emitterParams = json.decode(fileData)

          — fix start ——————————–
          — Corona builds do not support particle textures in subfolders
          — the code below fixes this issue
          local slashPos = nil
          local tmpPos = 0

          — find last slash in input string
          tmpPos = emitterFile:find(“/”, tmpPos + 1)

          if (tmpPos) then
          slashPos = tmpPos
          until not tmpPos

          if (slashPos) then
          local subfolder = emitterFile:sub(1, slashPos)

          — future-proofing in case CoronaLabs fixes this issue
          if (not emitterParams.textureFileName:find(“/”)) then
          emitterParams.textureFileName = subfolder .. emitterParams.textureFileName
          — fix end ———————————-


          local emitter = display.newEmitter(emitterParams)
          emitter.x, emitter.y = 0, 0
          –emitter.isVisible = false

          return emitter

  9. Is there anyone here that got a particle effect working on corona starter?
    I am planning to get the pro account,but right now I just updated to the last build and I still get this error:

    Attempt to call field ‘newEmitter’ (a nil value)

    I can’t even run the corona samples code because I always get the same error.
    Any Ideas?

    Thank you.

    • Brent Sorrentino says:

      Hi Gianluca,
      Particle Designer support is not available in the latest public build (#2189); it was released as a feature for Pro/Enterprise users in a daily build about a month ago.

      Best regards,

    • Hi Alex,
      While the emitter is a display library entity, it’s not really an “object” with width/height that you can sense touch on. It’s meant to be more of an associative object related to a standard display object, i.e. the exhaust coming from the engine of a ship. So, to drag/manipulate an emitter, you’ll need to associate it with a standard display object/group and use the typical touch functionality on that object, moving the emitter along with it.


  10. It looks like you only can create particles which start small and grow big, or start big and grow small. A really nice to have with particle designer would be to have particles which start small, grow big and then getting small again before disappearing. Or start big, get small and get big again before disappearing. Or did I miss something here and this is somehow possible to create already?

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>