Skip to content

How to raycast from code in Godot 4: PhysicsRayQueryParameters2D

By Eduardo Orellana · Updated

Build the query with PhysicsRayQueryParameters2D.create(from, to) and pass it to get_world_2d().direct_space_state.intersect_ray(query); the result is a Dictionary with collider, position and normal, or empty when nothing was hit. Godot 3's intersect_ray(from, to) fails to parse with Too many arguments for "intersect_ray()" call. Expected at most 1 but received 2.

AppImage, x86_64. Ubuntu 22.04, Debian 12, Fedora 39 or newer.

Intel or AMD Chromebook, with Linux turned on.

Download for macOSDownload for WindowsDownload for Linux

What Godot is checking

Godot 4 moved a ray's options (collision mask, exclusions, whether to hit areas) into a query object. intersect_ray() takes that one object, so two points are too many arguments and the first is the wrong type.

Query the space state in _physics_process(), when the physics space is in a consistent state. A RayCast2D node does the same every physics frame without code.

More on this: PhysicsDirectSpaceState in Godot 4: it is PhysicsDirectSpaceState3D now

Reproduce it

A Godot 3 ray query, in a Godot 4 project.

GDScript
extends Node2D

func _physics_process(_delta):
	var space = get_world_2d().direct_space_state
	var hit = space.intersect_ray(Vector2.ZERO, Vector2(200, 0))
	print(hit)

What Godot 4.7.2 prints

Output
Godot Engine v4.7.2.stable.mono.official.ed1daf0bf - https://godotengine.org

SCRIPT ERROR: Parse Error: Too many arguments for "intersect_ray()" call. Expected at most 1 but received 2.
   at: GDScript::reload (res://answers/how-to-raycast-from-code-in-godot-4/repro.gd:5)
SCRIPT ERROR: Parse Error: Invalid argument for "intersect_ray()" function: argument 1 should be "PhysicsRayQueryParameters2D" but is "Vector2".
   at: GDScript::reload (res://answers/how-to-raycast-from-code-in-godot-4/repro.gd:5)
ERROR: Failed to load script "res://answers/how-to-raycast-from-code-in-godot-4/repro.gd" with error "Parse error".
   at: load (modules/gdscript/gdscript_resource_format.cpp:46)

Fix it

A ray from the origin to the right, toward a StaticBody2D named Wall at x = 120.

GDScript
extends Node2D

func _physics_process(_delta: float) -> void:
	var space := get_world_2d().direct_space_state
	var query := PhysicsRayQueryParameters2D.create(Vector2.ZERO, Vector2(200, 0))
	var hit := space.intersect_ray(query)
	if hit:
		print("hit ", hit.collider.name, " at ", hit.position, ", normal ", hit.normal)
	else:
		print("nothing")
	set_physics_process(false)

What the fixed script prints

Output
Godot Engine v4.7.2.stable.mono.official.ed1daf0bf - https://godotengine.org

hit Wall at (110.0, 0.0), normal (-1.0, 0.0)

Run this fix with your agent

Flockbay is the Godot editor with an AI agent built in. Paste this into Flockbay's chat, or into Claude Code or Codex connected to Flockbay over MCP: the agent finds the cause in your project, applies the fix, runs the game headless and reads Godot's output to check it.

More on this: RayCast in Godot 4: it is RayCast3D now

Prompt
How to raycast from code in Godot 4: PhysicsRayQueryParameters2D Build the query with PhysicsRayQueryParameters2D.create(from, to) and pass it to get_world_2d().direct_space_state.intersect_ray(query); the result is a Dictionary with collider, position and normal, or empty when nothing was hit. Godot 3's intersect_ray(from, to) fails to parse with Too many arguments for "intersect_ray()" call. Expected at most 1 but received 2. Where this calls for a change in my Godot 4 project, make it, then run the game headless and check Godot's output for errors.

Verified on Godot 4.7.2

Both scripts on this page were run headless on Godot 4.7.2 (4.7.2.stable.mono.official.ed1daf0bf) on 18 October 2026, and the output above is what Godot printed, unedited.

Where the check lives in Godot's source: gdscript_analyzer.cpp line 3484, the message, PhysicsRayQueryParameters2D in the class reference.

Questions

How do I make the ray ignore the player?
query.exclude = [player.get_rid()], or set query.collision_mask to leave out the player's layer.
What is the 3D version?
PhysicsRayQueryParameters3D.create(from, to) with get_world_3d().direct_space_state.intersect_ray(query).

Flockbay's agent reads Godot's debugger output and fixes errors like this one in your project, on the official Godot.

Download Flockbay free