CSGPrimitive3D in Godot – Complete Guide

Welcome to this tutorial on CSGPrimitive3D, a key class in the world of Godot 4. If you’ve been dabbling with this incredible game engine or are thinking about starting, understanding how to use constructive solid geometry (CSG) will be an invaluable part of your development toolkit. CSG offers a unique way to create complex shapes and structures by combining simple primitives, such as boxes, spheres and cylinders, in intuitive ways. So buckle up as we dive into the exciting world of CSG in Godot 4, and discover how you can use these tools to bring your game worlds to life!

What is CSGPrimitive3D?

CSGPrimitive3D stands for Constructive Solid Geometry Primitive 3D. In essence, it is the backbone of a powerful modelling technique used within Godot 4 to combine simple shapes, or “primitives,” to create more complex 3D models. Think of it like using building blocks to craft the structure of your dreams.

What is it for?

This class is designed to streamline the creation process for game prototyping. By using primitives, you can rapidly construct and visualize levels without the need for external modeling software. It lays down the foundation for other CSG shapes, making it a vital aspect of level design in Godot 4.

Why Should I Learn It?

Understanding CSGPrimitive3D is essential for anyone who wants to prototype and build levels efficiently in Godot 4. It’s particularly advantageous for developers who want to stay within the engine for most of their development work. Moreover, given that CSG nodes are resource-intensive, learning how to use them correctly from the outset can save you significant development time and ensure smoother gameplay.

Part 1 of this tutorial has given you an overview of what CSGPrimitive3D is and why it’s beneficial to learn. Stay tuned as we go deeper into how to use this class with practical code examples and create something that really showcases the strength of CSG in Godot 4.

CTA Small Image

Creating a Simple CSG Box

To begin, let’s start simple by creating a CSG box, which is a standard 3D cube that can serve as a building block for various structures.

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

This code snippet sets up a basic CSGBox3D node, assigning it a width, height, and depth of 2.0 each, making it a perfect cube before adding it to the scene.

Manipulating CSG Box Properties

Next, let’s manipulate the properties of our CSG box to become more familiar with the control you have over these shapes.

var csg_box = CSGBox3D.new()
csg_box.material = preload("res://path_to_material.tres")
csg_box.width = 4.5
csg_box.height = 2.5
csg_box.depth = 3.0
csg_box.use_collision = true

Here, apart from changing the dimensions, we’ve also included material to the box and enabled collision.

Combining CSG Shapes

One of the strengths of CSG is creating more complex shapes by combining simple ones. Let’s cut a hole in our CSG box with a CSG cylinder.

var csg_box = CSGBox3D.new()
csg_box.width = 5.0
csg_box.height = 5.0
csg_box.depth = 5.0

var csg_cylinder = CSGCylinder3D.new()
csg_cylinder.radius = 1.0
csg_cylinder.height = 5.0
csg_cylinder.operation = CSGShape3D.OPERATION_SUBTRACT

In this example, we add a CSGCylinder3D as a child of CSGBox3D and set its operation to subtract, effectively cutting out the volume of the cylinder from the box.

Creating a Hollow Structure

Want to create a hollow structure, like a room with walls? Here’s how you could do that by subtracting one box from another:

# Create the outer box which represents the outer walls
var outer_box = CSGBox3D.new()
outer_box.width = 10.0
outer_box.height = 6.0
outer_box.depth = 10.0

# Create the inner box that will be subtracted from the outer box
var inner_box = CSGBox3D.new()
inner_box.width = 9.0
inner_box.height = 5.5
inner_box.depth = 9.0
inner_box.operation = CSGShape3D.OPERATION_SUBTRACT

# Move the inner box slightly downwards to make it a hollow bottomed box
inner_box.translation = Vector3(0, -0.25, 0)

Here, we create two boxes and subtract the inner smaller box from the outer larger one to create a room-like hollow space. We also adjust the inner box’s translation to ensure the bottom remains solid, creating a floor in our virtual room.

Smoothing the Intersecting Surfaces

Sometimes, you might want to smooth out the areas where CSG shapes intersect or where one is subtracted from another. See how it’s done:

var csg_box = CSGBox3D.new()
csg_box.width = 3.0
csg_box.height = 3.0
csg_box.depth = 3.0
csg_box.smooth_faces = true

