ProtoFlux:Raycast One: Difference between revisions

From Resonite Wiki
Changed the note from information to suggestion.
Expand on and correct some existing information. Added Usage section to cover some potentially surprising behavior
Line 25: Line 25:
|}}
|}}


The <code>Raycast One</code> node allows raycast checks when impulses are received, and can take in parameters that sets up the raycast and the validity of what it checks for. When this raycast detects a valid collider, it returns data pertaining to that hit and fires from the OnHit continuation output. When there is no valid colliders hit (whether it is due to not being a valid target or could not be reached), the OnMiss continuation output fires.
The <code>Raycast One</code> performs a single raycast check when an impulse is received. The input parameters determine from where, in what direction, and how far the ray should be cast as well as determining which colliders are valid hits. When a raycast detects a valid collider, it returns data pertaining to that hit and fires from the OnHit continuation output. If there is no valid hit, whether where were no colliders hit or the ones hit were not valid targets, the OnMiss continuation output fires.


This node can be combined with the [[ProtoFlux:Hit UV Coordinate|Hit UV Coordinate]] node to get further data from this hit, such as a 2D location point on the collider for example.
This node can be combined with the [[ProtoFlux:Hit UV Coordinate|Hit UV Coordinate]] node to get further data from this hit, such as a 2D location point on the collider for example.
Line 35: Line 35:
=== * ([[Impulses|Call]]) ===  
=== * ([[Impulses|Call]]) ===  


Calls an impulse to start the raycast check with the given parameters.
Performs a raycast with the input parameters when an impulse is received.


=== Origin ([[Type:float3|float3]]) ===  
=== Origin ([[Type:float3|float3]]) ===  


The point where we start this raycast.
The starting position from which the ray is cast. Default is [0;0;0].


=== Direction ([[Type:float3|float3]]) ===  
=== Direction ([[Type:float3|float3]]) ===  


The direction where this raycast should go in.
The direction in which the ray is cast. Default is [0;0;0] which results in no ray being cast.


=== MaxDistance ([[Type:float|float]]) ===  
=== MaxDistance ([[Type:float|float]]) ===  


The maximum distance this raycast should go.
The maximum distance the raycast should travel from its origin. Default is the maximum float value which is extremely high.


=== HitTriggers ([[Type:bool|bool]]) ===  
=== HitTriggers ([[Type:bool|bool]]) ===  


Should this raycast hit trigger colliders.
Determines whether colliders with the Trigger, StaticTrigger or StaticTriggerAuto ColliderType value are valid hit targets. Default is False.


=== UsersOnly ([[Type:bool|bool]]) ===  
=== UsersOnly ([[Type:bool|bool]]) ===  


Should this raycast only hit users.
Determines whether only user bone or simplified capsule colliders are valid targets. Default is False.


=== DebugDuration ([[Type:float|float]]) ===  
=== DebugDuration ([[Type:float|float]]) ===  


Shows a debug line of where this raycast came from and how far it went, as well as showing this line for the given duration.
Determines the duration in seconds that a debug visual will be shown after each raycast. Default is -1 which disables the debug visual. When enabled, the visual shows a yellow line indicating the full path of the raycast along with the hit point (red spheres) and hit normal direction (blue arrows).  


=== Root ([[Slot]]) ===  
=== Root ([[Slot]]) ===  


The slot hierarchy this raycast should check for when hitting slots, and only return data from slots it hit from within that slot hierarchy.
The slot in whose coordinate space the Origin, Direction and MaxDistance values should be evaluated. Default is the world root slot, i.e. the values are treated as being in the global coordinate space (see [[Coordinate spaces]]).


== Outputs ==
== Outputs ==
Line 69: Line 69:
=== OnHit ([[Impulses|Continuation]]) ===
=== OnHit ([[Impulses|Continuation]]) ===


This gets fired when a valid collider has been hit by this raycast.
Fires an impulse if a valid hit is found when performing a raycast.


=== OnMiss ([[Impulses|Continuation]]) ===
=== OnMiss ([[Impulses|Continuation]]) ===


This gets fired when there is no valid collider detected by his raycast.
Fires an impulse in any situation where a valid hit is not found when performing a raycast.


=== HitCollider ([[Type:ICollider|ICollider]]) ===
=== HitCollider ([[Type:ICollider|ICollider]]) ===


The collider we detected from this raycast.
The first valid hit collider.


=== HitDistance ([[Type:float|float]]) ===
=== HitDistance ([[Type:float|float]]) ===


The distance from where we hit a valid collider.
The distance from the Origin to the hit point in global coordinate space.


=== HitPoint ([[Type:float3|float3]]) ===
=== HitPoint ([[Type:float3|float3]]) ===


The point in 3D space where we hit this valid collider.
The global position at which the ray hit the collider.


=== HitNormal ([[Type:float3|float3]]) ===
=== HitNormal ([[Type:float3|float3]]) ===


The facing normal that we hit from a valid collider.
The facing normal direction of the hit collider at the hit point.


=== HitTriangleIndex ([[Type:int|int]]) ===
=== HitTriangleIndex ([[Type:int|int]]) ===


