VRTK_ControllerEvents

Overview

A relationship to a physical VR controller and emits events based on the inputs of the controller.

Script Usage:

• Place the VRTK_ControllerEvents script on the controller script alias GameObject of the controller to track (e.g. Right Controller Script Alias).

Inspector Parameters

• Axis Fidelity: The amount of fidelity in the changes on the axis, which is defaulted to 1. Any number higher than 2 will probably give too sensitive results.
• Sense Axis Force Zero Threshold: The level on a sense axis to reach before the sense axis is forced to 0f
• Sense Axis Press Threshold: The amount of pressure required to be applied to a sense button before considering the sense button pressed.
• Trigger Click Threshold: The level on the trigger axis to reach before a click is registered.
• Trigger Force Zero Threshold: The level on the trigger axis to reach before the axis is forced to 0f.
• Trigger Axis Zero On Untouch: If this is checked then the trigger axis will be forced to 0f when the trigger button reports an untouch event.
• Grip Click Threshold: The level on the grip axis to reach before a click is registered.
• Grip Force Zero Threshold: The level on the grip axis to reach before the axis is forced to 0f.
• Grip Axis Zero On Untouch: If this is checked then the grip axis will be forced to 0f when the grip button reports an untouch event.

Class Variables

• public enum ButtonAlias - Button types
  • Undefined - No button specified.
  • TriggerHairline - The trigger is squeezed past the current hairline threshold.
  • TriggerTouch - The trigger is squeezed a small amount.
  • TriggerPress - The trigger is squeezed about half way in.
  • TriggerClick - The trigger is squeezed all the way down.
  • GripHairline - The grip is squeezed past the current hairline threshold.
  • GripTouch - The grip button is touched.
  • GripPress - The grip button is pressed.
  • GripClick - The grip button is pressed all the way down.
  • TouchpadTouch - The touchpad is touched (without pressing down to click).
  • TouchpadPress - The touchpad is pressed (to the point of hearing a click).
  • TouchpadTwoTouch - The touchpad two is touched (without pressing down to click).
  • TouchpadTwoPress - The touchpad two is pressed (to the point of hearing a click).
  • ButtonOneTouch - The button one is touched.
  • ButtonOnePress - The button one is pressed.
  • ButtonTwoTouch - The button two is touched.
  • ButtonTwoPress - The button two is pressed.
  • StartMenuPress - The start menu is pressed.
  • TouchpadSense - The touchpad sense touch is active.
  • TriggerSense - The trigger sense touch is active.
  • MiddleFingerSense - The middle finger sense touch is active.
  • RingFingerSense - The ring finger sense touch is active.
  • PinkyFingerSense - The pinky finger sense touch is active.
  • GripSense - The grip sense axis touch is active.
  • GripSensePress - The grip sense axis is pressed.
• public enum Vector2AxisAlias - Vector2 Axis Types.
  • Undefined - No axis specified.
  • Touchpad - Touchpad on the controller.
  • TouchpadTwo - Touchpad Two on the controller.
• public enum AxisType - Axis Types
  • Digital - A digital axis with a binary result of 0f not pressed or 1f is pressed.
  • Axis - An analog axis ranging from no squeeze at 0f to full squeeze at 1f.
  • SenseAxis - A cap sens axis ranging from not near at 0f to touching at 1f.
