PhysicsShapeQueryParameters3D in Godot – Complete Guide

Diving into the realm of game development with Godot can be an exhilarating experience. Exploring physics in a three-dimensional space is a critical aspect of this journey, especially when it comes to understanding how objects interact within your game world. PhysicsShapeQueryParameters3D is a crucial class in the latest version of Godot, and comprehending its uses and functionalities can significantly enhance the realism and dynamics of your game.

What is PhysicsShapeQueryParameters3D?

The PhysicsShapeQueryParameters3D class is a cornerstone of 3D physics interactions in the Godot engine. It provides a set of parameters that you can configure to perform sophisticated shape intersection queries using the PhysicsDirectSpaceState3D. Whether you’re checking for potential collisions, finding objects within a certain area, or crafting custom physics behaviors, this class is the toolkit you need.

Why Dive into PhysicsShapeQueryParameters3D?

Understanding the intricacies of the PhysicsShapeQueryParameters3D class equips you with the ability to:

– Fine-tune collision and physics simulations.
– Create more immersive and interactive game experiences.
– Debug and optimize physics-related features efficiently.

By mastering how to use these parameters, you can take full control of the physical interactions in your 3D environment, making your game feel more authentic and responsive to the player’s actions.

What Can You Do With It?

With the properties offered by PhysicsShapeQueryParameters3D, game developers have the power to:

– Specify which types of physics objects to consider during queries.
– Filter objects based on collision layers and masks.
– Exclude specific objects from being considered in collision checks.
– Adjust the accuracy and performance of queries using margins and movements.

This enables you to craft tailored queries for your game’s unique physics needs, whether that’s determining if a character can take cover behind an object or if an enemy is within striking distance. Join us as we delve into the examples and discover the impact this can have on your game development projects.

CTA Small Image

Setting Up Your Query Parameters

Before we dive into running actual queries, it’s essential to grasp how to set up the PhysicsShapeQueryParameters3D. The setup phase allows you to define the nature of the physics query through various properties.

// Initialize the parameters
var query_parameters =

// Assign the shape you want to check for collisions, typically a collision shape 
// you've already added to a physics object in your scene

// Set the layer and mask bits to filter the objects that will be included in the query

// Exclude specific objects from the query, often the one that is initiating the query
query_parameters.exclude = [your_exclude_object]

// For more accuracy or broad queries, tweak the margin (optional)
query_parameters.margin = 0.04 # Feel free to change this to suit your needs

Performing A Simple Intersection Query

Once you’ve configured your PhysicsShapeQueryParameters3D, performing intersection queries is the next step. These queries can help you determine if and where your shape intersects with the physical world.

// Get the PhysicsDirectSpaceState3D singleton
var space_state = get_world_3d().direct_space_state

// Perform a simple intersection test
var intersected_bodies = space_state.get_rest_info(query_parameters)

if intersected_bodies.size() > 0:
    print("Collision detected with ", intersected_bodies["collider"].name)
    print("No collision detected.")

To perform a collision check along a trajectory and find the first object encountered:

// Define the end position of the query
var end_position = transform.xform(Vector3(0, -1, 0)) * 10 # Modify as necessary

// Perform intersection check along the path from current position to `end_position`
var intersection = space_state.intersect_ray(global_transform.origin, end_position, [self])

