QuadOccluder3D in Godot – Complete Guide

Learning about the various components of a game engine can unlock a whole new world of optimization and efficiency for your game development projects. Today, we dive into the QuadOccluder3D class in the powerful Godot 4 engine. Whether you’re a budding game developer or a seasoned programmer looking to polish your skills, understanding how to leverage the occlusion culling system in Godot can significantly improve your game’s performance. Let’s set out on a journey to discover how this seemingly simple feature can greatly enhance your 3D environments.

What is QuadOccluder3D?

QuadOccluder3D is a specific type of resource within the Godot engine dedicated to occlusion culling. In essence, occlusion culling is a technique used to improve rendering performance by not drawing objects that are obstructed from the camera’s view. The ‘Quad’ prefix denotes that this occluder uses a flat plane shape, making it ideal for simple blocking objects such as walls or large flat surfaces.

What is it for?

The primary purpose of a QuadOccluder3D is to define areas in your game that can hide other objects from the camera’s perspective. When setup properly within the scene, it signals the engine to skip rendering of the covered objects, thereby saving valuable processing power and potentially increasing your game’s framerate.

Why Should I Learn It?

With the gaming industry pushing towards more complex and visually stunning titles, the need for optimization is greater than ever. By learning how to use the QuadOccluder3D component effectively, you will be equipping yourself with the skills to manage the rendering workload of your games, making them run smoother on a wide range of hardware. This proficiency not only improves your game’s performance but also deepens your understanding of spatial relationships and engine efficiencies within 3D game development.

CTA Small Image

Setting up the Scene

First and foremost, let’s start by setting up a basic scene in Gododt. We’ll need a 3D environment with some objects that can be occluded. Here is how you set up your main scene:

var main_scene = PackedScene.new()
ResourceSaver.save("res://MainScene.tscn", main_scene)

Once you have your main scene, create a static body as your occluder holder and attach a QuadOccluder3D to it.

var static_body = StaticBody.new()
static_body.name = "OccluderHolder"

var quad_occluder = QuadOccluder3D.new()

Adjusting the Occluder’s Transform

Positioning your occluder correctly is crucial. You want it to represent a wall or another large, flat surface in your game that will block the view of objects behind it.

quad_occluder.transform = Transform(Basis(), Vector3(0, 0, 5))

It’s a good idea to adjust the size of the QuadOccluder3D to match that of the real-world object it is representing for accurate occlusion culling.

quad_occluder.size = Vector2(10, 5)

Setting Up Occludees

Next, let’s define some meshes that we want to be occluded. These will be set up as child nodes to our main scene.

var mesh_instance = MeshInstance3D.new()
mesh_instance.mesh = some_mesh_resource

And make several of these occludees to test our QuadOccluder3D:

for i in range(5):
    var mesh_instance = MeshInstance3D.new()
    mesh_instance.mesh = some_mesh_resource
    mesh_instance.transform = Transform(Basis(), Vector3(i*3, 0, 10))

Visualizing Occluded Objects

For testing purposes, we might want to visualize which objects are being occluded. Below is the way you can toggle the visibility of occluded objects using a simple debug mode.

quad_occluder.debug_mode = QuadOccluder3D.DEBUG_MODE_VISIBLE

This will flag the occluded objects with a visual indicator, confirming the QuadOccluder3D’s effect in your scene. Remember to turn this feature off in the production version of your game to maintain immersion.

Scripting Occlusion Logic

Lastly, it’s time to add some logic to automatically occlude objects behind the QuadOccluder3D. We can do this by extending the visibility notifier functionality.

extends VisibilityNotifier3D

func _ready():
    connect("screen_entered", self, "_on_ScreenEntered")
    connect("screen_exited", self, "_on_ScreenExited")

func _on_ScreenEntered():
    # Logic to handle when the object appears on screen

func _on_ScreenExited():
    # Logic to handle when the object is no longer visible

By connecting to the “screen_entered” and “screen_exited” signals, we can manage the occluded state of objects and potentially even cull them from the physics processing when not visible.

Stay tuned for the next section, where we’ll advance our example to include dynamic occluders and delve into how to handle moving objects and camera perspective changes.

Advancing from our static scenario, dynamic occluders add another layer of complexity to our occlusion culling strategy. Especially when dealing with moving cameras and objects, we need to update the occlusion information in real-time to ensure our scene remains efficiently rendered. Let’s look into how we can achieve this.

Firstly, for dynamic objects that can potentially be occluders, we need to attach an OccluderInstance3D to them. This instance will move with the occluder, ensuring the occlusion culling is accurate.

var dynamic_occluder = OccluderInstance3D.new()
var dynamic_body = RigidBody.new()

Now, suppose we have a moving camera in our scene. We can use the camera’s signals to update our occlusion culling.

var camera = Camera3D.new()
camera.connect("camera_moved", self, "_on_CameraMoved")

func _on_CameraMoved():
    # Update your occlusion culling logic here.

In the case of moving objects, we must update the culling information each time the object’s transform changes.

func _process(delta):
    for mesh_instance in get_tree().get_nodes_in_group("occludees"):
        if mesh_instance.transform.origin.distance_to(camera.global_transform.origin) > MAX_VISIBILITY_DISTANCE:
            # Logic to handle occlusion based on distance to the camera

If you have animated characters or objects that could be either occluders or occludees, you’ll want to ensure that their animations do not interfere with the culling process.

var animated_occludee = AnimationPlayer.new()
animated_occludee.connect("animation_finished", self, "_on_AnimationFinished")