• public bool triggerPressed - This will be true if the trigger is squeezed about half way in. Default: false
• public bool triggerTouched - This will be true if the trigger is squeezed a small amount. Default: false
• public bool triggerHairlinePressed - This will be true if the trigger is squeezed a small amount more from any previous squeeze on the trigger. Default: false
• public bool triggerClicked - This will be true if the trigger is squeezed all the way down. Default: false
• public bool triggerAxisChanged - This will be true if the trigger has been squeezed more or less. Default: false
• public bool triggerSenseAxisChanged - This will be true if the trigger sense is being touched more or less. Default: false
• public bool gripPressed - This will be true if the grip is squeezed about half way in. Default: false
• public bool gripTouched - This will be true if the grip is touched. Default: false
• public bool gripHairlinePressed - This will be true if the grip is squeezed a small amount more from any previous squeeze on the grip. Default: false
• public bool gripClicked - This will be true if the grip is squeezed all the way down. Default: false
• public bool gripAxisChanged - This will be true if the grip has been squeezed more or less. Default: false
• public bool touchpadPressed - This will be true if the touchpad is held down. Default: false
• public bool touchpadTouched - This will be true if the touchpad is being touched. Default: false
• public bool touchpadAxisChanged - This will be true if the touchpad position has changed. Default: false
• public bool touchpadSenseAxisChanged - This will be true if the touchpad sense is being touched more or less. Default: false
• public bool touchpadTwoTouched - This will be true if the touchpad two is being touched. Default: false
• public bool touchpadTwoPressed - This will be true if the touchpad two is held down. Default: false
• public bool touchpadTwoAxisChanged - This will be true if the touchpad two position has changed. Default: false
• public bool buttonOnePressed - This will be true if button one is held down. Default: false
• public bool buttonOneTouched - This will be true if button one is being touched. Default: false
• public bool buttonTwoPressed - This will be true if button two is held down. Default: false
• public bool buttonTwoTouched - This will be true if button two is being touched. Default: false
• public bool startMenuPressed - This will be true if start menu is held down. Default: false
• public bool middleFingerSenseAxisChanged - This will be true if the middle finger sense is being touched more or less. Default: false
• public bool ringFingerSenseAxisChanged - This will be true if the ring finger sense is being touched more or less. Default: false
• public bool pinkyFingerSenseAxisChanged - This will be true if the pinky finger sense is being touched more or less. Default: false
• public bool gripSenseAxisChanged - This will be true if the grip sense is being touched more or less. Default: false
• public bool gripSensePressed - This will be true if grip sense is held down. Default: false
• public bool controllerVisible - This will be true if the controller model alias renderers are visible. Default: true

Class Events

• TriggerPressed - Emitted when the trigger is squeezed about half way in.
• TriggerReleased - Emitted when the trigger is released under half way.
• TriggerTouchStart - Emitted when the trigger is squeezed a small amount.
• TriggerTouchEnd - Emitted when the trigger is no longer being squeezed at all.
• TriggerHairlineStart - Emitted when the trigger is squeezed past the current hairline threshold.
• TriggerHairlineEnd - Emitted when the trigger is released past the current hairline threshold.
• TriggerClicked - Emitted when the trigger is squeezed all the way down.
• TriggerUnclicked - Emitted when the trigger is no longer being held all the way down.
• TriggerAxisChanged - Emitted when the amount of squeeze on the trigger changes.
• TriggerSenseAxisChanged - Emitted when the amount of touch on the trigger sense changes.
• GripPressed - Emitted when the grip is squeezed about half way in.
• GripReleased - Emitted when the grip is released under half way.
• GripTouchStart - Emitted when the grip is squeezed a small amount.
• GripTouchEnd - Emitted when the grip is no longer being squeezed at all.
• GripHairlineStart - Emitted when the grip is squeezed past the current hairline threshold.
• GripHairlineEnd - Emitted when the grip is released past the current hairline threshold.
• GripClicked - Emitted when the grip is squeezed all the way down.
• GripUnclicked - Emitted when the grip is no longer being held all the way down.
• GripAxisChanged - Emitted when the amount of squeeze on the grip changes.
• TouchpadPressed - Emitted when the touchpad is pressed (to the point of hearing a click).
• TouchpadReleased - Emitted when the touchpad has been released after a pressed state.
• TouchpadTouchStart - Emitted when the touchpad is touched (without pressing down to click).
• TouchpadTouchEnd - Emitted when the touchpad is no longer being touched.
• TouchpadAxisChanged - Emitted when the touchpad is being touched in a different location.
• TouchpadSenseAxisChanged - Emitted when the amount of touch on the touchpad sense changes.
• TouchpadTwoPressed - Emitted when the touchpad two is pressed (to the point of hearing a click).
• TouchpadTwoReleased - Emitted when the touchpad two has been released after a pressed state.
• TouchpadTwoTouchStart - Emitted when the touchpad two is touched (without pressing down to click).
• TouchpadTwoTouchEnd - Emitted when the touchpad two is no longer being touched.
• TouchpadTwoAxisChanged - Emitted when the touchpad two is being touched in a different location.
• ButtonOneTouchStart - Emitted when button one is touched.
• ButtonOneTouchEnd - Emitted when button one is no longer being touched.
• ButtonOnePressed - Emitted when button one is pressed.
• ButtonOneReleased - Emitted when button one is released.
• ButtonTwoTouchStart - Emitted when button two is touched.
• ButtonTwoTouchEnd - Emitted when button two is no longer being touched.
• ButtonTwoPressed - Emitted when button two is pressed.
• ButtonTwoReleased - Emitted when button two is released.
• StartMenuPressed - Emitted when start menu is pressed.
• StartMenuReleased - Emitted when start menu is released.
• MiddleFingerSenseAxisChanged - Emitted when the amount of touch on the middle finger sense changes.
• RingFingerSenseAxisChanged - Emitted when the amount of touch on the ring finger sense changes.
• PinkyFingerSenseAxisChanged - Emitted when the amount of touch on the pinky finger sense changes.
• GripSenseAxisChanged - Emitted when the amount of touch on the grip sense changes.
• GripSensePressed - Emitted when grip sense is pressed.
• GripSenseReleased - Emitted when grip sense is released.
• ControllerEnabled - Emitted when the controller is enabled.
• ControllerDisabled - Emitted when the controller is disabled.
• ControllerIndexChanged - Emitted when the controller index changed.
• ControllerModelAvailable - Emitted when the controller model becomes available.
• ControllerVisible - Emitted when the controller is set to visible.
• ControllerHidden - Emitted when the controller is set to hidden.

