RaycastParams

Not yet Datatype

A container for parameters used in raycasting operations.

Not implemented in Nova

This datatype is not registered in Nova's Lua VM. Constructing or receiving it from an API call will not work.

Description

The RaycastParams data type stores parameters for WorldRoot.Raycast() operations. The ExcludeInstances and IncludeInstances properties store a set of objects and their descendants that will be excluded and included from the query. The RaycastParams.IgnoreWater property can be used to ignore Terrain water, and the RaycastParams.CollisionGroup property can specify a collision group for the raycasting operation.

This object is different from the similarly named RaycastResult which provides the results of a raycast.

Unlike most data types in Luau, you can change all of the members of RaycastParams without creating a new object, allowing you to reuse the same object repeatedly.

Constructors

new Not yet Returns a blank RaycastParams.

RaycastParams.new()

Returns a blank RaycastParams.

Returns a blank RaycastParams object. Unlike other data type constructors, this constructor does not have any parameters, so you should set its properties appropriately.

Properties

ExcludeInstances Not yet An optional array of instances whose descendants will be excluded from the query.

RaycastParams.ExcludeInstances()

An optional array of instances whose descendants will be excluded from the query. This property can be used simultaneously with IncludeInstances to allow for mixed filtering, for example including a large folder but excluding specific child instances. If an instance matches both an exclude and include filter, exclusions take priority over inclusions.

IncludeInstances Not yet An optional array of instances whose descendants will be included in the query.

RaycastParams.IncludeInstances()

An optional array of instances whose descendants will be included in the query. This property can be used simultaneously with ExcludeInstances to allow for mixed filtering. If an instance matches both an exclude and include filter, exclusions take priority over inclusions.

Setting IncludeInstances to nil versus an empty array ({}) has opposite effects. IncludeInstances = nil is the most permissive filter (includes everything), whereas IncludeInstances = {} is the most restrictive filter (includes nothing).

IgnoreWater Not yet Determines whether the water material is considered when raycasting against Terrain.

RaycastParams.IgnoreWater()

Determines whether the water material is considered when raycasting against Terrain.

CollisionGroup Not yet The collision group used for the operation.

RaycastParams.CollisionGroup()

The collision group used for the operation.

Specifies a collision group for the raycasting operation. Parts in collision groups that are set to not collide with this group are ignored. If this property is omitted, the raycast assumes the Default collision group.

RespectCanCollide Not yet Determines whether the raycast operation considers a part's CanCollide property value over its CanQuery value.

RaycastParams.RespectCanCollide()

Determines whether the raycast operation considers a part's CanCollide property value over its CanQuery value.

This property, if true, makes the raycast operation use an intersected part's CanCollide value in favor of its CanQuery value when determining whether that part is included in the RaycastResult.

BruteForceAllSlow Not yet When enabled, the query will ignore all part collision properties and perform a brute-force check on every part.

RaycastParams.BruteForceAllSlow()

When enabled, the query will ignore all part collision properties and perform a brute-force check on every part. This will negatively impact performance and should not be used in live experiences.

Margin Not yet Expands the cast shape uniformly in every direction.

RaycastParams.Margin()

Expands the cast shape uniformly in every direction. Must be finite and greater than or equal to 0. Defaults to 0.

Margin applies to WorldRoot.Shapecast(), WorldRoot.Blockcast(), WorldRoot.Spherecast() and WorldRoot.Raycast(). The expanded shape is what the maximum-size limit is checked against, so a large Margin can make an otherwise valid cast throw.

Setting a non-zero Margin on a WorldRoot.Raycast() makes the operation behave as a sphere cast of that radius.

SizeGradient Not yet Scales the cast shape over the length of the cast, tapering the swept volume.

RaycastParams.SizeGradient()

Scales the cast shape over the length of the cast, tapering the swept volume.

Scales the cast shape over the length of the cast. Must be finite and greater than or equal to -1. Defaults to 0, which casts the shape at a constant size.

The shape starts at its original size and is scaled by 1 + SizeGradient by the end of the cast, interpolating in between. A SizeGradient of 0.5 finishes the cast 50% larger, -0.5 finishes it at half size, and -1 shrinks it away entirely.

SizeGradient scales the shape's own size, not Margin, so a cast with both keeps its margin at a constant width along the way. WorldRoot.Spherecast() is the exception: radius and margin are one and the same for a sphere, so both scale together.

FilterDescendantsInstances Not yet An array of objects whose descendants are used to filter raycasting candidates.

RaycastParams.FilterDescendantsInstances()

An array of objects whose descendants are used to filter raycasting candidates. Note that this property has been superseded by ExcludeInstances and IncludeInstances which should be used for new work.

FilterType Not yet Determines whether the FilterDescendantsInstances array is used as an exclude or include list.

RaycastParams.FilterType()

Determines whether the FilterDescendantsInstances array is used as an exclude or include list. Note that this property has been superseded by ExcludeInstances and IncludeInstances which should be used for new work.

Methods

AddToFilter Not yet Adds the instances provided to FilterDescendantsInstances.

RaycastParams:AddToFilter(instances: Instance | Array)

Adds the instances provided to FilterDescendantsInstances. Note that this property has been superseded by ExcludeInstances and IncludeInstances which should be used for new work.

Roblox reference: RaycastParams