Skip to main content

Collision filtering

By default, every PhysicsBody will collide with every other PhysicsBody. This may not be what you want. For example, you might want to have a ball that bounces off the walls of the scene, but passes through other balls. This is called collision filtering because you are allowing some collisions and filtering out others. You can control which physics bodies collide with each other by with two properties: categoryBitMask and collisionBitMask.

A physics body's category​

You can define up to 32 categories of physics bodies. Each category can have a different kind of collision behavior. For example, you might have a category for walls, a category for balls, a category for dogs, and categories for other objects. Category 1 is the default category, and all physics bodies will be this category unless you change it.

The categoryBitMask property of a PhysicsBody represents the category. A category is defined not by its value, but by its bit position. For example, category 1 is the first bit position, category 2 is the second bit position, category 3 is the third bit position, and so on. The categoryBitMask property is a 32-bit integer, so it can represent up to 32 categories.

In JavaScript, it is convenient to specify a binary number with the 0b prefix:

  • 0b00000001 has the first bit position set.
  • 0b00000010 has the second bit position set.
  • 0b00000100 has the third bit position set.
  • 0b00001000 has the fourth bit position set.
  • and so on...
tip

You do not need to specify all 32 bits when setting the bit position. For example, 0b0100 is the same as 0b100 and 0b00000000000000000000000000000100.

A physics body can belong to multiple categories. For example, 0b0101 would be a physics body that is a member of both categories 1 and 3.

A physics body's collision filter​

The collisionBitMask of a physics body controls which categories of physics bodies it will collide with. The default value is 0b11111111111111111111111111111111 (sometimes written in hexadecimal as 0xFFFFFFFF), which means the physics body will collide with every category. You can change this value to control which categories the physics body will collide with.

For example, imagine we have two categories of physics bodies:

  • walls (category 1, or 0b0001)
  • balls (category 2, or 0b0010)

If you want a ball to collide only with walls (and pass through other balls), you would set every ball's collisionBitMask to 0b0001. If you want a ball to collide with walls and other balls, you would set every ball's collisionBitMask to 0b0011.

A rainy example​

In the example, there are three categories of physics bodies:

  • the edge loop (category 1, or 0b0001)
  • the umbrella (category 2, or 0b0010)
  • the raindrops (category 3, or 0b0100)

We want the raindrops to collide with the umbrella, but not with the edge loop (so the raindrops fall off the scene). To do this, each raindrop's collisionBitMask is set to 0b0010.

Click "Rain" to make it rain. The raindrops will roll around the umbrella before falling off the scene.

Loading...