DirectionalLight2D in Godot – Complete Guide

The world of 2D game development is teeming with potential, and mastering the play of light and shadow can truly propel your game environments to new heights. Enter the DirectionalLight2D node in Godot 4, a tool designed to simulate powerful, parallel rays of light across your entire scene. It’s akin to harnessing the beams of the sun or the glow of the moon right within your game, providing not only realism but also atmosphere to your creations.

What is DirectionalLight2D?

What is DirectionalLight2D?

The DirectionalLight2D class in Godot 4 is a powerful node derived from Light2D that enables developers to add directional lighting effects to their 2D games. This node models an infinite number of parallel rays, representing a light source that’s both intensely bright and seemingly distant, like sunlight or moonlight across the game environment. It’s an essential element when you want to add depth, dimension, and a sense of realism to your game scenes.

What is it for?

DirectionalLight2D is specifically designed for the purpose of casting light across your entire scene in a consistent direction. This consistency emulates the way we perceive sunlight and moonlight in the real world – as a steady source of light casting parallel beams. Whether you’re creating a vibrant game set under the noon sun or an eerie adventure illuminated by the soft glow of the moon, this node can be the key to setting the right tone.

Why Should I Learn to Use DirectionalLight2D?

Integrating DirectionalLight2D into your Godot projects opens up a world of aesthetic possibilities. By learning how to use this tool, you’ll be able to:

  • Create more immersive and dynamic scenes with the use of realistic lighting.
  • Understand the influence light has on the mood and style of your game’s environment.
  • Improve the visual quality of your game without a steep learning curve.
  • Stand out among other game developers with your ability to manipulate light and shadow effectively.

Now that we know what DirectionalLight2D is and why it’s valuable to learn, let’s dive into some code examples and see this node in action.

CTA Small Image

Setting up DirectionalLight2D

To get started with DirectionalLight2D in your Godot project, the first step is to add the node to your scene. Here’s how to do it through GDScript:

var directional_light =

This code snippet creates a new DirectionalLight2D node and adds it as a child to the current node, which should be your main scene or the scene’s root.

Next, adjust the direction and angle of the light to achieve the desired effect:

directional_light.rotation = deg2rad(45) # Rotate the light 45 degrees

By changing the rotation value, you can simulate different times of day, or adjust the source of light to better match the art and layout of your scene.

Configuring Light Properties

Once the DirectionalLight2D is in place, fine-tune its properties to fit your game’s aesthetic. Here’s an example that modifies the color and energy of the light:

directional_light.color = Color(1, 0.9, 0.8) # Soft warm light = 0.8                # Dim the light a bit

This will give your scene a warm, sunrise-like illumination. Experiment with different color values to mimic various lighting conditions.

To change the size of the light and the area it affects, you might adjust the scale of the DirectionalLight2D node:

directional_light.scale = Vector2(1.5, 1.5) # Enlarge the light's area

Sometimes, you’ll want your light to have an influence only over certain objects or layers. In Godot 4, you can use the “layer_range_min” and “layer_range_max” properties:

directional_light.layer_range_min = 1
directional_light.layer_range_max = 3

This confines the light’s effects to only the layers specified, giving you greater control over your scene’s illumination.

Shadows and Occlusion

A key feature of DirectionalLight2D is its ability to cast shadows. Enable shadow casting with:

directional_light.shadow_enabled = true

Then, you can adjust the shadow’s color to add atmosphere:

directional_light.shadow_color = Color(0, 0, 0, 0.5) # Semi-transparent dark shadows

This gives your shadows a semi-transparent, dark look—ideal for creating mood without overpowering the scene.

Occluders need to be set up on sprites that should cast shadows. This requires adding an ‘Occluder2D’ node, then configuring it:

var occluder =
occluder.set_closed(true) # Set the occluder to a closed shape

This creates an occluder for your DirectionalLight2D, allowing any sprite you attach it to cast a shadow.

In the next part, we’ll look into how to animate DirectionalLight2D properties and integrate it further with environmental effects for more advanced usage scenarios.

Animating the DirectionalLight2D properties can significantly enhance the dynamism of your game. For instance, to simulate the effect of a passing cloud shadow, you might animate the energy property:

var tween =
tween.interpolate_property(directional_light, 'energy', 0.8, 0.2, 2, Tween.TRANS_LINEAR, Tween.EASE_IN_OUT)

This snippet dims the light from its current energy level to a lower value, mimicking a cloud moving in front of the sun, then brightens back to the starting level over the course of 2 seconds.

Creating a day-night cycle adds immersion to your game. With timers and animations, you can shift from daylight to darkness and back:

func _on_DayNightTimer_timeout():
    # Check if it's currently day or night
    if > 0.5:
        tween.interpolate_property(directional_light, 'energy',, 0.2, 10, Tween.TRANS_QUAD, Tween.EASE_IN_OUT)
        tween.interpolate_property(directional_light, 'energy',, 1.0, 10, Tween.TRANS_QUAD, Tween.EASE_IN_OUT)

This function should be connected to a Timer node’s timeout signal and will toggle between day and night energy levels using the tween we created earlier.

Furthermore, animating the rotation can simulate the changing position of the sun:

func _on_SunPositionTimer_timeout():
    tween.interpolate_property(directional_light, 'rotation', directional_light.rotation, directional_light.rotation + deg2rad(40), 30, Tween.TRANS_SINE, Tween.EASE_IN_OUT)

Again, by connecting to a Timer’s timeout signal, this function gradually rotates the light source, changing the direction of the shadows and simulating the sun’s movement across the sky.

For added effect, you may wish to control the light color to simulate the warmer tones of sunrise or sunset:

