SphereShape3D in Godot – Complete Guide

Welcome to this tutorial on the SphereShape3D class in Godot 4—a fundamental element in 3D game development for the Godot engine. SphereShape3D is an efficient and effective 3D shape used in physics collision detection that brings your virtual worlds to life with realistic interactions. From rolling boulders to the spherical protagonists in your gaming universe, understanding how to implement and manipulate spheres is essential for compelling game play. Let’s dive into the world of Godot 4 and explore the spherical possibilities together.

What is SphereShape3D?

SphereShape3D is a shape resource in Godot 4 that represents a 3-dimensional sphere. It inherits from Shape3D and is particularly used to define the collision boundary for objects in a 3D space. In Godot, adding a physical presence to your game objects is crucial for interactions like collisions, physics simulations, or simply detecting when one object touches another. Spheres are especially advantageous due to their uniformity in every direction, which simplifies many calculations.

What is it for?

Primarily, a SphereShape3D is used within a CollisionShape3D node to give non-visible physical properties to visible 3D objects. This turns your 3D models into interactable items within the Godot physics engine, allowing for dynamic gameplay where objects can bounce, roll, or interact with the player and the environment in an intuitive manner.

Why should I learn it?

Being proficient with SphereShape3D can elevate your game development skills in many ways:

Performance: It is one of the fastest shapes to check collisions against, ensuring your game runs smoothly.
Realism: Spheres mimic many real-world objects, making them an ideal choice for realistic simulations.
Simplicity: Their uniform shape makes them easier to work with, particularly for those who are just starting their journey in game development.

By the end of this tutorial, you will not only understand how SphereShape3D works but also how to implement it in various engaging scenarios, ensuring you have the practical skills to enhance your projects in Godot 4.

CTA Small Image

Creating a SphereShape3D

To start working with SphereShape3D in Godot 4, we first need to create a new sphere shape and assign it to a CollisionShape3D node. The following code snippet shows how to create a SphereShape3D and set its radius in GDScript:

var sphere_shape = SphereShape3D.new()
sphere_shape.radius = 1.0

var collision_shape = CollisionShape3D.new()
collision_shape.shape = sphere_shape


This code block adds a spherical collision shape to the node that the script is attached to, giving it a physical boundary within the physics engine.

Adding SphereShape3D to a RigidBody3D

For our sphere to interact with the game world’s physics, we can attach it to a RigidBody3D node. Rigid bodies are objects that are affected by forces, torques, and collisions in the world. Here’s how you can set this up:

var rigid_body = RigidBody3D.new()


With this setup, the sphere will now respond to gravity and collide with other objects in your 3D scene.

Manipulating SphereShape3D Properties

Godot’s GDScript allows you to manipulate the SphereShape3D’s properties at runtime. Below are a couple of examples on how to change the radius of the sphere shape and how to get its current radius:

To set the radius:

# Assume sphere_shape is a previously created SphereShape3D instance.
sphere_shape.radius = 2.5

To get the current radius:

# Assume sphere_shape is a previously created SphereShape3D instance.
var current_radius = sphere_shape.radius

Detecting Collisions with SphereShape3D

An important aspect of using SphereShape3D is collision detection. Here we set up a signal on the RigidBody3D to detect when it has come into contact with another object:

# First, connect the 'body_entered' signal on the RigidBody3D.
rigid_body.connect("body_entered", self, "_on_body_entered")

# Then, define the callback function.
func _on_body_entered(body):
    print("Collided with another body: ", body.name)

With connected signals, your sphere will now be able to react whenever it hits another physical body within your game scene.

Remember, these are fundamental examples to get you started with SphereShape3D. As you become more comfortable with these basics, you can start experimenting with more advanced features like physics materials and various forces to simulate different interactions in your game world.To give you a deeper understanding of the capabilities of the SphereShape3D class in Godot 4 and how to utilize it effectively in your game development process, here are several practical code examples that you can experiment with and incorporate into your projects.

Applying Forces to a Sphere

To apply a force to your RigidBody3D with a SphereShape3D, such as simulating a kick that propels the sphere forward, you can use the following code:

# Apply a force to the rigid body in the direction of the vector (10, 0, 0).
rigid_body.apply_central_impulse(Vector3(10, 0, 0))

To simulate continuous movement, such as rolling the sphere in a specific direction by applying a force every frame, use _process or _physics_process:

func _physics_process(delta):
    var force_direction = Vector3(5, 0, 0) # Change the direction and magnitude as needed
    rigid_body.apply_central_impulse(force_direction * delta)

Adjusting Sphere Physical Properties

You might want to adjust the physical properties of your sphere to simulate different materials. For example, to increase the bounciness, you can change the bounce property:

# Increase the bounce factor of the rigid body.
rigid_body.physics_material_override = PhysicsMaterial.new()
rigid_body.physics_material_override.bounce = 0.8

Similarly, to change the friction of your sphere to simulate a slippery or sticky surface, you can adjust the friction property:

# Change the friction of the sphere.
rigid_body.physics_material_override.friction = 0.1  # A lower value for slippery, a higher for sticky.

Scaling the SphereShape3D

If you wish to scale a SphereShape3D without changing its collision properties, you can do so by adjusting the local_scale property of your visual node, such as MeshInstance3D:

