A fixture should belong to a single category only and will collide with every fixture in a category specified in category mask. A category has a number from 0 to 15. A fixture's category or categories are then specified by a single 16-bit number. A 16-bit number in the binary format consists of 16 zeroes and ones. We can index them from 0 to 15. If the fixture belongs to a category N, then the Nth bit will be 1. If it doesn't belong to the category, then the Nth bit will be 0.

There are 16 categories, but we will omit bits 5 to 16 and show just a simplified 4-bit example. We can imagine that there are 12 more zeroes prefixed to these numbers. Usually, the categories and masks are written as decimal numbers. The decimal number is simply the binary number with the base 10. We will see in the following example what this means:

Now, if we want a fixture to belong to category 4, we will pass 8 to the constructor as its category.

The category mask specifies with which other categories the fixture collides. It can collide with multiple categories. Specifying multiple categories using a single number can be done by adding the categories together. For example, if we want the fixture to collide with categories 1, 2, and 4, we will pass 1 + 2 + 8 = 11. It might be easier to imagine it in the binary representation, as follows:

It is important that each number is on a new line.

10112 (base 2, binary) is 1110 (base 10, decimal). When two fixtures A and B collide, a simple check is calculated using a logical conjunction (the AND operator): categoryA AND maskB must not be 0 and at the same time categoryB AND maskA must not be 0. Here are the possible results of the AND operator:

So if a fixture is defined to collide with the category mask 1101 (=13), it will collide with any fixture that belongs to category 1, 3, or 4 (1 + 4 + 8 = 13). A few examples of collisions are as follows:

The theory might be a bit difficult to grasp; let's see a real-world example in our game.

We are temporarily going to change the populate() method in GameScene to add our new objects. First, let's define some categories, as follows:

  public static final short CATEGORY_BOX_1 = 1;
  public static final short CATEGORY_BOX_2 = 2;
  public static final short CATEGORY_CIRCLE = 4;
  public static final short CATEGORY_PLATFORM = 8;

Then, we define masks, as follows:

  public static final short MASK_ALL = 
      CATEGORY_BOX_1 +
      CATEGORY_BOX_2 +
      CATEGORY_CIRCLE + 
      CATEGORY_PLATFORM;

  public static final short MASK_BOXES = 
      CATEGORY_BOX_1 +
      CATEGORY_BOX_2 +
      CATEGORY_PLATFORM;
  
  public static final short MASK_CIRCLE = 
      CATEGORY_CIRCLE +
      CATEGORY_PLATFORM;  

MASK_ALL means that the fixture collides with every other category. MASK_BOXES defines the fixture that collides with the platform and both boxes, and MASK_CIRCLE defines the fixture that collides with other circles and platforms.

Next, we temporarily stop the camera movement and remove the touch listener so that we can actually see a static scene with our new objects, as follows:

  @Override
  public void populate() { 
    createBackground();
    createPlayer();
    //camera.setChaseEntity(player);
    createHUD();
    
    addPlatform(240, 100, false);
    addPlatform(340, 400, false);
    addEnemy(140, 400);
     
    engine.enableAccelerationSensor(activity, this);
    registerUpdateHandler(physicsWorld);  
    
    //physicsWorld.setContactListener(new MyContactListener(player));
    
    ...
  }

Finally, just after the commented line in the populate() method, we can add the new code, as follows:

    FixtureDef boxFixture1 = PhysicsFactory.createFixtureDef(1f, 0f, 2f, false,
        CATEGORY_BOX_1, MASK_BOXES, (short) 0);
    PhysicsFactory.createBoxBody(physicsWorld, 100, 300, 50, 25, BodyType.DynamicBody, boxFixture1);  
    FixtureDef boxFixture2 = PhysicsFactory.createFixtureDef(1f, 0f, 2f, false,
        CATEGORY_BOX_2, MASK_BOXES, (short) 0);
    PhysicsFactory.createBoxBody(physicsWorld, 130, 350, 50, 25, BodyType.DynamicBody, boxFixture2);  
    
    FixtureDef circleFixture = PhysicsFactory.createFixtureDef(1f, 0f, 2f, false,
        CATEGORY_CIRCLE, MASK_CIRCLE, (short) 0);
    Body circle = PhysicsFactory.createCircleBody(physicsWorld, 100, 440, 25, BodyType.DynamicBody, circleFixture);  
    circle.setFixedRotation(true);
   
    FixtureDef platformFixture = PhysicsFactory.createFixtureDef(1f, 0f, 2f, false,
        CATEGORY_PLATFORM, MASK_ALL, (short) 0);
    PhysicsFactory.createBoxBody(physicsWorld, 100, 250, 150, 15, BodyType.StaticBody, platformFixture);  

This code defines four bodies; each of them belongs to a separate category. Right now, the circle and boxes don't collide, but the boxes collide with each other, as shown in the following screenshot:

Thanks to the category definitions, we can very easily turn off collisions for the rectangles by removing the categories from MASK_BOXES, as follows:

  public static final short MASK_ALL = 
      CATEGORY_BOX_1 +
      CATEGORY_BOX_2 +
      CATEGORY_CIRCLE + 
      CATEGORY_PLATFORM;

  public static final short MASK_BOXES = 
      CATEGORY_PLATFORM;
  
  public static final short MASK_CIRCLE = 
      CATEGORY_CIRCLE +
      CATEGORY_PLATFORM;  

The result looks as expected. The rectangular boxes now overlap too, as shown in the following screenshot:

The last parameter we can define when creating a fixture is group index. Group index is a positive or a negative number of a group. Members of the same group will either always collide with each other if the group number is positive, or never collide with each other if it is negative. Groups are different from categories and they have precedence over categories when deciding whether two objects collide or not.

In our example, if we defined both boxes and the circle in group 1, they would always collide. If we defined them with a negative group index, let's say -5, they would never collide. Group index 0 has no effect.

Here's an example how to make the boxes collide again without changing their categories or category masks. The change in the group index is highlighted in the following code:

    FixtureDef boxFixture1 = PhysicsFactory.createFixtureDef(1f, 0f, 2f, false,
        CATEGORY_BOX_1, MASK_BOXES, (short) 1);
    PhysicsFactory.createBoxBody(physicsWorld, 100, 300, 50, 20, BodyType.DynamicBody, boxFixture1);  
    FixtureDef boxFixture2 = PhysicsFactory.createFixtureDef(1f, 0f, 2f, false,
        CATEGORY_BOX_2, MASK_BOXES, (short) 1);
    PhysicsFactory.createBoxBody(physicsWorld, 130, 350, 50, 20, BodyType.DynamicBody, boxFixture2);