CSGCombiner3D in Godot – Complete Guide

When diving into the world of 3D game development, it’s crucial to have tools that both streamline processes and simultaneously offer the flexibility to create intricate designs. That’s where the CSGCombiner3D class in Godot 4 comes into play. Imagine you are an architect who has been given the task of designing a state-of-the-art building. Instead of laboriously carving out the structure from a solid block of material, you’d naturally opt for a tool that allows you to combine various preformed shapes. CSGCombiner3D is much like that tool, but for game creators in the digital realm.

What is CSGCombiner3D?

CSGCombiner3D is a class in Godot 4 which inherits from CSGShape3D, linking it to the wider Constructive Solid Geometry (CSG) toolbox that Godot provides. This class serves as a container for combining different CSG nodes, thereby allowing developers to manage and perform complex operations on 3D shapes more effectively.

What is it for?

The primary purpose of CSGCombiner3D is to provide a structured approach to combining shapes when designing levels or objects in a 3D space. It encapsulates the results of its children CSG nodes, offering a way to simplify and organize the operations undertaken on various sets of shapes. This hierarchy not only aids in designing intricate objects but also maintains a clear and manageable workflow.

Why Should I Learn It?

Learning to use CSGCombiner3D can greatly enhance your Godot prowess, especially when it comes to prototyping levels and creating complex structures with ease. It introduces efficiency and clarity to your development process and can be an exceptional skill for crafting detailed game environments. Understanding its function can save time and computational resources, as well as open up new avenues for creativity in your game design toolkit.

CTA Small Image

Creating a Basic CSGCombiner3D Shape

Let’s start with the basics. To create a simple combined shape using CSGCombiner3D in Godot 4, you first need to set up a new scene with a CSGCombiner3D node as its parent. We’ll then add two child nodes, CSGBox3D and CSGSphere3D, to demonstrate the combiner’s functionality.

var combiner = CSGCombiner3D.new()
var box = CSGBox3D.new()
var sphere = CSGSphere3D.new()



With these lines of code, you will have a CSGBox3D and a CSGSphere3D combined into one shape within the CSGCombiner3D node. The resulting shape will be displayed as both geometries put together in the same space.

Manipulating Child Shapes

Moving and transforming the child shapes is essential to create more interesting and complex structures. Manipulate the position, rotation, and scale of the child shapes to see how they interact within the CSGCombiner3D node.

box.transform = Transform(box.transform.basis, Vector3(0, 0, 0))
sphere.transform = Transform(sphere.transform.basis, Vector3(1, 1, 0))

Here, we’re setting the position of the box to the origin and moving the sphere on the x and y axis. When adjusted within the parent CSGCombiner3D’s coordinate space, the two shapes will overlap differently—giving you a new combined shape.

Adding Subtractive and Intersecting Shapes

Constructive Solid Geometry isn’t only about adding shapes together but also subtracting one shape from another or finding their intersection. Let’s create a scenario where you subtract a CSGCylinder3D shape from the previously created box and sphere combination.

var cylinder = CSGCylinder3D.new()
cylinder.operation = CSGShape3D.OPERATION_SUBTRACTION

And to find an intersection of the box and cylinder:


The operation property defines how the shape interacts with the other children of the CSGCombiner3D node. In these code snippets, we are subtracting the cylinder from the combined shape and finding the intersection between the box and other shapes, which showcases the versatility of CSG operations.

Adjusting Material and Rendering Properties

Next, it’s important to know how to change the appearance of your combined shapes. This includes setting materials and other rendering properties. Below you’ll find examples of setting materials to your shapes.

var material = SpatialMaterial.new()
material.albedo_color = Color(1, 0, 0)

box.material = material
sphere.material = material
cylinder.material = material

This code applies a red color to the albedo (or diffuse) channel of the material, which is then set to each of the child shapes within the CSGCombiner3D. Now your shapes will not only be combined but also have a consistent appearance.

By following these examples and experimenting with the properties provided, you can start to craft more complicated and interesting geometries using CSGCombiner3D. This foundation will serve you well as you advance your 3D game development skills.

Exploring the capabilities of CSGCombiner3D further, we can try more complex combinations and configurations to refine our design. Here are additional code examples and information that can expand your usage of CSGCombiner3D for more advanced applications.

Let’s customize our shapes even more by defining custom mesh instances within the CSG shapes:

var custom_mesh = MeshInstance3D.new()
var mesh = CubeMesh.new()
custom_mesh.mesh = mesh

var shape = CSGMesh3D.new()
shape.mesh_instance = custom_mesh

This allows us to incorporate a custom mesh into the combiner, offering extended flexibility beyond the CSG primitives provided by Godot.

To illustrate creating patterns or repeating structures, you could use a loop to generate an array of shapes:

for i in range(5):
    var small_box = CSGBox3D.new()
    small_box.transform = Transform(small_box.transform.basis, Vector3(i * 2, 0, 0))

Here, we’re creating a line of five spaced boxes. This technique is handy for creating walls, stairs, or other repetitive architectural features.

We can also experiment with boolean operations such as toggling a particular shape on or off:

var toggle_shape = CSGSphere3D.new()
toggle_shape.use_collision = false

This snippet adds a toggle mechanism for collision detection on a shape, which could be useful during the prototyping phase when interactive elements aren’t yet finalized.

Additionally, we can optimize our scene by merging the shapes into one mesh:

combiner.calculate_tangents = true  # Calculate tangents for normal maps
combiner.use_collision = true  # Enable collision for the resulting shape
combiner.is_root_shape = true  # Designate this shape as the root for collision and rendering

