Today’s tutorial introduces the Corona physics contact, a feature that was recently implemented within the physics engine. Generally speaking, a physics contact is a “reference to a specific collision that is about to occur.”

Developers familiar with the physics pre-collision might ask “how does a physics contact differ?”. While the physics contact will, in almost every case, be used during a pre-collision event, there are some important differences to note.

Pre-collision Event

In a typical pre-collision (or any collision) between two objects, Corona allows you to access each object by Lua ID. With those references, you might decide to perform an action on one (or both) objects. For example, you might change one object to a sensor, allowing it to pass through the other object when the collision occurs. Or you might choose to destroy one of the objects, animate it, apply a specific force upon it, or any number of other actions. This has all been possible in Corona for a long time, but there are a few limitations that the physics contact can solve.

One-Sided Platforms

A common requirement in 2D side-view games is the “one-sided platform” such as those in Super Mario Brothers and a thousand other 2D platform games. The character can jump from beneath a platform, pass through the platform, and land nicely atop it. Previously, this was “solved” in Corona by changing the character into a sensor at the beginning of a jump, such that it passes through the platform. Then, upon “exit” from the platform, the character is reverted back to a normal object.

While this is an acceptable solution in most cases, it presents at least one obvious problem. What if an enemy “goomba” is walking atop the platform? The character will still be a sensor when it collides with the enemy’s feet and will pass directly through! Similarly, what if the character collides with some other non-platform object during its upward trajectory toward the platform? Post-collision forces such as “bounce” would be lost.

Introducing the Physics Contact

The solution to the above dilemma can be solved with Corona’s new physics contact. As stated above, you can consider this as a specific reference to a collision that is about to occur. When used within a pre-collision event listener (typical usage), you can access the physics contact and four properties that weren’t previously accessible.

Let’s consider the one-sided platform example again. When the character jumps and collides with the platform from below, Corona understands that a collision is about to occur between the character’s head and the bottom of the platform. Using a physics contact, you can gain temporary access to this upcoming collision and tell Corona how you’d like to handle it. You can even tell Corona to ignore it completely!

Here’s how to access the physics contact in code, using a pre-collision event listener:

function character:preCollision( event )

   print( )  --"" is the physics contact "userdata"
   --the following properties of the collision can be accessed; the last three are settable!
   print( )  --read-only: are the two objects touching?
   print( ) --'true' or 'false'; will the collision resolve?
   print( )  --get/set the bounce factor of the collision
   print( )  --get/set the friction factor of the collision

character:addEventListener( "preCollision" )

Notice that the physics contact provides you with collision-specific properties that you cannot access in a traditional listener events. Using basic conditional logic, you can then opt to ignore a collision entirely, or change the bounce/friction factor(s) for that specific collision, overriding the inherent bounce/friction that you declared for the object(s).

For a one-sided platform, the physics contact method is much better. You initially set a property of the platform as “pass through” (or any other term), and then, using conditional logic, you tell Corona to ignore the collision entirely if the the platform is a “passthru” type, as in this example:

local platform = display.newImage( "platform.png" )
platform.collType = "passthru"
physics.addBody( platform, "static", { bounce=0.0, friction=0.3 } )

function character:preCollision( event )

   local collideObject = event.other
   if ( collideObject.collType == "passthru" ) then = false  --disable this specific collision!

It’s important to note that the physics contact is not a reference to either object involved in the collision, but rather a reference to the collision itself. With that reference, you can opt to override the collision entirely — or just tweak a few optional properties of it — before it actually occurs. Setting the physics contact properties does not permanently set those properties on either object involved — Corona only uses the properties for that specific collision, then it discards them. For example, if you change the “bounce” factor of the physics contact, it will not set/reset the core bounce factor on either object involved.

In Corona, the physics contact (and its properties) can be accessed from any type of collision listener: pre-, post-, or standard. In most cases, you will access it from a pre-collision, because logically you need to access or set a property of a collision before it occurs, not when or after it occurs.

Other Possibilities

While the one-sided platform case is fairly common, there are other potential applications of the physics contact. For example, in a “pinball” game, you could use conditional logic (and physics contacts) to achieve the following:

  • Silver balls collide with red bumper for extreme bounce (set physics contact bounce to 1)
  • Silver balls collide with blue bumper for no bounce (set physics contact bounce to 0)
  • Gold balls collide with red bumper for no bounce (opposite of the first case)
  • Gold balls collide with blue bumper for medium bounce

See it in Action

Check out this demo project to see the “one-sided platform” method in action, using physics contacts.

In Summary…

The new physics contact provides four new properties that can be accessed on a specific collision basis:

  • — read only: are the two objects touching?
  • — read/write: ‘true’ or ‘false'; should the collision resolve?
  • — read/write: get or set the bounce factor of the collision
  • — read/write: get or set the friction factor of the collision

In special circumstances, these properties allow a level of fine-tuned control that was not previously possible using basic collision events and collision filters. Give them a try in your next physics-based project and, as usual, please open up the conversation below with your questions, comments, and observations.

  1. This is great news and will make our testing much easier.

    But how do you use this with a spawn + table function?

    balls = { }
    function spawnBall ()
    local ball etc
    –add to balls table etc

    ball:addEventListener( “preCollision” ) — throws the expected assertion error


    function ball:preCollision( event )

    • Brent Sorrentino says:

      You can achieve this by using “local” pre-collisions. Replace the global function “char:preCollision” in the demo project with this local function (internal contents remain the same):

      local function preCollision( self, event )


      And then add a local collision listener to each ball in your scenario:

      ball.preCollision = preCollision
      ball:addEventListener( “preCollision”, ball )

      That should work. And thanks for bringing this topic to my attention; certainly its a useful method if there are many objects following this preCollision behavior.

      • Thanks for the reply. Don’t why I thought it required something other than the usual approach.

        Anyhow, this:

        function onLocalPreCollision( self, event ) — can’t use local on this function

        print( “enabled ” .. )

        Throws this error
        Build: 2012.971
        Runtime error
        d:\coronasdk\game\main.lua:616: attempt to concatenate field ‘isEnabled’ (a boolean value)

        Also, imho, adding the four new properties to ‘self’ would easily be as useful as your adding them to ‘event’

        • Brent Sorrentino says:

          Your error is a concatenation error, not an error with the For some reason (I have never determined why), Lua occasionally gripes when you try to concatenate two items. Instead of concatenating them, just type it like:

          print( “enabled”, )

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>