CSGCylinder3D in Godot – Complete Guide

Welcome to our comprehensive tutorial on the CSGCylinder3D class in Godot 4. Whether you’re a seasoned developer or just starting out, understanding Constructive Solid Geometry (CSG) can add a powerful tool to your game development toolkit. Godot’s user-friendly approach to CSG allows for creative level design and prototyping, making it an important feature to explore. So, let’s dive in and demystify the process of creating 3D cylinder shapes with CSG in Godot and find out just how valuable this skill can be for your projects.

What is CSGCylinder3D?

CSGCylinder3D is a class in Godot 4 that facilitates the creation of cylinder and cone shapes within the CSG system. CSG, or Constructive Solid Geometry, is a technique used in 3D computer graphics to build complex surfaces or objects by using Boolean operations like union, intersection, and difference on simpler shapes. The CSGCylinder3D node allows you to modify properties such as height, radius, material, and the number of sides to customize your cylinder or cone.

What is it for?

The CSG system is particularly useful for level prototyping in game development. By enabling rapid iteration and modification of 3D shapes, developers can visualize and refine game levels without the need for detailed modeling. This can be incredibly helpful in the early stages of game design, where you can experiment with different layouts and structures efficiently.

Why Should I Learn It?

Getting to grips with the CSGCylinder3D in Godot opens up opportunities for creativity in your level design. An understanding of CSG allows for quick prototyping, which is pivotal when testing out new ideas or constructing the framework of a level. Moreover, the skills gained from mastering CSG operations extend beyond game design and into broader 3D modeling and computer graphics practices. It’s a versatile tool that enhances your proficiency as a game developer and could be the key to unlocking the full potential of your creative vision.

CTA Small Image

Creating a Basic Cylinder with CSGCylinder3D

To start with CSGCylinder3D, let’s create a simple cylinder. This basic example will introduce you to the node and its primary properties.

var cylinder = CSGCylinder3D.new()
cylinder.height = 2.0
cylinder.radius = 1.0
cylinder.material = load("res://path_to_your_material.tres")

In the script above, we’ve instantiated a new CSGCylinder3D node, set its height and radius, applied a material, and then added it to the scene tree. This simple process sets up a basic cylinder in your Godot scene.

Modifying Cylinder Properties

Further customization of the cylinder can be achieved by modifying its other properties. For example, changing the number of sides will affect the cylinder’s smoothness.

cylinder.sides = 16

Increasing the number of sides will result in a smoother cylinder. If you’re going for a low-poly aesthetic, reducing the number of sides can give your cylinder a faceted look.

Creating a Tapered Cylinder (Cone)

CSGCylinder3D also allows you to create cones with the taper property. By setting this property to a value different from zero, you can taper the top radius to create a cone shape.

cylinder.taper = 0.5

In this snippet, we’ve changed our cylinder into a tapered shape, effectively creating a cone with half the radius at the top compared to the base.

Boolean Operations with CSGCylinder3D

One of the highlights of using CSG is the ability to perform Boolean operations. Let’s see how to subtract one CSGCylinder3D from another to create a hollow pipe.

var outer_cylinder = CSGCylinder3D.new()
var inner_cylinder = CSGCylinder3D.new()

outer_cylinder.height = 2.0
outer_cylinder.radius = 1.0
outer_cylinder.sides = 32

inner_cylinder.height = 2.2  # Slightly taller for clean subtraction
inner_cylinder.radius = 0.8  # Smaller radius for inner space
inner_cylinder.sides = 32
inner_cylinder.operation = CSGShape3D.OPERATION_SUBTRACTION


In the code above, two cylinders are created where the inner one subtracts its volume from the outer one, leading to a hollow cylinder. Note that for a clean operation, the inner cylinder is made slightly taller than the outer.

Adding Multiple Cylinders to Create Complex Shapes

By cleverly adding multiple CSGCylinder3D nodes, you can create more complex structures. Here’s how to combine a few cylinders to make a cross shape.

var main_cylinder = CSGCylinder3D.new()
main_cylinder.height = 1.0
main_cylinder.radius = 0.2

for i in 0..3:
    var arm = CSGCylinder3D.new()
    arm.height = 0.6
    arm.radius = 0.2
    arm.rotation_degrees.y = i * 90
    arm.translation = Vector3(0, 0, -0.3)

