PhysicsDirectSpaceState3D in Godot – Complete Guide

Physics plays a crucial role in providing realism and immersion in video games. Godot Engine, with its powerful and user-friendly toolkit, simplifies the implementation of such physics in three dimensions through a special class known as PhysicsDirectSpaceState3D. By mastering this class, developers can create dynamic interactions, realistic movements, and engaging gameplay mechanics to enhance the player experience.

For anyone diving into the development of 3D games, understanding the capabilities and use cases of PhysicsDirectSpaceState3D opens up a myriad of possibilities. As you embark on this tutorial, you’ll be equipped with the knowledge to leverage these features in your own gaming projects.

What is PhysicsDirectSpaceState3D?

PhysicsDirectSpaceState3D is a class in the Godot Engine that provides developers with direct access to a physics space within the larger PhysicsServer3D. It’s essentially a gateway to performing complex physics queries, enabling developers to programmatically interact with the physics engine in meaningful ways.

What is it for?

The utility of PhysicsDirectSpaceState3D lies in its ability to perform queries against different objects, like determining if a bullet has hit a target or if a character is standing on solid ground. It offers methods for a variety of physics interactions such as ray-casting, collision detection, and motion queries, which are foundational operations for any physics-driven game.

Why should I learn it?

Understanding PhysicsDirectSpaceState3D is crucial for any game developer working with Godot 4 who wishes to include accurate and responsive physics in their games. Whether it’s for simple collision detection or complex simulation of physics-based puzzles, knowing how to harness this class will dramatically enrich your 3D gaming world. Plus, it’s a consistent demand in the industry; by learning it, you not only improve your games but also boost your value as a developer.

CTA Small Image

Utilizing Raycasting with PhysicsDirectSpaceState3D

Raycasting is one of the most common uses of PhysicsDirectSpaceState3D in Godot Engine. This powerful feature allows you to detect objects along a line or ray from a point in space to another. Here’s how you can utilize raycasting in your games:


