CSGShape3D in Godot – Complete Guide

Welcome to our comprehensive guide on CSGShape3D class in Godot 4. Constructive Solid Geometry (CSG) is a powerful feature that allows you to create complex 3D shapes by combining simpler ones. Throughout this tutorial, we’ll dive into the capabilities that CSGShape3D offers—perfect for both beginners and experienced developers who want to quickly prototype levels or create intricate designs with ease.

What is CSGShape3D?


is a class in Godot Engine that serves as the base for performing CSG operations within the game environment. CSG, or Constructive Solid Geometry, provides an intuitive way to build complex 3D models by using simple shapes as building blocks. The


class in Godot enables us to use boolean operations like union, intersection, and subtraction to combine shapes in various ways.

What is it for?

Godot’s CSG features are primarily used for level prototyping. It allows level designers and developers to carve out space, add intricate details, or construct entire levels from simple geometric shapes. This can significantly accelerate the design process and provide immediate visual feedback within the Godot editor.

Why Should I Learn It?

Mastering CSGShape3D can be a game-changer for your prototyping workflow. Understanding how to efficiently use CSG can:

– Save time by quickly putting together level layouts.
– Enhance creativity by allowing you to experiment with complex shapes without the need for external 3D modeling tools.
– Simplify the collaboration process, as it’s easier to iterate on game levels when using a shared toolkit like Godot’s CSG system.

Learning CSGShape3D opens up new possibilities for rapid 3D content creation, making it a valuable skill in any game developer’s toolkit. Let’s get started and discover the full potential of CSG in Godot!

CTA Small Image

Creating Basic CSG Shapes

Let’s start by creating basic CSG shapes in Godot. We’ll need to add CSG nodes to our scene. Here’s how to create a simple CSG box:

var csg_box = CSGBox3D.new()
csg_box.width = 2.0
csg_box.height = 1.0
csg_box.depth = 1.0

The above script will add a rectangular box to our scene. You can adjust the width, height, and depth to size it according to your needs.

Now, to create a CSG sphere:

var csg_sphere = CSGSphere3D.new()
csg_sphere.radius = 1.0
csg_sphere.material = preload("res://your_material.tres")

This code snippet adds a sphere to our scene and assigns it a material. Make sure to replace “res://your_material.tres” with the path to your own material resource file.

Combining CSG Shapes with Boolean Operations

With the basics down, let’s combine shapes through boolean operations. We’ll start with a union, which fuses two shapes together:

var csg_box = CSGBox3D.new()
var csg_sphere = CSGSphere3D.new()
csg_sphere.translation = Vector3(0, 1, 0)

var csg_combiner = CSGCombiner3D.new()
csg_combiner.operation = CSGShape3D.Operation.UNION


This code creates a new combiner and uses it to combine a box and a sphere into a single shape.

Next, we’ll subtract one CSG shape from another:

var csg_box = CSGBox3D.new()
var csg_cylinder = CSGCylinder3D.new()
csg_cylinder.translation = Vector3(0, 1, 0)

var csg_combiner = CSGCombiner3D.new()
csg_combiner.operation = CSGShape3D.Operation.SUBTRACTION


Here, we’re using a cylinder to cut a hole through a box, creating a complex shape with an empty space inside.

Intersecting Shapes and Adjusting Parameters

Intersecting shapes allows you to create a new shape from the space where they overlap. Here’s how it’s done:

var csg_box = CSGBox3D.new()
var csg_sphere = CSGSphere3D.new()
csg_sphere.translation = Vector3(0, 1, 0)

var csg_combiner = CSGCombiner3D.new()
csg_combiner.operation = CSGShape3D.Operation.INTERSECTION


In this example, the resulting shape will only be the volume where the box and sphere overlap.

This section has shown you how to create and combine simple CSG shapes using boolean operations such as union, subtraction, and intersection. By mastering these basic functions, you can now start experimenting with your own designs, leading to more unique and sophisticated 3D models in your Godot projects. Continue to the next part where we’ll delve into more advanced operations and optimization techniques.Sure, let’s dig deeper into some advanced features and tips for using CSGShape3D to craft even more intricate models.

