VRTK_Pointer

extends VRTK_DestinationMarker

Overview

Provides a basis of being able to emit a pointer from a specified GameObject.

Required Components:

• VRTK_BasePointerRenderer - The visual representation of the pointer when activated.

Optional Components:

• VRTK_ControllerEvents - The events component to listen for the button presses on. This must be applied on the same GameObject as this script if one is not provided via the Controller parameter.
• VRTK_InteractUse - The use component to utilise when the pointer is to activate the use action on an Interactable Object. This must be applied on the same GameObject as this script if one is not provided via the Interact Use parameter.

Script Usage:

• Place the VRTK_Pointer script on either:
  • The controller script alias GameObject of the controller to emit the pointer from (e.g. Right Controller Script Alias).
  • Any other scene GameObject and provide a valid Transform component to the Custom Origin parameter of this script. This does not have to be a controller and can be any GameObject that will emit the pointer.
• Link the required Base Pointer Renderer script to the Pointer Renderer parameter of this script.

Inspector Parameters

• Pointer Renderer: The specific renderer to use when the pointer is activated. The renderer also determines how the pointer reaches it's destination (e.g. straight line, bezier curve).
• Activation Button: The button used to activate/deactivate the pointer.
• Hold Button To Activate: If this is checked then the Activation Button needs to be continuously held down to keep the pointer active. If this is unchecked then the Activation Button works as a toggle, the first press/release enables the pointer and the second press/release disables the pointer.
• Activate On Enable: If this is checked then the pointer will be toggled on when the script is enabled.
• Activation Delay: The time in seconds to delay the pointer being able to be active again.
• Selection Button: The button used to execute the select action at the pointer's target position.
• Select On Press: If this is checked then the pointer selection action is executed when the Selection Button is pressed down. If this is unchecked then the selection action is executed when the Selection Button is released.
• Selection Delay: The time in seconds to delay the pointer being able to execute the select action again.
• Select After Hover Duration: The amount of time the pointer can be over the same collider before it automatically attempts to select it. 0f means no selection attempt will be made.
• Interact With Objects: If this is checked then the pointer will be an extension of the controller and able to interact with Interactable Objects.
• Grab To Pointer Tip: If Interact With Objects is checked and this is checked then when an object is grabbed with the pointer touching it, the object will attach to the pointer tip and not snap to the controller.
• Attached To: An optional GameObject that determines what the pointer is to be attached to. If this is left blank then the GameObject the script is on will be used.
• Controller Events: An optional Controller Events that will be used to toggle the pointer. If the script is being applied onto a controller then this parameter can be left blank as it will be auto populated by the controller the script is on at runtime.
• Interact Use: An optional InteractUse script that will be used when using interactable objects with pointer. If this is left blank then it will attempt to get the InteractUse script from the same GameObject and if it cannot find one then it will attempt to get it from the attached controller.
• Custom Origin: A custom transform to use as the origin of the pointer. If no pointer origin transform is provided then the transform the script is attached to is used.

Class Events

• ActivationButtonPressed - Emitted when the pointer activation button is pressed.
• ActivationButtonReleased - Emitted when the pointer activation button is released.
• SelectionButtonPressed - Emitted when the pointer selection button is pressed.
• SelectionButtonReleased - Emitted when the pointer selection button is released.
• PointerStateValid - Emitted when the pointer is in a valid state.
• PointerStateInvalid - Emitted when the pointer is in an invalid state.

Unity Events

Adding the VRTK_Pointer_UnityEvents component to VRTK_Pointer object allows access to UnityEvents that will react identically to the Class Events.

• All C# delegate events are mapped to a Unity Event with the On prefix. e.g. MyEvent -> OnMyEvent.

Class Methods

IsActivationButtonPressed/0

public virtual bool IsActivationButtonPressed()

• Parameters
  • none
• Returns
  • bool - Returns true if the activationButton is being pressed.

The IsActivationButtonPressed method returns whether the configured activation button is being pressed.

IsSelectionButtonPressed/0

public virtual bool IsSelectionButtonPressed()

• Parameters
  • none
• Returns
  • bool - Returns true if the selectionButton is being pressed.

The IsSelectionButtonPressed method returns whether the configured activation button is being pressed.

PointerEnter/1

public virtual void PointerEnter(RaycastHit givenHit)

• Parameters
  • RaycastHit givenHit - The valid collision.
• Returns
  • none

The PointerEnter method emits a DestinationMarkerEnter event when the pointer first enters a valid object, it emits a DestinationMarkerHover for every following frame that the pointer stays over the valid object.

PointerExit/1

public virtual void PointerExit(RaycastHit givenHit)

• Parameters
  • RaycastHit givenHit - The previous valid collision.
• Returns
  • none

The PointerExit method emits a DestinationMarkerExit event when the pointer leaves a previously entered object.

CanActivate/0

public virtual bool CanActivate()

• Parameters
  • none
• Returns
  • bool - Returns true if the pointer can be activated.

The CanActivate method is used to determine if the pointer has passed the activation time limit.

CanSelect/0

public virtual bool CanSelect()

• Parameters
  • none
• Returns
  • bool - Returns true if the pointer can execute the select action.

The CanSelect method is used to determine if the pointer has passed the selection time limit.

IsPointerActive/0

public virtual bool IsPointerActive()

• Parameters
  • none
• Returns
  • bool - Returns true if the pointer is currently active.

The IsPointerActive method is used to determine if the pointer's current state is active or not.

ResetActivationTimer/1

public virtual void ResetActivationTimer(bool forceZero = false)

• Parameters
  • bool forceZero - If this is true then the next activation time will be 0.
• Returns
  • none

The ResetActivationTimer method is used to reset the pointer activation timer to the next valid activation time.

ResetSelectionTimer/1

public virtual void ResetSelectionTimer(bool forceZero = false)

• Parameters
  • bool forceZero - If this is true then the next activation time will be 0.
• Returns
  • none

The ResetSelectionTimer method is used to reset the pointer selection timer to the next valid activation time.

Toggle/1

public virtual void Toggle(bool state)

• Parameters
  • bool state - If true the pointer will be enabled if possible, if false the pointer will be disabled if possible.
• Returns
  • none

The Toggle method is used to enable or disable the pointer.

IsStateValid/0

public virtual bool IsStateValid()

• Parameters
  • none
• Returns
  • bool - Returns true if the pointer is in the valid state (showing the valid colour), returns false if the pointer is in the invalid state (showing the invalid colour).

The IsStateValid method is used to determine if the pointer is currently in a valid state (i.e. on it's valid colour).