func _on_AnimationFinished(anim_name):
    # Check if the animation might have moved the entity out of occlusion
    # If so, update occlusion information

It’s also essential to think about how level of detail (LOD) meshes and occlusion culling will work together. You can set different LOD levels for your meshes and update them based on the occlusion state.

func _process(delta):
    for mesh_instance in get_tree().get_nodes_in_group("lod_meshes"):
        var distance_to_camera = mesh_instance.transform.origin.distance_to(camera.global_transform.origin)
        # Update your occlusion culling logic accordingly

Lastly, consider the potential impact of lighting on occlusion culling. Dynamic lights might illuminate occluded areas, which in turn could affect your occlusion logic.

var dynamic_light = OmniLight3D.new()
dynamic_light.connect("visibility_changed", self, "_on_VisibilityChanged")

func _on_VisibilityChanged():
    # Check for objects that might now be visible due to the light's influence
    # Update occlusion information accordingly

As you can see, occlusion culling in a dynamic environment is complex and requires constant updates to ensure optimal rendering performance. Through careful planning and the use of Godot 4’s tools, you can achieve significant performance gains. Stay proactive in your updates, and consider the many scenarios that might affect occlusion in your game. That way, you might just squeeze out the extra frames per second that make your game that much smoother.

The next step in refining our occlusion culling system involves leveraging Godot 4’s signals and advanced scripting capabilities to handle complex scenarios. Here are some examples of how to handle various conditions that might affect the occlusion of moving objects.

Consider a scenario where objects can move in and out of occlusion based on their own logic or player interaction. We can check for changes in visibility within the process loop and update their occlusion state accordingly.

func _process(delta):
    for movable in get_tree().get_nodes_in_group("movable"):
        if is_occluded(movable):
            # Logic to cull or hide the object.
            # Logic to reveal or uncull the object.

But how do we decide if an object is occluded? That requires a function that checks if any occluders are between the camera and the object.

func is_occluded(target):
    # Perform a raycast from camera to the target position
    # Return true if an occluder is hit by the raycast

Now, what about objects that not only move but also change their shape? A morphing mesh can suddenly occlude previously visible objects or vice versa. We’ll need to react to shape changes:

func _on_MeshShapeChanged(mesh_instance):
    # Update occlusion information based on new mesh bounds

In a multiplayer scenario, you’d have to consider network-synchronized occlusion culling. For this, you can use RPC calls to ensure all clients update their occlusion information based on changes that occur on other clients.

rpc_config("update_occlusion_info", MULTIPLAYER_RPC_MODE_REMOTESYNC)
func update_occlusion_info(occluder_id, is_occluding):
    # Logic to update the scene based on network state

For dealing with groups of objects, like a flock of birds or a squad of enemies, we can iterate over these groups and determine their occlusion as a unit. This reduces the number of calculations when proximity to each other can imply shared visibility status.

func _process(delta):
    for group in get_tree().get_nodes_in_group("flocks"):
        var occluded = is_occluded(group[0]) # Check occlusion status of the group leader
        for member in group:
            # Apply the group leader's occlusion status to all members

Regardless of the scenario, it’s essential to have efficient and robust logic to determine occlusion. It’s recommended to use profiling tools within Godot to measure the performance gain from your occlusion culling setup. This will help you refine the balance between the computational cost of culling and the performance improvement it provides.

Keep in mind that performance optimizations are about finding balance. Too aggressive with occlusion culling, and you may end up with objects popping in and out of view jarringly. Too lenient, and you lose out on performance gains. Testing and incremental adjustments are key to finding this sweet spot.

With these advanced scripting techniques at your disposal, you’re well on your way to mastering occlusion culling within the Godot engine. The examples provided demonstrate the flexibility and power of Godot 4’s scripting API, making it possible to tailor an occlusion culling system that fits the unique needs of your game.

Where to Go Next in Your Godot 4 Journey

Diving into the intricacies of the QuadOccluder3D class is just the beginning of crafting highly optimized and visually compelling 3D games with Godot 4. Now that you’ve started, it’s crucial to keep the momentum going by exploring more advanced techniques and continuous learning.

To further sharpen your Godot game development skills, consider enrolling in our Godot Game Development Mini-Degree. This program offers a structured learning path covering everything from GDScript fundamentals to complex gameplay mechanics across various game genres. It’s the perfect next step to transform your rudimentary understanding into professional prowess, empowering you to create your own cross-platform games from scratch.

And if you’re looking to expand your knowledge beyond what’s covered in the Mini-Degree, or you’re interested in specific areas within Godot, we have a broad collection of Godot courses to suit all learning stages. Whether you’re a beginner or looking to refine existing skills, Zenva’s courses are designed to boost your career and help you build a strong portfolio of real Godot projects. Chart your path in game development and begin crafting the immersive experiences you’ve always dreamt of with Zenva.


Embracing the technical aspects of game development, such as learning to implement occlusion culling with QuadOccluder3D in Godot 4, is a journey that pays dividends in the polish and performance of your games. The pursuit of knowledge within the expansive universe of game programming is ongoing, but every step forward is a leap towards creating more immersive and responsive worlds for players to lose themselves in. At Zenva, we understand this passion and strive to provide the tools necessary to turn your game development dreams into reality.

As the pixel dust settles, we hope that you feel better equipped to tackle the challenges of 3D game design in Godot 4. And remember, our Godot Game Development Mini-Degree offers a treasure trove of knowledge just waiting to be unlocked. Seize this opportunity to expand your skillset, stand out in the world of game development, and start crafting the games that tomorrow’s players will cherish.

Python Blog Image

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