Creating and Using QRaycastObject

QRaycastObject instances allow you to cast a ray into the physics world and retrieve detailed collision information from all objects the ray intersects — ordered from the closest to the farthest hit point.

How to Create a QRaycastObject

QRaycastObject instances are not part of the scene tree; they are created via code. You don't need to manually delete them. If Godot finds no references to them, they will be automatically removed.

To use a QRaycastObject, you need to set up 4 main properties:

• position:
  The starting point of the ray in the physics world.

• ray_vector:
  The direction and length of the ray to be cast from the position.

• enable_containing_bodies:
  Determines whether bodies that already contain the ray's starting position should be included in the results.

  • If set to true:
    The first collision will be with the object that contains the ray’s origin, and the collision position will be the same as the ray’s starting point.

  • If set to false:
    Objects that contain the ray's origin are ignored.

• collidable_layers:
  Only objects on these specified layers will be considered in collision detection.

#Creating a QRaycastObject
var my_raycast:QRaycastObject=QRaycastObject.new()
#Configuring a QRaycastObject
my_raycast.configure(ray_position,ray_vector,enable_containing_bodies,collidable_layers)
#Adding a raycast to QWorldNode
world_node.add_raycast(my_raycast)

#You can also modify the properties of a QRaycastObject at any time
my_raycast.set_position(new_position) # to retrieve: get_position()
my_raycast.set_ray_vector(new_ray_vector) # to retrieve: get_ray_vector()
my_raycast.set_containing_bodies_enabled(true_or_false) # to retrieve : get_containing_bodies_enabled()
my_raycast.set_collidable_layers_bit(new_layers_bit) #to retrieve : get_collidable_layers_bit()

#Additionally, you can change the rotation of a QRaycastObject.
my_raycast.set_rotation(new_rotation) #to retrieve : get_rotation()

How to Get Collision Information

You can use the get_contacts() method to retrieve collision data for the current physics frame.
This method returns a Godot Array of Dictionary objects, each containing data about one collision.
The array is sorted from nearest to farthest based on the ray's origin.

Each collision dictionary contains the following:

• body: The QBody that was hit by the ray.
• position: The point in world space where the collision occurred.
• normal: The surface normal at the collision point.
• distance: The distance from the ray’s starting position to the collision point.

Example:
Here's how to retrieve the first collision (closest hit) using get_contacts():

#Retrieving contacts from a QRaycastObject
var contacts=my_raycast.get_contacts()
#Check if there are any contacts
if contacts.size()>0 :
	#Get the first contact
	var my_contact=contacts[0]
	var contact_body=my_contact["body"]
	var contact_position=my_contact["position"]
	var contact_normal=my_contact["normal"]
	var contact_distance=my_contact["distance"]

Do I Always Need to Use QRaycastObject to Cast a Ray?

Short answer: No.

QRaycastObject is ideal when you need to cast rays repeatedly (e.g., every frame), as it's optimized for performance and ease of use in such cases.

However, if you only need to cast a ray occasionally, using a QRaycastObject might be unnecessary and less efficient.

Instead, you can use the simpler raycast_to() method provided by QWorldNode. This method immediately casts a ray in the physics world and returns results in the same format as QRaycastObject.get_contacts().

#Casting a ray to QWorldNode
var ray_contacts=world_node.raycast_to(start_position,ray_vector,collidable_layers_bit,enable_containing_bodies)
if ray_contacts.size()>0 :
         #Get first contact
         var contact=ray_contacts[0]
         var contact_body=contact["body"]
         var contact_position=contact["position"]
         ...