Geometry3D in Godot – Complete Guide

Geometry3D in Godot 4 empowers creators to bring their virtual worlds to life by providing essential tools for working with 3D shapes, detecting intersections, and performing various geometric calculations within the game engine. By mastering these tools, game designers can craft more dynamic gameplay, construct intricate environments, and enhance the player’s interaction with the game world.

What is Geometry3D?

Geometry3D is a powerful class within the Godot 4 game engine that encompasses a variety of methods dedicated to 3D geometry. It offers numerous functionalities, such as building shapes, calculating intersections, and other geometric operations. Designed to simplify complex math and physics tasks, Geometry3D allows developers to concentrate more on the creative aspects of game development.

What is it for?

The Geometry3D class is particularly useful for game mechanics that involve spatial calculations and interactions between objects within a 3D space. It helps in creating bounds for objects, checking line of sight, managing collisions, and enhancing physical realism, all of which are essentials for an immersive game experience.

Why should I learn it?

Learning how to utilize the Geometry3D class in Godot is crucial for any game developer aiming to build 3D games. It not only enhances the gameplay by allowing for sophisticated mechanics but also streamlines the development process by providing ready-made solutions for common geometric problems. The knowledge of Geometry3D can elevate your coding skill set, making you a more competent and versatile developer within the Godot community.

CTA Small Image

Basic Geometric Calculations

Starting with simple calculations, let’s explore how we can utilize basic geometric functions within Godot’s Geometry3D.

var point_1 = Vector3(0, 0, 0)
var point_2 = Vector3(1, 1, 1)
var distance = Geometry3D.distance_to_point(point_1, point_2)
print("The distance between points is: " + str(distance))

This snippet shows how to calculate the distance between two points in 3D space—a fundamental operation in many games, particularly when measuring ranges and spacing out objects.

var direction = (point_2 - point_1).normalized()
print("Direction from point_1 to point_2: " + str(direction))

Here, we’re finding the direction vector from one point to another, which is useful for aligning objects, creating movement, or pointing towards a target.

Intersecting Lines and Shapes

Moving onto intersections, Godot’s Geometry3D provides methods for detecting if lines, rays, or shapes intersect.

var from = Vector3(0, 0, 0)
var to = Vector3(5, 5, 5)
var plane = Plane(Vector3(0, 1, 0), 0)
var intersection = Geometry3D.segment_intersects_plane(from, to, plane)

if intersection:
    print("The line segment intersects the plane at: " + str(intersection))
    print("No intersection with the plane.")

The above example demonstrates checking the intersection of a line segment with a plane. As game developers, knowing when and where a player’s path intersects with elements in the environment can be highly engaging, adding realism to the environment’s response to the player’s actions.

var ray_origin = Vector3(0, 0, 0)
var ray_direction = Vector3(1, 0, 0)
var sphere_center = Vector3(5, 0, 0)
var sphere_radius = 1.0
var ray_intersects_sphere = Geometry3D.ray_intersects_sphere(ray_origin, ray_direction, sphere_center, sphere_radius)

if ray_intersects_sphere:
    print("The ray intersects the sphere.")
    print("The ray does not intersect the sphere.")

Detecting ray-sphere intersections is paramount in games for object selection, shooting mechanics, and sight checks. This snippet shows how to check whether a ray from a point intersects a sphere.

Working with Boundaries and Shapes

Godot’s Geometry3D can also be used for checking points within boundaries or generating shapes.

var aabb = AABB(Vector3(0, 0, 0), Vector3(2, 2, 2))
var point_inside = Vector3(1, 1, 1)
var point_outside = Vector3(3, 3, 3)

print("Point inside AABB: " + str(Geometry3D.is_point_in_aabb(point_inside, aabb)))
print("Point outside AABB: " + str(Geometry3D.is_point_in_aabb(point_outside, aabb)))

The code above checks if certain points are within an axis-aligned bounding box (AABB), which is essential when determining whether objects are within a specific area or if an entity is inside the player’s field of view or reach.

var sphere_bounds = AABB(Vector3(-1, -1, -1), Vector3(2, 2, 2))
var sphere = Geometry3D.build_sphere(sphere_bounds, 10)
# Assume we have a MeshInstance to assign the generated sphere mesh
var mesh_instance =
mesh_instance.mesh = sphere

