UPDATE: Hector Sanchez shares a nice video on how to integrate Particle Candy with Kwik. You can download his sample code here.

From time to time I receive a request about how to integrate Particle Candy (a really nice particle system from X-Pressive) with Kwik. Although there is no native integration at this point, the ability to add external code in Kwik facilitates the process.

In this tutorial I will show how to use the external code integration, using an example from X-Pressive’s website. It assumes that you have purchased and installed Particle Candy library and that you know how to create the code for your emitters. I cannot cover all the many configuration possibilities that Particle Candy offers in this tutorial (there is no space, neither I am a power user of the tool) so, I strongly suggest you to bring your questions about the tool directly in their website.

This tutorial is very simple from a Kwik’s perspective. The reason I categorize it as Intermediate is due the fact you must be an expert in Particle Candy to get all the benefits of the tool.

This is what we are going to see when the tutorial is finished:

Setting up your project

For this tutorial, you will need Kwik 2.2 or above. You can download the PSD file here.

Download and unzip the Photoshop file provided above. Then, open Photoshop and the page1.psd file. With the psd file opened, create a new Kwik project:

Enter the project name, set the device to iPad and the orientation to landscape. Also, accept the current psd file as the first project page. You will see this:

The three layers represents:

• Layer_1 is the background;
• Cone is the visual reference for the particle emitter (an emitter is the object emitting the particle. For example, a fountain is an emitter for water drops – in this case, each drop is a particle);
• Emitter is the layer that will be used to draw the particles (each particle will be drawn using this layer as reference);

We are going to need only 3 steps to make the particles integrated:

1) Adding an External Library

Go to Project and Pages toolset. There, select the Add External Library icon, then click the + (plus) button:

In the opened window, enter Particles (this is the name we are going to refer to the library internally in our project). Using the Browser button, point to the Particle Candy library file (it is named lib_particle_candy.lua) and press Create. With this information, Kwik will copy the library to the final build folder, when you publish the project:

2) Bringing your particle code into Kwik

This is the most complex part (again, not in Kwik) and it assumes you have written all the particle references (emitter creation and particle sample creation). In this simple tutorial, let’s check each line (you will need to copy all of them into Kwik in just a few moments:

— CREATE AN EMITTER (NAME, SCREENW, SCREENH, ROTATION, ISVISIBLE, LOOP)
Particles.CreateEmitter(“E1”, emitter.x, emitter.y, 0, false, true) –this creates an emitter called “E1”, setting its original position to the same position of layer “emitter” (x and y), 0 sets the direction/angle of the emission, false makes the emitter sign invisible and true sets a forever loop for the emission)

menuGroup:insert(Particles.GetEmitter(“E1”)) –here, we add the emitter inside the current page group (this way, when we change pages, it will be removed with the other objects in the page

Kwik 3 users: instead of menuGroup, you must use sceneGroup in the line above.

— DEFINE A SIMPLE PARTICLE TYPE –lot’s of parameters for a particle, right? the important line here is the imagePath one, where we set the path for the image being used in the emitter (in this case, it points to p1_emitter.png, which contains the green rectangle from layer emitter)
Particles.CreateParticleType (“Test1″,
{
imagePath = imgDir..”p1_emitter.png”,
imageWidth = 32,
imageHeight = 32,
velocityStart = 150,
autoOrientation = true,
killOutsideScreen = true,
lifeTime = 3000,

alphaStart = 0,
fadeInSpeed = 0.5,
fadeOutSpeed = -0.75,
fadeOutDelay = 1500,
} )

— FEED EMITTERS (EMITTER NAME, PARTICLE TYPE NAME, EMISSION RATE, DURATION, DELAY)
Particles.AttachParticleType(“E1”, “Test1”, 5, 99999,0)

— TRIGGER THE EMITTERS
Particles.StartEmitter(“E1”)
— UPDATE PARTICLES FREQUENTLY
Particles.StartAutoUpdate()

Copy the code above. Still in the Project and Pages toolset. There, select the Add External Code icon:

Then, give a name to your code, paste it in the main area and set it to be rendered in the Middle of your final code (meaning it will be added just after the creating of the layer elements), and click Create:

3) Removing the particle when needed

When you decide to change pages (not in this case as our project has only one page) it is important to end the particle emission. To do so, repeat step 2, replacing the code with the one below:

4) Publish your project

Last step is to publish your project (make sure you are exporting the images) and check it in the Simulator. If you followed the instructions above, you will see the same results of the video in the beginning of this post with only one difference: you will see the original emitter layer green rectangle in front of the blue cone. To fix that, go back to Photoshop and move the emitter layer behind the cone layer. Re-publish.

Enjoy!