One powerful feature of CSG is the ability to combine multiple operations to create a series of compound shapes. Here’s an example:

var csg_box = CSGBox3D.new()
var csg_sphere = CSGSphere3D.new()
var csg_cylinder = CSGCylinder3D.new()

csg_sphere.translation = Vector3(0, 1, 0)
csg_cylinder.translation = Vector3(0, -1, 0)

var csg_union = CSGCombiner3D.new()
csg_union.operation = CSGShape3D.Operation.UNION


var csg_subtract = CSGCombiner3D.new()
csg_subtract.operation = CSGShape3D.Operation.SUBTRACTION



This complex code will create a shape that is the result of a sphere union-ed with a box, and then that resultant shape is subtracted by a cylinder.

Another advanced operation is to dynamically change the properties of CSG nodes to animate your CSG shapes:

var csg_box = CSGBox3D.new()
var t = 0.0

func _process(delta):
    t += delta
    csg_box.depth = 2.0 + sin(t) * 0.5

This script will make the box “breathe”, changing its depth with an oscillating pattern.

You can also use CSG for environmental elements such as creating windows or doorways in walls:

var wall = CSGBox3D.new()
wall.width = 8.0
wall.height = 3.0
wall.depth = 0.5

var door = CSGBox3D.new()
door.width = 1.0
door.height = 2.0
door.depth = 0.6
door.translation = Vector3(0, -0.5, 0)

var wall_with_door = CSGCombiner3D.new()
wall_with_door.operation = CSGShape3D.Operation.SUBTRACTION



This code creates a doorway by subtracting a smaller box from a larger wall-shaped box.

Another practical tip when using CSG shapes is to be careful with the level of detail and complexity to maintain performance:

var csg_sphere_high_detail = CSGSphere3D.new()
csg_sphere_high_detail.smooth_faces = true
csg_sphere_high_detail.radial_segments = 100
csg_sphere_high_detail.rings = 50

This high-detail sphere may look smooth and precise, but it’s resource-intensive. For better performance, especially when handling multiple CSG shapes, you should use lower polygon counts where possible:

var csg_sphere_low_detail = CSGSphere3D.new()
csg_sphere_low_detail.smooth_faces = false
csg_sphere_low_detail.radial_segments = 16
csg_sphere_low_detail.rings = 8

Finally, remember that while CSG is a great tool for prototyping, optimizing your final game requires converting CSG shapes to MeshInstances for better performance. Here’s how you can convert a CSG shape to a mesh:

var csg_box = CSGBox3D.new()
var mesh_instance = MeshInstance3D.new()
mesh_instance.mesh = csg_box.mesh

With these examples and tips, you’re equipped to handle more complex scenarios when designing with CSGShape3D in Godot. Use these powerful features carefully, always keeping an eye on performance, and let your creativity run wild with the shapes you can build!Certainly! Let’s build on our current knowledge by exploring additional ways to refine and control your CSG shapes in Godot. Applying material to your CSGShapes for visual flair is quite straightforward. Let’s see how you can do this:

var csg_box = CSGBox3D.new()
var material = preload("res://your_material.tres") 
csg_box.material = material

This assigns a preloaded material to our CSG box. Make sure that you’ve replaced “res://your_material.tres” with the correct path to your material file.

In case you would like to create a hollow object, such as a pipe, you would use CSGPoyl’s inner path feature:

var csg_poly = CSGPolygon3D.new()
csg_poly.polygon.push_back(Vector3(-1, -1, 0))
csg_poly.polygon.push_back(Vector3(1, -1, 0))
csg_poly.polygon.push_back(Vector3(1, 1, 0))
csg_poly.polygon.push_back(Vector3(-1, 1, 0))
csg_poly.depth = 5
csg_poly.mode = CSGPolygon3D.Mode.PATH
csg_poly.path_continuous_u = true
csg_poly.path_interval = 1.0
csg_poly.path_rotation = CSGPolygon3D.PathRotation.POLYGON

This defines a square cross-section, replicated along the z-axis, resulting in a square pipe object.