tween.interpolate_property(directional_light, "color", directional_light.color, Color(1, 0.5, 0.3), 5, Tween.TRANS_LINEAR, Tween.EASE_IN_OUT)

This transition animates the color of your DirectionalLight2D from its current value to a warm orange-red over 5 seconds, giving the impression of a sunrise or sunset.

Fine control over shadow details can add to the realism as time progresses:

func update_shadow_details():
    directional_light.shadow_filter = Light2D.SHADOW_FILTER_PCF13
    directional_light.shadow_gradient_length = 5

This function would be called to adjust the shadow filtering method and the gradient length, softening the edges of shadows and varying their intensity similar to natural light conditions.

It’s important to note that these animations and effects should be calibrated to provide the best experience without distracting the player or impacting gameplay negatively. Subtlety is often key in these enhancements.

Implementing and mastering these techniques with DirectionalLight2D can bring your 2D game environments to life. With the optimally tuned interplay of light and shadow, you can create games that are visually stunning and emotionally resonant, setting the stage for memorable player experiences.

As a leading online academy to learn coding and game development, we at Zenva encourage aspiring game creators to delve into these concepts and explore the rich features Godot 4 has to offer. By doing so, you’ll not only enhance your technical skills but also unlock the potential to craft games that stand out in today’s competitive industry.

Integrating DirectionalLight2D with particle systems can create dynamic environmental effects. For example, imagine a scene where sunlight filters through moving tree leaves, casting dappled shadows on the ground. Here’s how you can set this up:

var particles =
var material =

material.emission_shape = ParticlesMaterial.EMISSION_SHAPE_SPHERE
material.emission_sphere_radius = 2

particles.process_material = material
particles.one_shot = true
particles.emitting = true


The particles should then be set as occluders to interact with the DirectionalLight2D, casting moving shadows:

var particles_occluder =
particles_occluder.occluder_polygon = PoolVector2Array([Vector2(-10, -10), Vector2(10, -10), Vector2(10, 10), Vector2(-10, 10)])

Environmental details, such as fog, are also enhanced with the use of DirectionalLight2D. With a simple shader on a ColorRect node, fog can be made to respond to the light direction:

var fog =
fog.material =

# Shader code to respond to light direction would be set here
# Example: fog.material.shader_code = "..." 


When your game transitions between scenes or certain events trigger, it can be very impactful to adjust lighting in real-time. Here’s a script to fade the light out and back in, simulating a blink or transition effect:

func fade_light_to_black(duration):
    tween.interpolate_property(directional_light, 'color', directional_light.color, Color(0, 0, 0, 1), duration)

func fade_light_to_normal(duration):
    tween.interpolate_property(directional_light, 'color', Color(0, 0, 0, 1), directional_light.color, duration)

Keep player’s visibility in mind when designing levels. You can use DirectionalLight2D to highlight important areas or objects:

func highlight_area(area_position, highlight_duration):
    var saved_rotation = directional_light.rotation
    var saved_energy =

    directional_light.rotation = get_angle_to(area_position) = 1.5  # Increase the light intensity temporarily
    # Schedule to revert the light back to previous state after the highlight duration
    yield(get_tree().create_timer(highlight_duration), "timeout")
    directional_light.rotation = saved_rotation = saved_energy

And lastly, for those tricky scenarios where you need light to follow or lead the player, DirectionalLight2D can also be animated to match the player’s position with a smooth follow effect:

func follow_player(player_position, follow_speed):
    var direction_to_player = position.direction_to(player_position)
    directional_light.rotation = direction_to_player.angle()
    directional_light.position += direction_to_player * follow_speed * delta

Remember, all these techniques are not only about visual tricks but also about enhancing the experience of gameplay. DirectionalLight2D is a valuable tool that, when used creatively, can bring out the best of your game’s graphics and create an engaging environment for your players.

We, at Zenva, believe in harnessing the power of technology to create immersive and captivating content. Through our tutorials and courses, we strive to empower creators and developers like you to transform their visions into reality, ensuring that each game crafted is not just played, but genuinely experienced and remembered.

Where to Go Next in Your Game Development Journey

Exploring the capabilities of DirectionalLight2D in Godot 4 is just the beginning of your adventure in game development. As you dive deeper into the world of Godot and harness its full potential, your skills will grow, and so will your creations. We know that learning is a continuous journey, and we’re here to support you every step of the way.

For those eager to take their Godot expertise further, we invite you to check out our Godot Game Development Mini-Degree, featuring a wide array of project-based courses. Whether you are a budding game developer or looking to polish your skills, these courses will help you create cross-platform games with Godot 4. Learn at your own pace with our 24/7 accessible content and earn certificates to showcase your accomplishments.

If you’re keen on broadening your Godot horizons, Zenva offers an extensive collection of Godot courses, covering a multitude of topics and techniques suitable for all skill levels. As you continue to learn and grow, remember that Zenva’s resources will be with you every step of the journey, from beginner to professional. Leap into the world of game development with confidence, bolstered by the knowledge and skills acquired through our comprehensive courses.


Mastering the nuances of lighting with DirectionalLight2D in Godot 4 is an essential skill for any game developer aiming to craft visually stunning games. The examples and techniques we’ve shared are stepping stones on your path to greater creativity and control in game design. Remember, each feature you learn to utilize opens a new realm of possibilities, from the subtle atmospheric shifts of a dynamic sky to the interactive shadows that bring your world to life.

We believe in your potential to create amazing games that resonate with players around the world, weaving together art, code, and storytelling. Continue your learning journey with Zenva’s Godot Game Development Mini-Degree and harness the power of Godot to turn your game development dreams into reality. Let’s build the future of gaming together—one line of code at a time.

Python Blog Image

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