PointLight2D in Godot – Complete Guide

Welcome to our in-depth tutorial on the PointLight2D class within the recently released Godot 4. We’re about to plunge into the world of 2D lighting, exploring how you can add depth and ambiance to your games with positional lighting techniques. This tutorial is designed for both novice coders entering the realm of game development and seasoned developers looking to refine their lighting skills in a 2D environment. Together, we’ll unravel the mysteries of PointLight2D, discover its use cases, and learn why mastering it could be a game-changer for your projects. Let’s illuminate the path ahead and make your game worlds look more stunning than ever before.

What Is PointLight2D?

PointLight2D is a class in Godot 4 that allows you to create dynamic, positional light sources within your 2D scenes. It is an extension of the Light2D class, meaning it offers all the foundational features of 2D lighting, but with a focus on point illumination.

What Is It For?

This type of light emits equally in all directions from a single point, similar to how a lamp or a candle would in real life. The light’s shape and intensity can be controlled using textures, often grayscale, to create various atmospheric effects. It’s an essential tool for any developer wanting to enhance the visual appeal and mood of their game.

Why Should I Learn It?

Understanding how to use PointLight2D is crucial for several reasons:
– It allows you to add depth and realism to a flat 2D world.
– You can create different moods and atmospheres in your game levels.
– It gives you the ability to highlight specific areas, guiding the player’s attention.
– It enhances gameplay by integrating lighting into puzzles and mechanics.

By mastering PointLight2D, you’ll take a significant leap forward in producing professional-looking game environments that captivate and engage players.

CTA Small Image

Creating a Basic Point Light

Let’s start simple by creating a basic PointLight2D that can be used in any 2D scene.

var point_light = PointLight2D.new()
point_light.texture = preload("res://path_to_your_light_texture.png")
point_light.enabled = true

This code snippet demonstrates how to create a new PointLight2D instance, set its texture (which defines the shape and falloff of the light), enable it, and add it to the scene.

Adjusting Light Properties

Once the light is part of your scene, you may want to adjust its properties to fit your needs. Here’s how to modify the most common settings programmatically:

point_light.color = Color(1, 0.5, 0) # Orange light
point_light.energy = 2.0 # Brightness of the light
point_light.range = 150 # How far the light reaches

This code alters the color of the PointLight2D to orange, increases its brightness, and sets the range of the light to 150 pixels.

Animating the Light

Animating your PointLight2D can create dynamic and engaging effects. We can, for example, animate the energy of the light to simulate a flickering candle.

# Assuming this code is inside a function connected to a timer's timeout signal
point_light.energy = rand_range(1.8, 2.2)

This example uses the `rand_range` function to randomize the light’s energy, subtly changing its intensity over time, which can be called within a timer loop to create the flickering effect.

Interacting with Physics

PointLight2D can also interact with the physics system within Godot 4. Using light masks, we can make lights only affect certain objects in the scene.

Here’s how to set a light mask for our light and a collision object to only interact with this light.

# Set the light mask for the PointLight2D
point_light.mask = 1

# Assuming you have a physics body, like a KinematicBody2D
var body = KinematicBody2D.new()
body.collision_mask = 1
# This body will now interact with the light

This snippet assigns the light to a mask of 1, and any physics object with a collision mask that includes 1 will interact with this light.

By now, you should have a solid understanding of how to create and control basic PointLight2D in Godot 4. Up next, we’ll dive into more advanced features and show some creative ways to utilize PointLight2D in your games. Stay tuned for our next tutorial segment where the magic of 2D lighting with Godot 4 really starts to shine!

Using Texture Modes

Textures in PointLight2D can be used in different modes to achieve various effects. By default, the texture mode is set to ‘Add’, but you can change this to create unique lighting scenarios.

// Set the light's texture mode to "Mix" which blends with the underlying colors
point_light.texture_mode = Light2D.TEXTURE_MODE_MIX

In this example, we change the texture mode to ‘Mix’, which will blend the light with the scene’s colors, resulting in a more subdued lighting effect.

Shadows and Occlusion

An important feature of PointLight2D is its ability to cast shadows.

point_light.shadow_enabled = true
point_light.shadow_color = Color(0, 0, 0, 0.5) // Semi-transparent black for soft shadows

By enabling shadows and setting a shadow_color, you can create soft dark areas that add a layer of depth and realism to your scenes.

If you wish to have an occluder in your scene, you will need to use an Occluder2D node.

var occluder = Occluder2D.new()
occluder.polygon = PoolVector2Array([Vector2(0,0), Vector2(0,100), Vector2(100,100), Vector2(100,0)])

This code creates a new Occluder2D, defines a rectangular shape for it, and adds it to the scene, which the PointLight2D will then recognize to cast shadows.

Animating Color and Range

We can animate both the color and range of a PointLight2D to enhance the visual dynamics of the scene.

// Animate color over time
point_light.color = point_light.color.linear_interpolate(Color(1, 1, 0), 0.1) // Gradually change color to yellow

// Animate range over time
point_light.range = lerp(point_light.range, 250, 0.1) // Smoothly interpolate the range to 250 pixels

The first line demonstrates how to gradually transition the light’s color to yellow, while the second line shows how to interpolate the light’s range for a pulsing effect.

Scripting Intensity Fluctuations

Simulating a light source with fluctuating intensity can add a dramatic and lifelike quality to the lighting.

// Assume `base_energy` is predefined as the standard light brightness
var fluctuation = sin(OS.get_ticks_msec() * 0.001) * 0.1
point_light.energy = base_energy + fluctuation

Here, we use a sinusoidal wave to create a periodic fluctuation in the light’s brightness, simulating something like a wavering flame.

