Skip to Content
Kinemium
Datatypes

Spatial queries

Rays, regions, physical properties, path waypoints, and the parameter objects used by raycasts and overlaps.

Ray

Ray.new(origin, direction) describes a line in 3D. The direction does not have to be normalized.

local ray = Ray.new(Vector3.new(0, 5, 0), Vector3.new(0, -1, 0))
print(ray:Distance(Vector3.new(3, 5, 0))) -- 3
MemberTypeDescription
OriginVector3Starting point.
DirectionVector3Direction and length.
UnitRayRay with a unit-length direction.
MethodReturnsDescription
ClosestPoint(point)Vector3Point on the ray closest to point.
Distance(point)numberDistance from the ray to point.

Equality compares origin and direction.

Region3

Region3.new(min, max) is an axis-aligned box defined by two corners.

MemberTypeDescription
MinVector3Minimum corner.
MaxVector3Maximum corner.
SizeVector3Extent of the region.
CFrameCFrameFrame at the center of the region.
MethodReturnsDescription
ExpandToGrid(resolution)Region3Expands the region to a grid. resolution must be greater than zero.

Region3int16

Region3int16.new(min, max) uses Vector3int16 corners for a compact integer region.

MemberTypeDescription
MinVector3int16Minimum corner.
MaxVector3int16Maximum corner.
SizeVector3int16Extent of the region.

PhysicalProperties

PhysicalProperties.new(density, friction, elasticity, frictionWeight?, elasticityWeight?) describes surface behavior for custom physical properties.

local rubber = PhysicalProperties.new(0.7, 0.9, 0.8, 1, 1)
part.CustomPhysicalProperties = rubber
ArgumentDefaultDescription
densityRequiredMass per unit volume.
frictionRequiredSurface friction.
elasticityRequiredBounciness.
frictionWeight100Weight of this surface's friction in a contact.
elasticityWeight100Weight of this surface's elasticity in a contact.

Values outside the accepted range raise an error.

MemberTypeDescription
DensitynumberDensity.
FrictionnumberFriction.
ElasticitynumberElasticity.
FrictionWeightnumberFriction weight.
ElasticityWeightnumberElasticity weight.

PathWaypoint

PathWaypoint.new(position, action?, label?) is one point returned by pathfinding.

ArgumentDefaultDescription
positionRequiredVector3 position.
actionEnum.PathWaypointAction.WalkWhat happens at this point.
label""Optional label.
MemberTypeDescription
PositionVector3Position.
ActionEnum.PathWaypointActionAction at this point.
LabelstringLabel.

RaycastParams

RaycastParams.new() creates a filter object for Workspace:Raycast().

local params = RaycastParams.new()
params.FilterDescendantsInstances = { character }
params.FilterType = Enum.RaycastFilterType.Exclude
PropertyTypeDescription
FilterDescendantsInstances{Instance}Instances excluded or included by the filter.
ExcludeInstances{Instance}?Explicit exclusion list. nil when never set.
IncludeInstances{Instance}?Explicit inclusion list. nil when never set.
FilterTypeEnum.RaycastFilterTypeWhether the filter excludes or includes.
IgnoreWaterbooleanSkip water.
RespectCanCollidebooleanOnly hit parts where CanCollide is set.
BruteForceAllSlowbooleanTest every candidate instead of using the broad phase.
CollisionGroupstringCollision group to query.
MethodDescription
AddToFilter(instanceOrArray)Adds an instance, or a nested array of instances, to the filter.

RaycastResult

A raycast result is returned by the engine. You do not construct it.

MemberTypeDescription
PositionVector3Hit position.
NormalVector3Surface normal at the hit.
DistancenumberDistance from the origin.
MaterialEnum.MaterialMaterial at the hit.
InstanceInstancePart that was hit.

OverlapParams

OverlapParams.new() creates a filter object for overlap queries.

local params = OverlapParams.new()
params.FilterType = Enum.RaycastFilterType.Exclude
params.MaxParts = 10
PropertyTypeDescription
FilterDescendantsInstances{Instance}Instances excluded or included by the filter.
ExcludeInstances{Instance}?Explicit exclusion list.
IncludeInstances{Instance}?Explicit inclusion list.
FilterTypeEnum.RaycastFilterTypeWhether the filter excludes or includes.
MaxPartsnumberMaximum results. Must be a nonnegative 32-bit integer.
CollisionGroupstringCollision group to query.
TolerancenumberQuery tolerance, clamped to 0 through 0.05.
RespectCanCollidebooleanOnly include parts where CanCollide is set.
BruteForceAllSlowbooleanTest every candidate instead of using the broad phase.

AddToFilter(instanceOrArray) adds entries to FilterDescendantsInstances.

TerrainRegion

TerrainRegion is not creatable from Luau. Terrain APIs return it when they save a region, and you pass it back to restore that region.

See also

  • Workspace for raycasts and spatial queries.
  • Physics for practical query examples.

On this page