Introducing the Collision Filters plugin

07 June 2017

Introducing the Collision Filters plugin

For game designers who utilize Corona’s built-in Box2D physics system, collision filters usually enter the design equation at some point in development. For instance, if your player in an endless runner game should collect power-ups, you’ll need a collision handler for it — but it’s a waste of time (and processing effort) to handle collisions between enemies and power-ups.

Traditionally, setting up collision filters has been a tricky ordeal of calculating categoryBits and maskBits, as outlined in our Collision Detection guide. While our “helper chart” makes the process much easier, many game developers wish there was an easier way — and now there is!

Collision Filters plugin

Using the new Collision Filters plugin, you can skip all of the math and calculations involved in traditional collision filter setup. Instead, simply state your setup with clearly-named keys and strings. For instance:

collisionFilters.setupFilters( { player={ "powerUps", "enemies" } } )

With just this one simple command, the plugin will configure three collision filters:

1. player objects will collide with powerUps and enemies
2. powerUps objects will only collide with player
3. enemies objects will only collide with player

Once set up, getting the proper collision filter data is as simple as calling collisionFilters.getFilter() with a valid key or string from the configuration table:

local playerFilter = collisionFilters.getFilter( "player" )

Then, applying it to the player’s physics body, assuming thisPlayer represents the player object, is as easy as this:

physics.addBody( thisPlayer, "dynamic", { filter=playerFilter } )

Smart associations

For those who have set up collision filters the traditional way, you’ll know that doing so requires a “reverse association” methodology. For instance, if you tell Box2D that player can collide with enemies, you must also tell it that enemies can collide with player. Now, using the Collision Filters plugin, that extra step is unnecessary — simply set up your primary associations and the plugin will internally calculate the reverse relationships! What’s more, it will dispatch a console warning if you accidentally declare associations which don’t match.

Getting started

To get started, proceed to the plugin documentation. Simply add the plugin to your build.settings file, require() it in the module(s) where you’ll use it, set up your filter relationship with collisionFilters.setupFilters(), and add the appropriate filters to your physics bodies via collisionFilters.getFilter().

Hopefully this new plugin will simplify collision filter setup for all Corona game developers!