OccluderPolygon2D in Godot – Complete Guide

Lighting and its manipulation are pivotal elements when creating engaging 2D environments. Through clever use of light and shadow, you can add depth, atmosphere, and a sense of realism to your projects. In the Godot Engine, particularly in version 4, you have the ability to control how light interacts with objects using the OccluderPolygon2D class. This tutorial will delve into the features that OccluderPolygon2D offers, providing examples and insights that will illuminate this powerful tool and its uses in your game development journey.

What is OccluderPolygon2D?

OccluderPolygon2D is a class within the Godot Engine dedicated to defining the shape of shadows in a 2D environment. When combined with LightOccluder2D nodes, it allows creators to add depth to their scenes by controlling the way light behaves around objects.

What is it for?

By using OccluderPolygon2D, developers can dictate how light sources illuminate or avoid areas of the game, creating realistic shadows that enhance the player’s immersive experience. This feature can be used to create dynamic lighting effects, such as simulating the sun setting or casting shadows that move and change with the in-game environment.

Why Should I Learn It?

Learning how to use OccluderPolygon2D can elevate your game’s visual fidelity and potentially impact gameplay. It’s an essential skill for any budding game developer using Godot Engine, as it allows for more complex and engaging scenes. With proper understanding, you can craft environments that not only look great but also contribute to the storytelling and atmosphere of your game.

CTA Small Image

Creating a Simple Light Occluder in Godot

To get started with light occlusion, you first need to create a 2D scene and add a LightOccluder2D node. Within this node, you will use OccluderPolygon2D to define the shape that will cast shadows.

var light_occluder = LightOccluder2D.new()
var occluder_polygon = OccluderPolygon2D.new()
light_occluder.occluder = occluder_polygon

Once you’ve created and added the LightOccluder2D node, you can manually adjust the vertices of the OccluderPolygon2D to match the shape of the object that should cast a shadow.

Setting Up the OccluderPolygon2D Vertices

Defining the shape requires you to set the vertices of the polygon. This can be done through the editor or programmatically like in the following example:

    Vector2(0, 0),
    Vector2(0, 100),
    Vector2(100, 100),
    Vector2(100, 0)

It’s important to ensure that your vertices are listed in either clockwise or counterclockwise order to create a closed shape that can correctly cast shadows.

Adding a Light Source

No shadows will be visible without a light source. Let’s add a 2DLight node (like a PointLight2D for instance), which will interact with the occluder to generate shadows:

var point_light = Light2D.new()
point_light.texture = preload("res://path_to_your_light_texture.png")
point_light.color = Color(1, 1, 1, 1)  # White light with full opacity

When the scene is run with both the light source and the occluder present, shadows should become visible and react dynamically to the movement of the light.

Modifying OccluderPolygon2D Properties

There are several properties available in the OccluderPolygon2D class that affect how shadows are cast. For instance, changing the ‘closed’ property affects whether the polygon is treated as a closed shape or open.

occluder_polygon.closed = true

Additionally, the ‘cull_mode’ property can determine which direction of the light the polygon will cast the shadow:

occluder_polygon.cull_mode = OccluderPolygon2D.CULL_DISABLED  # Shadows cast in all directions

You might want to play with these properties to see the different effects they have on the shadows in your scene. Remember, the goal is to use these tools to create a more dynamic and atmospheric environment for your games. Keep tweaking and testing until you achieve the desired lighting effect.Great! Let’s dive deeper into the capabilities of the OccluderPolygon2D node and how you can use it to create more complex and visually appealing lighting arrangements in your 2D scenes.

Advanced Occluder Shapes

OccluderPolygon2D allows you to create more than just simple rectangular shadows. You can create any polygonal shape to fit the silhouette of your object. Here’s an example creating a triangle-shaped occluder:

    Vector2(50, 0),
    Vector2(100, 100),
    Vector2(0, 100)

Remember to update your light sources to see these shadow changes in real-time in your scene.

Sometimes, you might want to animate your occluder shapes to match animated objects. Here’s how you could change the shape over time through code:

func _process(delta):
    var time = OS.get_ticks_msec() / 1000.0
        Vector2(100 + sin(time) * 50, 0),
        Vector2(100, 100),
        Vector2(0, 100)

This code will animate the first vertex of the triangle back and forth, simulating a simple waving motion.

Handling Multiple Light Sources

In a scene with multiple lights, you might notice some interesting shadow behavior. Occluders will interact with all light sources. To make a particular occluder respond to a specific light, you simply adjust the layering:

// Assign the first light to layer 1
light1.light_layer = 1

// Assign the occluder to layer 1
occluder_polygon.light_mask = 1

// The second light remains in the default layer 
// (so it's not affected by the occluder above)

By using light layers and masks, you can fine-tune which objects cast shadows in response to which lights.

Creating Soft Shadows

Soft shadows can add a nice, subtle touch to your lighting, giving the scene a more natural feel. You can create soft shadows by adjusting the `shadow_mode` property:

// Enable soft shadows
light1.shadow_mode = Light2D.SHADOW_SOFT

