TUTORIALS, HINTS & TRICKS
Here you find articles that cover frequently asked questions, as well as short tutorials, hints and tricks.

WHAT IS PARTICLE CANDY?
In his well-written and detailed Particle Candy review, Jayant from oz-apps.com gives a great and understandable introduction to Particle Candy and the concept of particles in general. This article is a great starting point if you're new to Particle Candy or never used particles in your games so far.

PERFORMANCE HINTS
How fast is Particle Candy? It's not easy to answer this question, because this heavily depends on the type of effect, how many particles you are using, how many processing power the rest of your game needs etc. What we know for sure, however, is that we did our best to make Particle Candy as fast as a Corona or Gideros extension can be. We optimized all time-critical parts of the code and performance is still our primary goal. The final speed, however, primarily depends on Corona®'s / Gideros® mass handling of display objects and how wisely you are using Particle Candy within your project.

Here are some hints that may help you to obtain the best possible performance while using Particle Candy:

  • Keep particle count as low as possible
    For most effects, it is not neccessary to use dozens of particles. 99% of all effects can be done with a low count of particles on screen. It greatly depends on the particle graphics you use. If you would like to simulate snow, for example, it's a good solution to use an image with many different sized, non-uniformly positioned snow flakes on it instead of producing a high amount of particles showing a single snow flake only. You should also try to fiddle with a particle type's settings to achieve the same effect with less particles (vary particle scale, fading, movement etc.) If an effect looks less "uniform" you should be able to need less particles.
  • Keep particles small
    Bigger graphics (and particles) require higher fillrates and graphics processing time. This is why you should try to keep particles as small as possible without losing the visual quality of your effect. Try to experiment with less particles / bigger particle size. In some situations it might perform better when using less particles but with a bigger size, in other situations it might be better to use more but small sized particles.
  • Keep particle lifetime as short as possible
    This one is obvious: as less particles there are on screen at once, as better. So you should try to keep the lifetime of each particle as short as possible -especially, when killOutsideScreen is set to false. To increase performance, Particle Candy automatically removes particles as soon as they reached either complete transparency (alpha value of zero) or have been scaled below a value of 0.001, for example.
  • Transparency
    When using fading or transparency, the CPU / GPU needs to blend all pixels with the background pixels. This always costs performance. Unfortunately, transparency is a vital feature for most effects, but you should try to minimize the use of transparency, if possible.
  • Disable debugging
    By default, Particle Candy provides detailed debugging messages to let you know what's going on backstage. Once your project reaches a final stage, you should disbale debugging messages to gain performance. You can do this by editing the variable "debug = true" to "false" on top of the library file. There are also some other vars you may want to tweak like the strength of global gravity or the colors of emitters and force fields.
  • Preload your particle images
    You may sometimes experience slow downs or short freezes when starting an emitter. This happens when the images used with the attached particle types have been garbage collected since the last run of the emitter and therefore don't reside in memory anymore. You can prevend this by preloading the images used with your particle types. Simply load the images using display.newImageRect (use the same size as you do in your particle type settings). Just load these images to the stage, make them invisible and don't care about them. Leave them invisible on stage until you clean up your emitters or particle types. As long as there are invisible copies of your particle images on stage, you won't experience any hick-ups when starting emitters.

USING KWIK
If you are a Kwik user and would like to use both tools together, check out this easy-to-follow tutorial written by Alex from Kwiksher.com.

USING DIRECTOR CLASS
Particle Candy emitters can be used like common graphics objects, so Particle Candy can generally be combined with tools like the Director class, for example.

Particles always use the same parent as their emitter does. So if you place an emitter within a group called "MyGroup", its particles will be placed within that group.

Keep in mind that every emitter is connected with associated data. Therefore, emitters should not be removed from the display using :removeSelf(). Always use Particle Candy's clean-up commands to do so properly. So if you're using the Director class (or similar tools) and want to change or unload a scene, you should clear all particles from screen and remove all emitters before switching or unloading the scene.

You can use Particle Candy's CleanUp( ) command to conveniently get rid of all particles, emitters and particle types or just ClearParticles( ) and DeleteEmitter( ) if you want to keep any created particle types for later use.

Note the included sample code ("Sample_Director_Class") that demonstrates how to use Particle Candy together with Director Class (or download it here).

PARTICLE DRAWING ORDER
You have several images on screen and want to draw your particles in front of object A, but behind object B? No problem. Particle Candy always uses the emitter's parent to draw particles to. So just put your emitter into a group (or called sprite with Gideros) and all particles that it emits will be drawn to this group then. You can even put an emitter from one group to another while it emits particles, the particles are then instantly drawn to the new emitter parent.

Corona® display groups or Gideros® sprites are very useful, by the way! They are very similar to the layers you already know from Photoshop or Flash.

-- CORONA:
-- CREATE A GROUP
MyGroup = display.newGroup( )
-- PUT EMITTER INTO GROUP
MyGroup:insert( Particles.GetEmitter("MyEmitter") )

-- GIDEROS:
-- CREATE A SPRITE
MyGroup = Sprite.new( )
-- PUT EMITTER INTO SPRITE
MyGroup:addChild( Particles.GetEmitter("MyEmitter") )

Another way to specify where your particles should be drawn to is the .DrawParent property of a particle type, which was introduced with Particle Candy 1.0.27 (see reference, section 'CreateParticleType()'). Use the .DrawParent property to specify a group / sprite handle where the particles should be drawn to, regardless of the current emitter parent.

GOT BUILD ERRORS?
Particle Candy uses the SDK's plain standard API only, so it should run well on all devices supported by the SDK.

If your build doesn't run on your device, it may be related to the build.settings file in the project folder. Simply edit it or replace it by another one.

As with all seperate LUA files and modules, the Particle Candy library file should be placed within your project's root folder, where your main.lua resides (don't forget to change the path in the "require" line, too) to avoid any path problems.


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