This snippet demonstrates horizontal arms being added to a central cylinder, positioned and rotated to form a cross shape. This method showcases the power of CSG in Godot for creating composite forms from simple shapes.

Through these examples, we see how the CSGCylinder3D class simplifies complex 3D shape construction and offers a world of design possibilities at your fingertips. Stay tuned for the next part, where we will delve into more advanced examples and explore the creative potential of CSG in Godot 4.

Incorporating CSGCylinder3D into your scenes opens the door to elaborate designs with straightforward code. Here’s how you can integrate multiple CSG shapes to design a detailed component, like a gear.

var gear_base = CSGCylinder3D.new()
gear_base.height = 0.2
gear_base.radius = 1.0
gear_base.sides = 64

var tooth_template = CSGBox3D.new()
tooth_template.width = 0.1
tooth_template.depth = 0.1
tooth_template.height = 0.2

for i in 0..gear_base.sides-1:
    var tooth = tooth_template.duplicate()
    var angle = i * (360.0 / gear_base.sides)
    tooth.translation = Vector3(cos(deg2rad(angle)), 0, sin(deg2rad(angle)))
    tooth.rotation_degrees.y = angle

This script begins with a cylinder to form a gear base before adding individual teeth around it. We use duplication (a method in Godot that clones an existing node) and polar coordinates to place each tooth correctly around the cylinder’s perimeter and rotate it to align with the edge.

It is also possible to use CSGCylinder3D to create hollow cylindrical cutouts in other CSG shapes:

var cube = CSGBox3D.new()
cube.width = 2
cube.height = 1
cube.depth = 2

var cylinder_cutout = CSGCylinder3D.new()
cylinder_cutout.height = 1.2  # Slightly taller for a clean cutout
cylinder_cutout.radius = 0.5
cylinder_cutout.operation = CSGShape3D.OPERATION_SUBTRACTION
cylinder_cutout.translation = Vector3(0, 0.5, 0)

Here, we’re creating a rectangular cuboid and cutting a cylindrical hole right through it by setting the cylinder’s operation to SUBTRACTION and adjusting its position. Note how the cutout extends slightly beyond the cube’s height to ensure it fully penetrates the geometry.

If you want to create an array of cylinders aligned along a circular path, similar to a barrel or carousel, you can use the following loop:

var circle_radius = 3.0
var cylinder_count = 12

for i in 0..cylinder_count-1:
    var cylinder = CSGCylinder3D.new()
    cylinder.height = 1.0
    cylinder.radius = 0.2
    var angle = i * (360.0 / cylinder_count)
    cylinder.translation = Vector3(cos(deg2rad(angle)) * circle_radius, 0, sin(deg2rad(angle)) * circle_radius)

This loop creates an array of cylinders, placing each at an equal angular spacing along the circumference of an imaginary circle centered at the origin. You can imagine this technique being used for a variety of purposes, from environmental design to gameplay mechanics.

CSG operations are not limited to stationary objects. You can dynamically update properties to create animations or interactive elements:

# Assuming this code is part of a function called by an animation signal or frame update
func update_cylinder_height(cylinder, new_height):
    if cylinder is CSGCylinder3D:
        cylinder.height = new_height

# Usage
var my_cylinder = $CSGCylinder3D
var target_height = 4.0  # The new height you want to set
update_cylinder_height(my_cylinder, target_height)

By altering the properties of a CSGCylinder3D node in real-time, you have the potential to construct dynamic game scenarios. With this approach, you could create puzzles that involve changing the environment or visual effects that respond to player actions.

Each of these examples demonstrates the flexibility and power of CSGCylinder3D in Godot. By learning to manipulate these nodes, you can build intricate 3D models with code, streamlining your game’s development process.

As our exploration with CSGCylinder3D continues, consider how adding textures and materials can enhance the visual quality. Apply a wood texture to our barrel array to give it a more realistic appearance:

var wood_material = load("res://path_to_wood_material.tres")

for i in 0..cylinder_count-1:
    var cylinder = CSGCylinder3D.new()
    cylinder.height = 1.0
    cylinder.radius = 0.2
    cylinder.material = wood_material
    # ... continue with positioning as before ...

