Tutorial: Using Particle Designer in Corona

Share on Facebook0Share on Google+2Tweet about this on TwitterShare on LinkedIn0

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():

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

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:

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:

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:

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):

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.

Share on Facebook0Share on Google+2Tweet about this on TwitterShare on LinkedIn0

Brent Sorrentino serves as a full-time Developer Evangelist for Corona Labs, assisting developers in the forums, maintaining documentation/guides, and creating samples which highlight core features of Corona SDK.

This entry has 42 replies

  1. Andreas says:

    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.

      • Andreas says:

        Thanks Brent,

        that’s the answer I hoped for. 🙂


  2. Frode says:

    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.

      • Frode says:

        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.


  3. Dean says:


    Does this work with dynamically scaled images? i.e. can we use star.png, star@2x.png, star@4x.png etc

    Also, will the different blend modes available work across Android devices?


    • 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.

  4. Frode says:

    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.


    • Frode says:

      Ok fixed it by changing the Blend mode to: “GL_ONE”. Thanks Dean for mentioning the blend modes 😉


  5. Thomas says:

    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,
      We’re aware of this, and it should be remedied in the next update to Particle Designer.

      • Thomas says:

        Great! Is it possible at this point to edit the .json file to manually fix the problem?

        • 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 )
  6. PhilipFuchs says:

    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.

    • Brent Sorrentino says:

      Hi Philip,
      We’ve added support for this now… see Albert’s response below.

  7. I whipped up a PEX importer that allows us windows users to use the Starling Particle Editor instead of Particle Designer 2.0

    Code here:

    Cross Platform Particle Editor here:

  8. Jacques says:

    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.

  9. GregH says:

    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.

  10. Pablo Isidro says:

    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?


      • Pablo Isidro says:

        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

        • Ingemar says:

          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

          • Juarodmo says:

            Same issue with subfolders. Thanks Ingerman! Your fix solves de problem!

          • Pablo says:

            Thanks Ingeman! I’m using your function! 🙂

    • René says:

      Is this already posted as a bug? This error still exists.

  11. Gianluca says:

    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,

  12. Alex says:

    Can the emitter receive event listeners? I tried to tap and/or drag it without success.

    • Brent says:

      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.


  13. Martin says:

    What is a .app file?

    Is this MAC OS only?

    I need it for Windows 7 64bit.

  14. Daniela says:

    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?

  15. Joe says:

    Particle Designer is for MAC! Thank God I made the choice to buy a mac instead of a PC, lol…

  16. Kaleo PUaa says:

    Can you change any of the parameters of the json file in the game?

    Example: if level == 1 then json file speed = 500 elseif level = 2 then json file speed = 1000

  17. Simon says:

    Hey Brent,

    I have been looking for some info regarding the clean up of the individual emitter objects/textures that are created. I am currently assuming that the clean up of these is encapsulated within the emitter object once finished with. I haen’t been able to find any documentation that details this thus far.

    Is this correct?



  18. long says:

    Hey Brent,
    I want to using particle effect to making effect when tap on screen. Then, will remove this effect when particle is finished (end).
    But, I haven’t been able to find any documentation about event listener of particle when its finished.
    Please help me some guide for this problem. thanks

    • Brent Sorrentino says:

      Currently, there is no event listener for when a particle lifespan “completes”.

      I assume that you have a specific time for the effect defined by “particleLifespan”? If so, I suggest that, after the effect starts, you begin a timer of that amount or longer, then when it completes, remove the emitter.