PhysicsRayQueryParameters3D in Godot – Complete Guide

Exploring the realm of game development often leads to fascinating discoveries, one of which includes deciphering the invisible forces that govern the interactions within game worlds. This is where understanding the PhysicsRayQueryParameters3D class in Godot 4 comes into play, as it is a vital component for creating responsive and dynamic 3D environments. Whether you’re curious about the mechanics behind the scenes or aspiring to craft intricate games yourself, delving into the physics of game worlds is not just educational, but also quite exhilarating.

What is PhysicsRayQueryParameters3D?

PhysicsRayQueryParameters3D is a class in Godot Engine that equips game developers with the ability to fine-tune raycasting in 3D space. Raycasting is a pivotal technique used in games to detect and interact with objects in the environment, underpinning mechanics such as shooting, line of sight, or sensor detection. This class serves as a configurable set of instructions for the PhysicsDirectSpaceState3D.intersect_ray method, enabling you to dictate aspects like the ray’s position, collision mask, and which objects it should ignore or include during the query.

What is it for?

Raycasting has a multitude of purposes in game development. By emitting invisible rays from a point and checking what they collide with, developers can create:
– Selection tools to highlight and interact with in-game objects.
– Weapons systems that require precision, such as sniper rifles.
– AI vision systems that must ascertain line-of-sight to the player.
– Virtual world sensors that trigger events when something enters a certain area.

Why Should I Learn It?

Grasping the functionality of the PhysicsRayQueryParameters3D class and the concept of raycasting can dramatically elevate the level of control you have over your game’s environment. It enables you to create more immersive and interactive game experiences. Moreover, since Godot is an open-source engine, learning how to use its 3D physics tools effectively can also be quite empowering, offering a sense of achievement and laying down a robust foundation for further game development learning.

CTA Small Image

Setting Up the RayQuery Parameters

Before we cast our first ray, we need to initialize the PhysicsRayQueryParameters3D class and set up the necessary parameters. Here’s how to start:

var ray_query =

Now that we have our ray query object, let’s define the origin and the destination of the ray. The origin will be where the ray starts, and the destination is the direction it will travel towards.

ray_query.from = Vector3(0, 1, 0) # ray starts 1 meter above the origin = Vector3(0, -1, 0) # ray points downwards

This sets up a simple vertical ray that travels from one point on the y-axis to another.

Configuring Collision Layers and Masks

In Godot, collision layers and masks determine which objects will interact with each other. By setting these on our ray query, we control what the ray can hit:

ray_query.collision_layer = 1 # the layer the ray is set on
ray_query.collision_mask = 1 # the mask says which layers the ray can collide with

The collision_mask is particularly flexible, allowing us to check for collisions with multiple layers:

ray_query.collision_mask = (1<<1) | (1<<2) # the ray can collide with layers 1 and 2

Excluding Specific Objects from Raycasting

There are times when you want to exclude certain objects from the raycast, such as the player character or specific items. We can easily achieve this using the exclude array:

var player = get_node("Player")
ray_query.exclude = [player]

Adding the player to the exclude list ensures that your ray will ignore the player object during its collision detection.

Executing the Raycast and Retrieving Information

With our ray query parameters set, we can perform the raycast using the PhysicsDirectSpaceState3D class, which is accessible from the PhysicsServer3D Iinstance. You can get a reference to the physics space state from a viewport, often from the scene’s main viewport:

var space_state = get_viewport().find_world_3d().direct_space_state

Now, we’re ready to execute the raycast:

var result = space_state.intersect_ray(ray_query)

The result is a dictionary containing information about what the ray has hit, if anything.

We might want to check if the ray has actually hit something and then print out or use its location:

if result:
    print("The ray hit something at: ", result.position)
    print("The ray didn't hit anything.")

By using this data, you can make your game react to different collision points and objects, such as playing a sound upon impact or spawning a visual effect.

Advanced Raycast Configurations

