Posted on by

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

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

Universal Emitter Loader In Action

local pex = require( "rg.pex" )
pex.loadStarling( nil, 240, 300,
"emitters/Starling/campfire/particle.pex",
{ altTexture = "emitters/Starling/campfire/texture.png" } )

PEX4Corona Loader In Action

local pex = require( "ponywolf.pex" )
particleData = pex.load( "emitters/fire.pex", "emitters/fire.png" )
emitter = display.newEmitter( particleData )
emitter.x = display.contentCenterX
emitter.y = display.contentCenterY

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

Footnotes

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.


Posted by . Thanks for reading...

5 Responses to “Tutorial: Corona Particle Tools and Data Formats”

  1. George

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

    Reply
    • Alex

      Ed,

      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

      Reply
    • Brent Sorrentino

      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.

      Reply

Leave a Reply

  • (Will Not Be Published)