Interacting with Game Entities

Lights can also be used to indicate the player’s interactions with the game world. For example, if a character activates an object, the PointLight2D can react accordingly.

// If the player activates an object, make the light flicker
func _on_object_activated():
    point_light.color = Color(1, 0, 0) // Change to a red light
    # Further code to create a flickering effect

This function changes the light’s color to red when an in-game object is activated, signaling the player about the change.

Through these examples and more, you’ve seen some of the versatile and engaging ways PointLight2D can be used in your Godot 4 projects. The class offers a wealth of possibilities for enhancing the visual storytelling and gameplay experience of your 2D games. Remember, lighting in games isn’t just about illumination—it’s about creating a mood, directing player focus, and bringing your digital world to life.

Advanced Shadow Techniques

Creating a sense of depth with shadows can make your 2D worlds look more immersive. Let’s take a look at how to achieve advanced shadow effects with PointLight2D.

// Configure smoother edges for shadows
point_light.shadow_smooth = 0.1

Here, `shadow_smooth` is tweaked to soften the shadow edges, making them less harsh and more natural-looking.

You can also use code to create moving shadows, which can give the impression of dynamic light sources or moving objects.

// Move an occluder to simulate moving shadows
func _process(delta):
    var occluder_position = Vector2(sin(OS.get_ticks_msec() * 0.002), 0)
    get_node("Occluder2D").position += occluder_position * delta

In this script, an Occluder2D is moved back and forth using a sine wave function based on the system time, thereby creating moving shadows in the scene.

Script-Controlled Properties

You might want to change the properties of the light based on game events or interactions. Here’s how to tweak properties such as the light’s energy and range via code.

// Boost the light's energy temporarily when picking up a power-up
func _on_power_up_pickup():
    point_light.energy += 1.0
    yield(get_tree().create_timer(2.0), "timeout")
    point_light.energy -= 1.0

This function increases the light’s energy when a power-up is picked up, then, after a delay of 2 seconds, decreases it back down.

Now consider a case where you want the light’s range to expand, perhaps to reveal a larger area when an in-game item is used:

// Enlarge the light's range and then gradually return to its original size
func _on_expand_area_item_used():
    var original_range = point_light.range
    point_light.range = 300
    yield(get_tree().create_timer(3.0), "timeout")
    point_light.range = original_range

Upon using an item, the light’s range is increased significantly, then after three seconds, it’s reverted back to the original range.

Layering Lights for Depth

Layering multiple PointLight2Ds can result in even richer lighting effects.

// Create a second, smaller point light atop the original for a halo effect
var halo_light = PointLight2D.new()
halo_light.texture = preload("res://halo_light_texture.png")
halo_light.range = 75
halo_light.energy = 0.5
halo_light.z_index = point_light.z_index + 1 // Ensure it renders above the original

By adding a smaller, less intense light on a higher Z index, you create a halo effect around the primary light, adding depth and interest.

Responsive Light Intensity

You can also make your lights respond to the in-game environment, such as dimming when underwater or in a foggy area.

// Dim the light when the character is underwater
func _on_character_enters_water():
    point_light.color = Color(0.2, 0.5, 1) // Blue-tinted light for underwater
    point_light.energy = 0.6 // Dimmed energy for a submerged effect

The code above changes the light’s energy and color to simulate a submerged atmosphere when a character enters a water zone in-game.

Combining Lights with Particle Effects

By cleverly combining PointLight2Ds with particle systems, you can create magical effects or simulate fire and explosions.

// Add a flickering effect to a fire particle system
func _process(delta):
    var flicker = rand_range(-0.2, 0.2)
    point_light.energy = base_energy + flicker

The code snippet adds a flickering effect to the light that accompanies a fire particle effect, making the fire seem alive with its fluctuating brightness.

These examples should give you a clearer view of the myriad ways you can use PointLight2D to get creative with lighting in your Godot 4 projects. Remember, lighting plays an essential role in setting the mood and transforming the aesthetic quality of your game. Whether you aim to create atmospheric cities, gloomy dungeons, or vibrant landscapes, PointLight2D offers you the versatility to bring your vision to life.

Continue Your Game Development Journey

You’ve made great strides in understanding the PointLight2D class in Godot 4. Now that you have the basics down and a few advanced techniques up your sleeve, it’s the perfect time to take your skills even further. At Zenva, we’re keen on supporting your growth as a game developer, and our Godot Game Development Mini-Degree is an excellent way to keep learning and building your proficiencies.

Our Mini-Degree is a treasure trove of knowledge, waiting for you to unlock the doors to creating your own fantastic games using Godot 4. With in-depth courses on a wide spectrum of topics from 2D and 3D assets to GDScript and various game mechanics, you can go from beginner to professional at your own pace.

And when you’re ready to explore even more, check out our full range of Godot courses to find content that will suit your specific needs and interests. Whether you’re looking to sharpen your basics or tackle new challenges, we at Zenva have your back all the way through your game development journey. So dive in, and let’s create amazing things together!


Congratulations on taking this deep dive into the PointLight2D class for Godot 4! The art of lighting is indeed a vital aspect of game development that can bring your creations to life. Remember, every light you craft is not just a source of visibility but a brushstroke in the grand painting of your game’s world.

We at Zenva are excited to see how you illuminate your projects with the newfound knowledge and skills. Keep experimenting, keep learning, and when you’re ready to add even more tools to your game development kit, our Godot Game Development Mini-Degree is here to guide you. Each victory in learning is a level up in your developer journey, and we can’t wait to join you on your quest to create the next standout indie game. Shine on, creators!

Python Blog Image

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