The final example showcases how to generate a sphere mesh from AABB. This can be particularly useful for dynamically creating bounds or visualizing areas of effect in your game.

Through these code examples, we begin to see the creative potential unlocked by Geometry3D in Godot 4. Understanding how to implement these basic geometric operations is an essential first step in crafting engaging 3D games capable of interacting with the player in intuitive and complex ways.

As we delve deeper into the capabilities of Geometry3D, let’s explore additional practical examples of geometric operations that can enhance the gameplay experience.

Constructing Convex Polygons:

var points = PoolVector3Array([Vector3(0,0,0), Vector3(0,1,0), Vector3(1,1,0), Vector3(1,0,0)])
var convex_polygon = Geometry3D.build_convex_polygon(points)
# Use the convex polygon mesh in your game

This code snippet demonstrates creating a convex polygon from a set of points. This operation can be particularly useful for generating navigable platforms or dynamic obstacles in a 3D space.

Calculating the Closest Point on a Segment:

var closest_point = Geometry3D.get_closest_point_to_segment(Vector3(3,3,3), Vector3(0,0,0), Vector3(5,5,5))
print("Closest point on the segment: " + str(closest_point))

Determining the closest point on a segment from a given point can be invaluable when handling AI movement, ensuring that non-player characters move smoothly along predefined paths.

Building a Capsule:

var capsule_mesh = Geometry3D.build_capsule(2.0, 5.0, 16, 1, true)
# Let's say we wish to visualize this capsule within our scene
var mesh_instance =
mesh_instance.mesh = capsule_mesh

In this example, we create a mesh for a capsule shape. Capsules are often used for character collision bounds due to their smooth shape, which avoids snagging on the environment.

Performing a Convex Cast:

var shape = ... # A Shape3D reference, e.g., from a CollisionShape3D node
var xform = Transform.IDENTITY
var cast_to = Vector3(0, -10, 0)
var state = ... # Reference to the physics server's space state, typically obtained from a World3D resource

var result = state.convex_cast(shape, xform, cast_to)
if result:
    var collision_point = result.position
    var collision_normal = result.normal
    # Use this information for gameplay mechanics, like detecting if a jump is possible or if an entity is above a surface

The convex cast performs a shape cast in the physics environment, which is useful for determining potential collisions before they occur, such as forecasting an entity’s landing point.

Calculating a Bounding Box for a Set of Points:

var point_cloud = PoolVector3Array([Vector3(1, 2, 3), Vector3(4, 5, 6), Vector3(7, 8, 9), Vector3(10, 11, 12)])
var bounding_box = Geometry3D.merge_aabb_array(point_cloud)
print("Bounding box for points: " + str(bounding_box))

This operation calculates an axis-aligned bounding box that encloses a set of points. Used for spatial partitioning, this technique optimizes rendering and physics calculations by limiting checks to relevant areas.

Overall, these operations within the Geometry3D class are just the tip of the iceberg. By learning to implement and combine these functions, you’ll be able to solve complex spatial problems and make 3D space in your games feel intuitive and responsive to players. Mastering these tools will pave the way for creating truly captivating and interactive gaming experiences.

Let’s further our journey into the Geometry3D class by exploring more examples and how these geometric tools can be applied to enhance various aspects of gameplay in Godot 4.

One of the essentials of 3D gameplay is managing intersections and contacts between objects. Godot’s Geometry3D class offers a comprehensive set of methods for these tasks. Here’s how you can detect the intersection of two convex shapes:

var shape1_transform = Transform.IDENTITY
var shape1 = ... # Your first Shape3D reference
var shape2_transform = Transform.IDENTITY
var shape2 = ... # Your second Shape3D reference
var intersect = Geometry3D.convex_intersect(shape1, shape1_transform, shape2, shape2_transform)

if intersect:
    print("The convex shapes intersect!")
    print("The convex shapes do not intersect.")

Determining the intersection between convex shapes is crucial for physics responses and gameplay mechanics, like in puzzle games where the conjunction of specific shapes might trigger events or outcomes.

Next, let’s look at how to extrapolate the normal of a convex polygon which can come in handy for lighting effects or determining the direction of forces upon collision:

var polygon_points = PoolVector3Array([Vector3(0,1,0), Vector3(1,0,0), Vector3(0,0,1)])
var normal = Geometry3D.get_plane_normal(polygon_points)
print("Normal of the convex polygon is: " + str(normal))

Finding the normal of a surface allows for realistic applications of physics and provides essential information for shading and graphical effects like reflections.

In the context of AI and NPC navigation, it’s often necessary to determine visibility lines. Here’s how you can check if a line of sight between two points is unobstructed:

var from = Vector3(1,1,1)
var to = Vector3(5,5,5)
var state = ... # Assume you have the World3D state or similar
var hit = state.intersect_ray(from, to)

if not hit:
    print("Line of sight is clear between points.")
    print("Line of sight is obstructed by: " + str(

Ray intersection tests can be used to determine if the player or AI has a clear line of sight for aiming, attention, or activation of objects, adding to the realistic interaction within the game world.

Godot’s Geometry3D can also help in procedural generation or dynamic adjustments of terrains and environments. Here’s a snippet on how to calculate the intersection of a ray with a triangle, which can be used for heightmaps or terrain sculpting:

var ray_origin = Vector3(0, 10, 0)
var ray_direction = Vector3(0, -1, 0)
var triangle = PoolVector3Array([Vector3(0,0,0), Vector3(10,0,0), Vector3(5,5,0)])

var hit = Geometry3D.ray_intersects_triangle(ray_origin, ray_direction, triangle[0], triangle[1], triangle[2])

if hit:
    print("Ray intersects the triangle at: " + str(hit))

With this method, developers can have rays interact with custom meshes, allowing for editable terrain in editor tools or runtime gameplay mechanics such as revealing hidden objects beneath terrain.

Lastly, for gameplay mechanics that require precision and prediction, such as billiards or marble games, you’ll need to calculate the motion of objects after collisions. Here’s an example of predicting the movement after a collision:

var initial_velocity = Vector3(5,0,0)
var normal_at_collision = Vector3(0,1,0)
var bounce_factor = 0.8 # This could simulate the bounciness of the surface
var final_velocity = initial_velocity.bounce(normal_at_collision) * bounce_factor
print("The final velocity after collision: " + str(final_velocity))

This uses the Vector3 `bounce` method combined with a bounce factor to simulate the effect of an object hitting a surface and rebounding off it.

By integrating these code examples, you can create various gameplay elements, from simple mechanics to more complex, interactive systems. The Geometry3D class is flexible and versatile, allowing for a wide range of spatial computations that can bring innovation and depth to your 3D games.

Where to Go Next in Your Game Development Journey

Embarking upon the journey of mastering Godot 4 and its powerful Geometry3D class is just the beginning. As you continue to explore the depths of game development, why not take your skills to the next level with our Godot Game Development Mini-Degree? You’ll find a rich curriculum designed to enhance your understanding and help you create cross-platform games using Godot.

In our comprehensive collection of courses, you’ll tackle a variety of game development topics, from leveraging both 2D and 3D assets to scripting gameplay mechanics across multiple game genres. Whether you’re just starting or are looking to sharpen your existing skill set, these courses provide the flexibility and depth needed to grow as a game developer. Dive into the Godot Game Development Mini-Degree here.

For those who seek a broader range of content and wish to explore various facets of Godot’s capabilities, our extensive collection of Godot courses is the perfect resource. With Zenva, you will get hands-on with creating games and earn certificates that aid in your career growth. From beginner to professional-level content, your educational pathway is catered for at Zenva’s Godot courses. Continue your learning adventure with us, and transform your game development dreams into reality.


The world of Godot 4 and its Geometry3D class is filled with incredible potentials for game development. By grasping these concepts, you unlock new avenues to express creativity, solve complex problems, and bring immersive experiences to your audience. Remember, every great game begins with the fundamentals, and your journey with Geometry3D is a stepping stone towards building the next big title. So why wait?

Embark on this adventure by diving into our Godot Game Development Mini-Degree, where every lesson brings you closer to becoming the game developer you aspire to be. Let us be a part of your success story, where your passion meets our expertise. Take that step forward with Zenva, and let’s create, innovate, and inspire together!

Python Blog Image

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