var csg_sphere = CSGSphere3D.new()
csg_sphere.radius = 1.5
csg_sphere.smooth_faces = true
csg_sphere.operation = CSGShape3D.OPERATION_SUBTRACT

Here, we’ve set the smooth_faces property to true on both shapes, which are the CSGBox3D and CSGSphere3D. The CSGSphere3D is set to subtract from the CSGBox3D, and the resulting intersection will be smoothed.

This completes part two of our tutorial. Make sure to play around with the examples provided here, as experimentation is a critical step in learning. Coming up next in part three, we will dive into more complex operations and how to further manipulate CSG shapes to create different architectural elements and complex models in Godot 4!Let’s delve deeper into the power of CSG by exploring various operations and additional properties. As you become more acquainted with these examples, you’ll start to see the unlimited potential CSG has for your game development projects in Godot 4.

Advanced CSG Operations

Godot’s CSG capabilities go beyond simple subtraction and addition. For example, you can use the intersection operation to create a shape that is the shared volume of two primitives:

# Create the first box
var csg_box1 = CSGBox3D.new()
csg_box1.width = 6.0
csg_box1.height = 6.0
csg_box1.depth = 6.0

# Create the second box
var csg_box2 = CSGBox3D.new()
csg_box2.width = 6.0
csg_box2.height = 6.0
csg_box2.depth = 6.0
csg_box2.translation = Vector3(3, 0, 3)
csg_box2.operation = CSGShape3D.OPERATION_INTERSECT

In this scenario, the intersection between csg_box1 and csg_box2 is formed, revealing the shared space of these two boxes.

Creating architectural features like arches is simple, combining subtraction and addition:

# Create the wall
var wall = CSGBox3D.new()
wall.width = 10.0
wall.height = 10.0
wall.depth = 1.0

# Carve out the archway with a cylinder
var archway = CSGCylinder3D.new()
archway.radius = 2.0
archway.height = 1.0
archway.rotation_degrees = Vector3(90, 0, 0) # Rotating the cylinder to align with the wall
archway.operation = CSGShape3D.OPERATION_SUBTRACT

Adding archway details is effortless:

# Add a keystone block at the top of the arch
var keystone = CSGBox3D.new()
keystone.width = 1.0
keystone.height = 1.5
keystone.depth = 1.0
keystone.translation = Vector3(0, wall.height/2 - keystone.height/2, wall.depth/2)

Using CSG tori, you can create interesting decorative elements or structural components:

# Create a basic torus and add it to the scene
var csg_torus = CSGTorus3D.new()
csg_torus.inner_radius = 1.0
csg_torus.outer_radius = 2.0
csg_torus.material = preload("res://path_to_material.tres")

CSG primitives can be used to build more organic-looking elements, such as hills or landscapes:

# Create a hill by subtracting a sphere from a stretched box
var base = CSGBox3D.new()
base.width = 50.0
base.height = 20.0
base.depth = 50.0

var hill = CSGSphere3D.new()
hill.radius = 25.0
hill.translation = Vector3(0, -5, 0)
hill.operation = CSGShape3D.OPERATION_SUBTRACT

You can further refine the shapes with modifiers, controlling their resolution for higher detail or optimizing for performance:

# Adjusting the resolution of a CSGSphere3D
var high_res_sphere = CSGSphere3D.new()
high_res_sphere.radius = 2.0
high_res_sphere.radial_segments = 64
high_res_sphere.rings = 32

var low_res_sphere = CSGSphere3D.new()
low_res_sphere.radius = 2.0
low_res_sphere.radial_segments = 8
low_res_sphere.rings = 4
low_res_sphere.translation = Vector3(5, 0, 0)

These examples showcase how to work with more intricate designs using Godot’s CSG system. Each step you take now becomes a step towards mastering the art of level creation within the engine. Remember, practice is the key.

Manipulate these examples, experiment with your own designs, and enjoy the process of building and learning. In the next section, we’ll explore how to optimize your CSG creations for performance and look at potential pitfalls and best practices. Stay tuned!Optimization is a crucial part of working with CSG in Godot. It’s important to remember that while CSG is a powerful tool for prototyping and level design, it can be resource-intensive. Below are some tips and tricks accompanied by code examples to help you create more performance-friendly structures.

**Minimize the Number of CSG Nodes**

It’s wise to limit the number of CSG nodes present in your scene. Combine them where possible, and always remove unnecessary nodes.

# Combining several CSG shapes into a single node
var combined_shape = CSGCombiner3D.new()

var shape1 = CSGBox3D.new()
shape1.width = 1.0
shape1.height = 1.0
shape1.depth = 1.0

var shape2 = CSGSphere3D.new()
shape2.radius = 0.5
shape2.translation = Vector3(0, 1, 0)

**Use Meshes for Static Structures**

If you’ve finalized a structure with CSG, consider converting it to a static mesh to reduce the computation required during runtime.

# Convert a CSG shape to a MeshInstance3D
var csg_shape = CSGBox3D.new()
csg_shape.width = 1.0
csg_shape.height = 1.0
csg_shape.depth = 1.0

var mesh = csg_shape.get_meshes()[1]
var mesh_instance = MeshInstance3D.new()
mesh_instance.mesh = mesh
replace_child(csg_shape, mesh_instance)

**Use Colliders Efficiently**

When creating levels, ensure your colliders are as simple as possible. Only use detailed CSGShapes for collision when absolutely necessary, and consider using basic primitive shapes for collisions instead.

# Set a simple collision shape for a complex CSG structure
var csg_structure = CSGCombiner3D.new()
# ...[CSG creation code]...

var collision_shape = CollisionShape3D.new()
collision_shape.shape = BoxShape3D.new()
collision_shape.shape.extents = Vector3(2, 1, 0.5)

**Avoid Real-time Boolean Operations**

Avoid performing boolean operations, such as subtraction or intersection, during gameplay. Try to keep these operations for the design phase only.

# Do not perform these operations while the game is running:
var dynamic_subtract = CSGBox3D.new()
# ...[dynamic CSG operation setup]...
dynamic_subtract.operation = CSGShape3D.OPERATION_SUBTRACT

Spend time in the prototyping stage to ensure that boolean operations are finalized before the game runs.

**Use the Visibility Property for Debugging**

When troubleshooting complex CSG structures, toggle the visibility of individual CSG nodes to debug more easily. This can save time and frustration.

# Toggle visibility of a CSG node for debugging
var csg_debug_shape = CSGBox3D.new()
# ...[CSG setup]...

# Set to false to hide the shape temporarily
csg_debug_shape.visible = false

By following these guidelines, you’ll create more efficient levels that run smoothly on a variety of hardware. Remember, while CSG is a valuable tool within the Godot editor, it’s your creativity and optimization efforts that will ultimately shine through in the game experiences you craft. Keep experimenting, refining, and learning, and your work within Godot will become more impressive and efficient with each project.

Continue Your Game Development Journey

If you’ve enjoyed learning about CSG primitives and are eager to further your Godot 4 expertise, there’s no better way than to immerse yourself in our comprehensive Godot Game Development Mini-Degree. Transform your newfound skills into the creation of cross-platform games, learning at your own pace with a curriculum that covers all aspects of game development in Godot 4.

We at Zenva know that the path to mastery is a continuous learning journey. Our Mini-Degree is perfectly tailored to deepen your understanding, whether you’re beginning your game development odyssey or looking to refine existing skills. You’ll not only gain practical knowledge but also build a portfolio of projects to show potential employers, all while learning from the comfort of your own home.

For those who want to explore the full breadth of our Godot offerings, check out our complete collection of Godot courses. Regardless of where you are in your learning path or what your schedule looks like, you have the flexibility to pick and choose what suits you best. With Zenva, you can confidently progress from beginner to professional, turning your passion for game creation into a tangible reality.


Your exploration of CSGPrimitive3D in Godot 4 is just the beginning of what you can achieve in the realm of game development. Armed with this knowledge, you’re on your way to bringing imaginative environments to life, all within the versatile Godot engine. Remember, the key to mastery is practice, so keep experimenting with these CSG techniques until they feel like second nature. And, when you’re ready to level up your skills, we’re here to guide you every step of the way.

Embrace the journey ahead—full of creativity, challenges, and the satisfaction of seeing your games come to life. Swing by our Godot Game Development Mini-Degree whenever you crave more knowledge or need to sharpen your skills; we promise you’ll find just what you need to keep pushing the boundaries of what’s possible in game creation. Here’s to your success, and happy developing!

Python Blog Image

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