This optimizes rendering and collision calculations, improving game performance by treating the combined shape as a single object.

Finally, let’s look at an example that allows you to dynamically change the operation of a CSG shape at runtime:

func _on_OperationButton_pressed(new_operation):
    for child in combiner.get_children():
        if child is CSGShape3D:
            child.operation = new_operation

Through this function, you are able to interact with your game environment in real-time, changing how shapes combine depending upon user input or game logic, adding an interactive element to your design.

Mastery of CSGCombiner3D in Godot 4 empowers you with creative and technical abilities to build detailed and optimized 3D environments. With these examples, you can start implementing more complex designs, establish efficient workflows, and breathe life into your game worlds. Remember, experimenting with these functions can give you deeper insights and enhance your game designs in ways that may not be immediately apparent, so we encourage you to explore and push the boundaries of what is possible with your creations.

Delving further into the potential of Godot’s CSGCombiner3D, let’s discover how we can manipulate combined shapes in real-time, affect the lighting and shadows they produce, and control their visibility – all of which are important for creating dynamic and immersive game environments.

Modifying a combined shape during gameplay can create interactive scenes. Here’s an example of scaling a CSGShape3D child on-the-fly:

func _process(delta):
    var child_shape = combiner.get_child(0)
    if child_shape is CSGShape3D:
        var scale_factor = 1 + sin(OS.get_ticks_msec() * 0.002)
        child_shape.scale = Vector3(scale_factor, scale_factor, scale_factor)

This snippet utilizes the sine function to provide a pulsating scaling effect to the first child of our CSGCombiner3D node, simulating a breathing effect which could be used for organic elements or interactive items in the game.

Shadows and lighting can drastically affect the mood of a game. Using Godot’s material properties, we can assign shadow casting behavior to our shapes:

var cast_shadow_material = SpatialMaterial.new()
cast_shadow_material.cast_shadow = SpatialMaterial.SHADOW_CASTING_SETTING_ON

for child in combiner.get_children():
    if child is CSGShape3D:
        child.material = cast_shadow_material

By applying this material to each CSG shape child, we’re making sure they all cast shadows in the scene, contributing to a more realistic and visually rich environment.

Controlling visibility can also play a crucial role in game mechanics, such as in stealth games or puzzles. You may implement a function to toggle visibility like this:

func toggle_visibility(on):
    for child in combiner.get_children():
        if child is CSGShape3D:
            child.visible = on

Calling this function with either ‘true’ or ‘false’ can show or hide all the CSGShape3D children of our combiner, making it a flexible method for gameplay or scene transitions.

CSGCombiner3D can also work alongside Godot’s physics engine to provide collision responses. This can be particularly useful in a physics-based game:

combiner.create_trimesh_shape()  # Creates a TrimeshShape for collision

Creating a TrimeshShape provides a collision shape that matches the complex geometry of your combined mesh, allowing for accurate physics interactions.

To enhance performance, especially with intricate or numerous combined shapes, it’s a good practice to bake the final mesh:

func _ready():
    yield(get_tree(), "idle_frame")

This should be done when changes to the combined shapes have been finalized, as it prevents further dynamic changes but significantly boosts performance by reducing the load on the CPU during runtime.

In addition to basic boolean operations, Godot’s CSG nodes can create more sophisticated shapes by manipulating the geometry directly. Consider an example where we merge vertices close to one another to create a smoother mesh:

combiner.snap_distance = 0.5
combiner.use_collision = true

Setting the ‘snap_distance’ property allows vertices within a certain range to merge, giving you a cleaner, more optimized shape. When combined with the collision property, it ensures the physical representation is as optimized as the visual one.

These examples showcase the versatility and adaptability of CSGCombiner3D within Godot 4. CSGCombiner3D is not just a static tool for building environment assets but can be used in creative ways to add interactive and dynamic elements to your games. Proper understanding and application of this node empower you to bring your game’s world to life with real-time transformations, sophisticated visual effects, and responsive physical interactions that delight players and enhance their gaming experience.

Where to Go Next in Your Godot Learning Journey

Mastering CSGCombiner3D and the intricacies of Godot 4 is just the beginning of your game development journey. As you continue building your skills and expanding your knowledge, we invite you to explore our Godot Game Development Mini-Degree. This comprehensive collection of courses will guide you through the creation of cross-platform games using the powerful and user-friendly Godot 4 engine.

At Zenva, we understand the importance of hands-on learning, which is why our courses are designed to be project-based, ensuring you gain practical experience as you progress. From crafting dynamic 2D and 3D worlds to implementing engaging gameplay mechanics, our Mini-Degree covers a wide array of essential game development skills that will help you bring your unique game ideas to life.

To broaden your horizons and delve into more specialized topics, peruse our full array of Godot courses. These lessons are available anytime, on any device, making learning flexible and convenient for your schedule. Take the next step; transform your passion for games into tangible projects and a diversified portfolio with Zenva—your adventure awaits!


Embarking on the journey of mastering Godot 4 and CSGCombiner3D is not just about learning to combine shapes; it’s about unlocking the full creative potential of 3D game design. Every new skill you acquire brings you closer to transforming your vision into a playable reality. Through our Godot Game Development Mini-Degree, you gain access to a wealth of knowledge that propels you forward in this exciting and ever-evolving field.

Remember, the path of a game developer is one of continuous learning and discovery. As you harness the power of Godot 4 with us by your side, you’re not just building games—you’re crafting the experiences that will captivate and inspire players around the world. Keep pushing the limits, keep innovating, and let Zenva be the companion that supports you through each line of code and every imaginative game world you create.

Python Blog Image

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