Raycast Sensor

Directional line-of-sight raycaster detecting intersection points, surface normals, and hit fractions.

Type: RaycastNode · Category: Physics & Collision · Also found as: raycast

Properties

Property	Type	Default	Description
direction	vec2	(1, 0.5)	Direction of the ray (rotated with the node). Range -1 to 1.
length	number	450	Length of the ray (px). Range 1 to 2000.
collideWithSensors	boolean	false	Sensor shapes (areas) also stop the ray.
categoryLayers	flags: Layer1, Layer2, Layer3, Layer4, Layer5, Layer6, Layer7, Layer8, Layer9, Layer10, Layer11, Layer12 …	[Layer1]	Collision layers this object is on (names in Project Settings > Physics).
maskLayers	flags: Layer1, Layer2, Layer3, Layer4, Layer5, Layer6, Layer7, Layer8, Layer9, Layer10, Layer11, Layer12 …	[Layer1, Layer2, Layer3, Layer4, Layer5, Layer6, Layer7, Layer8, Layer9, Layer10, Layer11, Layer12, Layer13, Layer14, Layer15, Layer16]	Collision layers this object collides with.
isColliding	boolean	false	The ray hit something this frame. Runtime state: read-only, not saved.
hitFraction	number	0	Where along the ray it hit (0 start, 1 end). Range 0 to 1. Runtime state: read-only, not saved.
hitPoint	vec2	(0, 0)	World point of the hit (px). Range 0 to 1280. Runtime state: read-only, not saved.
hitNormal	vec2	(0, 0)	Surface direction at the hit. Range -1 to 1. Runtime state: read-only, not saved.
rayColor	color	#38bdf8ff	Ray colour when it hits nothing.
hitColor	color	#f87171ff	Ray colour when it hits.

Plus the common properties every node has.

Lua methods

Call them on the node (self.node in its script, or self.node:get_node("path")). Every node also has the Node methods.

RaycastNode:connect(event, handler)

Connects a handler to one of this node’s events: hit_started (The ray started hitting a node), hit_ended (The ray stopped hitting a node); the tree events; custom ones.

self.node:connect("hit_started", function(value, source) Log.info("hit_started") end)

• event RaycastNodeEvent|string
• handler fun(value: any, source: RaycastNode)

Returns integer id Connection id for disconnect

RaycastNode:get_property(path)

Reads an Inspector property by its path (vectors and colours as tables); “script.” reads a field of the node’s script.

local value = self.node:get_property("direction")

• path RaycastNodeProperty|string

Returns any

RaycastNode:set_property(path, value, y)

Sets an Inspector property by its path: vectors as {x, y} or x, y; colours as {r, g, b[, a]} 0..1 or “#rrggbb[aa]”; enums by name; “script.” a field of the node’s script.

self.node:set_property("direction", 100, 50)

• path RaycastNodeProperty|string
• value any
• y? number

RaycastNode:raycast_cast()

Executes the raycast immediately against the physics world.

local ray = self.node:get_node("Ray"); ray:raycast_cast()

RaycastNode:raycast_is_colliding()

Checks whether the raycast is currently intersecting a physics obstacle.

local ray = self.node:get_node("Ray"); ray:raycast_cast(); local grounded = ray:raycast_is_colliding()

Returns boolean

RaycastNode:raycast_get_hit_point()

Gets the world-space intersection point of the raycast hit.

local ray = self.node:get_node("Ray"); local x, y = ray:raycast_get_hit_point()

Returns number x, number y

RaycastNode:raycast_get_hit_normal()

Gets the world-space surface normal at the raycast intersection.

local ray = self.node:get_node("Ray"); local nx, ny = ray:raycast_get_hit_normal()

Returns number nx, number ny

RaycastNode:raycast_get_hit_fraction()

Gets the fraction from 0.0 to 1.0 along the ray length where the hit occurred.

local ray = self.node:get_node("Ray"); local dist = ray:raycast_get_hit_fraction() * 64

Returns number fraction

RaycastNode:raycast_get_hit_node()

Gets the Node struck by the raycast, or nil if none.

local ray = self.node:get_node("Ray"); local hit = ray:raycast_get_hit_node(); if hit then Log.info(hit.name) end

Returns Node?

RaycastNode:raycast_set_direction(dx, dy)

Sets the local direction vector for the raycast node.

local ray = self.node:get_node("Ray"); ray:raycast_set_direction(1, 0)

• dx number
• dy number

RaycastNode:raycast_set_length(length)

Sets the maximum reach length in pixels for the raycast node.

local ray = self.node:get_node("Ray"); ray:raycast_set_length(128)

• length number

In a scene file

{
  "type": "RaycastNode",
  "name": "RaycastSensor",
  "position": [
    0,
    0
  ],
  "properties": {
    "direction": [
      1,
      0.5
    ],
    "length": 450,
    "collideWithSensors": false
  }
}