collisionFilters.setupFilters()

Type Function
Return value none
Revision Release 2024.3703
Keywords physics, collision, filter, setupFilters
See also collisionFilters.getFilter()
collisionFilters.viewAllFilters()

Overview

Creates a collision filter association using convenient human-readable strings to indicate which categories of objects may collide with other categories of objects.

This function returns nothing; it merely sets up the filters and alerts to any errors in configuration.

Syntax

collisionFilters.setupFilters( filterTable )
filterTable (required)

Table. A table of key-value pairs which define collision filters, following this methodology:

  • Each key in the table must be unique and it should represent a general category for the object(s) which will use it. For example, player, enemies, or powerUps.

  • The key's value can be either a single string or an array of strings. In either case, the specified string(s) should match other general categories which the key category will be masked against.

Example

local collisionFilters = require( "plugin.collisionFilters" )

-- Set up collision filter relationship
-- This example creates 4 collision categories ("player", "enemies", "powerUps", "playerBullets")
collisionFilters.setupFilters(
{
    player = { "enemies", "powerUps" },  -- Objects with "player" filter will collide with "enemies" + "powerUps"
    enemies = "playerBullets",           -- Objects with "enemies" filter will collide with "playerBullets"
})

Note that, even though only two key-value pairs are defined in this example, the collision filters plugin effectively creates four collision categories. This is because the plugin automatically works through the keys and the associated values (strings), intuitively associating filter relationships without expecting you to specify the "reverse associations" required in manual filter setup.