What's the difference between Collision layers and Collision masks?

Question

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.

Comments

Related: http://godotengine.org/qa/3020/collision-masks-and-its-propper-uses

---

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.)

Answer 1

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)

Comments

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.

---

https://docs.godotengine.org/en/latest/tutorials/physics/physics_introduction.html#collision-layers-and-masks

---

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.

Answer 2

Just incase someone is still confused with the other answer:

collision layer: decides which layer object is in

collision mask: decides which layer the object can collide with