LightOccluder2D in Godot – Complete Guide

Welcome to the illuminating world of 2D game development with Godot 4! In today’s tutorial, we’re diving into LightOccluder2D, a class that forms the backbone of realistic lighting effects, crucial for adding depth and atmosphere in 2D games. If you’ve ever marvelled at the way shadows dance across the screen or how a light source can change the mood of a scene, you’ll appreciate the power of LightOccluder2D. Join us as we explore the mechanics of this class across various examples, and get ready to throw some shade – in the most literal sense!

What is LightOccluder2D?

LightOccluder2D is a node in the Godot Engine that interacts with Light2D nodes to cast dynamic shadows. It’s an essential component in a 2D game’s lighting system because it helps establish a more immersive and visually engaging environment.

What is it for?

The primary purpose of a LightOccluder2D is to define regions where light is blocked, creating shadows that react to the game’s light sources. When paired with an OccluderPolygon2D, it tells the engine precisely which areas should be in shadow based on the shape and position of the polygon.

Why Should I Learn It?

Understanding how to integrate LightOccluder2D into your games opens up a myriad of possibilities for enhancing visual storytelling and gameplay dynamics. It’s not just about making your game look better – shadows can influence player behavior, highlight critical areas or threats, and improve the overall gaming experience. Let’s light the path to mastering 2D lighting together!

CTA Small Image

Creating a Basic Light Occluder in Godot 4

To get started with lighting in Godot 4, we need to create a basic light occluder setup that can later be customized and expanded upon.

First, add a new LightOccluder2D node to your scene:

var occluder =

After adding the LightOccluder2D node, we must define its shape with an OccluderPolygon2D:

var polygon =
polygon.set_polygon(Vector2Array([Vector2(0, 0), Vector2(0, 100), Vector2(100, 100), Vector2(100, 0)]))

This code snippet creates a square occluder. Note that in Godot 4, you would use Vector2Array instead of PoolVector2Array used in Godot 3.

Adjusting Occluder Properties

Now, let’s adjust some properties of the LightOccluder2D to see different effects:

# Set the occluder to cast shadows only to one side

In this example, the occluder is set to cast shadows in all directions, but by adjusting the cull mode, you can make the shadow appear only on one side of the occluder:

# Cast shadows only to the clockwise direction

# Cast shadows only to the counterclockwise direction

It allows you to have more control over the direction of shadows, making for more dynamic and realistic lighting.

Interacting with Light2D

For the LightOccluder2D to cast shadows, we need a light source. Here’s how to create a simple Light2D:

var light =
light.set_texture(preload("res://path_to_your_texture.png")) # Use your light texture

This light will now interact with the occluder to create shadows. You can move it around to see how shadows change dynamically:

# Update the light's position
light.set_global_position(Vector2(200, 200))

Adjusting the energy of the Light2D node affects the shadow’s intensity:

# Make the light stronger = 2.0

# Make the light weaker = 0.5

These snippets show the basics of setting up a lighting system using Light2D and LightOccluder2D in Godot 4. With this foundation, you can start to play around with the settings to affect the ambiance of your game scenes.At this point, you have the essentials to start incorporating LightOccluder2D into your game. But let’s delve a bit deeper and explore additional functionalities and scenarios that can really bring your 2D world to life.

Using Light Masks

In Godot, Light2D nodes can be set to only interact with objects on the same light layer. This means that you can create complex lighting scenarios where certain lights affect only specific objects or areas:

# Set the light mask bit
light.set_layer_mask_bit(1, true) # This sets the second bit to true

# Set the occluder light mask bit
occluder.set_light_mask_bit(1, true) # Both are on the same bit, so they will interact

By changing which layers each Light2D and LightOccluder2D are on, you can control which shadows are cast by which lights.

Moving Shadows with AnimationPlayer

Animating lights or occluders can result in dynamic shadow movements. Here’s a simple setup with AnimationPlayer:

# Assuming you have an AnimationPlayer node set up
$AnimationPlayer.create_animation("Move Light")
var track = $AnimationPlayer.add_track(Animation.TYPE_VALUE)
$AnimationPlayer.track_set_path(track, "Light2D:transform/pos")
$AnimationPlayer.track_insert_key(track, 0.0, Vector2(100, 100))
$AnimationPlayer.track_insert_key(track, 1.0, Vector2(300, 100))
$"Move Light")

The light will now move over a second from one point to another, and the shadow will dynamically follow along.

Changing Occluder Polygon at Runtime

Sometimes, the shape of your occluder may need to change during gameplay. Perhaps a door opens, or a platform moves, and you want the shadows to update accordingly.

# Dynamically update the occluder's shape
polygon.set_polygon(Vector2Array([Vector2(0, 0), Vector2(0, 150), Vector2(150, 150), Vector2(150, 0)]))

Now your occluder has transformed, and so will the shadows.

Creating Lights with Varying Colors and Modes

Besides the intensity, you can change the color and mode of your Light2D to achieve different effects.

# Change light color
light.color = Color(1, 0, 0) # Red light

# Set light to 'subtract' mode for darkness effects
light.color = Color(0, 0, 0, 0.5) # Use with lower alpha for an eerie dimming effect

This can be used for mood settings like alarm situations, night/day cycles, or even magical spells.