The smoothing groups can be manipulated to create smooth or sharp transitions:

var csg_box1 = CSGBox3D.new()
var csg_box2 = CSGBox3D.new()
csg_box2.smoothing_group = 1

var csg_combiner = CSGCombiner3D.new()
csg_combiner.operation = CSGShape3D.Operation.UNION
csg_combiner.use_collision = false


In this case, the two boxes will be union-ed smoothly due to being in different smoothing groups.

You can also use Godot’s scripting to make real-time adjustments to your CSG shapes, such as adding a script that dynamically changes the shape’s dimensions based on user input or other in-game events:

var csg_box = CSGBox3D.new()

func _input(event):
    if event is InputEventMouseMotion:
        csg_box.width = clamp(csg_box.width + event.relative.x * 0.01, 0.1, 10)
        csg_box.height = clamp(csg_box.height + event.relative.y * 0.01, 0.1, 10)

This dynamically changes the width and height of the box as we move the mouse across the screen, great for interactive applications or games requiring real-time shape manipulation.

Remember, when using CSG nodes to create moving or animated objects, it’s important to update the collision shapes if the geometry changes:

var csg_box = CSGBox3D.new()
csg_box.use_collision = true

func _process(delta):
    csg_box.width = 2.0 + sin(OS.get_ticks_msec() * 0.001) * 1.0

This example will cause the box to oscillate in width, and by calling `update_collision_shape()` every frame, we ensure that the collision shape matches the visual shape.

Lastly, you can use scripts to build combinations of CSG shapes, creating more complex objects programmatically:

var csg_tower = CSGCombiner3D.new()
csg_tower.operation = CSGShape3D.Operation.UNION

for i in range(3):
    var floor = CSGBox3D.new()
    floor.width = 5
    floor.height = 0.2
    floor.depth = 5
    floor.translation = Vector3(0, i * 0.5, 0)

var csg_roof = CSGCylinder3D.new()
csg_roof.radius = 2.5
csg_roof.height = 1.0
csg_roof.translation = Vector3(0, 1.5, 0)


This example builds a simple three-story tower with a cylindrical roof. This technique can be incredibly useful in randomly generating structures or landscapes.

As you dive further into CSGShape3D, the possibilities become endless. Creativity and efficiency in use can result in incredibly detailed scenes, customized objects, or anything else you might envision for your Godot project. Experiment with these examples and see how you can implement CSG shapes into your workflow to enhance your game’s environment and experience!

Continuing Your Game Development Journey

You’ve taken an exciting step into the world of 3D modeling and level design with Godot’s CSGShape3D class. But where should you go from here? To truly master Godot and game development, consider taking your skills to the next level with our Godot Game Development Mini-Degree. This collection of courses will guide you through building cross-platform games with Godot 4, covering essential topics such as GDScript, UI systems, and a variety of game mechanics.

Our curriculum is designed to transition you from beginner tutorials to advanced content, ensuring that, no matter your starting point, you can become proficient in game development. With our structured learning path, you can build a comprehensive portfolio of real Godot projects and gain the knowledge needed to start your career in the industry. And if you’re looking for more expertise in specific areas, explore our broad collection of Godot courses.

Begin your journey with confidence, knowing that Zenva’s library of over 250 supported courses is there to back you up. From mastering the basics to pushing the boundaries of what you can create, we’re here to support every step of your game development journey. Happy coding!


In your hands now is the power to craft, conjure, and combine shapes in ways only limited by your imagination. But this is just the beginning! You’ve scratched the surface of what’s possible with Godot’s CSGShape3D, a tool that unlocks rapid prototyping and creative design. When you’re ready to expand beyond CSG and dive deeper into Godot’s vast ocean of features, our Godot Game Development Mini-Degree awaits.

As you continue your journey, each step forward with us at Zenva will refine your skills, push your boundaries, and shape you into a developer capable of bringing your grandest game ideas to life. Remember, whether you’re sketching out the first lines of code or polishing the final pixels of your game, we’ll be here to guide you through every challenge and celebrate every victory. Now, go forth and create incredible 3D worlds that are uniquely yours!

Python Blog Image

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