func _physics_process(delta):
    var space_state = get_world().direct_space_state
    var ray_start = global_transform.origin
    var ray_end = ray_start + Vector3(0, -1, 0) * 100
    var ray_result = space_state.intersect_ray(ray_start, ray_end)

    if ray_result:
        print("Ray collided with: ",


This example will print the name of the object that the ray has collided with, which is directly below the starting point.

Detecting Collisions

Collision detection is another pivotal feature of PhysicsDirectSpaceState3D. You can check if a moving object will collide with something along its path by using the following code snippet:


func test_move_collide():
    var from_position = global_transform.origin
    var to_position = from_position + Vector3(1, 0, 0) * 50
    var space_state = get_world().direct_space_state
    var motion = to_position - from_position
    var collision = space_state.test_motion(collision_shape.global_transform, motion, 0.1)

    if collision:
        print("Motion collided with: ",


This checks if the object will collide when it moves 50 units to the right.

Intersecting Shapes

Godot also allows you to check intersections of various shapes, which can be useful for detecting whether objects are within certain areas, like triggering an area effect or creating a detection zone:


var space_state = get_world().direct_space_state
var shape =
shape.radius = 5

var intersect_dict = space_state.intersect_shape(shape, global_transform, 10)
if intersect_dict:
    for object in intersect_dict:
        print("Shape intersected with: ",


This code checks for any object’s collision shapes within a sphere with a radius of 5 units around the global transform of the node.

Using Areas to Detect Bodies

In some cases, you might want to detect bodies entering a predefined area. With PhysicsDirectSpaceState3D, you can achieve this effect:


func _process(delta):
    var space_state = get_world().direct_space_state
    var area = get_node("Area")
    var area_transform = area.get_global_transform()
    var area_shape = area.get_shape(0)
    var intersected_bodies = space_state.intersect_shape(area_shape, area_transform, 100, [], 1)

    for body in intersected_bodies:
        print("Body entered area: ",


This snippet will print the names of all the physics bodies that have just entered the area.

Each of these examples provides fundamental ways to interact with the Godot Physics Server using PhysicsDirectSpaceState3D. This knowledge is foundational for creating responsive and interactive 3D environments where physics plays a key role in gameplay and mechanics.Continuing with our exploration of PhysicsDirectSpaceState3D, let’s delve into other powerful functions and how to use them in your game development process. We’ll look into more complex examples and analyze the code to understand its purpose.

Advanced Raycasting

Advanced raycasting allows you to obtain more specific information about the collision, such as the exact position, normal at the collision point, and more:


func _physics_process(delta):
    var space_state = get_world().direct_space_state
    var ray_origin = global_transform.origin
    var ray_target = ray_origin + transform.basis.z * 100
    var collision_info = space_state.intersect_ray(ray_origin, ray_target)
    if collision_info:
        print("Collided with: ",
        print("Collision at position: ", collision_info.position)
        print("Collision normal: ", collision_info.normal)


This advanced code will output not just the name of the object hit, but also the point of impact and the surface normal at that point.

Intersecting Shapes with Exclusion

Sometimes you may want to exclude certain objects from your shape intersection queries, which can be done using the exclude parameter:


func _physics_process(delta):
    var space_state = get_world().direct_space_state
    var shape =
    shape.radius = 5
    var excluded_objects = [get_rid()] # Exclude the current object.
    var intersected_objects = space_state.intersect_shape(shape, global_transform, 10, excluded_objects)
    for item in intersected_objects:
        print("Shape intersected with object: ",


Here we’re excluding the object that’s running the code to avoid detecting collisions with itself.

Detecting and Responding to Multiple Collisions

Games often feature multiple potential collision points. The example below illustrates how to loop through these collisions and react accordingly:


func handle_collisions(collision_shape):
    var space_state = get_world().direct_space_state
    var transform = collision_shape.global_transform
    var motion = Vector3(1, 0, 0) * 50
    var collisions = space_state.test_move(transform, motion, 0.1, rest_info:=true)
    for collision in collisions:
        # Process each collision


In this code, `rest_info:=true` flags that you want detailed information about rest collisions, which could be used to implement sliding along walls or standing still on slopes.

Custom Collision Masks and Layers

In more complex scenarios, you might want to filter out collisions based on custom-defined masks and layers. Here’s an example of how to perform a raycast query that only collides with objects in a certain layer:


func raycast_in_layer(layer_mask):
    var space_state = get_world().direct_space_state
    var ray_origin = global_transform.origin
    var ray_target = ray_origin + transform.basis.z * 100
    var collision_info = space_state.intersect_ray(ray_origin, ray_target, [], layer_mask)
    if collision_info:
        print("Ray hit object in specified layer: ",


By providing the `layer_mask` parameter to `intersect_ray`, you ensure that only objects within that layer will be reported.

Collision Layers in Shape Queries

Similarly, when querying with shapes, you can specify collision layers to interact with specific objects:


func intersect_shapes_in_layer(collision_shape, layer_mask):
    var space_state = get_world().direct_space_state
    var transform = collision_shape.global_transform
    var intersected_shapes = space_state.intersect_shape(collision_shape.shape, transform, 100, [], layer_mask)
    for shape in intersected_shapes:
        print("Intersection with object in specified layer: ",


This code helps you to ensure that your area effects, detection zones, or other game mechanics interact only with the objects you have defined to be relevant.

Mastering the use of PhysicsDirectSpaceState3D and understanding its functions will significantly advance your ability to create rich, physics-based gameplay experiences. By following these examples, you’ll be well-equipped to integrate sophisticated physics interactions into your Godot 3D games.Let’s delve into even more practical implementations of PhysicsDirectSpaceState3D that you can utilize in your game development with Godot Engine.

Managing Physics Layers for Complex Interactions

As your game complexity grows, so does the need for managing which objects interact with each other. Here’s how you can assign specific layers to physics bodies and query them:


# Assigning a physics layer to a body
var body =
body.collision_layer = 1 << 2

# Querying a specific layer using bitmasks
func _physics_process(delta):
    var space_state = get_world().direct_space_state
    var collision_layer_bitmask = 1 << 2
    var intersection = space_state.intersect_ray(ray_origin, ray_target, [], collision_layer_bitmask)
    if intersection:
        print("Ray intersected with something on layer 3")


In this example, we move the body to the third layer (counting from zero) and adjust the raycast query to interact only with that layer.

Collision Points for Complex Surfaces

Sometimes you need more precise collision contacts, especially when dealing with complex surfaces:


# Configuring a raycast for multiple contact points
func get_collision_points(ray_origin, ray_target):
    var space_state = get_world().direct_space_state
    var result = space_state.intersect_ray(ray_origin, ray_target, rest_info:=true)
    if result:
        print("First contact point: ", result.position)
        if "collisions" in result:
            for contact in result.collisions:
                print("Additional contact point: ", contact.position)


The `rest_info` flag will provide additional information, like an array of all contact points for the ray.

Adjusting Queries for Moving Objects

Moving objects might need continuous collision detection that goes beyond simple raycasting:


# Predicting the path of a moving object
func _physics_process(delta):
    var body_state = self.state  # Assuming this is a PhysicsBody derived node
    var space_state = get_world().direct_space_state
    var future_transform = body_state.transform.translated(body_state.linear_velocity * delta)
    var intersected_shapes = space_state.intersect_shape(shape, future_transform, 100)
    for shape in intersected_shapes:
        print("Moving object will intersect with: ",


In this scenario, we predict the future position of a moving object and check for intersections before the movement is actually made.

Physics Layers for Projectile Logic

Projectiles often have unique interactions, such as passing through certain objects or triggering specific effects:


# Configuring projectile interactions
var projectile =
projectile.collision_mask = 1 << 1 # Only collide with layer 2

func _physics_process(delta):
    var space_state = get_world().direct_space_state
    var collision_info = space_state.intersect_ray(projectile.transform.origin, target_position, [], projectile.collision_mask)
    if collision_info:
        if collision_info.collider.is_in_group("Enemies"):


This projectile will interact only with objects in the second physics layer, and when it collides with an enemy, it triggers a damage routine.

Shape Casting for Pathfinding

Shape casting can be handy, especially in pathfinding or AI programming, where you may need to check if a path is clear of obstacles for NPC movement:


# Shape casting using a capsule shape
func is_path_clear(start_pos, end_pos):
    var shape =
    shape.radius = 0.5
    shape.height = 2.0
    var motion = end_pos - start_pos
    var space_state = get_world().direct_space_state
    return !space_state.test_motion(start_pos, motion, shape)


The code returns `false` when the path is not clear, indicating an obstacle is present.

Adapting these code examples and techniques to fit your game’s specific needs allows you to control and refine the physics interactions in your 3D world. Whether it be for player mechanics or environmental effects, Godot’s PhysicsDirectSpaceState3D is a versatile tool that, once mastered, unlocks a new level of engagement and realism in your projects.

Continue Your Game Development Journey

You’ve taken an important step in mastering Godot Engine’s PhysicsDirectSpaceState3D, but your game development journey doesn’t have to stop here. If you’re eager to build upon the skills you’ve learned and expand your expertise, our **Godot Game Development Mini-Degree** offers a valuable next step. This series of comprehensive courses is designed to take you deeper into the world of game creation with Godot 4, covering a wide array of topics that include 2D and 3D game development, GDScript programming, and creating engaging game mechanics across various genres.

Whether you’re a complete beginner or looking to polish your skills, our flexible learning path allows you to progress at your own pace, with the added benefit of creating a robust portfolio of real Godot projects along the way. By diving into these courses, you’ll gain the practical, in-demand skills that can open doors to exciting opportunities in the game development industry.

For those who wish to explore a broader range of topics, we also invite you to check out our full collection of **Godot courses**. From the basics to more advanced techniques, these courses are tailored to empower you at every stage of your learning journey, ensuring that you’re well-equipped to bring your game ideas to life.

Unlock your potential with high-quality content and take another step towards professional game development with Zenva!

[Explore the Godot Game Development Mini-Degree](

[Discover More Godot Courses](


As we wrap up our exploration of PhysicsDirectSpaceState3D, remember that the techniques and concepts we’ve discussed serve as building blocks for creating immersive and interactive 3D games with Godot Engine. With the knowledge you’ve gained, you can confidently implement complex physics interactions that will captivate players and set your games apart. Don’t stop here—continue refining your craft, and keep pushing the boundaries of what you can create.

We at Zenva are excited to support you on your game development journey. Whether you’re expanding your skills or embarking on new creative endeavors, we’re here to provide the resources and learning opportunities you need to succeed. Ready to take the next leap? Dive into our comprehensive **Godot courses** and the **Godot Game Development Mini-Degree**. Unleash your creativity, and let’s build something extraordinary together.

[Join the Godot Game Development Mini-Degree](

[Explore Our Godot Courses for More Learning Adventures](

Python Blog Image

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