# Scale your visual sphere node.
var visual_sphere = $MeshInstance3D
visual_sphere.transform = visual_sphere.transform.scaled(Vector3(2, 2, 2)) 
# This will double the size of your visual sphere model.

Changing Sphere Position

To move the sphere physically to a new position, modify the translation property of the RigidBody3D:

# Teleport the sphere to a new position.
rigid_body.translation = Vector3(10, 0, 0) 
# This moves the sphere to coordinates (10, 0, 0).

Remember, when working with physics in Godot, it is generally best to use the physics engine’s functions to move and rotate objects to ensure realistic interactions and avoid unexpected physics behavior. As you get more familiar with these examples, feel free to experiment with the values and properties to create the exact behavior you want for the spheres in your 3D world.Moving forward, let’s look at how we can leverage the SphereShape3D class in different scenarios to add depth and interactive elements to your game.

Interacting with Raycasts

Interacting with raycasts is a common requirement in games, whether it’s to detect if the player is looking at an object, to cast spells, or to shoot bullets. Here’s how you can check if a raycast is intersecting with your sphere:

# Assuming you have a RayCast3D node set up and named "RayCast".
if $RayCast.is_colliding():
    var collider = $RayCast.get_collider()
    if collider == rigid_body:
        print("The raycast is hitting the sphere!")

Responding to Input

We can also make the sphere respond to player input, such as jumping when a key is pressed. This can be done within the _input function by checking for the event and applying a force upward:

func _input(event):
    if event is InputEventKey and event.pressed and event.scancode == KEY_SPACE:
        rigid_body.apply_central_impulse(Vector3.UP * 300)

Changing Collision Layer

Sometimes you’ll want your sphere to only collide with certain objects. Godot’s layer-based collision system allows you to specify what each object collides with. Here’s how to set the collision layer on your RigidBody3D:

# Set the sphere to the second collision layer.
rigid_body.collision_layer = 2

And to make the sphere collide with objects on the second layer:

# Make the sphere only collide with objects on the second layer.
rigid_body.collision_mask = 2

Sensing Proximity

You can use a Area3D node with a SphereShape3D to sense when objects enter its vicinity. Here’s a simple setup:

# Assuming you have an Area3D node with a SphereShape3D attached:
func _on_Area_body_entered(body):
    if body.name == "Player":
        print("The player has entered the sphere's area!")

Deforming the SphereShape3D

While SphereShape3D offers a perfect sphere shape, games often need variations like ellipsoids. However, the shape cannot be deformed directly through the SphereShape3D resource. To create ellipsoids or deformed spheres, you would typically scale the visual mesh and use a different collision shape, such as a ConvexPolygonShape3D:

# Set up the visual mesh as an ellipsoid.
var mesh_instance = $MeshInstance3D
mesh_instance.transform = mesh_instance.transform.scaled(Vector3(2, 1, 1))  # Ellipsoid with a stretched x-axis.

# Set up the collision shape using ConvexPolygonShape3D.
var ellipsoid_shape = ConvexPolygonShape3D.new()
# Points would be set here to define the shape.
var collision_shape = CollisionShape3D.new()
collision_shape.shape = ellipsoid_shape

Combining Multiple Shapes

For complex objects, you might combine different collision shapes. For example, a character wearing a spherical helmet:

# Add a sphere shape for the character's head.
var head_collision_shape = CollisionShape3D.new()
head_collision_shape.shape = SphereShape3D.new()
head_collision_shape.shape.radius = 0.5
head_collision_shape.translation = Vector3(0, 1, 0)  # Position the sphere at the top of the character model.

These examples give you a broad foundation on how to use SphereShape3D in a variety of ways within the Godot engine. This kind of flexibility and the ability to manipulate physics provide an incredible toolbox for creating engaging 3D gameplay in your projects.

Continuing Your Game Development Journey

Mastering SphereShape3D is just the beginning of your adventure in the world of game development with Godot 4. To continue growing your skills and to delve deeper into what this powerful engine has to offer, we recommend exploring our Godot Game Development Mini-Degree. This tailored learning path will guide you through creating cross-platform games and offer a wide spectrum of knowledge on topics ranging from GDScript to intricate game mechanics for RPGs, RTS games, and platformers.

Whether you’re starting out or looking to refine your existing skills, Zenva’s comprehensive courses will enable you to build a robust portfolio of real Godot projects. Furthermore, our collection of Godot courses encompasses a variety of topics that are fundamental to game development. This blend of courses is perfect for those aspiring to become proficient game developers, offering flexible learning opportunities on every aspect of Godot 4.

Dive in today to craft incredible game experiences, enhance your technical abilities, and push the boundaries of your creativity. Your journey with Godot doesn’t have to end here—let it thrive and evolve with Zenva.


Through this tutorial, you’ve taken an important step towards mastering 3D game development in Godot 4 by learning about SphereShape3D. With this knowledge, you’re well on your way to creating dynamic, interactive worlds that can capture the imagination of players. But remember, this is only a fraction of what you can achieve with Godot 4.

We at Zenva are excited to see the incredible games you’ll create with your newfound skills. Continue to hone your craft with our Godot Game Development Mini-Degree, and unlock the full potential of this extraordinary game engine. The quest for game development mastery awaits—embrace it and transform your creative visions into playable realities with Zenva, your ally in learning and innovation.

Python Blog Image

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