Collision Masking

Collision masking is a way to make physics bodies only collide with (or never collide with) particular other bodies. This filtering is based on masking groups which are determined by rigid bodies' collision_groups property. To add a body to a particular object group just set the corresponding bit to collision_groups.

Example

Imagine you are building a game where small objects should interact with grass but the main character shouldn't. You could set up this scene in Goblin as shown below. NOTE: NEVER use 1 as a group's bit mask, see "Inclusive Filtering" below

// assume `grass`, `small_object`, and `player` are already defined RigidBody instances
var GROUP_GRASS = 2; // assign the grass group to bit value `2`

grass.collision_groups = GROUP_GRASS; // add `grass` as a member to `GROUP_GRASS` collision group
player.collision_mask = GROUP_GRASS; // indicate `player` should NOT ever collide with members of `GROUP_GRASS`

Say the game is extended further and there is another type of objects, portals, which the player shouldn't collide with. You can combine multiple groups into the mask.

var GROUP_GRASS = 2,
    GROUP_PORTALS = 4;
player.collision_mask = GROUP_GRASS | GROUP_PORTALS;

Inclusive Filtering

The above examples showed how to prevent particular groups from colliding. Sometimes you may want to ONLY allow particular groups to collide. In the first example, instead of preventing the player from colliding with grass you could configure grass to only collide with a small objects group. This is set up in the same way, but the object's collision_groups property needs to have the first bit set as well.

var INCLUSIVE_MASK = 1,
    GROUP_SMALL_OBJECTS = 2;

small_object.collision_groups = GROUP_SMALL_OBJECTS;
grass.collision_mask = INCLUSIVE_MASK | GROUP_SMALL_OBJECTS;

Maximum groups

You can have at most 30 individual object groups. This limitation stems from being unable to perform bitwise operations in JavaScript on values over 2147483647 which is 2^31 - 1 and the maximum value you can store in a 32-bit signed integer.