Type Function
Library physics.*
Return value Array of tables describing each hit
Revision Release 2024.3703
Keywords ray, raycast, casting, physics, collision
See also physics.reflectRay()


This function is used to find the objects that collide with a line, and the collision points along that line.

The positions returned are in content space while the normals returned are in local space.


If the starting position is inside an object, no hit will be registered for that object.


physics.rayCast( fromX, fromY, toX, toY, behavior )
fromX (required)

Number. The starting x position of the ray.

fromY (required)

Number. The starting y position of the ray.

toX (required)

Number. The ending x position of the ray.

toY (required)

Number. The ending y position of the ray.

behavior (optional)

String. The collision test behavior, in increasing order of performance cost:

  • "any" — Return one result, but not necessarily the closest one.
  • "closest" — Return only the closest hit from the starting point, if any. This is the default behavior.
  • "unsorted" — Return all results in no particular order.
  • "sorted" — Return all results, sorted from closest to farthest.

Result Properties

hits will be an array of elements containing these properties:


local hits = physics.rayCast( 0, 0, 200, 300, "closest" )

if ( hits ) then

    -- There's at least one hit
    print( "Hit count: " .. tostring( #hits ) )

    -- Output the results
    for i,v in ipairs( hits ) do
        print( "Hit: ", i, v.object, " Position: ", v.position.x, v.position.y, " Surface normal: ", v.normal.x, v.normal.y )

    print( "The first object hit is: ", hits[1].object, " at position: ", hits[1].position.x, hits[1].position.y, " where the surface normal is: ", hits[1].normal.x, hits[1].normal.y, " and where the fraction along the ray is: ", hits[1].fraction )
    -- No hits on raycast