Unity Events

Adding the VRTK_ControllerEvents_UnityEvents component to VRTK_ControllerEvents 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.

Event Payload

• VRTK_ControllerReference controllerReference - The reference for the controller that initiated the event.
• float buttonPressure - The amount of pressure being applied to the button pressed. 0f to 1f.
• Vector2 touchpadAxis - The position the touchpad is touched at. (0,0) to (1,1).
• float touchpadAngle - The rotational position the touchpad is being touched at, 0 being top, 180 being bottom and all other angles accordingly. 0f to 360f.
• Vector2 touchpadTwoAxis - The position the touchpad two is touched at. (0,0) to (1,1).
• float touchpadTwoAngle - The rotational position the touchpad two is being touched at, 0 being top, 180 being bottom and all other angles accordingly. 0f to 360f.

Class Methods

SetControllerEvent/0

public virtual ControllerInteractionEventArgs SetControllerEvent()

• Parameters
  • none
• Returns
  • ControllerInteractionEventArgs - The payload for a Controller Event.

The SetControllerEvent/0 method is used to set the Controller Event payload.

SetControllerEvent/3

public virtual ControllerInteractionEventArgs SetControllerEvent(ref bool buttonBool, bool value = false, float buttonPressure = 0f)

• Parameters
  • ref bool buttonBool - The state of the pressed button if required.
  • bool value - The value to set the buttonBool reference to.
  • float buttonPressure - The pressure of the button pressed if required.
• Returns
  • ControllerInteractionEventArgs - The payload for a Controller Event.

The SetControllerEvent/3 method is used to set the Controller Event payload.

GetControllerType/0

public virtual SDK_BaseController.ControllerType GetControllerType()

• Parameters
  • none
• Returns
  • SDK_BaseController.ControllerType - The type of controller that the Controller Events is attached to.

The GetControllerType method is a shortcut to retrieve the current controller type the Controller Events is attached to.

GetAxis/1

public virtual Vector2 GetAxis(Vector2AxisAlias vector2AxisType)

• Parameters
  • Vector2AxisAlias vector2AxisType - The Vector2AxisType to check the touch position of.
• Returns
  • Vector2 - A two dimensional vector containing the x and y position of where the given axis type is being touched. (0,0) to (1,1).

The GetAxis method returns the coordinates of where the given axis type is being touched.

GetTouchpadAxis/0

public virtual Vector2 GetTouchpadAxis()

• Parameters
  • none
• Returns
  • Vector2 - A two dimensional vector containing the x and y position of where the touchpad is being touched. (0,0) to (1,1).

The GetTouchpadAxis method returns the coordinates of where the touchpad is being touched and can be used for directional input via the touchpad. The x value is the horizontal touch plane and the y value is the vertical touch plane.

GetTouchpadTwoAxis/0

public virtual Vector2 GetTouchpadTwoAxis()

• Parameters
  • none