The triangle mesh number we hit.
The triangle index on the mesh corresponding to the hit collider. This value is 0 unless the HitCollider is a MeshCollider.


== Usage ==
There are a few ways in which the Raycast One node may not work as expected, particularly relating to directions and distances.
Firstly, the global scale of the input Root slot is taken into account when calculating a raycast's path. For example, assume that the Root slot input has global position [0;0;0] and global scale [0.1;0.1;0.1]; if the Origin input is [0;0;0], the raycast will start at global [0;0;0], however, if the Origin input is [0;1;0] the raycast will start at global [0;0.1;0] not global [0;1;0].
Similarly, the input Root slot's global scale affects the Direction vector and MaxDistance values too. With the same example input Root slot, a Direction of [0;0;1] and a MaxDistance of 1 result in a ray which travels only 0.1 units.
Secondly, the magnitude of the Direction vector affects the distance that the ray travels and the reported HitDistance output value. Assuming no input Root slot, a Direction input of [0;0;1] and MaxDistance of 1 will produce a ray 1 unit long. However, a Direction input of [0;0;2] and MaxDistance of 1 will produce a ray 2 units long. Additionally, the reported HitDistance value will be halved in the second case.
The data output values are only valid for a given raycast hit for the duration of the impulse chain downstream of OnHit.
[[Category:ProtoFlux:Physics]]
[[Category:ProtoFlux:Physics]]

Revision as of 06:22, 20 May 2024

Raycast One
*
OnHit
Origin
OnMiss
Direction
HitCollider
MaxDistance
HitDistance
HitTriggers
HitPoint
UsersOnly
HitNormal
DebugDuration
HitTriangleIndex
Root
Physics

The Raycast One performs a single raycast check when an impulse is received. The input parameters determine from where, in what direction, and how far the ray should be cast as well as determining which colliders are valid hits. When a raycast detects a valid collider, it returns data pertaining to that hit and fires from the OnHit continuation output. If there is no valid hit, whether where were no colliders hit or the ones hit were not valid targets, the OnMiss continuation output fires.

This node can be combined with the Hit UV Coordinate node to get further data from this hit, such as a 2D location point on the collider for example.

If you want the same functionality as this node, but want to check for valid hits continuously, use Raycaster instead.

Inputs

* (Call)

Performs a raycast with the input parameters when an impulse is received.

Origin (float3)

The starting position from which the ray is cast. Default is [0;0;0].

Direction (float3)

The direction in which the ray is cast. Default is [0;0;0] which results in no ray being cast.

MaxDistance (float)

The maximum distance the raycast should travel from its origin. Default is the maximum float value which is extremely high.

HitTriggers (bool)

Determines whether colliders with the Trigger, StaticTrigger or StaticTriggerAuto ColliderType value are valid hit targets. Default is False.

UsersOnly (bool)

Determines whether only user bone or simplified capsule colliders are valid targets. Default is False.

DebugDuration (float)

Determines the duration in seconds that a debug visual will be shown after each raycast. Default is -1 which disables the debug visual. When enabled, the visual shows a yellow line indicating the full path of the raycast along with the hit point (red spheres) and hit normal direction (blue arrows).

Root (Slot)

The slot in whose coordinate space the Origin, Direction and MaxDistance values should be evaluated. Default is the world root slot, i.e. the values are treated as being in the global coordinate space (see Coordinate spaces).

Outputs

OnHit (Continuation)

Fires an impulse if a valid hit is found when performing a raycast.

OnMiss (Continuation)

Fires an impulse in any situation where a valid hit is not found when performing a raycast.

HitCollider (ICollider)

The first valid hit collider.

HitDistance (float)

The distance from the Origin to the hit point in global coordinate space.

HitPoint (float3)

The global position at which the ray hit the collider.

HitNormal (float3)

The facing normal direction of the hit collider at the hit point.

HitTriangleIndex (int)

The triangle index on the mesh corresponding to the hit collider. This value is 0 unless the HitCollider is a MeshCollider.

Usage

There are a few ways in which the Raycast One node may not work as expected, particularly relating to directions and distances.

Firstly, the global scale of the input Root slot is taken into account when calculating a raycast's path. For example, assume that the Root slot input has global position [0;0;0] and global scale [0.1;0.1;0.1]; if the Origin input is [0;0;0], the raycast will start at global [0;0;0], however, if the Origin input is [0;1;0] the raycast will start at global [0;0.1;0] not global [0;1;0]. Similarly, the input Root slot's global scale affects the Direction vector and MaxDistance values too. With the same example input Root slot, a Direction of [0;0;1] and a MaxDistance of 1 result in a ray which travels only 0.1 units.

Secondly, the magnitude of the Direction vector affects the distance that the ray travels and the reported HitDistance output value. Assuming no input Root slot, a Direction input of [0;0;1] and MaxDistance of 1 will produce a ray 1 unit long. However, a Direction input of [0;0;2] and MaxDistance of 1 will produce a ray 2 units long. Additionally, the reported HitDistance value will be halved in the second case.

The data output values are only valid for a given raycast hit for the duration of the impulse chain downstream of OnHit.