For more complex scenarios, PhysicsRayQueryParameters3D allows us to adjust even more parameters. For instance, you might want to set a maximum distance for your ray, beyond which it won’t register collisions:

ray_query.max_distance = 100 # the ray will only travel 100 meters

Another valuable feature is the ability to specify which types of collision objects the ray should detect:

ray_query.collision_mask = PhysicsDirectSpaceState3D.TYPE_MASK_STATIC_BODY | PhysicsDirectSpaceState3D.TYPE_MASK_RIGID_BODY

This configuration ensures that the ray only interacts with static and rigid bodies, ignoring all other types, such as areas or kinematic bodies.

With these code snippets and explanations, you’re now aware of how to configure and use raycasting using the PhysicsRayQueryParameters3D class in Godot 4. Understanding these fundamentals is a significant first step in harnessing the power of raycasting within your game projects.When working with advanced applications of raycasting, you may want to access detailed information about the collisions. For example, you might be interested in the exact normal of the surface the ray collided with, or potentially the colliding object’s velocity if it’s moving.

Let’s see how to retrieve this information from our raycast hit result:

if result:
    var collision_point = result.position
    var collision_normal = result.normal
    var collider_velocity = result.collider.velocity if result.collider has_method("velocity") else Vector3()
    print("Collision point: ", collision_point)
    print("Collision normal: ", collision_normal)
    print("Collider velocity: ", collider_velocity)

Here we are extracting the position, normal of the collision surface, and the collider’s velocity from the result dictionary. Notice the use of has_method() which is a safeguard for cases where the collider might not have a velocity method.

Another helpful feature is the use of the mask property of the PhysicsRayQueryParameters3D, which lets you add constraints to the raycast, like ignoring certain physics layers:

ray_query.mask = (1<<2) | (1<<4) # the ray will check for collisions only on layers 2 and 4

You may also need to perform raycasts from the camera or a moving object’s point of view. To ensure the ray aligns with the viewport or object’s forward direction, you can calculate the desired direction:

# Assume 'camera' is the node of your camera
var from_position = camera.global_transform.origin
var to_position = from_position + camera.global_transform.basis.z * -ray_distance

ray_query.from = from_position = to_position

In the above example, we declare the from position as the camera’s global position and the to position as a point in front of the camera, at a distance specified by ray_distance.

Sometimes, you’ll want to react to the type of object the ray has hit. Godot offers the convenience of obtaining the collider directly:

if result:
    var hit_object = result.collider
    if "is_enemy" in hit_object and hit_object.is_enemy:
        print("Hit an enemy!")

Here, we check if the hit object has an is_enemy variable, and if so, if it’s set to true.

Customizing the properties of your raycast, for instance, to allow the inclusion of specific physics body types (like kinematic bodies) is also possible:

ray_query.type_mask = PhysicsDirectSpaceState3D.TYPE_MASK_KINEMATIC_BODY

By setting the type_mask, we can specify that our ray should include kinematic bodies for the type of physics bodies the ray should query.

Lastly, triggering different behavior based on the shape of the object hit by the ray is sometimes necessary. In Godot 4, you can get the shape that was hit, which is particularly useful for advanced physics interactions:

if result:
    var shape = result.collider_shape
    if shape.get_shape_type() == Shape.TYPE_SPHERE:
        print("Hit a spherical object!")

In this segment of code, we’re retrieving the shape of the collider and then checking if it’s a sphere using the get_shape_type() method.

These various code examples demonstrate just a fraction of the power and flexibility offered by raycasting and the PhysicsRayQueryParameters3D class. By integrating these techniques into your workflow, you will have a robust toolkit to create highly interactive and reactive 3D worlds.Raycasting is versatile, and one of its significant uses is detecting obstacles between two objects. For instance, if you’re creating a stealth game, you might want to know if the enemy can see the player. Here is how you could set this up using raycasting with Godot 4:

var from_position = enemy.global_transform.origin
var to_position = player.global_transform.origin
ray_query.from = from_position = to_position

