PhysicsRayQueryParameters2D in Godot – Complete Guide

Discovering PhysicsRayQueryParameters2D in Godot 4

Working with physics in a game can often feel like a balancing act between accuracy and performance. Luckily, for those of us delving into the world of 2D game development with Godot 4, the PhysicsRayQueryParameters2D class offers a powerful way to query our game’s physics space with precision and flexibility. Whether you’re a budding game developer or you’ve already had your fair share of coding battles, understanding the intricacies of physics queries can be a game-changer.

What is PhysicsRayQueryParameters2D?

The PhysicsRayQueryParameters2D class in Godot 4 lets us fine-tune the details of a raycast query in our game’s 2D space. Raycasting is a technique that involves sending out an “imaginary ray” from one point to another in the game world, checking for intersections with game objects along the way.

What is it used for?

Ever wondered how games detect when a character sees an enemy, or how bullets find their targets? That’s often done through raycasting. By utilizing the PhysicsRayQueryParameters2D class, we can efficiently determine line-of-sight, create laser sensors, or even simulate realistic light rays within our game environments.

Why should I learn it?

Raycasting is a cornerstone of game physics, and mastering it can give you a lot of control over game mechanics. It’s an efficient way to handle collision detection without the overhead of physics bodies interacting. By learning how to properly configure and use PhysicsRayQueryParameters2D, you’ll be adding a vital tool to your game development toolkit, one that brings your game to life with dynamic interactions.

CTA Small Image

Setting Up PhysicsRayQueryParameters2D

Before you can start using PhysicsRayQueryParameters2D, you need to set it up properly in your Godot project. To begin, you must create an instance of the PhysicsRayQueryParameters2D class.

var ray_query =

Once you have the instance, we need to define the starting point of the ray and the direction it will travel. You can set these properties using the ‘from’ and ‘to’ vectors.

ray_query.from = Vector2(100, 100) = Vector2(300, 100)

Configuring the Ray’s Properties

Customization is key when working with raycasting. PhysicsRayQueryParameters2D allows you to set properties such as the collision layer and mask, which control which objects the ray interacts with.

ray_query.collide_with_areas = true
ray_query.collide_with_bodies = false
ray_query.collision_mask = 1

The ‘collide_with_areas’ and ‘collide_with_bodies’ flags determine whether the ray should consider areas and physics bodies, respectively. Setting the ‘collision_mask’ ensures that the ray only checks for collisions with objects on the specified layers.

Executing the Raycast Query

Now that your PhysicsRayQueryParameters2D is configured, it’s time to query the physics space. You need to do this through the Physics2DServer, which is the server responsible for managing the physics in Godot. Here’s how you perform the raycast:

var space_state = get_world_2d().direct_space_state
var result = space_state.intersect_ray(ray_query.from,, [], ray_query.collision_mask)

The ‘intersect_ray’ method will return a dictionary with details about the collision if it finds one. If there is no collision, the result will be empty.

Interpreting the Query Results

The raycast query will provide you with useful information about any collisions that occur. Here’s how to interpret the results from the dictionary:

if result:
    print("Collision at position: ", result.position)
    print("Collided with object: ", result.collider)
    print("Collision normal: ", result.normal)

Each key in the result dictionary provides different pieces of information:
– ‘position’ gives you the exact point where the ray intersected with an object.
– ‘collider’ is a reference to the object that was hit by the ray.
– ‘normal’ gives you the normal of the collision point, which can be useful for reflection calculations or determining the angle of the surface hit.

Through these examples, you’ve seen how to create, configure, execute, and interpret a PhysicsRayQueryParameters2D raycast in Godot 4. By understanding these basics, you’re well on your way to incorporating dynamic physics-based queries into your game projects. Stay tuned for the next part, where we’ll dive deeper into practical use cases of raycasting, and explore some more advanced features!Sometimes, you will want to exclude certain objects from the raycast query, such as the player character to prevent self-collision detection. You can achieve this by defining an exclude list.

var exclude = [player]
var result = space_state.intersect_ray(ray_query.from,, exclude, ray_query.collision_mask)

It’s important to adjust the collision mask if you add new layers to your game. This ensures that your ray is interacting with the intended layers.

ray_query.collision_mask = (1 << 2) | (1 << 3)  # Collides with layers 2 and 3

You can also fine-tune the behavior of your raycast by colliding only with the closest object, which can be crucial for line-of-sight mechanics:

ray_query.exclude_raycast_shapes = true  # Ignores other raycast shapes
ray_query.collision_mask = 1
var result = space_state.intersect_ray(ray_query.from,, [], ray_query.collision_mask)

There might be scenarios where you need to adjust the ray’s endpoint dynamically, like when you’re casting a laser pointer that should stop at the first obstacle it meets. Here’s how you could update the ‘to’ vector on-the-fly:

if result: = result.position

If you’re working with complex shapes or need more granular control over the collision, Godot 4 allows you to attach a shape to the ray query for shape casting. This can be especially useful for simulating wider beams or area effects:

var shape =
shape.radius = 10
ray_query.shape_rid = shape.get_rid()
var result = space_state.intersect_shape(ray_query, 10)

Sometimes during gameplay, you may need to activate or deactivate raycasting dynamically. You can easily enable or disable your ray queries without needing to recreate them from scratch, preserving performance:

func toggle_ray_active(is_active):
    ray_query.enabled = is_active

In advanced cases, you might need to execute multiple ray queries at once, such as casting rays in a fan shape to simulate a field of view. You can loop through a series of angles and cast multiple rays accordingly:

