Skip to main content

Ray Sensor

The Ray Sensor detects objects intersected by a ray. It uses the family of raycast functions inside Physics or Physics2D. The sensor detects all objects along its path up until it hits an Obstructing Collider. It will not detect objects beyond the obstruction.


A Ray Sensor detects the ground beneath the falling character

Output Signals

  • Object - Collider.gameObject or Collider.attachedRigidBody.gameObject depending on Detection Mode
  • Strength - Set to 1
  • Shape - Zero-size Bounds centred at the point of intersection

An obstruction does not have a Signal because obstructions are not detected. It is possible however for the same GameObject to be detected and obstructing simultaneously.

you can retrieve details about the intersection of the ray with each object. Access it with the GetDetectionRayHit() or GetObstructionRayHit() methods.

Configuration

Shape

There are several casting shapes to choose from. The 3D sensor has: Ray, Sphere, Box and Capsule. The 2D sensor has 2D equivalents of these shapes. The shape you choose determines which physics function is called. For example Ray would use Physics.RayCast and Sphere would use Physics.SphereCast.

Layers

Both Detects On Layers and Obstructed By Layers are layer masks where you can choose one or more physics layers. The ray will intersect with a Collider if it's layer is specified in either mask, but the two cases work differently.

  • Detects On Layers - Will detect all intersected objects in one of these layers (depending on filter settings).
  • Obstructed By Layers - A Collider on this layer will obstruct the sensor if it's intersected.


The ray on top is unobstructed and detects all three characters. On the bottom the ray is obstructed by the wall, it will detect the character in front, but will not detect the characters behind

Filters

These properties let you filter which objects are detected by the sensor:

Ignore List

Any GameObject in this list will not be detected by the sensor and will not obstruct the sensor. There is some nuance for how it filters obstructions. To decide if an obstructing Collider is ignored the following logic is used:

  • Ignore if Collider.gameObject is present in the ignore list.
  • Ignore if Collider.attachedRigidBody.gameObject is present in the ignore list.

A Signal is ignored if its Signal.Object is present in the ignore list.

Tag Filter

Activate tag filtering by clicking the Enable Tag Filter option. Configure the filter by populating a list of allowed tags. For an object to be detected it's tag must be specified in this list. Obstructions aren't affected by the tag filter.

Minimum Slope Angle

Filters detections and obstructions depending on the slope angle at the point of intersection. The slope angle is measured between the Normal of the RayCastHit and the configured Up direction.

Optimisation Considerations

Depending on the configuration the sensor will use either Physics.RayCast or Physics.RayCastNonAlloc.

  • Physics.RayCast - Calculates only the first intersection along the rays path. This has better performance.
  • Physics.RayCastNonAlloc - Calculates all intersections along the rays path. Not as good performance.

The sensor is smart enough to use the better performance Physics.RayCast in certain configurations.

  • The Detects On Layers mask is a subset of Obstructed By Layers. Anything the sensor can detect will also obstruct it.
  • Tag Filter is disabled, Ignore List is empty and Minimum Slope Angle is set to 0.

API

API Page