Raycast - stingray.Raycast object reference - Stingray Lua API Reference

stingray.Raycast object reference
Functions
expand all | collapse all

Description

This object allows you to perform collision tests against the physics objects in a PhysicsWorld.

Raycast objects are full userdata objects. That means:

  • Creating them is relatively heavy, so avoid creating many of them over the course of your game. The best practice is to create them in an initialization phase and re-use the same ones multiple times with new starting points and directions.
  • They are garbage collected when no references to them remain in the script. Once you create a Raycast object, you do not need to do anything in order to delete it. It is garbage collected as soon as it goes out of scope.

Conducting a raycast

You can carry out raycasts in three different ways, depending on how you want to retrieve the results.

Option 1. Single, synchronous raycasts

Use this option if you only need to conduct a single raycast, and you want the results immediately.

In this scenario, call the stingray.PhysicsWorld.raycast() function. You must specify the starting point, direction and maximum length of the ray, as well as parameters that control the collision test (see Raycast Parameters below).

For example:

local foundCollision, collisionPos, distance, normal, actor = stingray.PhysicsWorld.raycast(my_world, start, dir, "closest")

In this example, the raycast is called with the "closest" parameter, which means that the function will return detailed information about the first collision point (if any).

Option 2. Multiple, synchronous raycasts

Use this option if you want to carry out multiple raycasts with the same parameters (see Raycast Parameters below), and you need to handle the results immediately. This option is typically more efficient than calling stingray.PhysicsWorld.raycast() multiple times in sequence, since you are re-using the same Raycast object.

In this scenario, create a new Raycast object by calling stingray.PhysicsWorld.make_raycast(), omitting the callback parameter entirely. Then call the stingray.Raycast.cast() function of the new object. For example:

local raycastObj = stingray.PhysicsWorld.make_raycast(my_world, "all")
local collisionResultsA = raycastObj:cast(start, dirA, length)
local collisionResultsB = raycastObj:cast(start, dirB, length)
...

In this example, because the Raycast is initialized with the "all" parameter, the collisionResultsA and collisionResultsB variables are each set to an array of collision_hit data tables.

Option 3. Multiple, asynchronous raycasts

Use this option if you want to carry out multiple raycasts, and you can defer handling their results to a later frame.

In this scenario:

  1. You must first write a callback function that will be called automatically when the collision test has completed. The types of parameters your function must handle depends on the parameters that you specify when you create the Raycast object that you use to perform the test. See Raycast Parameters below.
  2. Create a new Raycast object by calling stingray.PhysicsWorld.make_raycast(), passing your function as the callback parameter.
  3. Call the stingray.Raycast.cast() function of the new object.

For example:

local raycastObj = stingray.PhysicsWorld.make_raycast(my_world, my_raycast_callback, "all", "types", "statics")
raycastObj:cast(start, dirA, length)
raycastObj:cast(start, dirB, length)
...

In this case, because the Raycast is initialized with the "all" parameter, the my_raycast_callback function will be passed an array of collision_hit data tables.

Raycast parameters

When you create a new Raycast object using stingray.PhysicsWorld.make_raycast(), or when you carry out a single synchronous raycast by calling stingray.PhysicsWorld.raycast(), you can specify some parameters that control the behavior of the collision test and the kinds of results that are produced.

The accepted parameter values are:

  • "any": Use this value if you only want to know whether or not the ray hit anything. When you use this option, the raycast produces only a single boolean value that indicates whether or not a collision was detected.

  • "all": Use this value if you want details on every collision along the path of the ray. When you use this option, the raycast produces a table that contains an array of collision_hit tables, each of which records one collision point along the ray.

  • "closest": Use this value if you only care about the first collision encountered by the ray. This is the default mode. When you use this option, the raycast produces several values:

    • A boolean value that indicates whether or not a collision was detected. If this is value is true, the following values are also provided.
    • A Vector3 that indicates the position of the collision in the 3D world.
    • A number that indicates the distance of the collision point from the starting point of the request.
    • A Vector3 that indicates the normal of the surface that was hit.
    • An Actor that indicates the physics actor that was hit.

  • "types": Determines the types of objects that should be considered for collision. If you specify this parameter, you must follow it with an additional string parameter that specifies the types. "statics" specifies that the ray should only test against static objects. "dynamics" specifies that the ray should only test against dynamic objects. "both" specifies that the ray should test against both static and dynamic objects; this is the default value.

  • "collision_filter": This parameter allows you to specify a collision filter that the ray should use to determine which objects it collides with. If you specify this parameter, you must follow it with an additional string parameter that specifies the name of the collision filter, as defined in your global.physics_properties data file. By default, the ray collides with all objects in the scene.

  • "mesh_both_sides" Add this parameter if you want the raycast to also hit back facing triangles in a physics mesh.

Functions

Parameters

self :

stingray.Raycast

Specifies the object instance that this function will act on.

You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.

start :

stingray.Vector3

Specifies the starting position for the raycast.

dir :

stingray.Vector3

Specifies the direction that the ray will be cast from its starting point.

length :

number?

Optional. Specifies the maximum length of the ray. If not specified, the ray will be infinitely long.

The ? notation indicates that this type is optional: there may be zero or one instances of it.
Returns

any(boolean, collision_hit[])

Whether or not a collision occurred.

The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

stingray.Vector3?

Position of the collision.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

number?

Distance to collision.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

stingray.Vector3?

Normal of collision surface.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

stingray.Actor?

Actor that was hit.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

If you specified a callback function when you called PhysicsWorld.make_raycast() to create the Raycast object, the raycast will be run asynchronously, and the results of the collision test will be passed to that callback function.

If you passed a nil value for the callback function when you called PhysicsWorld.make_raycast(), the raycast will be run immediately and the results of the collision test will be returned by Raycast.cast(). See the description of the Raycast object for details about how to interpret the return values.

Please send us your comment about this page