To control the softness level or ‘blur’ of the shadow, you can modify the `shadow_gradient_length` property:

// Adjust the gradient length for a softer shadow
light1.shadow_gradient_length = 10

Combining all these elements, you are well-equipped to add dynamic, responsive lighting to your 2D projects in Godot Engine. You can now experiment with OccluderPolygon2D shapes, animate them, properly layer them for complex lighting scenarios, and even soften your shadows for a more realistic look. Each feature plays a part in bringing your scenes to life, enhancing not only the visual aspect but also the overall experience for players engaging with your creations. Remember to test your lighting setups in various conditions to ensure they contribute positively to the atmosphere and gameplay. Happy developing!Creating an engaging game experience often hinges on the small details, like the interplay between light and shadow. With Godot’s OccluderPolygon2D, you have a robust tool at your disposal to craft those details. Here’s how you could further enhance your game’s visuals with a few more advanced implementations.

To create a dynamic shadow that alters its shape based on an object’s rotation, you can adjust the occluder’s vertices in accordance with the parent object’s orientation. Here’s an example:

func _process(delta):
    var rotation_degrees = $YourObject.rotation_degrees
    var rotated_polygon = PoolVector2Array()
    for vertex in occluder_polygon.polygon:

In this snippet, we’re making sure that the shadow correctly represents the object’s current rotation by applying the same rotation to the vertices of the occluder polygon.

Now, suppose you want to change the opacity of the shadow based on game logic, such as simulating a cloud passing overhead. This can be done by adjusting the light’s `energy` property:

func _process(delta):
    if cloud_overhead:  # Assuming this variable tracks cloud coverage
        $PointLight2D.energy = lerp($PointLight2D.energy, 0.5, delta)
        $PointLight2D.energy = lerp($PointLight2D.energy, 1.0, delta)

In the above example, `lerp` is used to smoothly transition the light’s energy, thus decreasing or increasing shadow opacity gradually.

Another fascinating effect you can create is simulating light flickering. To achieve this random fluctuating light effect as seen with fire or faulty electricity, apply the following modification:

func _process(delta):
    $PointLight2D.energy = 1 + rand_range(-0.2, 0.2)

The `rand_range` function generates a random value each frame, within the specified range, causing the light’s energy to vary and simulate a flickering effect.

For shadows moving with a character or objects, attach a LightOccluder2D node to the moving node and update its position in the `_process` function:

func _process(delta):
    $LightOccluder2D.global_position = $YourObject.global_position

Making the global position of the LightOccluder2D match your object ensures that the shadow will always be cast from the correct location as the object moves.

Finally, you might want to respond to environmental changes, such as having your shadows stretch or shrink based on the time of day. For a simple day-night cycle effect, you could adjust the angle of the light source:

var time_of_day = 12  # Update this dynamically in your game logic.
var light_angle = map(time_of_day, 0, 24, -90, 90)
$DirectionalLight2D.rotation_degrees = light_angle

Using the `map` function, we convert a time of day value into an angle for the light, creating longer shadows in the morning and evening, and shorter ones around noon.

These techniques showcase just how much detail and life you can breathe into your game world with the Godot Engine’s lighting system. By mastering these skills, you’re not just making your game look better — you’re crafting an environment that tells a story and enhances the player’s engagement with your game world. Play around with these examples, tweak parameters, and see how they can be integrated and modified to fit the needs of your project. Happy coding!

Continuing Your Learning Journey in Godot

With the fundamental understanding of how to use OccluderPolygon2D for dynamic lighting in Godot, you’re well on your way to creating beautifully lit 2D scenes. However, this is just the beginning! To keep advancing your game development skills, we at Zenva encourage you to dive deeper into what Godot has to offer. Our Godot Game Development Mini-Degree is the ideal next step for aspiring developers who want to expand their knowledge and portfolio with real Godot projects.

In our program, you’ll tackle various aspects of game development with Godot 4, from mastering GDScript to designing complete UI systems for different game genres. Each course is packed with practical lessons and projects that cater to both novices and developers looking to polish their skills. You’ll not only learn the ins and outs of Godot but also create a strong foundation that will benefit all your future game development endeavors.

For an even broader selection of high-quality content, we also invite you to explore our full range of Godot courses. Each course is designed to help you learn at your own pace, with a mix of live coding examples and quizzes to cement your knowledge. Start creating your dream games today with Zenva, and watch as you go from beginner to professional, one exciting project at a time!


Embarking on the journey of game development is an adventure filled with continuous learning and creativity. As you’ve seen throughout this tutorial, the Godot Engine’s OccluderPolygon2D tool is just a peek into the vast world of possibilities for making your game stand out. Remember, practice is key; every game scene you light up using Godot’s powerful features is a step towards mastering the art of game creation.

We at Zenva are excited to be part of your journey into game development. With our Godot Game Development Mini-Degree, you have access to an extensive catalog of tutorials and courses that will help you build your skills, from lighting techniques to complete game builds. So why wait? Continue your learning adventure with us and start shaping the exceptional games you’ve always envisioned.

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.