Tutorial: Particle collisions in LiquidFun

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

This tutorial is a brief discussion of how to handle collisions between LiquidFun particles and Box2D rigid bodies. Handling these collisions is essential to implementing a more comprehensive and responsive scenario using LiquidFun physics.

If you missed the previous Introduction to LiquidFun tutorial, please read it carefully so that you fully understand LiquidFun and the basis of the system.

Basic Setup

For this tutorial, we’ll need to create, at the minimum, a particleSystem and another object with which the particles can collide:

This is fairly basic code. First, we create a static platform for the particles to collide with and rotate it to 10 degrees so we can watch the liquid particles flow off it. Then we create the particleSystem and assign it a .myName parameter which will help us identify the system when detecting collisions.

Next we create the particleParams table with some basic properties. This doesn’t vary too much from the examples in the previous tutorial except for the inclusion of one very important flag: "fixtureContactListener". If you don’t include this flag, you will not receive collision responses.

Finally we queue a timer to generate 5 particles at an increment of 20 milliseconds.

Particle System Collision Handling

Now let’s set up a function to listen for collision events on the actual particleSystem. This is similar to the method of local collision handling between traditional physical objects described here — in this case, we just need to set up the function, set its name as the .particleCollision property of the particleSystem, and then add an event listener of the "particleCollision" type to the system:

This provides you with a very basic collision framework, but in most cases you’ll need more information to properly react to particle collisions. Fortunately, Corona provides a considerable amount of information as properties of the event table of the listener function. These include:

  • event.phase — One of the typical collision phases of "began" or "ended".
  • event.object — Reference to the object that the particle collided with.
  • event.element — The fixture index of the other object, relevant for multi-element bodies.
  • event.particleSystem — Reference to the parent ParticleSystem of the colliding particle.
  • event.x — The x position (screen content coordinates) of the particle that’s involved in the collision.
  • event.y — The y position (screen content coordinates) of the particle that’s involved in the collision.
  • event.normalX — The collision normal’s x direction.
  • event.normalY — The collision normal’s y direction.
  • event.r — The red color value of the particle.
  • event.g — The green color value of the particle.
  • event.b — The blue color value of the particle.
  • event.a — The alpha color value of the particle.

For future reference, a list of these properties are documented here, so please bookmark the link if you intend to utilize LiquidFun in depth.

Object Collision Handling

Alternatively, you can detect collisions on other objects instead of directly on the particle system. This may be more logical if you’re designing an app with multiple particle systems and you prefer to detect collisions with one core object like a player character.

In our existing example, we can achieve this by adding a collision listener to the platform object instead of the particle system. Inspect the difference:

Conveniently, this model also provides the same event table properties listed above, so you can gather info about the specific particle involved in the collision, including the particle system which generated it.

Global Collision Handling

Yet another option to handle collisions is a global Runtime listener. This will detect collisions between particles and other physical objects at the global level.

Further reading

Sample code

In Summary

Hopefully this tutorial has illustrated how simple it is to detect collisions between LiquidFun particles and other physical objects. This feature should help take your liquidFun-based apps to the next level of interactivity.

Share on Facebook0Share on Google+0Tweet 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 9 replies

  1. Andreas says:

    You promised it, you delivered – thanks a lot, it’s very useful!


  2. KM says:

    How about preCollision?

    • Albert Yale says:

      LiquidFun doesn’t report collisions in the Pre/Post collision style. Just Began/Ended.

  3. 17Studio says:

    Very necessary to be able put the Liquidfun particle system inside a transformed displaygroup parent. Currently with Liquidfun not do anything.

    • Andreas says:


      since 2359 the LiquidFun particles are now fully integrated into the display groups, I already experimented with this and I love it!


  4. Daniela says:

    Thank you for this great tutorial!

    Is it possible to add another one showing how the color mixing and smooth effects like in the video from the top can be made…? (Video: http://coronalabs.com/blog/2014/05/27/tutorial-introduction-to-liquidfun/)

    Thank you!


    • hgbrian says:

      Hi Daniela,
      look in SampleCode/Physics/LiquidFun/ColorFaucet and you’ll find how to do it. It’s not so hard — you just add the colorMixing flag to your particles.

      • Daniela says:

        Thank you very much! I totally missed this!

  5. nick says:

    I had a project from oh 2011, it’s back on thanks to this. Woot.