Assigning the wood_material to each cylinder in the loop instantly changes their look, offering a visually appealing barrel effect.

Next, let’s explore the use of scripts to create moving parts. Imagine a scenario where cylinders represent pistons moving up and down:

func _process(delta):
    for i in range(get_child_count()):
        var cylinder = get_child(i)
        if cylinder is CSGCylinder3D:
            var t = OS.get_ticks_msec() / 1000.0
            var new_height = 1.0 + sin(t + i) * 0.5  # Oscillating height
            cylinder.height = new_height

In this example, the _process function animates each cylinder’s height using a sine wave over time, making them act like pistons in real-time. This dynamic effect could signify machinery or add life to environmental designs.

For a more interactive example, let’s create a cylinder that the player can scale in real-time by pressing a key:

func _input(event):
    if event is InputEventKey and event.pressed and not event.echo:
        if event.scancode == KEY_UP:
            $CSGCylinder3D.height += 0.1
        elif event.scancode == KEY_DOWN:
            $CSGCylinder3D.height -= 0.1

This input handling script allows players to modify the height of a selected cylinder using the UP and DOWN arrow keys. This basic interaction can be expanded into more complex gameplay mechanics.

CSGCylinder3D can also work in tandem with other nodes. Consider a scenario where a spotlight follows the height of a cylinder:

func _ready():
    var spotlight = SpotLight3D.new()

func _process(delta):
    var spot_height = $CSGCylinder3D.height + 2.0
    $SpotLight3D.translation = Vector3(0, spot_height, 0)

This code creates a SpotLight3D that moves up and down in sync with the CSGCylinder3D, maintaining a constant distance above its top face.

Using CSGCylinder3D’s geometry for collision detection is another powerful feature, useful in physics-based games:

# First, ensure the cylinder has a CollisionShape3D child
var cylinder = $CSGCylinder3D
var collision_shape = CollisionShape3D.new()
var shape = CylinderShape3D.new()
shape.height = cylinder.height
shape.radius = cylinder.radius
collision_shape.shape = shape

In this script, we’re adding a collision shape to a CSGCylinder3D so it can interact with other physics-enabled objects.

Remember that CSG operations can cause performance issues when overused, especially in complex scenes or when involving many dynamic updates. Always profile your game and use these features judiciously for the best results.

With these varied examples, it’s clear that CSGCylinder3D is a remarkably adaptable class within Godot. It can play a role in everything from environmental art and interactive design to complex animations and physics interactions. Mastery over these nodes can greatly enhance the capability and polish of your Godot projects, making your game worlds more dynamic and engaging.

Where to Go Next with Godot

Now that you’ve started your journey into 3D shapes and CSG with CSGCylinder3D in Godot 4, the path to mastering game development is just beginning. To continue building your skills and broaden your understanding of Godot, we invite you to check out our Godot Game Development Mini-Degree. Our comprehensive course collection will guide you through a wide array of game development topics within Godot, from leveraging both 2D and 3D assets to mastering game mechanics across various genres.

The Mini-Degree is designed to support both beginners and experienced developers, offering a structured yet flexible learning experience that integrates project-based courses with live coding lessons. You’ll gain hands-on experience and create a robust portfolio of real Godot projects, establishing a solid foundation to thrive in the game development landscape.

If you’re eager to expand your knowledge even further, explore our broader catalog of Godot courses. With Zenva, you can grow from beginner to professional status. Continue learning, create amazing games, and step confidently forward on your game development journey with us.


In wrapping up, we’ve just scratched the surface of what’s possible with the CSGCylinder3D class in Godot 4. The real magic happens when you apply these tools to your unique ideas, laying the groundwork for innovative gameplay and stunning visual designs that could define the next generation of indie games. Remember, this is just one piece of the vast puzzle that is game development, and with each new skill, you’re adding to your arsenal of knowledge.

Whether you are honing your craft or just starting, we at Zenva are here to support you every step of the way. Our Godot Game Development Mini-Degree offers a deep dive into Godot’s full capabilities, empowering you to turn your game development dreams into reality. So take the next step, ignite your passion for learning and let’s build the future of gaming together!

Python Blog Image

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