+23 votes

In PhysicsBody and PhysicsBody2D, I see there since a few months a new attribute called Mask (PhysicsBody / Collision / Mask). I noticed that a body collides with another body if they have a layer in common or a mask in common. But then, if there's already a collision layer, what's the purpose of the mask? Alas the documentation is yet incomplete about this subject.

in Engine by (696 points)

I still haven't seen a good explanation of the difference.

Here's a really good way to think of it:

  • The Layer tells us "I exist on" the following layer(s)."
  • The Mask tells us "I will collide with items that exist on the following layers."

So if we have
Player: Layer 1, Mask 2
Enemy: Layer 2, Mask 1,3
and
Bullet: Layer 3, no mask
then the Player will collide with an Enemy only, Enemies will collide with Bullets and the Player but not each other, and Bullets will only collide with what is set to collide with them (which in this case is Enemies, since the Bullet's ("I exist on") Layer (i.e., 3) is the same as one of Enemy's ("I collide with items that exist on") Masks (i.e., 1 and 3).
(A collision between Object 1 and Object 2 happens when either Object 1's Layer == Object 2's Mask, or Object 1's Mask == Object 2's Layer, or both.)

1 Answer

+33 votes
Best answer

Collision mask bit is for choosing what layer should be collided.

Let's assume we set collision layer and mask layer as below.

Player node : collision layer is on 1st bit / mask layer is on 2nd,3rd bit
Enemy node : collision layer is on 2nd bit / mask layer is on 1st bit
Object node : collision layer is on 3rd bit / mask layer is on 1st bit

then,
Player mask(2) == Enemy layer(2)
Player mask(3) == Object layer(3)
so, Player can be collided with Enemy and Object.

but Enemy nodes are not collided each other or Object nodes.
Because Enemy mask(1) != Enemy layer(2) / Enemy mask(1) != Object layer(3)

by (9,664 points)
selected by

Two notes:

  1. If enemy's mask and object's mask are set to 0 (i.e. no layers), they will still collide with the player, because the player's mask still includes their respective layers.
  2. Overall, if the objects are A and B, the check for collision is A.mask & B.layers || B.mask & A.layers, where & is bitwise-and, and || is the or operator. I.e. it takes the layers that correspond to the other object's mask, and checks if any of them is on in both places. It will they proceed to check it the other way around, and if any of the two tests passes, it would report the collision.

thank you very much worked

So basically Collision Layer is to simply organize certain objects onto a layer, and Collision Mask actually tells what objects to collide with?

Great answer! I searched official docs, but no examples for explaining this was found. Thank you for this example, easy to understand now.

It's like the layer can collide with another mask
But a mask can't collide with another mask
The layer collides with both mask and layer
But the mask can't collide with anything by itself

Found a very good explanation at http://kidscancode.org/blog/2018/02/godot3_kinematic2d/

Quoting, so the reader can find it easier:

  • collision_layer describes the layers that the object appears in. By default, all bodies are on layer 1.
  • collision_mask describes what layers the body will scan for collisions. If an object isn’t in one of the mask layers, the body will ignore it. By default, all bodies scan layer 1.

See examples on that page.

Does the layer collide with the layer? I didn't think so based on the previous comments.

So in the situation where:
A is on layer 1 and has a mask on 2
B is on layer 2 and has no mask
then A will detect a collision with B, but B won't detect a collision with A?

Is that right?

I think the best explanation would be a key and lock explanation.

So, Layers = locks, and Masks = keys.

Let's say each Lock is assigned a number, i.e. Lock1, and each key is assigned a number i.e. Key1. And keys can only open locks with their corresponding locks.

So for your example:

Player node has Lock1, while the other two nodes have Key1, which allows them to unlock (interact) with Player node.

Welcome to Godot Engine Q&A, where you can ask questions and receive answers from other members of the community.

Please make sure to read How to use this Q&A? before posting your first questions.
Social login is currently unavailable. If you've previously logged in with a Facebook or GitHub account, use the I forgot my password link in the login box to set a password for your account. If you still can't access your account, send an email to webmaster@godotengine.org with your username.