var result = space_state.intersect_ray(ray_query)
if result.empty() or result.collider == player:
    # The path is clear, or the player is the first hit
    print("Enemy has line of sight to the player!")

In some scenarios, you may want to perform multiple raycasts from a single source, like simulating a laser grid or casting rays from multiple points on an object to get a better understanding of the surrounding environment:

var origins = [Vector3(0, 1, 0), Vector3(0, 1, 1), Vector3(0, 1, -1)]
foreach origin in origins:
    ray_query.from = origin = origin + Vector3(0, -1, 0)
    var result = space_state.intersect_ray(ray_query)
    if result:
        print("Ray from ", origin, " hit something at ", result.position)

The above loop goes through multiple origins, each casting its own ray directly downward, checking for collisions.

Frequently, games require precise detection of different materials or surfaces, such as distinguishing between hitting water, metal, or stone. By customizing the physics material on your collidable objects, you can then read this data from the raycast hit:

if result:
    var collision_material = result.collider_shape.material
    if collision_material.is_class("PhysicsMaterial"):
        # PhysicsMaterial-specific logic here
        print("Hit material: ",

In this case, `collider_shape.material` provides access to the material of the shape we hit. We can use this to produce a variety of game responses.

Sometimes, your game mechanics may require the ray to respect or ignore certain properties of the collidable objects. A common requirement is for rays to only react to objects that are rendered, ignoring invisible or non-rendered elements:

if result:
    var hit_object = result.collider
    var is_visible = hit_object.is_visible_in_tree()
    if is_visible:
        print("Hit a visible object: ",

Here, `is_visible_in_tree()` checks if the object (and its parents) is visible in the scene tree, ensuring that gameplay elements respond only to those that should be “active” within the game world.

Creating dynamic interactions such as activating mechanisms or traps when they are hit by a ray is also a staple in many games:

if result:
    var hit_object = result.collider
    if hit_object.has_method("activate_trap"):
        print("Activated a trap!")

This code illustrates how you could activate a function on an object that the ray hits, provided that the method exists on that object.

Whether you are crafting a simple game or an elaborate simulation, understanding and using PhysicsRayQueryParameters3D and raycasting can open up a world of possibilities. By stepping through these examples, we’ve showcased the potential for creating interactive, realistic, and engaging experiences within the Godot 4 environment.

Where to Go Next in Your Game Development Journey

Mastering the intricacies of Godot 4 is an adventure filled with endless possibilities. If you’re looking to build on your knowledge and elevate your game development skills even further, we invite you to explore our comprehensive Godot Game Development Mini-Degree. Dive into a curated curriculum that covers a broad spectrum of topics, ranging from asset creation to mastering GDScript, and from fleshing out gameplay mechanics to piecing together full-fledged games across various genres. Whether you’re a newcomer or a seasoned developer, our project-based courses offer structured lessons, quizzes, and a project portfolio to showcase your newly acquired expertise.

For those hungry for more Godot content and diverse learning experiences, take a look at our wider collection of Godot courses. Our library is designed to support you from the beginning of your journey to professional levels. With Zenva, you have the flexibility to learn at your own pace, on any device, anytime, anywhere. Continue shaping your path in game development with us, and unlock the doors to creating captivating games that resonate with players across the globe.


We’ve journeyed through the practical applications of PhysicsRayQueryParameters3D in Godot 4, uncovering how this powerful tool can transform the way you interact with your game’s environment. Whether you’re building a game with intricate puzzles, designing immersive worlds, or implementing complex AI systems, mastering raycasting is an essential step. Embrace the lessons learned here and imagine the worlds you can create and the narratives you can weave with these game development superpowers.

Rise to the challenge and take your skills even further with our Godot Game Development Mini-Degree. This is your gateway to a universe of creative potential, where your passion for game design meets the power of knowledge. Join us at Zenva, fuel your game development aspirations, and step into the role of not just a game maker, but a game changer.

Python Blog Image

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