Guides
These docs are for v3.2.0. Click to read the latest docs for v3.3.0.

VRTK_ControllerEvents

Overview

The Controller Events script deals with events that the game controller is sending out.

The Controller Events script requires the Controller Mapper script on the same GameObject and provides event listeners for every button press on the controller (excluding the System Menu button as this cannot be overridden and is always used by Steam).

When a controller button is pressed, the script emits an event to denote that the button has been pressed which allows other scripts to listen for this event without needing to implement any controller logic. When a controller button is released, the script also emits an event denoting that the button has been released.

The script also has a public boolean pressed state for the buttons to allow the script to be queried by other scripts to check if a button is being held down.

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.
  • 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).
  • ButtonOneTouch - The button one is touched.
  • ButtonOnePress - The button one is pressed.
  • ButtonTwoTouch - The button one is touched.
  • ButtonTwoPress - The button one is pressed.
  • StartMenuPress - The button one is pressed.
  • 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 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 touch 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 pointerPressed - This will be true if the button aliased to the pointer is held down. Default: false
  • public bool grabPressed - This will be true if the button aliased to the grab is held down. Default: false
  • public bool usePressed - This will be true if the button aliased to the use is held down. Default: false
  • public bool uiClickPressed - This will be true if the button aliased to the UI click is held down. Default: false
  • public bool menuPressed - This will be true if the button aliased to the menu 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.
  • 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.
  • 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.
  • AliasPointerOn - Emitted when the pointer toggle alias button is pressed.
  • AliasPointerOff - Emitted when the pointer toggle alias button is released.
  • AliasPointerSet - Emitted when the pointer set alias button is released.
  • AliasGrabOn - Emitted when the grab toggle alias button is pressed.
  • AliasGrabOff - Emitted when the grab toggle alias button is released.
  • AliasUseOn - Emitted when the use toggle alias button is pressed.
  • AliasUseOff - Emitted when the use toggle alias button is released.
  • AliasMenuOn - Emitted when the menu toggle alias button is pressed.
  • AliasMenuOff - Emitted when the menu toggle alias button is released.
  • AliasUIClickOn - Emitted when the UI click alias button is pressed.
  • AliasUIClickOff - Emitted when the UI click alias button is released.
  • ControllerEnabled - Emitted when the controller is enabled.
  • ControllerDisabled - Emitted when the controller is disabled.
  • ControllerIndexChanged - Emitted when the controller index changed.
  • 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 was used.
  • 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.

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.

GetTouchpadAxis/0

public virtual Vector2 GetTouchpadAxis()

  • Parameters
  • none
  • Returns
  • Vector2 - A 2 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.

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.

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.

AnyButtonPressed/0

public virtual bool AnyButtonPressed()

  • Parameters
  • none
  • Returns
  • bool - Is 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.

IsButtonPressed/1

public virtual bool IsButtonPressed(ButtonAlias button)

  • Parameters
  • ButtonAlias button - The button to check if it's being pressed.
  • Returns
  • bool - Is 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 ButtonAlias 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 ButtonAlias 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.

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/Resources/Scripts/VRTK_ControllerEvents_ListenerExample.cs.