collisionFilters.getFilter()

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

Overview

Calling this function with just a valid filterName returns the table which should be referenced as the filter parameter of the physics.addBody() function for the object you want to associate the filter with.

Alternatively, calling this function with humanReadableFormat as true returns a table of all the corresponding mask category names, allowing the filter's contents to be clearly understood.

Syntax

collisionFilters.getFilter( filterName [, humanReadableFormat] )
filterName (required)

String. A valid filter name as previously defined with collisionFilters.setupFilters().

humanReadableFormat (optional)

Boolean. If set to true, the return value becomes a table of all the corresponding mask category names, allowing the filter's contents to be clearly understood. This table is not valid for usage in the physics.addBody() function — its purpose is primarily for examining the filter's relationships.

Examples

Physics Body Filter Usage
local collisionFilters = require( "plugin.collisionFilters" )

collisionFilters.setupFilters(
{
    player = { "enemies", "powerUps" },
    enemies = "playerBullets",
})
 
-- Create the player object
local thisPlayer = display.newImageRect( "player.png", 64, 64 )
thisPlayer.x, thisPlayer.y = 100, 100

-- Add a physics body using the player filter
local playerFilter = collisionFilters.getFilter( "player" )
physics.addBody( thisPlayer, "dynamic", { filter=playerFilter } )
Human-Readable Format Usage
local collisionFilters = require( "plugin.collisionFilters" )

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

-- Display the player filter in an understandable format
local playerFilter = collisionFilters.getFilter( "player", true )
print( "'player' is set to collide with: " .. table.concat( playerFilter, ", " ) )