if intersection:
    print("First object hit: ",

Implementing A Sphere Cast

Sphere casting is a type of ray casting where you check for intersections within a spherical shape along a path. This is particularly useful for things like bullet trajectories or detecting surrounding objects.

// Set up the sphere shape for our query
var sphere_shape =
sphere_shape.radius = 1.0

// Configure the query parameters

// Define start and end positions of the cast
var from_position = global_transform.origin
var to_position = from_position + Vector3(0, -5, 0) // Modify as necessary

// Perform the sphere cast
var sphere_cast = space_state.intersect_shape(query_parameters, from_position, to_position)

if sphere_cast.size() > 0:
    for collision in sphere_cast:
        print("Sphere cast collided with ",
    print("Sphere cast did not detect any collisions.")

By running a sphere cast, you can detect all objects within the sphere’s path, providing you with valuable information for decision-making processes within your game logic.

Area Overlap Checks

In order to verify if a specific area or zone is occupied or free from other objects, you can make use of area overlap checks.

// Define the shape for the area overlap, e.g., a box shape could represent a room
var box_shape =
box_shape.extents = Vector3(2, 2, 2) // Modify as necessary

// Set the shape for the overlap check
query_parameters.transform = global_transform

// Perform an area overlap check
var overlapped_bodies = space_state.get_overlapping_bodies(query_parameters)

if overlapped_bodies.size() > 0:
    print("Area is overlapped by other colliders: ")
    for body in overlapped_bodies:
    print("Area is clear.")

These overlap checks can be particularly useful for things such as detecting player presence within a specific zone or ensuring an area is clear before spawning new game objects. Each of these examples lays a fundamental understanding of how PhysicsShapeQueryParameters3D can be used to achieve complex and realistic physics scenarios in your Godot games.While the previous sections covered various uses of PhysicsShapeQueryParameters3D, let’s explore additional practical examples that demonstrate its versatility and power in game development.

Adjusting the Query’s Transform
Setting the transform property of the query parameters allows you to control the position and orientation of the shape during the query.

// Create a new transform that positions the shape 3 units up and rotates it 45 degrees around the Y axis
var new_transform = Transform3D().translated(Vector3(0, 3, 0)).rotated(Vector3(0, 1, 0), deg2rad(45))

// Apply the new transform to the query parameters
query_parameters.transform = new_transform

Checking for Collisions Before Moving an Object
Imagine you’re about to move an object in your game. With PhysicsShapeQueryParameters3D, you can check for collisions before the actual movement to prevent clipping through other objects.

// Set the end position for the query, which is the target location after movement
var move_to_position = global_transform.origin + Vector3(5, 0, 0) // Modify as per desired movement vector

// Perform the collision check
var collision_info = space_state.get_rest_info(query_parameters, global_transform.origin, move_to_position)

if collision_info.empty():
    global_transform.origin = move_to_position
    print("Moved object without any collisions.")
    print("Cannot move, collision detected with ", collision_info["collider"].name)

Using a Capsule Cast to Simulate a Character’s Field of View
A capsule shape is ideal for approximating a character’s field of view or physical space. Below is an example of how you might perform a capsule cast.

// Define the capsule shape for the cast
var capsule_shape =
capsule_shape.radius = 1.5
capsule_shape.height = 3.0

// Set the capsule shape for the query

// Perform the capsule cast
var capsule_cast_results = space_state.intersect_shape(query_parameters)

for result in capsule_cast_results:
    print("Object within the character's field of view: ",

Reducing the Performance Impact of Complex Queries
Complex physics operations can be demanding on performance. Godot provides mechanisms to simplify the collision checks and reduce the computational requirements.

// For performance-sensitive scenarios, use a simpler shape
var box_shape =
box_shape.extents = Vector3(0.5, 0.5, 0.5)

// Apply a simpler shape to the query parameters

// Proceed with your intersection check or physics query

Investigating Point Collisions with Point Queries
If you need to check whether a specific point in space collides with any physic bodies, a point query can offer a precise answer.

// Execute a point collision query at the position (0, 1, 0)
var is_point_colliding = space_state.collide_with_point(Vector3(0, 1, 0), query_parameters.get_layers(), 32, false, true)

print("Point colliding: ", is_point_colliding ? "Yes" : "No")

These examples showcase PhysicsShapeQueryParameters3D as a versatile class capable of handling a wide array of physics-related scenarios in Godot. Through the manipulation of shape, transform, and collision layers/masks, game developers can create complex and dynamic interactions that respond to environmental situations, adding depth and realism to the gameplay. The ability to preemptively assess collisions and apply efficient approaches ensures that games run smoothly without compromising on the quality and accuracy of physics calculations.Simulating Gravity and Ground Check for Characters
For platformers or any game where gravity is a concern, it’s crucial to determine if a character is grounded. Here’s how you can use PhysicsShapeQueryParameters3D to perform a ground check:

// Define a ray shape starting from the character's feet downward
var ray_shape =
ray_shape.length = 1.0  // Slightly more than the distance to the ground

// Configure the ground check parameters
query_parameters.transform.origin = character_feet_position

// Perform a ground check with the shape
var on_ground = !space_state.intersect_shape(query_parameters).empty()

print("Character is ", on_ground ? "grounded" : "in mid-air")

Detecting Objects in a Cone Shape for AI Perception
An AI character might need to detect players or other objects within a cone-shaped field of view. By using a series of ray casts in a cone pattern, you can simulate this detection.

// Define the origin, range and angle for the cone perception
var origin = AI_character.global_transform.origin
var range = 10.0
var angle = 45.0

// Calculate the direction vectors at the edge of the cone
var left_direction = origin.looking_at(origin + AI_character.transform.basis.x.rotated(Vector3(0,1,0), deg2rad(-angle)), Vector3(0,1,0))
var right_direction = origin.looking_at(origin + AI_character.transform.basis.x.rotated(Vector3(0,1,0), deg2rad(angle)), Vector3(0,1,0))

// Perform ray casts along the edges of the cone
var left_hit = space_state.intersect_ray(origin, origin + left_direction * range)
var right_hit = space_state.intersect_ray(origin, origin + right_direction * range)

print("AI Perception Cone:")
print("Left Edge Hits: ", left_hit ? : "None")
print("Right Edge Hits: ", right_hit ? : "None")

Implementing Projectile Collision For a Shooting Game
When firing a projectile, you want to know if it collides with an enemy or obstacle. PhysicsShapeQueryParameters3D allows you to simulate the projectile’s trajectory and check for collisions using a sphere cast.

// Define the shape of the projectile
var projectile_shape =
projectile_shape.radius = 0.2

// Set up query parameters for the projectile's path
query_parameters.transform = projectile_global_transform

// Perform the sphere cast to simulate the projectile's path
var hit_info = space_state.intersect_shape(query_parameters)

if hit_info:
    print("Projectile hit: ",
    // Apply damage or effects

Using Convex Cast for Custom Collision Shapes
Complex objects might not fit simple shapes like boxes or spheres. Here’s how to perform a cast with a convex shape to match the object accurately.

// Create a convex shape from the mesh data
var mesh_data = your_mesh.create_convex_collision()
var convex_shape =
convex_shape.points = mesh_data

// Attach the convex shape to the query parameters

// Perform the convex cast
var hit_results = space_state.intersect_shape(query_parameters)

if hit_results:
    for hit in hit_results:
        print("Convex cast hit: ",

Adjusting Physics Layers in Real-Time
Sometimes, you might want to change which layers are included in a physics query during gameplay, such as when a character enters ‘stealth’ mode.

// Toggle the character's collision layer for stealth mode
func toggle_stealth_mode(is_stealth_active):
    var collision_layer = is_stealth_active ? 1 << 2 : 1 << 1  // Change to stealth or normal layer

These additional examples display the flexibility of the PhysicsShapeQueryParameters3D class in various game development contexts. Whether simulating realistic physics interactions, customizing AI perception, or handling dynamic collision detection for projectiles, PhysicsShapeQueryParameters3D offers the functionality needed for advanced and nuanced physical computation in Godot.

Where to Go Next in Your Godot Learning Journey

You’ve just scratched the surface of what’s possible with the PhysicsShapeQueryParameters3D class in Godot. As you continue developing your skills and building more complex and engaging games, you’ll find that there’s always more to learn and implement. To further advance your knowledge of Godot and game development, we highly encourage you to explore our Godot Game Development Mini-Degree. This comprehensive training program is tailor-made to enrich your understanding of game design and the powerful tools Godot offers, ranging from 2D and 3D development, gameplay mechanics, to interactive UI systems.

Delve deep into different game genres and take your capabilities from beginner to professional with our expertly crafted courses. Our curriculum is designed for flexibility, meaning you can learn at your own pace, anytime, anywhere, and solidify your skills by building real projects. Plus, Godot 4 is completely free and open-source, with a welcoming community to support your game development endeavors.

For a broader range of resources and to keep expanding your know-how, don’t forget to check out our full spectrum of Godot courses. With these tools and resources at your fingertips, we’re excited to see what you’ll create next. Let the adventure continue!


Diving into the depths of Godot’s three-dimensional physics with the PhysicsShapeQueryParameters3D class allows for the creation of truly dynamic and interactive game experiences. By mastering its application, you can bring nuanced physical interactions and complex behaviors to life in your virtual worlds. At Zenva, we’re passionate about supporting your journey through every line of code and every successful game launch. Empower your creativity and technical skills by joining us in our Godot Game Development Mini-Degree, where the possibilities are as limitless as your imagination.

It’s time to turn your game development aspirations into reality and create the games you’ve always dreamed of. Push the boundaries of what’s possible with Godot, and arm yourself with the expertise to transform your ideas into engaging, polished games. Remember, every expert was once a beginner, and with Zenva, you’re never alone on your path to becoming a game development pro. Let’s build incredible games together!

Python Blog Image

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