Type Library
Revision Release 2024.3703
Keywords physics, collision, filter
Platforms Android, iOS, macOS, Windows, tvOS
See also Collision Detection (guide)
Physics Bodies (guide)


This plugin is designed to circumvent the math and complication of creating physics body collision filters using categoryBits and maskBits as documented here. It works by letting you assign user-friendly names to "categories" of objects in your physics simulation, without worrying about internal binary values and sums which are liable to change as you adjust game behavior.


This plugin enforces the standard compliance with Box2D to ensure correct functionality, including:

  • A maximum of 16 distinct collision categories may be used (note that even complex games don't often require more than 10).

  • When necessary, new filters and unpaired masks are added to ensure compliance with Box2D category+mask relationships. Console alerts are generated when this occurs.


local collisionFilters = require( "plugin.collisionFilters" )

Project Settings

To use this plugin, add an entry into the plugins table of build.settings. When added, the build server will integrate the plugin during the build phase.

settings =
    plugins =
        ["plugin.collisionFilters"] =
            publisherId = "com.coronalabs"