Tutorial: Corona Particle Tools and Data Formats

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

Today’s guest tutorial comes to you courtesy of Corona Ambassador and Portland, Oregon app developer Ed Maurina. Ed is a regular contributor to the weekly Corona Geek hangouts and an active member of the Corona Community. He has developed games for REEL FX Studios, maintains his Corona SSK game development library, and recently created a particle editor that runs in the Corona Simulator. In this tutorial, he introduces us to the various aspects of particle editors. Check out his work and blog at RoamingGamer.com.

As of Daily Build #2214, Corona SDK supports a Particle Emitter display object via display.newEmitter(). Now, implementing particle effects in your game is as simple as writing a few lines of code (tutorial). However, the question still exists: “How do I create and edit emitters?” In this article (part of a series), we’ll briefly examine Emitter Authoring Tools, the Starling Format, and Emitter Loaders.

Emitter Authoring Tools

An emitter authoring tool is a tool that allows you to create, edit, export, and import particle emitter data. When the new emitter feature was first announced, there was some confusion and consternation in the community with regards to emitter authoring tools.

As of today, there are three primary emitter authoring tools available to Corona developers.1

Particle Designer 2.0 (71 Squared)

Particle Designer 2.0 (PD2) is a paid tool for OS X that can be used to author Corona-compatible emitter definition files. This editor produces an emitter definition file containing a JSON-encoded table and a particle image file. This definition file can be loaded and decoded using standard Lua libraries.

Particle Editor for Corona SDK (Roaming Gamer, LLC.)

Particle Editor for Corona SDK (PECS) is a paid tool that runs in the Corona Simulator. It can also be built as an app for Android and iOS devices, enabling on-the-go particle authoring. Like PD2, it produces two files, a JSON-encoded emitter definition and a particle image.

Particle Editor (One By One Design)

Particle Editor (PE) is a free browser-based tool that allows you to author an emitter and subsequently export it to XML. This tool, while free, is the odd man out as it requires a little extra work to make full use of the definition data.

Because the “right” tool is the one that best suits you and your needs, you should take some time to examine each. To assist in that effort, the following table summarizes the basic differences between these three tools:

Particle Designer 2.0 Particle Editor for Corona SDK Particle Editor
Operating System OS X OS X, Windows, Android, iOS (runs in browser)
License Cost2 $75 new / $50 upgrade $30 new free
Alternative Licensing* Yes Yes
Export Format(s) JSON-Encoded Table JSON-Encoded Table XML-Encoded Table
Import Format(s) JSON-Encoded Table
XML-Encoded Table
JSON-Encoded Table
XML-Encoded Table
XML-Encoded Table
Special Features —You can edit and preview multiple emitters simultaneously.
—The tool provides access to a large library of community-developed emitters.
—Because the tool runs in Corona, it’s guaranteed to produce the same visual results in your app.
—You get source code access and can modify the tool to suit your needs.
Warning — Although this tool provides a preview, on occasion the results do not match what is displayed by Corona.

* Multi-Seat, Re-Assignable, etc.

Emitter Definition Files: The Starling Format

The emitter definition format used by Corona SDK and each of the authoring tools is commonly referred to as the Starling Format. Depending upon the tool you use to author your emitters, you will have to follow different steps to make the emitter data usable.

Currently there are two variants of the Starling format in use:

Authoring Tool File Extension File Contents
Particle Designer 2.0 .json JSON-encoded Lua table
Starling Format 1
Particle Editor for Corona SDK .rg JSON-encoded Lua table
Starling Format 1
Particle Editor .pex XML-encoded Lua table
Starling Format 2

Using Starling Format 1 (PD2, PECS)

Corona SDK accepts format 1 by default. Additionally, both PD2 and PECS produce emitter files whose content is a JSON-encoded table. So, to create an emitter using the output of these tools, you can simply follow these steps:

  1. Load file as a string
  2. JSON-decode to Lua table
  3. Create emitter

Using Starling Format 2 (PE)

If you choose to use PE, you will have to perform the additional step of pre-processing the emitter table to match the naming convention expected by Corona SDK:

  1. Load file as a string
  2. JSON-decode to Lua table
  3. Process to change names
  4. Create emitter

Emitter Loaders

It has been several weeks since the emitter display object was introduced, and in that time, the Corona Labs staff and community members have illustrated various methods for the loading/usage of emitter definition files. The following table lists solutions for each of the previously mentioned tools:

Authoring Tool Ready-to-Use Loaders
Particle Designer 2.0 1. Corona Labs’ Loader Module
2. Roaming Gamer Universal Emitter Loader
Particle Editor for Corona SDK 1. Corona Labs’ Loader Module
2. Roaming Gamer Universal Emitter Loader
Particle Editor 1. Roaming Gamer Universal Emitter Loader
2. PEX4Corona Importer

Corona’s Loader In Action

Universal Emitter Loader In Action

PEX4Corona Loader In Action

Next Time…

teaserIn the next part of this series, Designing Particle Emitters, we will learn how to create specific emitter types and particle effects for common uses, including:

  • Fires
  • Waterfalls
  • Explosions


1 More than three particle emitter authoring tools are available. The tools discussed in this article were selected because they each produce emitter definitions that are 100% compatible with Corona SDK, although some processing may be required.

2 Prices as of April 14, 2014.

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 10 replies

  1. George says:

    Great tutorial! It will be so great if you continue to publish next parts about particles!

  2. Ed Maurina says:

    @All Readers,

    There is a code sample to go with this article which I failed to post earlier! My bad.

    Here is a link: https://github.com/roaminggamer/RG_FreeStuff/raw/master/ParticleEmitters/001_EmitterToolOptions.zip

    • Alex says:


      I am Alex Souza, founder of Kwiksher (www.kwiksher.com), creators of Kwik, a plugin that creates full apps for Corona SDK directly from Photoshop. I was wondering if you want to work together in a cross-promo for Kwik users. Let me know your thoughts.

      Thanks a lot,

      alex at kwiksher dot com

  3. jolzy says:

    I am not sure but i thought the particle candy also compatible with corona is ?

    • Brent Sorrentino says:

      Hi @jolzy,
      Yes, Particle Candy is fully compatible with Corona SDK and has many useful and powerful features, but its system is proprietary and does not use the display.newEmitter() API. The tools discussed in this tutorial are common to that API, so they are slightly different than Particle Candy. However, all tools meet the goals of beautiful particle effects in Corona.

  4. Hi,
    The roaming gamer’s particle editor doesn’t really work especially the save and send functionality 🙁
    I’m still trying to contact the developer to see if there’s a fix coming but after what happened with Particle Candy in which they just left to oblivion without replying any mails, I’m not sure I’ll get much out of this.

    Please Corona, don’t endorse a product (especially if it’s paid product) to your community if you’re not sure it’s good/stable.

    • Dean says:

      Hi @Januar,
      I got stuck on this as well but finally cracked it.

      If you run the Particle Editor in the simulator and then press send it doesn’t actually seem to do anything but if you then go to File > Show Project Sandbox under the Temp folder you will see the two emitter files you need.

      One other tip is that it isnt easy to rename them as the json file (.rg) contains a reference to the image file. Also easiest to keep the emitter files in the root folder rather than a subfolder I found.

      Hope this helps.