Understand Collision Layers and Masks in Godot 4

 Welcome to an exciting tutorial about collision layers and masks in Godot 4! Today we’re going to muck around with these settings using a simple visual demo — a falling ball and a grumpy floating platform — until we have a clear understanding of what collision layers and masks are, how they work together, and how they differ. By the end of this tutorial, you'll know exactly how to control the objects that interact in your game… and bend them to your will.

Creating the Crash Course

First, let’s meet our stars: the falling ball and the grumpy floating platform. They’re going to show us exactly how collisions work — whether they play nicely or crash spectacularly.

Both are RigidBody2D nodes, which means they will have physics applied to them automatically. The red ball has a Gravity Scale set to 1.0, which will pull it down nicely. But our grumpy platform has a Gravity Scale set to -1.0. This darn thing wants to float, or fall actually, straight up!

So with our scene ready, we should get some entertaining interactions between the two objects.

Lets start by peeking at the Inspector under the Collision section.

I have turned off the Layer and Mask values for the ball and the platform. Lets start from a place of no collisions. They should pass right through each other, when I play the scene.

And they did! As you can see in the screen shot, the ball fell straight down, right through the floating platform. And the platform was trying to fly right up to the moon.

This is our “no-collision” baseline — the perfect place to start experimenting with layers and masks, so we can decide who gets to touch who… and who gets a free pass.

Layers

What Are Collision Layers?

Think of layers as existence badges for your objects in the physics world.

• Every object lives on one or more layers.

• A layer answers the question: “Where am I?”

• Example:

  • The ball might live on the “Balls” layer.

  • The platform might live on the “Platforms” layer.

By itself, a layer doesn’t make objects collide. It just tags the object, like putting a sticker on it.

Our two test objects can exist on different layers or they can even exist on the same layer. But as I already mentioned. Layers by themselves won't cause interactions. Watch what happens when I set both the ball and the platform to layer 1.

What is going on here! If they exist on the same layer, why didn't they interact?

This is where Masks come into play.

Masks

What Are Collision Masks?

Masks define which layers will affect our object.

So lets start playing with this now. Let set the ball to layer 1. Then lets put the platform on layer 2.

Now lets define our masks. The ball's maks will be set to 2 and the platforms mask will be set to 1. What this mean... The ball exists on layer 1 but will only be affected by objects from layer 2. On the other hand, our platform exists on layer 2 but can only be affected by objects from layer 1. With these settings our ball and platform should come together and stop each other rather than passing through each other.

And the result...

Yes... They ran into each other and stopped. But what happens if I turn off one of the masks and leave the other on?

I will turn off the mask for the ball.

The result... The ball pushes the platform straight down.

But why?

Here's the scoop... The ball has no mask selected. Therefore no object can affect it. It just keeps falling as if the platform weren't even there. Meanwhile... the platform has its mask still set to 1. So any object from layer 1 will affect it.

The outcome: the unstoppable ball barrels down, and the platform gets pushed straight to… well, somewhere below the scene. The poor platform doesn’t stand a chance!

If we switch things around and turn off platform's mask but leave ball's on...

You guessed it!

The platform pushes the ball right through the roof.

Can an object not exist on any layer but still have a mask? Lets set ball's layer to nothing and leave the mask on 2.

What will this do?

Platform pushes ball up.

Why? Because platform only gets affected by objects on layer 1. Ball is no longer on layer 1. So the platform keeps trucking like ain't nothing there. Meanwhile the ball gets affected by objects from layer 2, which is where the platform exists. So it goes for a ride.

This is a fun example that really shows how layers define “where I am” and masks define “who I can be affected by.”

Conclusion: You’re Now a Collision Master

Congratulations! You’ve navigated the wild world of collision layers and masks in Godot 4.

By experimenting with our falling ball and grumpy floating platform, you’ve seen firsthand:

• How layers define who an object is.

• How masks decide who an object interacts with.

• How mixing and matching layers and masks can produce all kinds of surprising, chaotic, or just plain fun results.

Now you have the power to control your physics objects with precision — making sure bullets hit enemies but ignore each other, players pass through triggers without stopping, or platforms float and interact exactly the way you want.

Go ahead, take this knowledge, and bend your game objects to your will! And remember: sometimes, the most interesting interactions come from a little chaos… just like our grumpy platform trying to fly to the moon.