var angle_step = 5
var num_rays = 20
var angle_offset = -num_rays * angle_step * 0.5
for i in range(num_rays):
    var angle = (angle_offset + i * angle_step) * PI / 180
    var dir = Vector2(cos(angle), sin(angle))
    var result = space_state.intersect_ray(ray_query.from, ray_query.from + dir * ray_distance, [], ray_query.collision_mask)
    if result:
        draw_line(ray_query.from, result.position,

Understanding these examples can significantly enhance your game’s physics interactions. As always, remember that the best way to master these techniques is through practice—the more you experiment with the PhysicsRayQueryParameters2D class, the more nuanced and exciting your game mechanics can become. Happy coding!Continuing from the previous examples, here are additional ways you can leverage the PhysicsRayQueryParameters2D class in Godot 4 to create sophisticated game mechanics.

To begin with, let’s discuss how you might use raycasts to create traps or sensors in your game. Here’s a simple way to trigger an event when something breaks a “laser tripwire”:

func check_tripwire():
    var result = space_state.intersect_ray(tripwire_start, tripwire_end, [], ray_query.collision_mask)
    if result:

In this example, `activate_trap()` is a function you would define that takes action based on what the ray has hit, such as setting off an alarm or springing a trap.

Sometimes, you’ll want to perform multiple raycasts between two points. This can be done in a loop to, for instance, create a grid of sensors:

var step_size = 10
for x in range(start_x, end_x, step_size):
    for y in range(start_y, end_y, step_size):
        var from = Vector2(x, y)
        var to = Vector2(x, y + ray_length)
        var result = space_state.intersect_ray(from, to, [], collision_mask)
        if result:

In the above code, `handle_detection()` would manage the logic for when a sensor detects something within its grid area.

Another interesting use case for PhysicsRayQueryParameters2D is simulating echoes or sonar, by casting rays out and measuring their distance before they hit an object. This can be utilized for stealth mechanics, underwater exploration, or environment scanning:

var echo_results = []
for angle in range(0, 360, angle_increment):
    var direction = Vector2(cos(angle), sin(angle))
    var result = space_state.intersect_ray(echo_origin, echo_origin + direction * max_distance, [], ray_query.collision_mask)
    if result:

This will fill `echo_results` with data about all the objects detected in a 360-degree scan around the `echo_origin`.

For platformers or other physics-driven genres, you may want to use raycasts to detect ground or walls, which can be useful for grounding characters or enabling wall-jumps:

var down_ray_to = player_position + Vector2(0, 1) * ground_ray_length
var wall_ray_to = player_position + player_facing_direction * wall_ray_length

var on_ground = space_state.intersect_ray(player_position, down_ray_to, [], ray_query.collision_mask)
var hit_wall = space_state.intersect_ray(player_position, wall_ray_to, [], ray_query.collision_mask)

if on_ground:
    # Code to handle player landing
if hit_wall:
    # Code to handle wall collision

Lastly, in games where lighting is dynamic, you might want to use raycasts to determine if areas are lit or in shadows. Here’s how you might check for light obstruction:

func is_in_light(light_position, object_position, light_radius):
    var to_light = light_position - object_position
    if to_light.length() > light_radius:
        return false  # Object is outside the light's radius
    var result = space_state.intersect_ray(object_position, light_position, [self], ray_query.collision_mask)
    return result == null  # If no collision, the object is not obstructed and is in light

In this function, we check whether an object is within a light’s radius and then whether the light is reaching the object without being blocked.

All these examples demonstrate how flexible and integral PhysicsRayQueryParameters2D can be to game development within Godot 4. Each game can benefit from these raycasting techniques to create responsive, interactive, and realistic worlds. Keep practicing with these examples and see how you can adapt them to fit your own game’s needs. With each new project, you’ll find more creative and efficient ways to implement physics queries, making your gameplay experience all the more compelling.

Where to Go Next with Your Godot Education

Having honed your skills with PhysicsRayQueryParameters2D in Godot 4, you might be wondering what the next step in your game development journey should be. Each new technique you learn is a step towards building richer and more interactive game experiences, and there’s always more to discover.

If you’re eager to expand your knowledge and take your game development abilities to the next level, we invite you to explore our Godot Game Development Mini-Degree. This series of meticulously crafted courses covers a range of foundational and advanced topics in Godot. From rendering graphics and mastering GDScript to creating games across various genres, our Mini-Degree is geared to empower you with the practical skills needed to design and launch your own cross-platform games.

For those who seek a broader outlook on everything Godot has to offer, our collection of Godot courses is the perfect hub. Whether you’re just starting out or looking to fine-tune specific aspects of your game development expertise, we’ve got you covered. At Zenva, we are committed to providing you with high-quality content that caters to all levels of experience, helping you to transform your game concepts into playable realities. Continue your learning adventure with us, and let’s build amazing games together!


The journey of game creation is one of continuous learning and creation. Dive into the PhysicsRayQueryParameters2D in Godot 4 and you’ll unveil a realm of possibilities, allowing you to craft games that engage players on a whole new level. Remember, the mechanics you’ve learned are tools to turn the imagined into reality, to breathe life into your digital worlds, and to capture the imaginations of those who dare to explore them.

Continue to expand your game development toolkit with us at Zenva, where empowering your passion through education is our mission. Embrace the full spectrum of Godot’s capabilities by checking out our complete range of Godot tutorials, and take another step toward becoming an architect of virtual worlds. Your ideas are waiting to leap from your mind onto the screen—let’s make them play!

Python Blog Image

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