STEP 1: INCLUDE THE LIBRARY
With Corona SDK:
Place the library's .lua file in the directory of your project and include it with the following command (just place the name of the library within the quotes, without the ".lua" extension) :

local Particles = require("lib_particle_candy")


With Gideros SDK:
In Gideros Manager, right-click your project's name and choose 'Add existing file'. Browse for the 'lib_particle_candy.lua' file and add it to your project. Once included, all Particle Candy functions are available using the global variable 'Particles' (or '_G.Particles') then from anywhere in your code.

You are then ready to go. Access all the library's features like this:

Particles.CreateEmitter(...)

STEP 2: CREATE AN EMITTER
Now create some emitters. Emitters can be created and deleted at any time, but it's a good practice to create them right before your level starts, re-use them during the game and delete them on level clean-up:

Particles.CreateEmitter("name", x,y, rotation, visible, loop, autoDestroy)

You can also receive a handle to the created emitter. This handle can then be used to freely position, rotate or move the emitter. An emitter's handle can be used like any common graphics object. Therefore, you can also place an emitter within a certain group. Principally, all particles of an emitter will be drawn inside the emitter's parent. So if you put the emitter into a display group, it's particles will be drawn inside this group only. This is quite useful!

Important note!
If you store an emitter's handle, you must set this reference to the emitter to "nil" before you delete the emitter. Otherwise, it cannot be garbage collected and will remain in memory! So be careful when storing emitter handles on your own!

local MyEmitter = Particles.GetEmitter("name")

-- CORONA SDK:
MyEmitter.x		= 50
MyEmitter.y		= 150
MyEmitter.rotation 	= 180
MyEmitter.alpha		= 0.5

-- GIDEROS SDK:
MyEmitter:setX(50)
MyEmitter:setY(150)
MyEmitter:setRotation(180)
MyEmitter:setAlpha(0.5)

STEP 3: DESIGN A PARTICLE TYPE
A particle type describes how particles behave, so a particle type contains all relevant properties of a certain kind of particle. You can create as many different particle types and attach as many of them to an emitter as you like. For a fire effect, for example, you would create one particle type for the smoke, another one for the flames and maybe a third one to show some sparks flying around. Attach them to an emitter then and you are ready to go.

Here is a very basic one (see section "Reference" for all available particle properties):

-- DEFINE PARTICLE TYPE PROPERTIES
local Properties 		= {}
Properties.imagePath		= "arrow.png"
Properties.imageWidth		= 32
Properties.imageHeight		= 32
Properties.velocityStart	= 150
Properties.autoOrientation	= true
Properties.killOutsideScreen	= true
Properties.lifeTime		= 3000
Properties.alphaStart		= 0
Properties.fadeInSpeed		= 0.5
Properties.fadeOutSpeed		= -0.75
Properties.fadeOutDelay		= 1500

-- CREATE THE ACTUAL PARTICLE TYPE
Particles.CreateParticleType ("MyParticleType1", Properties)

-- WE DON'T NEED THIS ANYMORE
Properties = nil

STEP 4: FEED THE EMITTER
Now feed the emitters with the particle types you just created. You can attach as many particle types to an emitter as you like and define an emission rate, emission duration and a delay for each attached particle type (repeat this with each particle type you'd like to attach to the emitter):

Particles.AttachParticleType("emitter", "particleName", emissionRate, duration, delay)

STEP 5: TRIGGER THE EMITTER
Now your emitters are charged and can be triggered (or stopped) at any time within the game. The particles will be drawn in the emitter's parent group (if there is one) and will be shot in the direction where the emitter points (remember, you can freely move and rotate the emitter -you can also attach it to the exhaust of your space ship, for example):

Important note!
In order to update and animate your particles, don't forget to call the library's Update() function once every frame (within your main loop).

-- THIS FUNCTION CALLED PERIODICALLY
function mainLoop()
	-- TO UPDATE / ANIMATE PARTICLES:
	Particles.Update()

	-- YOUR onEnterFrame CODE HERE:
	-- ...
end

STEP 6: CLEAN UP
After your main game loop finished, simply remove all created emitters, particle types and particles on screen by using:

Particles.CleanUp()

Important note!
If you stored any emitter handles using GetEmitter(), you must set these references to the emitters to "nil" before you delete the emitters. Otherwise, they cannot be garbage collected and will remain in memory! So be careful when storing emitter handles on your own!


X-PRESSIVE.COM  •  PARTICLE CANDY FEATURES  •  QUICKSTART  •  API REFERENCE  •  HINTS & TRICKS  •  VIDEOS  •  ORDER  •  SUPPORT