• Returns
  • Vector2 - A two dimensional vector containing the x and y position of where the touchpad two is being touched. (0,0) to (1,1).

The GetTouchpadTwoAxis method returns the coordinates of where the touchpad two is being touched and can be used for directional input via the touchpad two. The x value is the horizontal touch plane and the y value is the vertical touch plane.

GetAxisAngle/1

public virtual float GetAxisAngle(Vector2AxisAlias vector2AxisType)

• Parameters
  • Vector2AxisAlias vector2AxisType - The Vector2AxisType to get the touch angle for.
• Returns
  • float - A float representing the angle of where the given axis type is being touched. 0f to 360f.

The GetAxisAngle method returns the angle of where the given axis type is currently being touched with the top of the given axis type being 0 degrees and the bottom of the given axis type being 180 degrees.

GetTouchpadAxisAngle/0

public virtual float GetTouchpadAxisAngle()

• Parameters
  • none
• Returns
  • float - A float representing the angle of where the touchpad is being touched. 0f to 360f.

The GetTouchpadAxisAngle method returns the angle of where the touchpad is currently being touched with the top of the touchpad being 0 degrees and the bottom of the touchpad being 180 degrees.

GetTouchpadTwoAxisAngle/0

public virtual float GetTouchpadTwoAxisAngle()

• Parameters
  • none
• Returns
  • float - A float representing the angle of where the touchpad two is being touched. 0f to 360f.

The GetTouchpadTwoAxisAngle method returns the angle of where the touchpad two is currently being touched with the top of the touchpad two being 0 degrees and the bottom of the touchpad two being 180 degrees.

GetTriggerAxis/0

public virtual float GetTriggerAxis()

• Parameters
  • none
• Returns
  • float - A float representing the amount of squeeze that is being applied to the trigger. 0f to 1f.

The GetTriggerAxis method returns a float that represents how much the trigger is being squeezed. This can be useful for using the trigger axis to perform high fidelity tasks or only activating the trigger press once it has exceeded a given press threshold.

GetGripAxis/0

public virtual float GetGripAxis()

• Parameters
  • none
• Returns
  • float - A float representing the amount of squeeze that is being applied to the grip. 0f to 1f.

The GetGripAxis method returns a float that represents how much the grip is being squeezed. This can be useful for using the grip axis to perform high fidelity tasks or only activating the grip press once it has exceeded a given press threshold.

GetHairTriggerDelta/0

public virtual float GetHairTriggerDelta()

• Parameters
  • none
• Returns
  • float - A float representing the difference in the trigger pressure from the hairline threshold start to current position.

The GetHairTriggerDelta method returns a float representing the difference in how much the trigger is being pressed in relation to the hairline threshold start.

GetHairGripDelta/0

public virtual float GetHairGripDelta()

• Parameters
  • none
• Returns
  • float - A float representing the difference in the trigger pressure from the hairline threshold start to current position.

The GetHairTriggerDelta method returns a float representing the difference in how much the trigger is being pressed in relation to the hairline threshold start.

GetTouchpadSenseAxis/0

public virtual float GetTouchpadSenseAxis()

• Parameters
  • none
• Returns
  • float - A float representing how much the touch sensor is being touched.

The GetTouchpadSenseAxis method returns a float representing how much of the touch sensor is being touched.

GetTriggerSenseAxis/0

public virtual float GetTriggerSenseAxis()

• Parameters
  • none
• Returns
  • float - A float representing how much the touch sensor is being touched.

The GetTriggerSenseAxis method returns a float representing how much of the touch sensor is being touched.

GetMiddleFingerSenseAxis/0

public virtual float GetMiddleFingerSenseAxis()

• Parameters
  • none
• Returns
  • float - A float representing how much the touch sensor is being touched.

The GetMiddleFingerSenseAxis method returns a float representing how much of the touch sensor is being touched.

GetRingFingerSenseAxis/0

public virtual float GetRingFingerSenseAxis()

• Parameters
  • none
• Returns
  • float - A float representing how much the touch sensor is being touched.

The GetRingFingerSenseAxis method returns a float representing how much of the touch sensor is being touched.

GetPinkyFingerSenseAxis/0

public virtual float GetPinkyFingerSenseAxis()

• Parameters
  • none
• Returns
  • float - A float representing how much the touch sensor is being touched.