Combining Multiple Occluders

For complex scenes, you might have multiple occluders. You can add them to the same or different layers to create intricate shadow interplays.

var occluder2 =
var polygon2 =
polygon2.set_polygon(Vector2Array([Vector2(200, 200), Vector2(250, 200), Vector2(250, 250), Vector2(200, 250)]))
occluder2.set_light_mask_bit(1, true)

This second occluder will now work with the same light to create additional shadow effects.

Through these examples, you can see how the LightOccluder2D node can be used in Godot 4 to create lights and shadows that add realism and depth to your 2D games. Experimenting with these features is not just about the visual payoff; it’s about discovering the interplay between light and darkness as gameplay elements — a hallmark of atmospheric and immersive game worlds. Happy game designing!Let’s expand our knowledge and apply advanced application of LightOccluder2D, pushing creativity and functionality further in your 2D games with Godot 4.

Consider a scenario where the environment responds to in-game events, like an explosion that alters the lighting. You can animate occluders to mimic debris impacting the light path:

# Assuming 'occluder' is already a LightOccluder2D node instance
# Before the explosion
var original_polygon = Vector2Array([Vector2(0, 0), Vector2(0, 100), Vector2(100, 100), Vector2(100, 0)])

# After the explosion
func on_explosion():
    var new_polygon = Vector2Array([Vector2(0, 0), Vector2(-50, 100), Vector2(50, 150), Vector2(150, 50)])

Flickering lights can emulate fire or electrical issues creatively. We can vary the energy of a light over time:

# Flicker a Light2D node named 'flickering_light'
func _process(delta):
    var flicker_intensity = rand_range(0.8, 1.2) # Randomize between 80% and 120% intensity
    $ = flicker_intensity

Shadows can also respond to the weather! Imagine a stormy scenario where lightning temporarily brightens the entire scene:

# Function to simulate a lightning strike effect
func lightning_strike():
    $ = 5.0  # Strong light for the lightning flash
    yield(get_tree().create_timer(0.2), "timeout")  # Wait for 0.2 seconds
    $ = 1.0  # Return to normal light level

Shadows can indeed be more than just aesthetic; they can reveal hidden paths or items when a player uses a torch or lantern:

# Use a 'torch_light' as a movable light source by attaching it to the player
func _on_player_move(position):

Let’s set up occluders to cast long shadows in the evening and shorter ones during the day to simulate the sun’s movement:

# Update occluder polygon based on time_of_day
func update_occluder_for_time_of_day(time_of_day):
    var angle = time_of_day * 180.0  # Convert time_of_day to angle
    var length = cos(deg2rad(angle)) * 100.0  # Length of the shadow
    # Set new polygon based on shadow length
    occluder.get_occluder_polygon().set_polygon(Vector2Array([Vector2(0, 0), Vector2(0, length), Vector2(100, length), Vector2(100, 0)]))

Finally, shadows could be an element of puzzle gameplay, where aligning objects correctly casts a shadow that unveils a clue:

# Assuming 'puzzle_piece' is an object that needs to be aligned
func _on_puzzle_piece_aligned(correct_position):
    if puzzle_piece.global_position == correct_position:
        show_shadow_clue()  # Function to display the shadow as a clue to the puzzle

These code examples demonstrate the versatility of LightOccluder2D. With creativity and these powerful tools at your disposal, the potential for what you can build in your 2D games with Godot 4 is nearly limitless. Whether you’re crafting moody atmospheres, dynamic lighting effects, or integrating shadows into your gameplay mechanics, mastery over light and shadow is an invaluable skill for any game developer. Keep experimenting, and let the interplay of light and darkness inspire your game’s development journey. Happy coding!

Where to Go Next in Your Godot Journey

Embracing the world of Godot 4 through LightOccluder2D and lighting effects is just the beginning of what you can achieve. Don’t stop here! To keep building on your newfound skills and explore the myriad of possibilities in game development with Godot 4, we encourage you to check out our Godot Game Development Mini-Degree. This comprehensive course collection is perfect for both beginners and more advanced developers and covers everything from 2D and 3D assets to complex game mechanics across various genres.

With Zenva, you’ll learn at your own pace and turn your enthusiasm into tangible projects that can bolster your portfolio, all while gaining the skills necessary to thrive in the game development industry. Additionally, for those eager to expand their Godot expertise even further, explore our broad range of Godot courses.

Join our community of learners and take the next step to become a game development pro. Remember, every expert was once a beginner, and with Zenva, you can confidently go from novice to professional as you craft the games of your dreams. Let’s keep learning and creating together!


Your journey into the intricate world of game development with Godot 4 doesn’t end here. Armed with the knowledge of LightOccluder2D and the powerful lighting mechanisms at your fingertips, you’re well on your way to creating games that not only look stunning but also offer engaging and dynamic experiences. Remember, every shadow painted and every light placed is a step towards mastering the art of game design.

As you continue to harness the capabilities of Godot 4, don’t forget to explore our Godot Game Development Mini-Degree to further refine your skills and broaden your horizons. At Zenva, we’re committed to helping you turn your dreams into playable realities with our expert-led courses. So, keep on learning, keep on building, and may your games shine bright in the hearts of players around the world.

Python Blog Image

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