If you have already taken a look at the Box2DCollisionFiltering.java file, you will have noticed the two quiet dinosaurs that get really angry whenever any of the friendly cavemen get closer to them. The characters that belong to the same faction will not collide.

The code of this example comes with two inner classes defined with the purpose of making things clearer. Each of them will represent a faction: cavemen and dinosaurs. As their content is mostly not new for us, we will not put them in the spotlight but please feel free to take a look at the source code.

Sensors

Each dinosaur will have a nonvisible sphere around him to detect whether a caveman is within its vicinity, as shown in the following screenshot:

That is what we will call a sensor, and its usage is really simple:

1. Create a second fixture for each enemy body and enable the sensor flag:

   CircleShape circle = new CircleShape();
   circle.setRadius(1f);
   
   FixtureDef sensorFD = new FixtureDef();
   sensorFD.isSensor = true;
   sensorFD.shape = circle;
   enemyBody.createFixture(sensorFD);

2. Implement the ContactListener interface and within the beginContact(…) function, check whether the sensor is overlapped by another fixture:

   if (fixtureA.isSensor()) {
     Enemy e = (Enemy) bodyA.getUserData();
     e.setAngry(true);
   }

   A reference to the object itself is attached into the UserData field of the body within the Enemy constructor so that it can be retrieved later. In addition, the SetAngry function will just change the tint of the dinosaur to red when the received argument is true.

   The brightest readers will have realized that we are only checking whether one of the fixtures involved in the contact is a sensor and it is an insufficient condition to determine that a caveman has gone into a dinosaur's territory. However, that simple condition becomes valid because of collision filtering, which directly omits the undesired fixtures.

All these bits calculation might seem complex but in the next paragraphs, you will find a brief explanation to make it clear.

The way that Box2D determines whether to filter a certain collision or not, is performed with the following code snippet:

const b2Filter& filterA = fixtureA->GetFilterData();
const b2Filter& filterB = fixtureB->GetFilterData();

if (filterA.groupIndex == filterB.groupIndex && filterA.groupIndex != 0)
{
  return filterA.groupIndex > 0;
}

bool collide = (filterA.maskBits & filterB.categoryBits) != 0 && (filterA.categoryBits & filterB.maskBits) != 0;

For group filtering, Box2D makes use of signed integers.

On one hand, two fixtures will collide if they share the same positive groupIndex. On the other hand, they will not collide if they belong to the same groupIndex and it is negative. For the rest of the cases, colliding delegates to category/mask filtering.

Masks and categories are set through bit fields. The previous code checks that after applying an AND operation to the mask bits of a fixture and the category bits of another, it does not result in 0. An example might shed some light on this:

final short CATEGORY_PLAYER = 0x0001;
final short CATEGORY_ALLY = 0x0002;
final short MASK_PLAYER = ~CATEGORY_ALLY;

The explanation of why a player cannot collide with an ally is because doing an AND operation between CATEGORY_ALLY(00000010) and MASK_PLAYER(11111101) results in 0 (00000000).

Bit fields are stored as short values, which in Java takes 16 bits, ranging from -32768 up to 32767. The next table shows the correspondence between decimal and hexadecimal values:

As you will have seen, the decimal column is not ordered, which can lead to errors when setting a bit field to a specific value. This is one reason to find hexadecimal notation more frequently within this context.

In addition, values must be powers of two under this scope.

Groups, categories, and masks can live together, being aware of the higher precedence of groups. However, my advice here is to keep it as simple as possible.

In addition, you can explicitly find a set of cases in the Box2D manual where they internally make use of collision filtering: