CSGTorus3D in Godot – Complete Guide

Welcome to the fascinating world of Godot Engine, specifically focusing on the robust capabilities of the CSGTorus3D class. This powerful feature within Godot 4 enables creators to wield the art of constructive solid geometry (CSG) to bring to life elaborate designs and structures within their games. As we dive into the intricacies of CSGTorus3D, we invite beginners and experienced developers alike to explore this tool, understand its usefulness, and learn how to effectively integrate it into your game’s environment. Let’s embark on this technical journey and discover how you can leverage the CSGTorus3D to prototype levels, create intriguing game elements, and add a spark to your developmental aspirations.

What is CSGTorus3D?

CSGTorus3D is a class in Godot 4’s suite of tools designed for constructive solid geometry. It specifically allows the creation of a torus shape which can be a fundamental part of your 3D level geometry.

What is it for?

If you’re looking to prototype levels quickly or craft unique architectural elements within your 3D environments, CSGTorus3D will be invaluable. It’s utilized for its simplicity and versatility in representing complex shapes that would otherwise be time-consuming to model from scratch.

Why Should I Learn It?

Learning how to handle CSGTorus3D gives you a significant advantage when it comes to rapid development and prototyping within Godot. CSG shapes are remarkably efficient for testing gameplay mechanics and iterating on level design without the overhead of detailed modeling. However, knowing when and how to use CSGTorus3D effectively is critical due to its impact on CPU resources. It’s a skill that broadens your toolkit as a game developer and enhances your ability to convey your creative vision in a highly practical way.

CTA Small Image

Creating a Basic Torus with CSGTorus3D

To begin using CSGTorus3D, let’s start by creating a basic torus. This will introduce you to the process of adding and configuring a CSGTorus3D node within your Godot project.

var torus = CSGTorus3D.new()
torus.inner_radius = 1.0
torus.outer_radius = 2.0
torus.material = preload("res://example_material.tres")

In the code above, we first instantiate a new CSGTorus3D object. We then set the inner_radius and outer_radius properties to dictate the size of the torus. Lastly, we assign a material to the torus and add it as a child of the current node.

Manipulating Torus Properties

Now that we have a basic torus, it’s time to manipulate some of its properties to see the immediate effects on its appearance. Specifically, we will adjust the number of sides and the smoothness of the torus.

torus.sides = 16
torus.smooth_faces = true

The ‘sides’ property defines the number of sides for the torus, influencing its level of detail, with a higher number creating a smoother appearance. The ‘smooth_faces’ property toggles the smoothing of faces, making the torus look less like a faceted gem and more like a smooth donut.

Positioning and Rotating the Torus

Positioning and rotation are crucial for placing your torus precisely within your game world. The following demonstrates how to move and rotate the torus using the transform.basis and transform.origin properties.

torus.transform.basis = Basis().rotated(Vector3.UP, deg2rad(45))
torus.transform.origin = Vector3(5, 0, 3)

This snippet rotates the torus 45 degrees around the axis pointing upwards (Y-axis in this case) and moves the torus to the position (5, 0, 3) in the space.

Creating Multiple Tori and Combining Them

Godot Engine’s CSG features excel at creating complex structures by combining simple shapes. Let’s create two tori and combine them to form an interlocking design.

# Create the first torus
var torus1 = CSGTorus3D.new()
torus1.inner_radius = 0.75
torus1.outer_radius = 1.5

# Create the second torus
var torus2 = CSGTorus3D.new()
torus2.inner_radius = 0.75
torus2.outer_radius = 1.5
torus2.transform.basis = Basis().rotated(Vector3.FORWARD, deg2rad(90))

In this example, we create two tori with the same radii but rotate the second torus 90 degrees forwards. When these two tori are placed within the same coordinates, the result is an interlocking design.

Understanding these basic principles of creating and manipulating CSGTorus3D in Godot is essential for developing complex 3D structures with ease. Experimenting with these features will allow you to get comfortable with the toolset and inspire you to explore more advanced techniques in subsequent parts of our tutorial.

Deepening our exploration into CSGTorus3D, we’ll consider how to utilize Boolean operations to subtract or intersect shapes, how to animate the torus, and how to optimize the torus for performance. These operations open up numerous possibilities for creative and dynamic design within your projects.

Boolean Operations with CSGTorus3D

Boolean operations are a cornerstone of CSG, allowing complex shapes to be crafted from the combination of simpler ones. In Godot, CSG nodes can be used to add, subtract, or intersect with each other to create intricate models.

# Create the primary torus
var torus_main = CSGTorus3D.new()

# Create a sphere for subtraction
var sphere = CSGSphere.new()
sphere.radius = 1.5
sphere.operation = CSGShape.Operation.SUBTRACTION

In this snippet, we subtract a sphere from our main torus, cutting out a spherical shape from the torus. By changing the operation of the sphere node, we are able to conduct different Boolean operations.

Animating the Torus

Animation can breathe life into your static CSG shapes. Godot’s scripting allows for the dynamic modification of nodes, including our CSGTorus3D. Let’s animate the rotation of our torus over time.

func _process(delta):
    torus.transform.basis *= Basis().rotated(Vector3.UP, delta * 0.5)

This function rotates the torus incrementally every frame around the vertical axis based on the time since the last frame (delta), providing a smooth and continuous rotation.

Optimizing CSGTorus3D

To ensure smooth performance, particularly in larger scenes with multiple CSG nodes, it’s important to consider optimization. The following are ways to manage the complexity and performance impact of your CSG shapes:

# Reduce the number of sides
torus.sides = 12

# Use modes that calculate collision shapes more simply
torus.collision_layer = 0

# After finalizing the shape, convert it to a MeshInstance for better performance
var mesh = torus.mesh
var mesh_instance = MeshInstance.new()
mesh_instance.mesh = mesh

By reducing the number of sides, we lower the complexity of the torus. Setting the collision layer to 0 ensures the CSGTorus3D does not calculate unnecessary collision shapes. Finally, converting the CSG shape to a MeshInstance can significantly improve performance, as static meshes are more efficient to render than CSG shapes.

Applying these principles can greatly enhance the manageability and efficiency of your game’s environments or design elements. Always remember to balance between the visual needs of your project and the performance requirements of the platform you’re targeting.

We at Zenva hope this tutorial has provided you with a clear understanding of how to manipulate and optimize CSGTorus3D within the Godot Engine. By leveraging the power of CSG, you’ll be well on your way to creating stunning and efficient 3D projects with greater ease and creative freedom.

Delving deeper into the capabilities of Godot’s CSGTorus3D, it’s time to look at the level of detail (LOD) management, the usage of materials for visual enhancement, and how to integrate CSGTorus3D within a larger CSG hierarchy for complex designs. Learning how to efficiently use these features will empower you to create more intricate and optimized 3D scenes.

Let’s jump into some code examples to explore these concepts further:

Managing Level of Detail (LOD)

LOD is crucial for performance, especially when creating games that are large or have many entities. Godot allows for adjustments in real-time to maintain an effective balance between performance and visual quality.

func _viewport_size_changed():
    var screen_size = OS.window_size
    var detail_level = screen_size.x > 1080 ? 24 : 12
    for torus in get_tree().get_nodes_in_group("tori"):
        torus.sides = detail_level

This snippet demonstrates a method that adjusts the detail level of all `CSGTorus3D` nodes in the group “tori” based on the viewport’s width. Higher resolutions get more sides for a smoother torus, while lower resolutions save on performance with fewer sides.

Using Materials to Enhance Visuals

Materials can significantly impact the look of your CSG shapes. They add textures, reflections, and other effects that turn a simple shape into a visual element that fits seamlessly into your game’s aesthetic.

# Apply a standard material with a texture
var material = SpatialMaterial.new()
material.albedo_texture = preload("res://textures/albedo.png")
torus.material = material

# Set up a shader material for custom effects
var shader_material = ShaderMaterial.new()
shader_material.shader = preload("res://shaders/custom_shader.shader")
torus.material = shader_material

In the first example, we create a `SpatialMaterial` and assign a texture to it. We then apply this material to our torus to give it more detail. In the second example, a `ShaderMaterial` is used for more advanced visual effects and customizations.

Integrating CSGTorus3D in CSG Hierarchies

Godot’s CSG tools shine when you utilize them together. By using different CSG nodes in a hierarchy, you can create elaborate shapes that would be quite complex to model conventionally.

# Combine a torus with a cylinder to create a detailed pillar
var pillar_base = CSGTorus3D.new()
pillar_base.outer_radius = 2.0
pillar_base.inner_radius = 0.5

var pillar_shaft = CSGCylinder.new()
pillar_shaft.radius = 0.5
pillar_shaft.height = 5.0
pillar_shaft.operation = CSGShape.Operation.UNION


This code produces a new shape by unionizing a torus and a cylinder, representing a pillar’s base and shaft. By carefully planning your CSG hierarchy, you can build structures and level elements efficiently, combining simplicity with creativity.

Reacting to Environment and Physics

Although CSG nodes are often used for static geometry, they can be dynamic and respond to game events or physics. Here’s how to make a `CSGTorus3D` respond to a collision:

# Assuming the torus is part of an interactable object
func _on_body_entered(body):
    mesh_instance.material.set_shader_param("hit_effect", true)

When a collision occurs, we can use a shader parameter to indicate a hit effect, such as changing the torus’s color or making it emit light briefly. By listening for the `_on_body_entered` signal, you can create interactive or destructible environments.

These examples showcase the power of `CSGTorus3D` class in Godot 4, from optimization techniques like LOD management to aesthetic enhancements using materials and advanced CSG hierarchies. Such understanding enables you to craft visually appealing and performance-optimized experiences within your games.

We at Zenva pride ourselves on delivering comprehensive guides like this one to help you elevate your game development skills. We encourage you to experiment with these techniques, explore Godot’s vast toolset further, and turn your creative concepts into playable realities. Happy developing!

Continuing Your Journey in Game Development

Embarking on the journey of game development can be both thrilling and challenging. If you’ve enjoyed diving into Godot 4’s CSGTorus3D and the powerful features of the Godot engine, your adventure is just beginning. To further your skills and expand your knowledge, we encourage you to explore our Godot Game Development Mini-Degree. This comprehensive collection of courses will guide you through the nuts and bolts of game creation, from the basics of GDScript to advanced gameplay mechanics for various game genres.

Whether you’re a budding game designer or an experienced developer looking to polish your skills, the Mini-Degree is tailored to facilitate learning at your own pace. The Godot engine’s flexibility and our step-by-step course structure create a perfect synergy for hands-on learning and tangible project development.

For those desiring a broader spectrum of content, our extensive range of Godot courses offers an abundance of opportunities to learn and grow. With Zenva, you can transform from a beginner to a professional, supported by a library of over 250 courses to boost your tech career. So take the next step, build a portfolio with real-world projects, and become a game development pro with Zenva.


As we wrap up our exploration of the dynamic CSGTorus3D class within Godot 4, it’s clear that the power to craft and manipulate stunning 3D environments and components is at your fingertips. With the Godot engine’s extensive capabilities and your growing expertise, the possibilities for your game development projects are boundlessly exciting. Remember, every game developer starts with a single line of code, and with each new skill, you move one step closer to bringing your incredible visions to life.

Stay curious, keep experimenting, and sharpen your skills with us at Zenva. The universe of game development awaits you, and there’s no better way to forge ahead than with our Godot Game Development Mini-Degree. Continue to build on what you’ve learned, create games that resonate and inspire, and join the ranks of successful developers with a solid foundation in Godot and a passion for gaming. Your creative journey is just beginning – let’s make it epic together!

Python Blog Image

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