The GetPinkyFingerSenseAxis method returns a float representing how much of the touch sensor is being touched.

GetGripSenseAxis/0

public virtual float GetGripSenseAxis()

• Parameters
  • none
• Returns
  • float - A float representing how much the touch sensor is being touched.

The GetGripSenseAxis method returns a float representing how much of the touch sensor is being touched.

AnyButtonPressed/0

public virtual bool AnyButtonPressed()

• Parameters
  • none
• Returns
  • bool - Returns true if any of the controller buttons are currently being pressed.

The AnyButtonPressed method returns true if any of the controller buttons are being pressed and this can be useful to determine if an action can be taken whilst the user is using the controller.

GetAxisState/2

public virtual bool GetAxisState(Vector2AxisAlias axis, SDK_BaseController.ButtonPressTypes pressType)

• Parameters
  • Vector2AxisAlias axis - The axis to check on.
  • SDK_BaseController.ButtonPressTypes pressType - The button press type to check for.
• Returns
  • bool - Returns true if the axis is being interacted with via the given press type.

The GetAxisState method takes a given Vector2Axis and returns a boolean whether that given axis is currently being touched or pressed.

IsButtonPressed/1

public virtual bool IsButtonPressed(ButtonAlias button)

• Parameters
  • ButtonAlias button - The button to check if it's being pressed.
• Returns
  • bool - Returns true if the button is being pressed.

The IsButtonPressed method takes a given button alias and returns a boolean whether that given button is currently being pressed or not.

SubscribeToButtonAliasEvent/3

public virtual void SubscribeToButtonAliasEvent(ButtonAlias givenButton, bool startEvent, ControllerInteractionEventHandler callbackMethod)

• Parameters
  • ButtonAlias givenButton - The Button Alias to register the event on.
  • bool startEvent - If this is true then the start event related to the button is used (e.g. OnPress). If this is false then the end event related to the button is used (e.g. OnRelease).
  • ControllerInteractionEventHandler callbackMethod - The method to subscribe to the event.
• Returns
  • none

The SubscribeToButtonAliasEvent method makes it easier to subscribe to a button event on either the start or end action. Upon the event firing, the given callback method is executed.

UnsubscribeToButtonAliasEvent/3

public virtual void UnsubscribeToButtonAliasEvent(ButtonAlias givenButton, bool startEvent, ControllerInteractionEventHandler callbackMethod)

• Parameters
  • ButtonAlias givenButton - The Button Alias to unregister the event on.
  • bool startEvent - If this is true then the start event related to the button is used (e.g. OnPress). If this is false then the end event related to the button is used (e.g. OnRelease).
  • ControllerInteractionEventHandler callbackMethod - The method to unsubscribe from the event.
• Returns
  • none

The UnsubscribeToButtonAliasEvent method makes it easier to unsubscribe to from button event on either the start or end action.

SubscribeToAxisAliasEvent/3

public virtual void SubscribeToAxisAliasEvent(SDK_BaseController.ButtonTypes buttonType, AxisType axisType, ControllerInteractionEventHandler callbackMethod)

• Parameters
  • SDK_BaseController.ButtonTypes buttonType - The button to listen for axis changes on.
  • AxisType axisType - The type of axis change to listen for.
  • ControllerInteractionEventHandler callbackMethod - The method to subscribe to the event.
• Returns
  • none

The SubscribeToAxisAliasEvent method makes it easier to subscribe to axis changes on a given button for a given axis type.

UnsubscribeToAxisAliasEvent/3

public virtual void UnsubscribeToAxisAliasEvent(SDK_BaseController.ButtonTypes buttonType, AxisType axisType, ControllerInteractionEventHandler callbackMethod)

• Parameters
  • SDK_BaseController.ButtonTypes buttonType - The button to unregister for axis changes on.
  • AxisType axisType - The type of axis change to unregister on.
  • ControllerInteractionEventHandler callbackMethod - The method to unsubscribe from the event.
• Returns
  • none

The UnsubscribeToAxisAliasEvent method makes it easier to unsubscribe from axis changes on a given button for a given axis type.

Example

VRTK/Examples/002_Controller_Events shows how the events are utilised and listened to. The accompanying example script can be viewed in VRTK/Examples/ExampleResources/Scripts/VRTK_ControllerEvents_ListenerExample.cs.