This file provides documentation on how to use the included prefabs and scripts.
A collection of pre-defined usable prefabs have been included to allow for each drag-and-drop set up of common elements.
- Frames Per Second Canvas
- Object Tooltip
- Controller Tooltips
- Controller Rigidbody Activator
- Snap Drop Zone
- Radial Menu
- Independent Radial Menu Controller
- Console Viewer Canvas
- Panel Menu Controller
- Panel Menu Item Controller
This canvas adds a frames per second text element to the headset. To use the prefab it must be placed into the scene then the headset camera needs attaching to the canvas:
- Select
FramesPerSecondCanvasobject from the scene objects - Find the
Canvascomponent - Set the
Render Cameraparameter toCamera(eye)which can be found in the[CameraRig]prefab.
This script is pretty much a copy and paste from the script at: http://talesfromtherift.com/vr-fps-counter/ So all credit to Peter Koch for his work. Twitter: @peterept
- Display FPS: Toggles whether the FPS text is visible.
- Target FPS: The frames per second deemed acceptable that is used as the benchmark to change the FPS text colour.
- Font Size: The size of the font the FPS is displayed in.
- Position: The position of the FPS text within the headset view.
- Good Color: The colour of the FPS text when the frames per second are within reasonable limits of the Target FPS.
- Warn Color: The colour of the FPS text when the frames per second are falling short of reasonable limits of the Target FPS.
- Bad Color: The colour of the FPS text when the frames per second are at an unreasonable level of the Target FPS.
VRTK/Examples/018_CameraRig_FramesPerSecondCounter displays the frames per second in the centre of the headset view. Pressing the trigger generates a new sphere and pressing the touchpad generates ten new spheres. Eventually when lots of spheres are present the FPS will drop and demonstrate the prefab.
This adds a UI element into the World Space that can be used to provide additional information about an object by providing a piece of text with a line drawn to a destination point.
There are a number of parameters that can be set on the Prefab which are provided by the VRTK/Scripts/VRTK_ObjectTooltip script which is applied to the prefab.
- Display Text: The text that is displayed on the tooltip.
- Font Size: The size of the text that is displayed.
- Draw Line From: An optional transform of where to start drawing the line from. If one is not provided the centre of the tooltip is used for the initial line position.
- Draw Line To: A transform of another object in the scene that a line will be drawn from the tooltip to, this helps denote what the tooltip is in relation to. If no transform is provided and the tooltip is a child of another object, then the parent object's transform will be used as this destination position.
- Line Width: The width of the line drawn between the tooltip and the destination transform.
- Font Color: The colour to use for the text on the tooltip.
- Container Color: The colour to use for the background container of the tooltip.
- Line Color: The colour to use for the line drawn between the tooltip and the destination transform.
public void ResetTooltip()
- Parameters
- none
- Returns
- none
The ResetTooltip method resets the tooltip back to its initial state.
public void UpdateText(string newText)
- Parameters
string newText- A string containing the text to update the tooltip to display.- Returns
- none
The UpdateText method allows the tooltip text to be updated at runtime.
VRTK/Examples/029_Controller_Tooltips displays two cubes that have an object tooltip added to them along with tooltips that have been added to the controllers.
This adds a collection of Object Tooltips to the Controller that give information on what the main controller buttons may do. To add the prefab, it just needs to be added as a child of the relevant controller e.g. [CameraRig]/Controller (right) would add the controller tooltips to the right controller.
If the transforms for the buttons are not provided, then the script will attempt to find the attach transforms on the default controller model in the [CameraRig] prefab.
If no text is provided for one of the elements then the tooltip for that element will be set to disabled.
There are a number of parameters that can be set on the Prefab which are provided by the VRTK/Scripts/VRTK_ControllerTooltips script which is applied to the prefab.
- Trigger Text: The text to display for the trigger button action.
- Grip Text: The text to display for the grip button action.
- Touchpad Text: The text to display for the touchpad action.
- App Menu Text: The text to display for the application menu button action.
- Tip Background Color: The colour to use for the tooltip background container.
- Tip Text Color: The colour to use for the text within the tooltip.
- Tip Line Color: The colour to use for the line between the tooltip and the relevant controller button.
- Trigger: The transform for the position of the trigger button on the controller (this is usually found in
Model/trigger/attach. - Grip: The transform for the position of the grip button on the controller (this is usually found in
Model/lgrip/attach. - Touchpad: The transform for the position of the touchpad button on the controller (this is usually found in
Model/trackpad/attach. - App Menu: The transform for the position of the app menu button on the controller (this is usually found in
Model/button/attach.
public void ResetTooltip()
- Parameters
- none
- Returns
- none
The Reset method reinitalises the tooltips on all of the controller elements.
public void UpdateText(TooltipButtons element, string newText)
- Parameters
TooltipButtons element- The specific controller element to change the tooltip text on.string newText- A string containing the text to update the tooltip to display.- Returns
- none
The UpdateText method allows the tooltip text on a specific controller element to be updated at runtime.
public void ToggleTips(bool state, TooltipButtons element = TooltipButtons.None)
- Parameters
bool state- The state of whether to display or hide the controller tooltips, true will display and false will hide.TooltipButtons element- The specific element to hide the tooltip on, if it isTooltipButtons.Nonethen it will hide all tooltips. Optional parameter defaults toTooltipButtons.None- Returns
- none
The ToggleTips method will display the controller tooltips if the state is true and will hide the controller tooltips if the state is false. An optional element can be passed to target a specific controller tooltip to toggle otherwise all tooltips are toggled.
VRTK/Examples/029_Controller_Tooltips displays two cubes that have an object tooltip added to them along with tooltips that have been added to the controllers.
This adds a simple trigger collider volume that when a controller enters will enable the rigidbody on the controller.
The prefab game object should be placed in the scene where another interactable game object (such as a button control) is located to turn the controller rigidbody on at the appropriate time for interaction with the control without needing to manually activate by pressing the grab.
If the prefab is placed as a child of the target interactable game object then the collider volume on the prefab will trigger collisions on the interactable object.
The sphere collider on the prefab can have the radius adjusted to determine how close the controller needs to be to the object before the rigidbody is activated.
It's also possible to replace the sphere trigger collider with an alternative trigger collider for customised collision detection.
This sets up a predefined zone where an existing interactable object can be dropped and upon dropping it snaps to the set snap drop zone transform position, rotation and scale.
The position, rotation and scale of the SnapDropZone Game Object will be used to determine the final position of the dropped interactable object if it is dropped within the drop zone collider volume.
The provided Highlight Object Prefab is used to create the highlighting object (also within the Editor for easy placement) and by default the standard Material Color Swap highlighter is used.
An alternative highlighter can also be added to the SnapDropZone Game Object and this new highlighter component will be used to show the interactable object position on release.
The prefab is a pre-built game object that contains a default trigger collider (Sphere Collider) and a kinematic rigidbody (to ensure collisions occur).
If an alternative collider is required, then the default Sphere Collider can be removed and another collider added.
If the Use Joint Snap Type is selected then a custom Joint component is required to be added to the SnapDropZone Game Object and upon release the interactable object's rigidbody will be linked to this joint as the Connected Body.
- Highlight Object Prefab: A game object that is used to draw the highlighted destination for within the drop zone. This object will also be created in the Editor for easy placement.
- Snap Type: The Snap Type to apply when a valid interactable object is dropped within the snap zone.
- Snap Duration: The amount of time it takes for the object being snapped to move into the new snapped position, rotation and scale.
- Apply Scaling On Snap: If this is checked then the scaled size of the snap drop zone will be applied to the object that is snapped to it.
- Highlight Color: The colour to use when showing the snap zone is active.
- Highlight Always Active: The highlight object will always be displayed when the snap drop zone is available even if a valid item isn't being hovered over.
- Valid Object With Tag Or Class: A string that specifies an object Tag or the name of a Script attached to an object and notifies the snap drop zone that this is a valid object for snapping on release.
- Valid Object Tag Or Script List Policy: A specified VRTK_TagOrScriptPolicyList to use to determine which interactable objects will be snapped to the snap drop zone on release. If a list is provided then the 'Valid Object With Tag Or Class' parameter will be ignored.
- Display Drop Zone In Editor: If this is checked then the drop zone highlight section will be displayed in the scene editor window.
public enum SnapTypes- The types of snap on release available.Use_Kinematic- Will set the interactable object rigidbody toisKinematic = true.Use_Joint- Will attach the interactable object's rigidbody to the provided joint as it'sConnected Body.Use_Parenting- Will set the SnapDropZone as the interactable object's parent and set it's rigidbody toisKinematic = true.
ObjectEnteredSnapDropZone- Emitted when a valid interactable object enters the snap drop zone trigger collider.ObjectExitedSnapDropZone- Emitted when a valid interactable object exists the snap drop zone trigger collider.ObjectSnappedToDropZone- Emitted when an interactable object is successfully snapped into a drop zone.ObjectUnsnappedFromDropZone- Emitted when an interactable object is removed from a snapped drop zone.
Adding the VRTK_SnapDropZone_UnityEvents component to VRTK_SnapDropZone object allows access to UnityEvents that will react identically to the Class Events.
OnObjectEnteredSnapDropZone- Emits the ObjectEnteredSnapDropZone class event.OnObjectExitedSnapDropZone- Emits the ObjectExitedSnapDropZone class event.OnObjectSnappedToDropZone- Emits the ObjectSnappedToDropZone class event.OnObjectUnsnappedFromDropZone- Emits the ObjectUnsnappedFromDropZone class event.
GameObject snappedObject- The interactable object that is dealing with the snap drop zone.
public void InitaliseHighlightObject(bool removeOldObject = false)
- Parameters
bool removeOldObject- If this is set to true then it attempts to delete the old highlight object if it exists. Defaults tofalse- Returns
- none
The InitaliseHighlightObject method sets up the highlight object based on the given Highlight Object Prefab.
public void ForceSnap(GameObject objectToSnap)
- Parameters
GameObject objectToSnap- The GameObject to attempt to snap.- Returns
- none
the ForceSnap method attempts to automatically attach a valid game object to the snap drop zone.
public void ForceUnsnap()
- Parameters
- none
- Returns
- none
The ForceUnsnap method attempts to automatically remove the current snapped game object from the snap drop zone.
VRTK/Examples/041_Controller_ObjectSnappingToDropZones uses the VRTK_SnapDropZone prefab to set up pre-determined snap zones for a range of objects and demonstrates how only objects of certain types can be snapped into certain areas.
This adds a UI element into the world space that can be dropped into a Controller object and used to create and use Radial Menus from the touchpad.
If the RadialMenu is placed inside a controller, it will automatically find a VRTK_ControllerEvents in its parent to use at the input. However, a VRTK_ControllerEvents can be defined explicitly by setting the Events parameter of the Radial Menu Controller script also attached to the prefab.
The RadialMenu can also be placed inside a VRTK_InteractableObject for the RadialMenu to be anchored to a world object instead of the controller. The Events Manager parameter will automatically be set if the RadialMenu is a child of an InteractableObject, but it can also be set manually in the inspector. Additionally, for the RadialMenu to be anchored in the world, the RadialMenuController script in the prefab must be replaced with VRTK_IndependentRadialMenuController. See the script information for further details on making the RadialMenu independent of the controllers.
- Buttons: An array of Buttons that define the interactive buttons required to be displayed as part of the radial menu.
- Button Prefab: The base for each button in the menu, by default set to a dynamic circle arc that will fill up a portion of the menu.
- Button Thickness: Percentage of the menu the buttons should fill, 1.0 is a pie slice, 0.1 is a thin ring.
- Button Color: The background colour of the buttons, default is white.
- Offset Distance: The distance the buttons should move away from the centre. This creates space between the individual buttons.
- Offset Rotation: The additional rotation of the Radial Menu.
- Rotate Icons: Whether button icons should rotate according to their arc or be vertical compared to the controller.
- Icon Margin: The margin in pixels that the icon should keep within the button.
- Is Shown: Whether the buttons are shown
- Hide On Release: Whether the buttons should be visible when not in use.
- Execute On Unclick: Whether the button action should happen when the button is released, as opposed to happening immediately when the button is pressed.
- Base Haptic Strength: The base strength of the haptic pulses when the selected button is changed, or a button is pressed. Set to zero to disable.
- Menu Buttons: The actual GameObjects that make up the radial menu.
VRTK/Examples/030_Controls_RadialTouchpadMenu displays a radial menu for each controller. The left controller uses the Hide On Release variable, so it will only be visible if the left touchpad is being touched. It also uses the Execute On Unclick variable to delay execution until the touchpad button is unclicked. The example scene also contains a demonstration of anchoring the RadialMenu to an interactable cube instead of a controller.
extends RadialMenuController
This script inherited from RadialMenuController and therefore can be used instead of RadialMenuController to allow the RadialMenu to be anchored to any object, not just a controller. The RadialMenu will show when a controller is near the object and the buttons can be clicked with the Use Alias button. The menu also automatically rotates towards the user.
To convert the default RadialMenu prefab to be independent of the controllers:
- Make the
RadialMenua child of an object other than a controller. - Position and scale the menu by adjusting the transform of the
RadialMenuempty. - Replace
RadialMenuControllerwithVRTK_IndependentRadialMenuController. - Ensure the parent object has the
VRTK_InteractableObjectscript. - Verify that
Is UsableandHold Button to Useare both checked. - Attach
VRTK_InteractTouchandVRTK_InteractUsescripts to the controllers.
- Events Manager: If the RadialMenu is the child of an object with VRTK_InteractableObject attached, this will be automatically obtained. It can also be manually set.
- Add Menu Collider: Whether or not the script should dynamically add a SphereCollider to surround the menu.
- Collider Radius Multiplier: This times the size of the RadialMenu is the size of the collider.
- Hide After Execution: If true, after a button is clicked, the RadialMenu will hide.
- Offset Multiplier: How far away from the object the menu should be placed, relative to the size of the RadialMenu.
- Rotate Towards: The object the RadialMenu should face towards. If left empty, it will automatically try to find the Headset Camera.
This canvas adds the unity console log to a world game object. To use the prefab, it simply needs to be placed into the scene and it will be visible in world space. It's also possible to child it to other objects such as the controller so it can track where the user is.
It's also recommended to use the Simple Pointer and UI Pointer on a controller to interact with the Console Viewer Canvas as it has a scrollable text area, a button to clear the log and a checkbox to toggle whether the log messages are collapsed.
- Font Size: The size of the font the log text is displayed in.
- Info Message: The colour of the text for an info log message.
- Assert Message: The colour of the text for an assertion log message.
- Warning Message: The colour of the text for a warning log message.
- Error Message: The colour of the text for an error log message.
- Exception Message: The colour of the text for an exception log message.
public void SetCollapse(bool state)
- Parameters
bool state- The state of whether to collapse the output messages, true will collapse and false will not collapse.- Returns
- none
The SetCollapse method determines whether the console will collapse same message output into the same line. A state of true will collapse messages and false will print the same message for each line.
public void ClearLog()
- Parameters
- none
- Returns
- none
The ClearLog method clears the current log view of all messages
Purpose: top-level controller class to handle the display of up to four child PanelMenuItemController items which are displayed as a canvas UI panel.
This script should be attached to a VRTK_InteractableObject > first child GameObject [PanelMenuController]. The [PanelMenuController] must have a child GameObject [panel items container]. The [panel items container] must have a Canvas component. A [panel items container] can have up to four child GameObject, each of these contains the UI for a panel that can be displayed by [PanelMenuController]. They also have the [PanelMenuItemController] script attached to them. The [PanelMenuItemController] script intercepts the controller events sent from this [PanelMenuController] and passes them onto additional custom event subscriber scripts, which then carry out the required custom UI actions. To show / hide a UI panel, you must first pick up the VRTK_InteractableObject and then by pressing the touchpad top/bottom/left/right you can open/close the child UI panel that has been assigned via the Unity Editor panel. Button type UI actions are handled by a trigger press when the panel is open.
- Rotate Towards: The GameObject the panel should rotate towards, which is the Camera (eye) by default.
- Zoom Scale Multiplier: The scale multiplier, which relates to the scale of parent interactable object.
- Top Panel Menu Item Controller: The top PanelMenuItemController, which is triggered by pressing up on the controller touchpad.
- Bottom Panel Menu Item Controller: The bottom PanelMenuItemController, which is triggered by pressing down on the controller touchpad.
- Left Panel Menu Item Controller: The left PanelMenuItemController, which is triggered by pressing left on the controller touchpad.
- Right Panel Menu Item Controller: The right PanelMenuItemController, which is triggered by pressing right on the controller touchpad.
040_Controls_Panel_Menu contains three basic interactive object examples of the PanelMenu in use.
Purpose: panel item controller class that intercepts the controller events sent from a [PanelMenuController] and passes them onto additional custom event subscriber scripts, which then carry out the required custom UI actions.
This script should be attached to a VRTK_InteractableObject > [PanelMenuController] > [panel items container] > child GameObject (See the [PanelMenuController] class for more details on setup structure.). To show / hide a UI panel, you must first pick up the VRTK_InteractableObject and then by pressing the touchpad top/bottom/left/right you can open/close the child UI panel that has been assigned via the Unity Editor panel.
PanelMenuItemShowing- Emitted when the panel menu item is showing.PanelMenuItemHiding- Emitted when the panel menu item is hiding.PanelMenuItemSwipeLeft- Emitted when the panel menu item is open and the user swipes left on the controller touchpad.PanelMenuItemSwipeRight- Emitted when the panel menu item is open and the user swipes right on the controller touchpad.PanelMenuItemSwipeTop- Emitted when the panel menu item is open and the user swipes top on the controller touchpad.PanelMenuItemSwipeBottom- Emitted when the panel menu item is open and the user swipes bottom on the controller touchpad.PanelMenuItemTriggerPressed- Emitted when the panel menu item is open and the user presses the trigger of the controller holding the interactable object.
GameObject interactableObject- The GameObject for the interactable object the PanelMenu is attached to.
040_Controls_Panel_Menu contains three basic interactive object examples of the PanelMenu in use.
To allow for re-usability and object consistency, a collection of abstract classes are provided which can be used to extend into a concrete class providing consistent functionality across many different scripts without needing to duplicate code.
This abstract class provides the ability to emit events of destination markers within the game world. It can be useful for tagging locations for specific purposes such as teleporting.
It is utilised by the VRTK_WorldPointer for dealing with pointer events when the pointer cursor touches areas within the game world.
- Enable Teleport: If this is checked then the teleport flag is set to true in the Destination Set event so teleport scripts will know whether to action the new destination.
DestinationMarkerEnter- Emitted when a collision with another game object has occurred.DestinationMarkerExit- Emitted when the collision with the other game object finishes.DestinationMarkerSet- Emitted when the destination marker is active in the scene to determine the last destination position (useful for selecting and teleporting).
Adding the VRTK_DestinationMarker_UnityEvents component to VRTK_DestinationMarker object allows access to UnityEvents that will react identically to the Class Events.
OnDestinationMarkerEnter- Emits the DestinationMarkerEnter class event.OnDestinationMarkerExit- Emits the DestinationMarkerExit class event.OnDestinationMarkerSet- Emits the DestinationMarkerSet class event.
float distance- The distance between the origin and the collided destination.Transform target- The Transform of the collided destination object.RaycastHit raycastHit- The optional RaycastHit generated from when the ray collided.Vector3 destinationPosition- The world position of the destination marker.bool enableTeleport- Whether the destination set event should trigger teleport.uint controllerIndex- The optional index of the controller emitting the beam.
public virtual void SetInvalidTarget(string name, VRTK_TagOrScriptPolicyList list = null)
- Parameters
string name- The name of the tag or class that is the invalid target.VRTK_TagOrScriptPolicyList list- The Tag Or Script list policy to check the set operation on.- Returns
- none
The SetInvalidTarget method is used to set objects that contain the given tag or class matching the name as invalid destination targets. It can also accept a VRTK_TagOrScriptPolicyList for a more custom level of policy management.
public virtual void SetNavMeshCheckDistance(float distance)
- Parameters
float distance- The max distance the nav mesh can be from the sample point to be valid.- Returns
- none
The SetNavMeshCheckDistance method sets the max distance the destination marker position can be from the edge of a nav mesh to be considered a valid destination.
public virtual void SetHeadsetPositionCompensation(bool state)
- Parameters
bool state- The state of whether to take the position of the headset within the play area into account when setting the destination marker.- Returns
- none
The SetHeadsetPositionCompensation method determines whether the offset position of the headset from the centre of the play area should be taken into consideration when setting the destination marker. If true then it will take the offset position into consideration.
extends VRTK_DestinationMarker
This abstract class provides any game pointer the ability to know the state of the implemented pointer. It extends the VRTK_DestinationMarker to allow for destination events to be emitted when the pointer cursor collides with objects.
The World Pointer also provides a play area cursor to be displayed for all cursors that utilise this class. The play area cursor is a representation of the current calibrated play area space and is useful for visualising the potential new play area space in the game world prior to teleporting. It can also handle collisions with objects on the new play area space and prevent teleporting if there are any collisions with objects at the potential new destination.
The play area collider does not work well with terrains as they are uneven and cause collisions regularly so it is recommended that handling play area collisions is not enabled when using terrains.
- Controller: The controller 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.
- Pointer Origin Transform: 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.
- Pointer Material: The material to use on the rendered version of the pointer. If no material is selected then the default
WorldPointermaterial will be used. - Hold Button To Activate: If this is checked then the pointer beam will be activated on first press of the pointer alias button and will stay active until the pointer alias button is pressed again. The destination set event is emitted when the beam is deactivated on the second button press.
- Interact With Objects: If this is checked then the pointer will be an extension of the controller and able to interact with Interactable Objects.
- Activate Delay: The time in seconds to delay the pointer beam being able to be active again. Useful for preventing constant teleportation.
- Pointer Visibility: Determines when the pointer beam should be displayed.
- Layers To Ignore: The layers to ignore when raycasting.
public enum pointerVisibilityStates- States of Pointer Visibility.On_When_Active- Only shows the pointer beam when the Pointer button on the controller is pressed.Always_On- Ensures the pointer beam is always visible but pressing the Pointer button on the controller initiates the destination set event.Always_Off- Ensures the pointer beam is never visible but the destination point is still set and pressing the Pointer button on the controller still initiates the destination set event.
public virtual bool IsActive()
- Parameters
- none
- Returns
bool- Is true if the pointer is currently active.
The IsActive method is used to determine if the pointer currently active.
public virtual bool CanActivate()
- Parameters
- none
- Returns
bool- Is true if the pointer is able to be activated due to the activation delay timer being zero.
The CanActivate method checks to see if the pointer can be activated as long as the activation delay timer is zero.
public virtual void ToggleBeam(bool state)
- Parameters
bool state- The state of whether to enable or disable the beam.- Returns
- none
The ToggleBeam method allows the pointer beam to be toggled on or off via code at runtime. If true is passed as the state then the beam is activated, if false then the beam is deactivated.
This directory contains scripts that are used to provide different object highlighting.
The Base Highlighter is an abstract class that all other highlighters inherit and are required to implement the public methods.
As this is an abstract class, it cannot be applied directly to a game object and performs no logic.
- Active: Determines if this highlighter is the active highlighter for the object the component is attached to. Only 1 active highlighter can be applied to a game object.
public abstract void Initialise(Color? color = null, Dictionary<string, object> options = null);
- Parameters
Color? color- An optional colour may be passed through at point of initialisation in case the highlighter requires it.Dictionary<string, object> options- An optional dictionary of highlighter specific options that may be differ with highlighter implementations.- Returns
- none
The Initalise method is used to set up the state of the highlighter.
public abstract void ResetHighlighter();
- Parameters
- none
- Returns
- none
The ResetHighlighter method is used to reset the highlighter if anything on the object has changed. It should be called by any scripts changing object materials or colours.
public abstract void Highlight(Color? color = null, float duration = 0f);
- Parameters
Color? color- An optional colour to highlight the game object to. The highlight colour may already have been set in theInitialisemethod so may not be required here.float duration- An optional duration of how long before the highlight has occured. It can be used by highlighters to fade the colour if possible.- Returns
- none
The Highlight method is used to initiate the highlighting logic to apply to an object.
public abstract void Unhighlight(Color? color = null, float duration = 0f);
- Parameters
Color? color- An optional colour that could be used during the unhighlight phase. Usually will be left as null.float duration- An optional duration of how long before the unhighlight has occured.- Returns
- none
The Unhighlight method is used to initiate the logic that returns an object back to it's original appearance.
public virtual T GetOption<T>(Dictionary<string, object> options, string key)
- Type Params
T- The system type that is expected to be returned.- Parameters
Dictionary<string, object> options- The dictionary of options to check in.string key- The identifier key to look for.- Returns
T- The value in the options at the given key returned in the provided system type.
The GetOption method is used to return a value from the options array if the given key exists.
public virtual bool UsesClonedObject()
- Parameters
- none
- Returns
bool- Returns true if the highlighter creates a cloned object to apply the highlighter on, returns false if no additional object is created.
The UsesClonedObject method is used to return whether the current highlighter creates a cloned object to do the highlighting with.
extends VRTK_BaseHighlighter
The Material Colour Swap Highlighter is a basic implementation that simply swaps the texture colour for the given highlight colour.
Due to the way the object material is interacted with, changing the material colour will break Draw Call Batching in Unity whilst the object is highlighted.
The Draw Call Batching will resume on the original material when the item is no longer highlighted.
This is the default highlighter that is applied to any script that requires a highlighting component (e.g. VRTK_Interactable_Object or VRTK_ControllerActions).
- Emission Darken: The emission colour of the texture will be the highlight colour but this percent darker.
- Custom Material: A custom material to use on the highlighted object.
public override void Initialise(Color? color = null, Dictionary<string, object> options = null)
- Parameters
Color? color- Not used.Dictionary<string, object> options- A dictionary array containing the highlighter options:<'resetMainTexture', bool>- Determines if the default main texture should be cleared on highlight.trueto reset the main default texture,falseto not reset it.
- Returns
- none
The Initialise method sets up the highlighter for use.
public override void ResetHighlighter()
- Parameters
- none
- Returns
- none
The ResetHighlighter method stores the object's materials and shared materials prior to highlighting.
public override void Highlight(Color? color, float duration = 0f)
- Parameters
Color? color- The colour to highlight to.float duration- The time taken to fade to the highlighted colour.- Returns
- none
The Highlight method initiates the change of colour on the object and will fade to that colour (from a base white colour) for the given duration.
public override void Unhighlight(Color? color = null, float duration = 0f)
- Parameters
Color? color- Not used.float duration- Not used.- Returns
- none
The Unhighlight method returns the object back to it's original colour.
VRTK/Examples/005_Controller_BasicObjectGrabbing demonstrates the solid highlighting on the green cube, red cube and flying saucer when the controller touches it.
VRTK/Examples/035_Controller_OpacityAndHighlighting demonstrates the solid highlighting if the right controller collides with the green box or if any of the buttons are pressed.
extends VRTK_BaseHighlighter
The Outline Object Copy Highlighter works by making a copy of a mesh and adding an outline shader to it and toggling the appearance of the highlighted object.
- Thickness: The thickness of the outline effect
- Custom Outline Model: The GameObject to use as the model to outline. If one isn't provided then the first GameObject with a valid Renderer in the current GameObject hierarchy will be used.
- Custom Outline Model Path: A path to a GameObject to find at runtime, if the GameObject doesn't exist at edit time.
public override void Initialise(Color? color = null, Dictionary<string, object> options = null)
- Parameters
Color? color- Not used.Dictionary<string, object> options- A dictionary array containing the highlighter options:<'thickness', float>- Same asthicknessinspector parameter.<'customOutlineModel', GameObject>- Same ascustomOutlineModelinspector parameter.<'customOutlineModelPath', string>- Same ascustomOutlineModelPathinspector parameter.
- Returns
- none
The Initialise method sets up the highlighter for use.
public override void ResetHighlighter()
- Parameters
- none
- Returns
- none
The ResetHighlighter method creates the additional model to use as the outline highlighted object.
public override void Highlight(Color? color, float duration = 0f)
- Parameters
Color? color- The colour to outline with.float duration- Not used.- Returns
- none
The Highlight method initiates the outline object to be enabled and display the outline colour.
public override void Unhighlight(Color? color = null, float duration = 0f)
- Parameters
Color? color- Not used.float duration- Not used.- Returns
- none
The Unhighlight method hides the outline object and removes the outline colour.
VRTK/Examples/005_Controller_BasicObjectGrabbing demonstrates the outline highlighting on the green sphere when the controller touches it.
VRTK/Examples/035_Controller_OpacityAndHighlighting demonstrates the outline highlighting if the left controller collides with the green box.
This directory contains scripts that are used to provide different actions when a secondary controller grabs a grabbed obejct.
The Base Grab Action is an abstract class that all other secondary controller actions inherit and are required to implement the public abstract methods.
As this is an abstract class, it cannot be applied directly to a game object and performs no logic.
- Ungrab Distance: The distance the secondary controller must move away from the original grab position before the secondary controller auto ungrabs the object.
public virtual void Initialise(VRTK_InteractableObject currentGrabbdObject, VRTK_InteractGrab currentPrimaryGrabbingObject, VRTK_InteractGrab currentSecondaryGrabbingObject, Transform primaryGrabPoint, Transform secondaryGrabPoint)
- Parameters
VRTK_InteractableObject currentGrabbdObject- The Interactable Object script for the object currently being grabbed by the primary controller.VRTK_InteractGrab currentPrimaryGrabbingObject- The Interact Grab script for the object that is associated with the primary controller.VRTK_InteractGrab currentSecondaryGrabbingObject- The Interact Grab script for the object that is associated with the secondary controller.Transform primaryGrabPoint- The point on the object where the primary controller initially grabbed the object.Transform secondaryGrabPoint- The point on the object where the secondary controller initially grabbed the object.- Returns
- none
The Initalise method is used to set up the state of the secondary action when the object is initially grabbed by a secondary controller.
public virtual void ResetAction()
- Parameters
- none
- Returns
- none
The ResetAction method is used to reset the secondary action when the object is no longer grabbed by a secondary controller.
public virtual void ProcessUpdate()
- Parameters
- none
- Returns
- none
The ProcessUpdate method runs in every Update on the Interactable Object whilst it is being grabbed by a secondary controller.
public virtual void ProcessFixedUpdate()
- Parameters
- none
- Returns
- none
The ProcessFixedUpdate method runs in every FixedUpdate on the Interactable Object whilst it is being grabbed by a secondary controller.
public virtual void OnDropAction()
- Parameters
- none
- Returns
- none
The OnDropAction method is executed when the current grabbed object is dropped and can be used up to clean up any secondary grab actions.
extends VRTK_BaseGrabAction
The Axis Scale Grab Action provides a mechanism to scale objects when they are grabbed with a secondary controller.
- Lock X Axis: If checked the current X Axis of the object won't be scaled
- Lock Y Axis: If checked the current Y Axis of the object won't be scaled
- Lock Z Axis: If checked the current Z Axis of the object won't be scaled
public override void Initialise(VRTK_InteractableObject currentGrabbdObject, VRTK_InteractGrab currentPrimaryGrabbingObject, VRTK_InteractGrab currentSecondaryGrabbingObject, Transform primaryGrabPoint, Transform secondaryGrabPoint)
- Parameters
VRTK_InteractableObject currentGrabbdObject- The Interactable Object script for the object currently being grabbed by the primary controller.VRTK_InteractGrab currentPrimaryGrabbingObject- The Interact Grab script for the object that is associated with the primary controller.VRTK_InteractGrab currentSecondaryGrabbingObject- The Interact Grab script for the object that is associated with the secondary controller.Transform primaryGrabPoint- The point on the object where the primary controller initially grabbed the object.Transform secondaryGrabPoint- The point on the object where the secondary controller initially grabbed the object.- Returns
- none
The Initalise method is used to set up the state of the secondary action when the object is initially grabbed by a secondary controller.
public override void ProcessFixedUpdate()
- Parameters
- none
- Returns
- none
The ProcessFixedUpdate method runs in every FixedUpdate on the Interactable Object whilst it is being grabbed by a secondary controller and performs the scaling action.
VRTK/Examples/043_Controller_SecondaryControllerActions demonstrates the ability to grab an object with one controller and scale it by grabbing and pulling with the second controller.
extends VRTK_BaseGrabAction
The Control Direction Grab Action provides a mechanism to control the facing direction of the object when they are grabbed with a secondary controller.
For an object to correctly be rotated it must be created with the front of the object pointing down the z-axis (forward) and the upwards of the object pointing up the y-axis (up).
It's not possible to control the direction of an interactable object with a Fixed_Joint as the joint fixes the rotation of the object.
- Release Snap Speed: The speed in which the object will snap back to it's original rotation when the secondary controller stops grabbing it.
0for instant snap,infinityfor no snap back.
public override void Initialise(VRTK_InteractableObject currentGrabbdObject, VRTK_InteractGrab currentPrimaryGrabbingObject, VRTK_InteractGrab currentSecondaryGrabbingObject, Transform primaryGrabPoint, Transform secondaryGrabPoint)
- Parameters
VRTK_InteractableObject currentGrabbdObject- The Interactable Object script for the object currently being grabbed by the primary controller.VRTK_InteractGrab currentPrimaryGrabbingObject- The Interact Grab script for the object that is associated with the primary controller.VRTK_InteractGrab currentSecondaryGrabbingObject- The Interact Grab script for the object that is associated with the secondary controller.Transform primaryGrabPoint- The point on the object where the primary controller initially grabbed the object.Transform secondaryGrabPoint- The point on the object where the secondary controller initially grabbed the object.- Returns
- none
The Initalise method is used to set up the state of the secondary action when the object is initially grabbed by a secondary controller.
public override void ResetAction()
- Parameters
- none
- Returns
- none
The ResetAction method is used to reset the secondary action when the object is no longer grabbed by a secondary controller.
public override void OnDropAction()
- Parameters
- none
- Returns
- none
The OnDropAction method is executed when the current grabbed object is dropped and can be used up to clean up any secondary grab actions.
public override void ProcessFixedUpdate()
- Parameters
- none
- Returns
- none
The ProcessFixedUpdate method runs in every FixedUpdate on the Interactable Object whilst it is being grabbed by a secondary controller and influences the rotation of the object.
VRTK/Examples/043_Controller_SecondaryControllerActions demonstrates the ability to grab an object with one controller and control their direction with the second controller.
This directory contains all of the toolkit scripts that add VR functionality to Unity.
- Controller Events
- Controller Actions
- Device Finder
- Simple Pointer
- Bezier Pointer
- Play Area Cursor
- UI Pointer
- UI Canvas
- UI Draggable Item
- UI Drop Zone
- Basic Teleport
- Height Adjust Teleport
- Headset Collision
- Headset Fade
- Headset Collision Fade
- Headset Controller Aware
- Teleport Disable On Headset Collision
- Teleport Disable On Controller Obscured
- Player Presence
- Hip Tracking
- Touchpad Walking
- Move In Place
- Room Extender
- Interactable Object
- Interact Touch
- Interact Grab
- Interact Use
- Object Auto Grab
- Player Climb
- Dash Teleport
- Tag Or Script Policy List
- Simulating Headset Movement
- Adaptive Quality
The Controller Events script deals with events that the game controller is sending out.
The Controller Events script is attached to a Controller object within the [CameraRig] prefab 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.
- Pointer Toggle Button: The button to use for the action of turning a laser pointer on / off.
- Pointer Set Button: The button to use for the action of setting a destination marker from the cursor position of the pointer.
- Grab Toggle Button: The button to use for the action of grabbing game objects.
- Use Toggle Button: The button to use for the action of using game objects.
- Ui Click Button: The button to use for the action of clicking a UI element.
- Menu Toggle Button: The button to use for the action of bringing up an in-game menu.
- 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.
public enum ButtonAlias- Button typesTrigger_Hairline- The trigger is squeezed past the current hairline threshold.Trigger_Touch- The trigger is squeezed a small amount.Trigger_Press- The trigger is squeezed about half way in.Trigger_Click- The trigger is squeezed all the way until it clicks.Grip- The grip button is pressed.Touchpad_Touch- The touchpad is touched (without pressing down to click).Touchpad_Press- The touchpad is pressed (to the point of hearing a click).Application_Menu- The application menu button is pressed.Undefined- No button specifiedpublic bool triggerPressed- This will be true if the trigger is squeezed about half way in. Default:falsepublic bool triggerTouched- This will be true if the trigger is squeezed a small amount. Default:falsepublic bool triggerHairlinePressed- This will be true if the trigger is squeezed a small amount more from any previous squeeze on the trigger. Default:falsepublic bool triggerClicked- This will be true if the trigger is squeezed all the way until it clicks. Default:falsepublic bool triggerAxisChanged- This will be true if the trigger has been squeezed more or less. Default:falsepublic bool applicationMenuPressed- This will be true if the application menu is held down. Default:falsepublic bool touchpadPressed- This will be true if the touchpad is held down. Default:falsepublic bool touchpadTouched- This will be true if the touchpad is being touched. Default:falsepublic bool touchpadAxisChanged- This will be true if the touchpad touch position has changed. Default:falsepublic bool gripPressed- This will be true if the grip is held down. Default:falsepublic bool pointerPressed- This will be true if the button aliased to the pointer is held down. Default:falsepublic bool grabPressed- This will be true if the button aliased to the grab is held down. Default:falsepublic bool usePressed- This will be true if the button aliased to the use is held down. Default:falsepublic bool uiClickPressed- This will be true if the button aliased to the UI click is held down. Default:falsepublic bool menuPressed- This will be true if the button aliased to the application menu is held down. Default:false
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 until it clicks.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.ApplicationMenuPressed- Emitted when the application menu button is pressed.ApplicationMenuReleased- Emitted when the application menu button is released.GripPressed- Emitted when the grip button is pressed.GripReleased- Emitted when the grip button is released.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.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.
Adding the VRTK_ControllerEvents_UnityEvents component to VRTK_ControllerEvents object allows access to UnityEvents that will react identically to the Class Events.
OnTriggerPressed- Emits the TriggerPressed class event.OnTriggerReleased- Emits the TriggerReleased class event.OnTriggerTouchStart- Emits the TriggerTouchStart class event.OnTriggerTouchEnd- Emits the TriggerTouchEnd class event.OnTriggerHairlineStart- Emits the TriggerHairlineStart class event.OnTriggerHairlineEnd- Emits the TriggerHairlineEnd class event.OnTriggerClicked- Emits the TriggerClicked class event.OnTriggerUnclicked- Emits the TriggerUnclicked class event.OnTriggerAxisChanged- Emits the TriggerAxisChanged class event.OnApplicationMenuPressed- Emits the ApplicationMenuPressed class event.OnApplicationMenuReleased- Emits the ApplicationMenuReleased class event.OnGripPressed- Emits the GripPressed class event.OnGripReleased- Emits the GripReleased class event.OnTouchpadPressed- Emits the TouchpadPressed class event.OnTouchpadReleased- Emits the TouchpadReleased class event.OnTouchpadTouchStart- Emits the TouchpadTouchStart class event.OnTouchpadTouchEnd- Emits the TouchpadTouchEnd class event.OnTouchpadAxisChanged- Emits the TouchpadAxisChanged class event.OnAliasPointerOn- Emits the AliasPointerOn class event.OnAliasPointerOff- Emits the AliasPointerOff class event.OnAliasPointerSet- Emits the AliasPointerSet class event.OnAliasGrabOn- Emits the AliasGrabOn class event.OnAliasGrabOff- Emits the AliasGrabOff class event.OnAliasUseOn- Emits the AliasUseOn class event.OnAliasUseOff- Emits the AliasUseOff class event.OnAliasUIClickOn- Emits the AliasMenuOn class event.OnAliasUIClickOff- Emits the AliasMenuOff class event.OnAliasMenuOn- Emits the AliasUIClickOn class event.OnAliasMenuOff- Emits the AliasUIClickOff class event.OnControllerEnabled- Emits the ControllerEnabled class event.OnControllerDisabled- Emits the ControllerDisabled class event.
uint controllerIndex- The index of the controller that was used.float buttonPressure- The amount of pressure being applied to the button pressed.0fto1f.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.0fto360f.
public Vector3 GetVelocity()
- Parameters
- none
- Returns
Vector3- A 3 dimensional vector containing the current real world physical controller velocity.
The GetVelocity method is useful for getting the current velocity of the physical game controller. This can be useful to determine the speed at which the controller is being swung or the direction it is being moved in.
public Vector3 GetAngularVelocity()
- Parameters
- none
- Returns
Vector3- A 3 dimensional vector containing the current real world physical controller angular (rotational) velocity.
The GetAngularVelocity method is useful for getting the current rotational velocity of the physical game controller. This can be useful for determining which way the controller is being rotated and at what speed the rotation is occurring.
public 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.
public float GetTouchpadAxisAngle()
- Parameters
- none
- Returns
float- A float representing the angle of where the touchpad is being touched.0fto360f.
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.
public float GetTriggerAxis()
- Parameters
- none
- Returns
float- A float representing the amount of squeeze that is being applied to the trigger.0fto1f.
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.
public 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.
public 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.
public 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.
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.
The Controller Actions script provides helper methods to deal with common controller actions. It deals with actions that can be done to the controller.
The highlighting of the controller is defaulted to use the VRTK_MaterialColorSwapHighlighter if no other highlighter is applied to the Object.
- Model Element Paths: A collection of strings that determine the path to the controller model sub elements for identifying the model parts at runtime. If the paths are left empty they will default to the model element paths of the selected SDK Bridge.
- The available model sub elements are:
Body Model Path: The overall shape of the controller.Trigger Model Path: The model that represents the trigger button.Grip Left Model Path: The model that represents the left grip button.Grip Right Model Path: The model that represents the right grip button.Touchpad Model Path: The model that represents the touchpad.App Menu Model Path: The model that represents the application menu button.System Menu Model Path: The model that represents the system menu button.
- Element Highlighter Overrides: A collection of highlighter overrides for each controller model sub element. If no highlighter override is given then highlighter on the Controller game object is used.
- The available model sub elements are:
Body: The highlighter to use on the overall shape of the controller.Trigger: The highlighter to use on the trigger button.Grip Left: The highlighter to use on the left grip button.Grip Right: The highlighter to use on the right grip button.Touchpad: The highlighter to use on the touchpad.App Menu: The highlighter to use on the application menu button.System Menu: The highlighter to use on the system menu button.
ControllerModelVisible- Emitted when the controller model is toggled to be visible.ControllerModelInvisible- Emitted when the controller model is toggled to be invisible.
Adding the VRTK_ControllerActions_UnityEvents component to VRTK_ControllerActions object allows access to UnityEvents that will react identically to the Class Events.
OnControllerModelVisible- Emits the ControllerModelVisible class event.OnControllerModelInvisible- Emits the ControllerModelInvisible class event.
uint controllerIndex- The index of the controller that was used.
public bool IsControllerVisible()
- Parameters
- none
- Returns
bool- Is true if the controller model has the renderers that are attached to it are enabled.
The IsControllerVisible method returns true if the controller is currently visible by whether the renderers on the controller are enabled.
public void ToggleControllerModel(bool state, GameObject grabbedChildObject)
- Parameters
bool state- The visibility state to toggle the controller to,truewill make the controller visible -falsewill hide the controller model.GameObject grabbedChildObject- If an object is being held by the controller then this can be passed through to prevent hiding the grabbed game object as well.- Returns
- none
The ToggleControllerModel method is used to turn on or off the controller model by enabling or disabling the renderers on the object. It will also work for any custom controllers. It should also not disable any objects being held by the controller if they are a child of the controller object.
public void SetControllerOpacity(float alpha)
- Parameters
float alpha- The alpha level to apply to opacity of the controller object.0fto1f.- Returns
- none
The SetControllerOpacity method allows the opacity of the controller model to be changed to make the controller more transparent. A lower alpha value will make the object more transparent, such as 0.5f will make the controller partially transparent where as 0f will make the controller completely transparent.
public void HighlightControllerElement(GameObject element, Color? highlight, float fadeDuration = 0f)
- Parameters
GameObject element- The element of the controller to apply the highlight to.Color? highlight- The colour of the highlight.float fadeDuration- The duration of fade from white to the highlight colour. Optional parameter defaults to0f.- Returns
- none
The HighlightControllerElement method allows for an element of the controller to have its colour changed to simulate a highlighting effect of that element on the controller. It's useful for being able to draw a user's attention to a specific button on the controller.
public void UnhighlightControllerElement(GameObject element)
- Parameters
GameObject element- The element of the controller to remove the highlight from.- Returns
- none
The UnhighlightControllerElement method is the inverse of the HighlightControllerElement method and resets the controller element to its original colour.
public void ToggleHighlightControllerElement(bool state, GameObject element, Color? highlight = null, float duration = 0f)
- Parameters
bool state- The highlight colour state,truewill enable the highlight on the given element andfalsewill remove the highlight from the given element.GameObject element- The element of the controller to apply the highlight to.Color? highlight- The colour of the highlight.float duration- The duration of fade from white to the highlight colour.- Returns
- none
The ToggleHighlightControllerElement method is a shortcut method that makes it easier to highlight and unhighlight a controller element in a single method rather than using the HighlightControllerElement and UnhighlightControllerElement methods separately.
public void ToggleHighlightTrigger(bool state, Color? highlight = null, float duration = 0f)
- Parameters
bool state- The highlight colour state,truewill enable the highlight on the trigger andfalsewill remove the highlight from the trigger.Color? highlight- The colour to highlight the trigger with.float duration- The duration of fade from white to the highlight colour.- Returns
- none
The ToggleHighlightTrigger method is a shortcut method that makes it easier to toggle the highlight state of the controller trigger element.
public void ToggleHighlightGrip(bool state, Color? highlight = null, float duration = 0f)
- Parameters
bool state- The highlight colour state,truewill enable the highlight on the grip andfalsewill remove the highlight from the grip.Color? highlight- The colour to highlight the grip with.float duration- The duration of fade from white to the highlight colour.- Returns
- none
The ToggleHighlightGrip method is a shortcut method that makes it easier to toggle the highlight state of the controller grip element.
public void ToggleHighlightTouchpad(bool state, Color? highlight = null, float duration = 0f)
- Parameters
bool state- The highlight colour state,truewill enable the highlight on the touchpad andfalsewill remove the highlight from the touchpad.Color? highlight- The colour to highlight the touchpad with.float duration- The duration of fade from white to the highlight colour.- Returns
- none
The ToggleHighlightTouchpad method is a shortcut method that makes it easier to toggle the highlight state of the controller touchpad element.
public void ToggleHighlightApplicationMenu(bool state, Color? highlight = null, float duration = 0f)
- Parameters
bool state- The highlight colour state,truewill enable the highlight on the application menu andfalsewill remove the highlight from the application menu.Color? highlight- The colour to highlight the application menu with.float duration- The duration of fade from white to the highlight colour.- Returns
- none
The ToggleHighlightApplicationMenu method is a shortcut method that makes it easier to toggle the highlight state of the controller application menu element.
public void ToggleHighlighBody(bool state, Color? highlight = null, float duration = 0f)
- Parameters
bool state- The highlight colour state,truewill enable the highlight on the body andfalsewill remove the highlight from the body.Color? highlight- The colour to highlight the body with.float duration- The duration of fade from white to the highlight colour.- Returns
- none
The ToggleHighlighBody method is a shortcut method that makes it easier to toggle the highlight state of the controller body element.
public void ToggleHighlightController(bool state, Color? highlight = null, float duration = 0f)
- Parameters
bool state- The highlight colour state,truewill enable the highlight on the entire controllerfalsewill remove the highlight from the entire controller.Color? highlight- The colour to highlight the entire controller with.float duration- The duration of fade from white to the highlight colour.- Returns
- none
The ToggleHighlightController method is a shortcut method that makes it easier to toggle the highlight state of the entire controller.
public void TriggerHapticPulse(ushort strength)
- Parameters
ushort strength- The intensity of the rumble of the controller motor.0to3999.- Returns
- none
The TriggerHapticPulse/1 method calls a single haptic pulse call on the controller for a single tick.
public void TriggerHapticPulse(ushort strength, float duration, float pulseInterval)
- Parameters
ushort strength- The intensity of the rumble of the controller motor.0to3999.float duration- The length of time the rumble should continue for.float pulseInterval- The interval to wait between each haptic pulse.- Returns
- none
The TriggerHapticPulse/3 method calls a haptic pulse for a specified amount of time rather than just a single tick. Each pulse can be separated by providing a pulseInterval to pause between each haptic pulse.
public void InitaliseHighlighters()
- Parameters
- none
- Returns
- none
The InitaliseHighlighters method sets up the highlighters on the controller model.
VRTK/Examples/016_Controller_HapticRumble demonstrates the ability to hide a controller model and make the controller vibrate for a given length of time at a given intensity.
VRTK/Examples/035_Controller_OpacityAndHighlighting demonstrates the ability to change the opacity of a controller model and to highlight specific elements of a controller such as the buttons or even the entire controller model.
The Device Finder offers a collection of static methods that can be called to find common game devices such as the headset or controllers, or used to determine key information about the connected devices.
public enum Devices- Possible devices.Headset- The headset.Left_Controller- The left hand controller.Right_Controller- The right hand controller.public enum ControllerHand- Controller hand reference.None- No hand is assigned.Left- The left hand is assigned.Right- The right hand is assigned.
public static bool TrackedIndexIsController(uint index)
- Parameters
uint index- The index of the tracked object to find.- Returns
bool- Returns true if the given index is a tracked object of type controller.
The TrackedIndexIsController method is used to determine if a given tracked object index belongs to a tracked controller.
public static uint GetControllerIndex(GameObject controller)
- Parameters
GameObject controller- The controller object to check the index on.- Returns
uint- The index of the given controller.
The GetControllerIndex method is used to find the index of a given controller object.
public static GameObject TrackedObjectByIndex(uint index)
- Parameters
uint index- The index of the tracked object to find.- Returns
GameObject- The tracked object that matches the given index.
The TrackedObjectByIndex method is used to find the GameObject of a tracked object by its generated index.
public static Transform TrackedObjectOrigin(GameObject obj)
- Parameters
GameObject obj- The GameObject to get the origin for.- Returns
Transform- The transform of the tracked object's origin or if an origin is not set then the transform parent.
The TrackedObjectOrigin method is used to find the tracked object's origin.
public static GameObject TrackedObjectOfGameObject(GameObject obj, out uint index)
- Parameters
GameObject obj- The game object to check for the presence of a tracked object on.out uint index- The variable to store the tracked object's index if one is found. It returns 0 if no index is found.- Returns
GameObject- The GameObject of the tracked object.
The TrackedObjectOfGameObject method is used to find the tracked object associated with the given game object and it can also return the index of the tracked object.
public static Transform DeviceTransform(Devices device)
- Parameters
Devices device- The Devices enum to get the transform for.- Returns
Transform- The transform for the given Devices enum.
The DeviceTransform method returns the transform for a given Devices enum.
public static ControllerHand GetControllerHandType(string hand)
- Parameters
string hand- The string representation of the hand to retrieve the type of.leftorright.- Returns
ControllerHand- A ControllerHand representing either the Left or Right hand.
The GetControllerHandType method is used for getting the enum representation of ControllerHand from a given string.
public static ControllerHand GetControllerHand(GameObject controller)
- Parameters
GameObject controller- The controller game object to check the hand of.- Returns
ControllerHand- A ControllerHand representing either the Left or Right hand.
The GetControllerHand method is used for getting the enum representation of ControllerHand for the given controller game object.
public static GameObject GetControllerLeftHand()
- Parameters
- none
- Returns
GameObject- The left hand controller.
The GetControllerLeftHand method retrieves the game object for the left hand controller.
public static GameObject GetControllerRightHand()
- Parameters
- none
- Returns
GameObject- The right hand controller.
The GetControllerRightHand method retrieves the game object for the right hand controller.
public static bool IsControllerOfHand(GameObject checkController, ControllerHand hand)
- Parameters
GameObject checkController- The actual controller object that is being checked.ControllerHand hand- The representation of a hand to check if the given controller matches.- Returns
bool- Is true if the given controller matches the given hand.
The IsControllerOfHand method is used to check if a given controller game object is of the hand type provided.
public static Transform HeadsetTransform()
- Parameters
- none
- Returns
Transform- The transform of the VR Headset component.
The HeadsetTransform method is used to retrieve the transform for the VR Headset in the scene. It can be useful to determine the position of the user's head in the game world.
public static Transform HeadsetCamera()
- Parameters
- none
- Returns
Transform- The transform of the VR Camera component.
The HeadsetCamera method is used to retrieve the transform for the VR Camera in the scene.
public static Transform PlayAreaTransform()
- Parameters
- none
- Returns
Transform- The transform of the VR Play Area component.
The PlayAreaTransform method is used to retrieve the transform for the play area in the scene.
extends VRTK_WorldPointer
The Simple Pointer emits a coloured beam from the end of the controller to simulate a laser beam. It can be useful for pointing to objects within a scene and it can also determine the object it is pointing at and the distance the object is from the controller the beam is being emitted from.
The laser beam is activated by default by pressing the Touchpad on the controller. The event it is listening for is the AliasPointer events so the pointer toggle button can be set by changing the Pointer Toggle button on the VRTK_ControllerEvents script parameters.
The Simple Pointer script can be attached to a Controller object within the [CameraRig] prefab and the Controller object also requires the VRTK_ControllerEvents script to be attached as it uses this for listening to the controller button events for enabling and disabling the beam. It is also possible to attach the Simple Pointer script to another object (like the [CameraRig]/Camera (head)) to enable other objects to project the beam. The controller parameter must be entered with the desired controller to toggle the beam if this is the case.
- Pointer Thickness: The thickness and length of the beam can also be set on the script as well as the ability to toggle the sphere beam tip that is displayed at the end of the beam (to represent a cursor).
- Pointer Length: The distance the beam will project before stopping.
- Show Pointer Tip: Toggle whether the cursor is shown on the end of the pointer beam.
- Custom Pointer Cursor: A custom Game Object can be applied here to use instead of the default sphere for the pointer cursor.
- Pointer Cursor Match Target Normal: Rotate the pointer cursor to match the normal of the target surface (or the pointer direction if no target was hit).
- Pointer Cursor Rescaled Along Distance: Rescale the pointer cursor proportionally to the distance from this game object (useful when used as a gaze pointer).
VRTK/Examples/003_Controller_SimplePointer shows the simple pointer in action and code examples of how the events are utilised and listened to can be viewed in the script VRTK/Examples/Resources/Scripts/VRTK_ControllerPointerEvents_ListenerExample.cs
extends VRTK_WorldPointer
The Bezier Pointer emits a curved line (made out of game objects) from the end of the controller to a point on a ground surface (at any height). It is more useful than the Simple Laser Pointer for traversing objects of various heights as the end point can be curved on top of objects that are not visible to the user.
The laser beam is activated by default by pressing the Touchpad on the controller. The event it is listening for is the AliasPointer events so the pointer toggle button can be set by changing the Pointer Toggle button on the VRTK_ControllerEvents script parameters.
The Bezier Pointer script can be attached to a Controller object within the [CameraRig] prefab and the Controller object also requires the VRTK_ControllerEvents script to be attached as it uses this for listening to the controller button events for enabling and disabling the beam. It is also possible to attach the Bezier Pointer script to another object (like the [CameraRig]/Camera (head)) to enable other objects to project the beam. The controller parameter must be entered with the desired controller to toggle the beam if this is the case.
The bezier curve generation code is in another script located at
VRTK/Scripts/Helper/CurveGenerator.csand was heavily inspired by the tutorial and code from Catlike Coding.
- Pointer Length: The length of the projected forward pointer beam, this is basically the distance able to point from the controller position.
- Pointer Density: The number of items to render in the beam bezier curve. A high number here will most likely have a negative impact of game performance due to large number of rendered objects.
- Beam Curve Offset: The amount of height offset to apply to the projected beam to generate a smoother curve even when the beam is pointing straight.
- Beam Height Limit Angle: The maximum angle in degrees of the controller before the beam curve height is restricted. A lower angle setting will prevent the beam being projected high into the sky and curving back down.
- Rescale Pointer Tracer: Rescale each pointer tracer element according to the length of the Bezier curve.
- Show Pointer Cursor: A cursor is displayed on the ground at the location the beam ends at, it is useful to see what height the beam end location is, however it can be turned off by toggling this.
- Pointer Cursor Radius: The size of the ground pointer cursor. This number also affects the size of the objects in the bezier curve beam. The larger the radius, the larger the objects will be.
- Pointer Cursor Match Target Rotation: The pointer cursor will be rotated to match the angle of the target surface if this is true, if it is false then the pointer cursor will always be horizontal.
- Custom Pointer Tracer: A custom Game Object can be applied here to use instead of the default sphere for the beam tracer. The custom Game Object will match the rotation of the controller.
- Custom Pointer Cursor: A custom Game Object can be applied here to use instead of the default flat cylinder for the pointer cursor.
- Valid Teleport Location Object: A custom Game Object can be applied here to appear only if the teleport is allowed (its material will not be changed ).
VRTK/Examples/009_Controller_BezierPointer is used in conjunction with the Height Adjust Teleporter shows how it is possible to traverse different height objects using the curved pointer without needing to see the top of the object.
`VRTK/Examples/036_Controller_CustomCompoundPointer' shows how to display an object (a teleport beam) only if the teleport location is valid, and can create an animated trail along the tracer curve.
The Play Area Cursor is used in conjunction with a World Pointer script and displays a representation of the play area where the pointer cursor hits.
- Play Area Cursor Dimensions: Determines the size of the play area cursor and collider. If the values are left as zero then the Play Area Cursor will be sized to the calibrated Play Area space.
- Handle Play Area Cursor Collisions: If this is ticked then if the play area cursor is colliding with any other object then the pointer colour will change to the
Pointer Miss Colorand theWorldPointerDestinationSetevent will not be triggered, which will prevent teleporting into areas where the play area will collide. - Headset Out Of Bounds Is Collision: If this is ticked then if the user's headset is outside of the play area cursor bounds then it is considered a collision even if the play area isn't colliding with anything.
- Ignore Target With Tag Or Class: A string that specifies an object Tag or the name of a Script attached to an object and notifies the play area cursor to ignore collisions with the object.
- Target Tag Or Script List Policy: A specified VRTK_TagOrScriptPolicyList to use to determine whether the play area cursor collisions will be acted upon. If a list is provided then the 'Ignore Target With Tag Or Class' parameter will be ignored.
public virtual bool HasCollided()
- Parameters
- none
- Returns
bool- A bool to determine the state of collision.trueif the play area is colliding with a valid object andfalseif not.
The HasCollided method returns the state of whether the play area cursor has currently collided with another valid object.
public virtual void SetHeadsetPositionCompensation(bool state)
- Parameters
bool state- The state of whether to take the position of the headset within the play area into account when setting the destination marker.- Returns
- none
The SetHeadsetPositionCompensation method determines whether the offset position of the headset from the centre of the play area should be taken into consideration when setting the destination marker. If true then it will take the offset position into consideration.
public virtual void SetPlayAreaCursorCollision(bool state)
- Parameters
bool state- The state of whether to check for play area collisions.- Returns
- none
The SetPlayAreaCursorCollision method determines whether play area collisions should be taken into consideration with the play area cursor.
public virtual void SetMaterialColor(Color color)
- Parameters
Color color- The colour to update the play area cursor material to.- Returns
- none
The SetMaterialColor method sets the current material colour on the play area cursor.
public virtual void SetPlayAreaCursorTransform(Vector3 location)
- Parameters
Vector3 location- The location where to draw the play area cursor.- Returns
- none
The SetPlayAreaCursorTransform method is used to update the position of the play area cursor in world space to the given location.
public virtual void ToggleState(bool state)
- Parameters
bool state- The state of whether to show or hide the play area cursor.- Returns
- none
The ToggleState method enables or disables the visibility of the play area cursor.
VRTK/Examples/012_Controller_PointerWithAreaCollision shows how a Bezier Pointer with the Play Area Cursor and Collision Detection enabled can be used to traverse a game area but not allow teleporting into areas where the walls or other objects would fall into the play area space enabling the user to enter walls.
The UI Pointer provides a mechanism for interacting with Unity UI elements on a world canvas. The UI Pointer can be attached to any game object the same way in which a World Pointer can be and the UI Pointer also requires a controller to initiate the pointer activation and pointer click states.
The simplest way to use the UI Pointer is to attach the script to a game controller within the [CameraRig] along with a Simple Pointer as this provides visual feedback as to where the UI ray is pointing.
The UI pointer is activated via the Pointer alias on the Controller Events and the UI pointer click state is triggered via the UI Click alias on the Controller Events.
- Controller: The controller 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.
- Pointer Origin Transform: 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.
- Activation Mode: Determines when the UI pointer should be active.
- Click Method: Determines when the UI Click event action should happen.
- Attempt Click On Deactivate: Determines whether the UI click action should be triggered when the pointer is deactivated. If the pointer is hovering over a clickable element then it will invoke the click action on that element. Note: Only works with
Click Method = Click_On_Button_Up
public enum ActivationMethods- Methods of activation.Hold_Button- Only activates the UI Pointer when the Pointer button on the controller is pressed and held down.Toggle_Button- Activates the UI Pointer on the first click of the Pointer button on the controller and it stays active until the Pointer button is clicked again.Always_On- The UI Pointer is always active regardless of whether the Pointer button on the controller is pressed or not.public enum ClickMethods- Methods of when to consider a UI Click actionClick_On_Button_Up- Consider a UI Click action has happened when the UI Click alias button is released.Click_On_Button_Down- Consider a UI Click action has happened when the UI Click alias button is pressed.public GameObject autoActivatingCanvas- The GameObject of the front trigger activator of the canvas currently being activated by this pointer. Default:nullpublic bool collisionClick- Determines if the UI Pointer has collided with a valid canvas that has collision click turned on. Default:false
UIPointerElementEnter- Emitted when the UI Pointer is colliding with a valid UI element.UIPointerElementExit- Emitted when the UI Pointer is no longer colliding with any valid UI elements.UIPointerElementClick- Emitted when the UI Pointer has clicked the currently collided UI element.UIPointerElementDragStart- Emitted when the UI Pointer begins dragging a valid UI element.UIPointerElementDragEnd- Emitted when the UI Pointer stops dragging a valid UI element.
Adding the VRTK_UIPointer_UnityEvents component to VRTK_UIPointer object allows access to UnityEvents that will react identically to the Class Events.
OnUIPointerElementEnter- Emits the UIPointerElementEnter class event.OnUIPointerElementExit- Emits the UIPointerElementExit class event.OnUIPointerElementClick- Emits the UIPointerElementClick class event.OnUIPointerElementDragStart- Emits the UIPointerElementDragStart class event.OnUIPointerElementDragEnd- Emits the UIPointerElementDragEnd class event.
uint controllerIndex- The index of the controller that was used.bool isActive- The state of whether the UI Pointer is currently active or not.GameObject currentTarget- The current UI element that the pointer is colliding with.GameObject previousTarget- The previous UI element that the pointer was colliding with.
public VRTK_EventSystemVRInput SetEventSystem(EventSystem eventSystem)
- Parameters
EventSystem eventSystem- The global Unity event system to be used by the UI pointers.- Returns
VRTK_EventSystemVRInput- A custom event system input class that is used to detect input from VR pointers.
The SetEventSystem method is used to set up the global Unity event system for the UI pointer. It also handles disabling the existing Standalone Input Module that exists on the EventSystem and adds a custom VRTK Event System VR Input component that is required for interacting with the UI with VR inputs.
public void RemoveEventSystem()
- Parameters
- none
- Returns
- none
The RemoveEventSystem resets the Unity EventSystem back to the original state before the VRTK_EventSystemVRInput was swapped for it.
public bool PointerActive()
- Parameters
- none
- Returns
bool- Returns true if the ui pointer should be currently active.
The PointerActive method determines if the ui pointer beam should be active based on whether the pointer alias is being held and whether the Hold Button To Use parameter is checked.
public bool ValidClick(bool checkLastClick, bool lastClickState = false)
- Parameters
bool checkLastClick- If this is true then the last frame's state of the UI Click button is also checked to see if a valid click has happened.bool lastClickState- This determines what the last frame's state of the UI Click button should be in for it to be a valid click.- Returns
bool- Returns true if the UI Click button is in a valid state to action a click, returns false if it is not in a valid state.
The ValidClick method determines if the UI Click button is in a valid state to register a click action.
public Vector3 GetOriginPosition()
- Parameters
- none
- Returns
Vector3- A Vector3 of the pointer transform position
The GetOriginPosition method returns the relevant transform position for the pointer based on whether the pointerOriginTransform variable is valid.
public Vector3 GetOriginForward()
- Parameters
- none
- Returns
Vector3- A Vector3 of the pointer transform forward
The GetOriginPosition method returns the relevant transform forward for the pointer based on whether the pointerOriginTransform variable is valid.
VRTK/Examples/034_Controls_InteractingWithUnityUI uses the VRTK_UIPointer script on the right Controller to allow for the interaction with Unity UI elements using a Simple Pointer beam. The left Controller controls a Simple Pointer on the headset to demonstrate gaze interaction with Unity UI elements.
The UI Canvas is used to denote which World Canvases are interactable by a UI Pointer.
When the script is enabled it will disable the Graphic Raycaster on the canvas and create a custom UI Graphics Raycaster and the Blocking Objects and Blocking Mask settings are copied over from the Graphic Raycaster.
- Click On Pointer Collision: Determines if a UI Click action should happen when a UI Pointer game object collides with this canvas.
- Auto Activate Within Distance: Determines if a UI Pointer will be auto activated if a UI Pointer game object comes within the given distance of this canvas. If a value of
0is given then no auto activation will occur.
VRTK/Examples/034_Controls_InteractingWithUnityUI uses the VRTK_UICanvas script on two of the canvases to show how the UI Pointer can interact with them.
extends MonoBehaviour, IBeginDragHandler, IDragHandler, IEndDragHandler
The UI Draggable item will make any UI element draggable on the canvas.
If a UI Draggable item is set to Restrict To Drop Zone = true then the UI Draggable item must be a child of an element that has the VRTK_UIDropZone script applied to it to ensure it starts in a valid drop zone.
- Restrict To Drop Zone: If checked then the UI element can only be dropped in valid a VRTK_UIDropZone object and must start as a child of a VRTK_UIDropZone object. If unchecked then the UI element can be dropped anywhere on the canvas.
- Restrict To Original Canvas: If checked then the UI element can only be dropped on the original parent canvas. If unchecked the UI element can be dropped on any valid VRTK_UICanvas.
- Forward Offset: The offset to bring the UI element forward when it is being dragged.
public GameObject validDropZone- The current valid drop zone the dragged element is hovering over.
VRTK/Examples/034_Controls_InteractingWithUnityUI demonstrates a collection of UI elements that are draggable
extends MonoBehaviour, IPointerEnterHandler, IPointerExitHandler
A UI Drop Zone is applied to any UI element that is to be considered a valid parent for any UI Draggable element to be dropped into it.
It's usually appropriate to use a Panel UI element as a drop zone with a layout group applied so new children dropped into the drop zone automatically align.
VRTK/Examples/034_Controls_InteractingWithUnityUI demonstrates a collection of UI Drop Zones.
The basic teleporter updates the [CameraRig] x/z position in the game world to the position of a World Pointer's tip location which is set via the WorldPointerDestinationSet event. The y position is never altered so the basic teleporter cannot be used to move up and down game objects as it only allows for travel across a flat plane.
The Basic Teleport script is attached to the [CameraRig] prefab.
- Blink Transition Speed: The fade blink speed can be changed on the basic teleport script to provide a customised teleport experience. Setting the speed to 0 will mean no fade blink effect is present.
- Distance Blink Delay: A range between 0 and 32 that determines how long the blink transition will stay blacked out depending on the distance being teleported. A value of 0 will not delay the teleport blink effect over any distance, a value of 32 will delay the teleport blink fade in even when the distance teleported is very close to the original position. This can be used to simulate time taking longer to pass the further a user teleports. A value of 16 provides a decent basis to simulate this to the user.
- Headset Position Compensation: If this is checked then the teleported location will be the position of the headset within the play area. If it is unchecked then the teleported location will always be the centre of the play area even if the headset position is not in the centre of the play area.
- Ignore Target With Tag Or Class: A string that specifies an object Tag or the name of a Script attached to an object and notifies the teleporter that the destination is to be ignored so the user cannot teleport to that location. It also ensure the pointer colour is set to the miss colour.
- Target Tag Or Script List Policy: A specified VRTK_TagOrScriptPolicyList to use to determine whether destination targets will be acted upon by the Teleporter. If a list is provided then the 'Ignore Target With Tag Or Class' parameter will be ignored.
- Nav Mesh Limit Distance: The max distance the nav mesh edge can be from the teleport destination to be considered valid. If a value of
0is given then the nav mesh restriction will be ignored.
Teleporting- Emitted when the teleport process has begun.Teleported- Emitted when the teleport process has successfully completed.
Adding the VRTK_BasicTeleport_UnityEvents component to VRTK_BasicTeleport object allows access to UnityEvents that will react identically to the Class Events.
OnTeleporting- Emits the Teleporting class event.OnTeleported- Emits the Teleported class event.
float distance- The distance between the origin and the collided destination.Transform target- The Transform of the collided destination object.RaycastHit raycastHit- The optional RaycastHit generated from when the ray collided.Vector3 destinationPosition- The world position of the destination marker.bool enableTeleport- Whether the destination set event should trigger teleport.uint controllerIndex- The optional index of the controller emitting the beam.
public void InitDestinationSetListener(GameObject markerMaker, bool register)
- Parameters
GameObject markerMaker- The game object that is used to generate destination marker events, such as a controller.bool register- Determines whether to register or unregister the listeners.- Returns
- none
The InitDestinationSetListener method is used to register the teleport script to listen to events from the given game object that is used to generate destination markers. Any destination set event emitted by a registered game object will initiate the teleport to the given destination location.
public void ToggleTeleportEnabled(bool state)
- Parameters
bool state- Toggles whether the teleporter is enabled or disabled.- Returns
- none
The ToggleTeleportEnabled method is used to determine whether the teleporter will initiate a teleport on a destination set event, if the state is true then the teleporter will work as normal, if the state is false then the teleporter will not be operational.
VRTK/Examples/004_CameraRig_BasicTeleport uses the VRTK_SimplePointer script on the Controllers to initiate a laser pointer by pressing the Touchpad on the controller and when the laser pointer is deactivated (release the Touchpad) then the user is teleported to the location of the laser pointer tip as this is where the pointer destination marker position is set to.
extends VRTK_BasicTeleport
The height adjust teleporter extends the basic teleporter and allows for the y position of the [CameraRig] to be altered based on whether the teleport location is on top of another object.
Like the basic teleporter the Height Adjust Teleport script is attached to the [CameraRig] prefab.
- Play Space Falling: Checks if the user steps off an object into a part of their play area that is not on the object then they are automatically teleported down to the nearest floor. The
Play Space Fallingoption also works in the opposite way that if the user's headset is above an object then the user is teleported automatically on top of that object, which is useful for simulating climbing stairs without needing to use the pointer beam location. If this option is turned off then the user can hover in mid-air at the same y position of the object they are standing on. - Play Space Fall Restriction: An additional check to see if the play space fall should take place. If the selected restrictor is still over the current floor then the play space fall will not occur. Works well for being able to lean over ledges and look down. Only works for falling down not teleporting up.
- Use Gravity: Allows for gravity based falling when the distance is greater than
Gravity Fall Height. - Gravity Fall Height: Fall distance needed before gravity based falling can be triggered.
- Blink Y Threshold: The
ydistance between the floor and the headset that must change before the fade transition is initiated. If the new user location is at a higher distance than the threshold then the headset blink transition will activate on teleport. If the new user location is within the threshold then no blink transition will happen, which is useful for walking up slopes, meshes and terrains where constant blinking would be annoying. - Floor Height Tolerance: The amount the
yposition needs to change by between the current flooryposition and the previous flooryposition before a change in floor height is considered to have occurred. A higher value here will mean that aDrop To Floorteleport event will be less likely to happen if theyof the floor beneath the user hasn't changed as much as the given threshold.
public enum FallingRestrictors- Options for testing if a play space fall is validNo_Restriction- Always play space fall when the headset is no longer over the current standing object.Left_Controller- Don't play space fall if the Left Controller is still over the current standing object even if the headset isn't.Right_Controller- Don't play space fall if the Right Controller is still over the current standing object even if the headset isn't.Either_Controller- Don't play space fall if Either Controller is still over the current standing object even if the headset isn't.Both_Controllers- Don't play space fall only if Both Controllers are still over the current standing object even if the headset isn't.
VRTK/Examples/007_CameraRig_HeightAdjustTeleport has a collection of varying height objects that the user can either walk up and down or use the laser pointer to climb on top of them.
VRTK/Examples/010_CameraRig_TerrainTeleporting shows how the teleportation of a user can also traverse terrain colliders.
VRTK/Examples/020_CameraRig_MeshTeleporting shows how the teleportation of a user can also traverse mesh colliders.
The purpose of the Headset Collision is to detect when the user's VR headset collides with another game object.
The Headset Collision script is added to the [CameraRig] prefab. It will automatically create a script on the headset to deal with the collision events.
- Ignore Target With Tag Or Class: A string that specifies an object Tag or the name of a Script attached to an object and will be ignored on headset collision.
- Target Tag Or Script List Policy: A specified VRTK_TagOrScriptPolicyList to use to determine whether any objects will be acted upon by the Headset Collision. If a list is provided then the 'Ignore Target With Tag Or Class' parameter will be ignored.
public bool headsetColliding- Determines if the headset is currently colliding with another object. Default:falsepublic Collider collidingWith- Stores the collider of what the headset is colliding with. Default:null
HeadsetCollisionDetect- Emitted when the user's headset collides with another game object.HeadsetCollisionEnded- Emitted when the user's headset stops colliding with a game object.
Adding the VRTK_HeadsetCollision_UnityEvents component to VRTK_HeadsetCollision object allows access to UnityEvents that will react identically to the Class Events.
OnHeadsetCollisionDetect- Emits the HeadsetCollisionDetect class event.OnHeadsetCollisionEnded- Emits the HeadsetCollisionEnded class event.
Collider collider- The Collider of the game object the headset has collided with.Transform currentTransform- The current Transform of the object that the Headset Collision Fade script is attached to (Camera).
public virtual bool IsColliding()
- Parameters
- none
- Returns
bool- Returns true if the headset is currently colliding with a valid game object.
The IsColliding method is used to determine if the headset is currently colliding with a valid game object and returns true if it is and false if it is not colliding with anything or an invalid game object.
VRTK/Examples/011_Camera_HeadSetCollisionFading has collidable walls around the play area and if the user puts their head into any of the walls then the headset will fade to black.
The purpose of the Headset Fade is to change the colour of the headset view to a specified colour over a given duration and to also unfade it back to being transparent. The Fade and Unfade methods can only be called via another script and this Headset Fade script does not do anything on initialisation to fade or unfade the headset view.
The Headset Fade script is added to the [CameraRig] prefab.
HeadsetFadeStart- Emitted when the user's headset begins to fade to a given colour.HeadsetFadeComplete- Emitted when the user's headset has completed the fade and is now fully at the given colour.HeadsetUnfadeStart- Emitted when the user's headset begins to unfade back to a transparent colour.HeadsetUnfadeComplete- Emitted when the user's headset has completed unfading and is now fully transparent again.
Adding the VRTK_HeadsetFade_UnityEvents component to VRTK_HeadsetFade object allows access to UnityEvents that will react identically to the Class Events.
OnHeadsetFadeStart- Emits the HeadsetFadeStart class event.OnHeadsetFadeComplete- Emits the HeadsetFadeComplete class event.OnHeadsetUnfadeStart- Emits the HeadsetUnfadeStart class event.OnHeadsetUnfadeComplete- Emits the HeadsetUnfadeComplete class event.
float timeTillComplete- A float that is the duration for the fade/unfade process has remaining.Transform currentTransform- The current Transform of the object that the Headset Fade script is attached to (Camera).
public virtual bool IsFaded()
- Parameters
- none
- Returns
bool- Returns true if the headset is currently fading or faded.
The IsFaded method returns true if the headset is currently fading or has completely faded and returns false if it is completely unfaded.
public virtual bool IsTransitioning()
- Parameters
- none
- Returns
bool- Returns true if the headset is currently in the process of fading or unfading.
The IsTransitioning method returns true if the headset is currently fading or unfading and returns false if it is completely faded or unfaded.
public virtual void Fade(Color color, float duration)
- Parameters
Color color- The colour to fade the headset view to.float duration- The time in seconds to take to complete the fade transition.- Returns
- none
The Fade method initiates a change in the colour of the headset view to the given colour over a given duration.
public virtual void Unfade(float duration)
- Parameters
float duration- The time in seconds to take to complete the unfade transition.- Returns
- none
The Unfade method initiates the headset to change colour back to a transparent colour over a given duration.
VRTK/Examples/011_Camera_HeadSetCollisionFading has collidable walls around the play area and if the user puts their head into any of the walls then the headset will fade to black.
The purpose of the Headset Collision Fade is to detect when the user's VR headset collides with another game object and fades the screen to a solid colour. This is to deal with a user putting their head into a game object and seeing the inside of the object clipping, which is an undesired effect. The reasoning behind this is if the user puts their head where it shouldn't be, then fading to a colour (e.g. black) will make the user realise they've done something wrong and they'll probably naturally step backwards.
The Headset Collision Fade uses a composition of the Headset Collision and Headset Fade scripts to derive the desired behaviour.
The Headset Collision Fade script is added to the [CameraRig] prefab.
- Blink Transition Speed: The fade blink speed on collision.
- Fade Color: The colour to fade the headset to on collision.
VRTK/Examples/011_Camera_HeadSetCollisionFading has collidable walls around the play area and if the user puts their head into any of the walls then the headset will fade to black.
The purpose of Headset Controller Aware is to allow the headset to know if something is blocking the path between the headset and controllers and to know if the headset is looking at a controller.
- Track Left Controller: If this is checked then the left controller will be checked if items obscure it's path from the headset.
- Track Right Controller: If this is checked then the right controller will be checked if items obscure it's path from the headset.
- Controller Glance Radius: The radius of the accepted distance from the controller origin point to determine if the controller is being looked at.
- Custom Right Controller Origin: A custom transform to provide the world space position of the right controller.
- Custom Left Controller Origin: A custom transform to provide the world space position of the left controller.
ControllerObscured- Emitted when the controller is obscured by another object.ControllerUnobscured- Emitted when the controller is no longer obscured by an object.ControllerGlanceEnter- Emitted when the controller is seen by the headset view.ControllerGlanceExit- Emitted when the controller is no longer seen by the headset view.
Adding the VRTK_HeadsetControllerAware_UnityEvents component to VRTK_HeadsetControllerAware object allows access to UnityEvents that will react identically to the Class Events.
OnControllerObscured- Emits the ControllerObscured class event.OnControllerUnobscured- Emits the ControllerUnobscured class event.OnControllerGlanceEnter- Emits the ControllerGlanceEnter class event.OnControllerGlanceExit- Emits the ControllerGlanceExit class event.
RaycastHit raycastHit- The Raycast Hit struct of item that is obscuring the path to the controller.uint controllerIndex- The index of the controller that is being or has been obscured or being or has been glanced.
public bool LeftControllerObscured()
- Parameters
- none
- Returns
bool- Returns true if the path between the headset and the controller is obscured.
The LeftControllerObscured method returns the state of if the left controller is being obscured from the path of the headset.
public bool RightControllerObscured()
- Parameters
- none
- Returns
bool- Returns true if the path between the headset and the controller is obscured.
The RightControllerObscured method returns the state of if the right controller is being obscured from the path of the headset.
public bool LeftControllerGlanced()
- Parameters
- none
- Returns
bool- Returns true if the headset can currently see the controller within the given radius threshold.
the LeftControllerGlanced method returns the state of if the headset is currently looking at the left controller or not.
public bool RightControllerGlanced()
- Parameters
- none
- Returns
bool- Returns true if the headset can currently see the controller within the given radius threshold.
the RightControllerGlanced method returns the state of if the headset is currently looking at the right controller or not.
VRTK/Examples/029_Controller_Tooltips displays tooltips that have been added to the controllers and are only visible when the controller is being looked at.
The purpose of the Teleport Disable On Headset Collision script is to detect when the headset is colliding with a valid object and prevent teleportation from working. This is to ensure that if a user is clipping their head into a wall then they cannot teleport to an area beyond the wall.
The purpose of the Teleport Disable On Controller Obscured script is to detect when the headset does not have a line of sight to the controllers and prevent teleportation from working. This is to ensure that if a user is clipping their controllers through a wall then they cannot teleport to an area beyond the wall.
The concept that the VR user has a physical in game presence which is accomplished by adding a collider and a rigidbody at the position the user is standing within their play area. This physical collider and rigidbody will prevent the user from ever being able to walk through walls or intersect other collidable objects. The height of the collider is determined by the height the user has the headset at, so if the user crouches then the collider shrinks with them, meaning it's possible to crouch and crawl under low ceilings.
- Headset Y Offset: The collider which is created for the user is set at a height from the user's headset position. If the collider is required to be lower to allow for room between the play area collider and the headset then this offset value will shorten the height of the generated collider.
- Ignore Grabbed Collisions: If this is checked then any items that are grabbed with the controller will not collide with the player presence collider. This is very useful if the user is required to grab and wield objects because if the collider was active they would bounce off the collider.
- Reset Position On Collision: If this is checked then if the Headset Collision script is present and a headset collision occurs, the CameraRig is moved back to the last good known standing position. This deals with any collision issues if a user stands up whilst moving through a crouched area as instead of them being able to clip into objects they are transported back to a position where they are able to stand.
- Falling Physics Only: Only use physics when an explicit falling state is set.
PresenceFallStarted- Emitted when a gravity based fall has started.PresenceFallEnded- Emitted when a gravity based fall has ended.
Adding the VRTK_PlayerPresence_UnityEvents component to VRTK_PlayerPresence object allows access to UnityEvents that will react identically to the Class Events.
OnPresenceFallStarted- Emits the PresenceFallStarted class event.OnPresenceFallEnded- Emits the PresenceFallEnded class event.
float fallDistance- The total height the player has dropped from a gravity based fall.
public void SetFallingPhysicsOnlyParams(bool falling)
- Parameters
bool falling- Toggle the physics falling on or off.- Returns
- none
The SetFallingPhysicsOnlyParams method will toggle the fallingPhysicsOnly class state as well as enable or disable physics if needed.
public bool IsFalling()
- Parameters
- none
- Returns
bool- Returns if the player is in a physics falling state or not.
The IsFalling method will return if the class is using physics based falling and is currently in a falling state.
public void StartPhysicsFall(Vector3 velocity)
- Parameters
Vector3 velocity- The starting velocity to use at the start of a fall.- Returns
- none
The StartPhysicsFall method initializes the physics based fall state, enable physics and send out the PresenceFallStarted event.
public void StopPhysicsFall()
- Parameters
- none
- Returns
- none
The StopPhysicsFall method ends the physics based fall state, disables physics and send out the PresenceFallEnded event.
VRTK/Examples/017_CameraRig_TouchpadWalking has a collection of walls and slopes that can be traversed by the user with the touchpad but the user cannot pass through the objects as they are collidable and the rigidbody physics won't allow the intersection to occur.
Hip Tracking attempts to reasonably track hip position in the absence of a hip position sensor.
The Hip Tracking script is placed on an empty GameObject which will be positioned at the estimated hip position.
- Head Offset: Distance underneath Player Head for hips to reside.
- Head Override: Optional Transform to use as the Head Object for calculating hip position. If none is given one will try to be found in the scene.
- Reference Up: Optional Transform to use for calculating which way is 'Up' relative to the player for hip positioning.
The ability to move the play area around the game world by sliding a finger over the touchpad is achieved using this script. The Touchpad Walking script is applied to the [CameraRig] prefab and adds a rigidbody and a box collider to the user's position to prevent them from walking through other collidable game objects.
If the Headset Collision Fade script has been applied to the Camera prefab, then if a user attempts to collide with an object then their position is reset to the last good known position. This can happen if the user is moving through a section where they need to crouch and then they stand up and collide with the ceiling. Rather than allow a user to do this and cause collision resolution issues it is better to just move them back to a valid location. This does break immersion but the user is doing something that isn't natural.
- Max Walk Speed: The maximum speed the play area will be moved when the touchpad is being touched at the extremes of the axis. If a lower part of the touchpad axis is touched (nearer the centre) then the walk speed is slower.
- Deceleration: The speed in which the play area slows down to a complete stop when the user is no longer touching the touchpad. This deceleration effect can ease any motion sickness that may be suffered.
- Move On Button Press: If a button is defined then movement will only occur when the specified button is being held down and the touchpad axis changes.
- Device For Direction: The direction that will be moved in is the direction of this device.
VRTK/Examples/017_CameraRig_TouchpadWalking has a collection of walls and slopes that can be traversed by the user with the touchpad. There is also an area that can only be traversed if the user is crouching. Standing up in this crouched area will cause the user to appear back at their last good known position.
Move In Place allows the user to move the play area by calculating the y-movement of the user's headset and/or controllers. The user is propelled forward the more they are moving. This simulates moving in game by moving in real life.
This locomotion method is based on Immersive Movement, originally created by Highsight.
- Engage Button: Select which button to hold to engage Move In Place.
- Control Options: Select which trackables are used to determine movement.
- Speed Scale: Lower to decrease speed, raise to increase.
- Max Speed: The max speed the user can move in game units. (If 0 or less, max speed is uncapped)
- Direction Method: How the user's movement direction will be determined. The Gaze method tends to lead to the least motion sickness. Smart decoupling is still a Work In Progress.
- Smart Decouple Threshold: The degree threshold that all tracked objects (controllers, headset) must be within to change direction when using the Smart Decoupling Direction Method.
- Sensitivity: The maximum amount of movement required to register in the virtual world. Decreasing this will increase acceleration, and vice versa.
public enum ControlOptions- Options for testing if a play space fall is valid.HeadsetAndControllers- Track both headset and controllers for movement calculations.ControllersOnly- Track only the controllers for movement calculations.HeadsetOnly- Track only headset for movement caluclations.public enum DirectionalMethod- Options for which method is used to determine player direction while moving.Gaze- Player will always move in the direction they are currently looking.ControllerRotation- Player will move in the direction that the controllers are pointing (averaged).DumbDecoupling- Player will move in the direction they were first looking when they engaged Move In Place.SmartDecoupling- Player will move in the direction they are looking only if their headset point the same direction as their controllers.public bool LeftController- If true, the left controller's trackpad will engage Move In Place.public bool RightController- If true, the right controller's trackpad will engage Move In Place.
public void SetControlOptions(ControlOptions givenControlOptions)
- Parameters
ControlOptions givenControlOptions- The control options to set the current control options to.- Returns
- none
Set the control options and modify the trackables to match.
public Vector3 GetMovementDirection()
- Parameters
- none
- Returns
Vector3- Returns a vector representing the player's current movement direction.
The GetMovementDirection method will return the direction the player is moving.
public float GetSpeed()
- Parameters
- none
- Returns
float- Returns a float representing the player's current movement speed.
The GetSpeed method will return the current speed the player is moving at.
VRTK/Examples/042_CameraRig_MoveInPlace demonstrates how the user can move and traverse colliders by either swinging the controllers in a walking fashion or by running on the spot utilisng the head bob for movement.
This script allows the playArea to move with the user. The [CameraRig] is only moved when at the edge of a defined circle. Aims to create a virtually bigger play area. To use this add this script to the [CameraRig] prefab.
There is an additional script VRTK_RoomExtender_PlayAreaGizmo which can be attached to the [CameraRig] to visualize the extended playArea within the Editor.
- Movement Function: This determines the type of movement used by the extender.
- Additional Movement Enabled: This is the a public variable to enable the additional movement. This can be used in other scripts to toggle the
[CameraRig]movement. - Additional Movement Enabled On Button Press: This configures the controls of the RoomExtender. If this is true then the touchpad needs to be pressed to enable it. If this is false then it is disabled by pressing the touchpad.
- Additional Movement Multiplier: This is the factor by which movement at the edge of the circle is amplified. 0 is no movement of the
[CameraRig]. Higher values simulate a bigger play area but may be too uncomfortable. - Head Zone Radius: This is the size of the circle in which the playArea is not moved and everything is normal. If it is to low it becomes uncomfortable when crouching.
- Debug Transform: This transform visualises the circle around the user where the
[CameraRig]is not moved. In the demo scene this is a cylinder at floor level. Remember to turn of collisions.
public enum MovementFunction- Movement methods.Nonlinear- Moves the head with a non-linear drift movement.LinearDirect- Moves the headset in a direct linear movement.
VRTK/Examples/028_CameraRig_RoomExtender shows how the RoomExtender script is controlled by a VRTK_RoomExtender_Controller Example script located at both controllers. Pressing the Touchpad on the controller activates the Room Extender. The Additional Movement Multiplier is changed based on the touch distance to the centre of the touchpad.
The Interactable Object script is attached to any game object that is required to be interacted with (e.g. via the controllers).
The basis of this script is to provide a simple mechanism for identifying objects in the game world that can be grabbed or used but it is expected that this script is the base to be inherited into a script with richer functionality.
The highlighting of an Interactable Object is defaulted to use the VRTK_MaterialColorSwapHighlighter if no other highlighter is applied to the Object.
- Highlight On Touch: The object will only highlight when a controller touches it if this is checked.
- Touch Highlight Color: The colour to highlight the object when it is touched. This colour will override any globally set colour (for instance on the
VRTK_InteractTouchscript). - Rumble On Touch: The haptic feedback on the controller can be triggered upon touching the object, the
Strengthdenotes the strength of the pulse, theDurationdenotes the length of time. - Allowed Touch Controllers: Determines which controller can initiate a touch action.
- Hide Controller On Touch: Optionally override the controller setting.
- Is Grabbable: Determines if the object can be grabbed.
- Valid Drop: Determines in what situation the object can be dropped by the controller grab button.
- Secondary Grab Action: Determines what should happen to the object if another grab attempt is made by a secondary controller if the object is already being grabbed.
- Custom Secondary Action: The script to utilise to process the secondary controller action when a secondary grab attempt is made.
- Hold Button To Grab: If this is checked then the grab button on the controller needs to be continually held down to keep grabbing. If this is unchecked the grab button toggles the grab action with one button press to grab and another to release.
- Grab Override Button: If this is set to
Undefinedthen the global grab alias button will grab the object, setting it to any other button will ensure the override button is used to grab this specific interactable object. - Rumble On Grab: The haptic feedback on the controller can be triggered upon grabbing the object, the
Strengthdenotes the strength of the pulse, theDurationdenotes the length of time. - Allowed Grab Controllers: Determines which controller can initiate a grab action.
- Precision Snap: If this is checked then when the controller grabs the object, it will grab it with precision and pick it up at the particular point on the object the controller is touching.
- Right Snap Handle: A Transform provided as an empty game object which must be the child of the item being grabbed and serves as an orientation point to rotate and position the grabbed item in relation to the right handed controller. If no Right Snap Handle is provided but a Left Snap Handle is provided, then the Left Snap Handle will be used in place. If no Snap Handle is provided then the object will be grabbed at its central point. Not required for
Precision Snap. - Left Snap Handle: A Transform provided as an empty game object which must be the child of the item being grabbed and serves as an orientation point to rotate and position the grabbed item in relation to the left handed controller. If no Left Snap Handle is provided but a Right Snap Handle is provided, then the Right Snap Handle will be used in place. If no Snap Handle is provided then the object will be grabbed at its central point. Not required for
Precision Snap. - Hide Controller On Grab: Optionally override the controller setting.
- Stay Grabbed On Teleport: If this is checked then the object will stay grabbed to the controller when a teleport occurs. If it is unchecked then the object will be released when a teleport occurs.
- Grab Attach Mechanic: This determines how the grabbed item will be attached to the controller when it is grabbed.
- Detach Threshold: The force amount when to detach the object from the grabbed controller. If the controller tries to exert a force higher than this threshold on the object (from pulling it through another object or pushing it into another object) then the joint holding the object to the grabbing controller will break and the object will no longer be grabbed. This also works with Tracked Object grabbing but determines how far the controller is from the object before breaking the grab. Only required for
Fixed Joint,Spring Joint,Track ObjectandRotator Track. - Spring Joint Strength: The strength of the spring holding the object to the controller. A low number will mean the spring is very loose and the object will require more force to move it, a high number will mean a tight spring meaning less force is required to move it. Only required for
Spring Joint. - Spring Joint Damper: The amount to damper the spring effect when using a Spring Joint grab mechanic. A higher number here will reduce the oscillation effect when moving jointed Interactable Objects. Only required for
Spring Joint. - Throw Multiplier: An amount to multiply the velocity of the given object when it is thrown. This can also be used in conjunction with the Interact Grab Throw Multiplier to have certain objects be thrown even further than normal (or thrown a shorter distance if a number below 1 is entered).
- On Grab Collision Delay: The amount of time to delay collisions affecting the object when it is first grabbed. This is useful if a game object may get stuck inside another object when it is being grabbed.
- Is Usable: Determines if the object can be used.
- Use Only If Grabbed: If this is checked the object can be used only if it is currently being grabbed.
- Hold Button To Use: If this is checked then the use button on the controller needs to be continually held down to keep using. If this is unchecked the the use button toggles the use action with one button press to start using and another to stop using.
- Use Override Button: If this is set to
Undefinedthen the global use alias button will use the object, setting it to any other button will ensure the override button is used to use this specific interactable object. - Pointer Activates Use Action: If this is checked then when a World Pointer beam (projected from the controller) hits the interactable object, if the object has
Hold Button To Useunchecked then whilst the pointer is over the object it will run it'sUsingmethod. IfHold Button To Useis unchecked then theUsingmethod will be run when the pointer is deactivated. The world pointer will not throw theDestination Setevent if it is affecting an interactable object with this setting checked as this prevents unwanted teleporting from happening when using an object with a pointer. - Rumble On Use: The haptic feedback on the controller can be triggered upon using the object, the
Strengthdenotes the strength of the pulse, theDurationdenotes the length of time. - Allowed Use Controllers: Determines which controller can initiate a use action.
- Hide Controller On Use: Optionally override the controller setting.
public enum GrabAttachType- Types of grab attachment.Fixed_Joint- Attaches the object to the controller with a fixed joint meaning it tracks the position and rotation of the controller with perfect 1:1 tracking.Spring_Joint- Attaches the object to the controller with a spring joint meaning there is some flexibility between the item and the controller force moving the item. This works well when attempting to pull an item rather than snap the item directly to the controller. It creates the illusion that the item has resistance to move it.Track_Object- Doesn't attach the object to the controller via a joint, instead it ensures the object tracks the direction of the controller, which works well for items that are on hinged joints.Rotator_Track- Tracks the object but instead of the object tracking the direction of the controller, a force is applied to the object to cause it to rotate. This is ideal for hinged joints on items such as wheels or doors.Child_Of_Controller- Makes the object a child of the controller grabbing so it naturally tracks the position of the controller motion.Climbable- Non-rigid body interactable object used to allow player climbing.public enum AllowedController- Allowed controller type.Both- Both controllers are allowed to interact.Left_Only- Only the left controller is allowed to interact.Right_Only- Only the right controller is allowed to interact.public enum ControllerHideMode- Hide controller state.Default- Use the hide settings from the controller.OverrideHide- Hide the controller when interacting, overriding controller settings.OverrideDontHide- Don't hide the controller when interacting, overriding controller settings.public enum ValidDropTypes- The types of valid situations that the object can be released from grab.No_Drop- The object cannot be dropped via the controllerDrop_Anywhere- The object can be dropped anywhere in the scene via the controller.Drop_ValidSnapDropZone- The object can only be dropped when it is hovering over a valid snap drop zone.public enum SecondaryControllerActions- The types of actions the secondary controller will have on the object on a secondary grab attemptNo_Action- Nothing will happen to the grabbed object if a secondary controller attempts to grab it.Swap_Controller- The object will be swapped after another grab attempt to the secondary grabbing controller.Custom_Action- The object will be manipulated by the script provided in theSecondary Custom Actionparameter.public int usingState- The current using state of the object.0not being used,1being used. Default:0
InteractableObjectTouched- Emitted when another object touches the current object.InteractableObjectUntouched- Emitted when the other object stops touching the current object.InteractableObjectGrabbed- Emitted when another object grabs the current object (e.g. a controller).InteractableObjectUngrabbed- Emitted when the other object stops grabbing the current object.InteractableObjectUsed- Emitted when another object uses the current object (e.g. a controller).InteractableObjectUnused- Emitted when the other object stops using the current object.
Adding the VRTK_InteractableObject_UnityEvents component to VRTK_InteractableObject object allows access to UnityEvents that will react identically to the Class Events.
OnTouch- Emits the InteractableObjectTouched class event.OnUntouch- Emits the InteractableObjectUntouched class event.OnGrab- Emits the InteractableObjectGrabbed class event.OnUngrab- Emits the InteractableObjectUngrabbed class event.OnUse- Emits the InteractableObjectUsed class event.OnUnuse- Emits the InteractableObjectUnused class event.
GameObject interactingObject- The object that is initiating the interaction (e.g. a controller).
public bool CheckHideMode(bool defaultMode, ControllerHideMode overrideMode)
- Parameters
bool defaultMode- The default setting of the controller. true = hide, false = don't hide.ControllerHideMode overrideMode- The override setting of the object.- Returns
bool- Returnstrueif the combination ofdefaultModeandoverrideModelead to "hide controller.
The CheckHideMode method is a simple service method used only by some scripts (e.g. InteractTouch InteractGrab InteractUse) to calculate the "hide controller" condition according to the default controller settings and the interactive object override method.
public bool IsTouched()
- Parameters
- none
- Returns
bool- Returnstrueif the object is currently being touched.
The IsTouched method is used to determine if the object is currently being touched.
public bool IsGrabbed(GameObject grabbedBy = null)
- Parameters
GameObject grabbedBy- An optional GameObject to check if the Interactable Object is grabbed by that specific GameObject. Defaults tonull- Returns
bool- Returnstrueif the object is currently being grabbed.
The IsGrabbed method is used to determine if the object is currently being grabbed.
public bool IsUsing(GameObject usedBy = null)
- Parameters
GameObject usedBy- An optional GameObject to check if the Interactable Object is used by that specific GameObject. Defaults tonull- Returns
bool- Returnstrueif the object is currently being used.
The IsUsing method is used to determine if the object is currently being used.
public virtual void StartTouching(GameObject currentTouchingObject)
- Parameters
GameObject currentTouchingObject- The game object that is currently touching this object.- Returns
- none
The StartTouching method is called automatically when the object is touched initially. It is also a virtual method to allow for overriding in inherited classes.
public virtual void StopTouching(GameObject previousTouchingObject)
- Parameters
GameObject previousTouchingObject- The game object that was previously touching this object.- Returns
- none
The StopTouching method is called automatically when the object has stopped being touched. It is also a virtual method to allow for overriding in inherited classes.
public virtual void Grabbed(GameObject currentGrabbingObject)
- Parameters
GameObject currentGrabbingObject- The game object that is currently grabbing this object.- Returns
- none
The Grabbed method is called automatically when the object is grabbed initially. It is also a virtual method to allow for overriding in inherited classes.
public virtual void Ungrabbed(GameObject previousGrabbingObject)
- Parameters
GameObject previousGrabbingObject- The game object that was previously grabbing this object.- Returns
- none
The Ungrabbed method is called automatically when the object has stopped being grabbed. It is also a virtual method to allow for overriding in inherited classes.
public virtual void StartUsing(GameObject currentUsingObject)
- Parameters
GameObject currentUsingObject- The game object that is currently using this object.- Returns
- none
The StartUsing method is called automatically when the object is used initially. It is also a virtual method to allow for overriding in inherited classes.
public virtual void StopUsing(GameObject previousUsingObject)
- Parameters
GameObject previousUsingObject- The game object that was previously using this object.- Returns
- none
The StopUsing method is called automatically when the object has stopped being used. It is also a virtual method to allow for overriding in inherited classes.
public virtual void ToggleHighlight(bool toggle)
- Parameters
bool toggle- The state to determine whether to activate or deactivate the highlight.truewill enable the highlight andfalsewill remove the highlight.- Returns
- none
The ToggleHighlight/1 method is used as a shortcut to disable highlights whilst keeping the same method signature. It should always be used with false and it calls ToggleHighlight/2 with a Color.clear.
public virtual void ToggleHighlight(bool toggle, Color globalHighlightColor)
- Parameters
bool toggle- The state to determine whether to activate or deactivate the highlight.truewill enable the highlight andfalsewill remove the highlight.Color globalHighlightColor- The colour to use when highlighting the object.- Returns
- none
The ToggleHighlight/2 method is used to turn on or off the colour highlight of the object.
public void PauseCollisions()
- Parameters
- none
- Returns
- none
The PauseCollisions method temporarily pauses all collisions on the object at grab time by removing the object's rigidbody's ability to detect collisions. This can be useful for preventing clipping when initially grabbing an item.
public bool AttachIsTrackObject()
- Parameters
- none
- Returns
bool- Is true if the grab attach mechanic is one of the track types likeTrack ObjectorRotator Track.
The AttachIsTrackObject method is used to determine if the object is using one of the track grab attach mechanics.
public bool AttachIsClimbObject()
- Parameters
- none
- Returns
bool- Is true if the grab attach mechanic isClimbable.
The AttachIsClimbObject method is used to determine if the object is using the Climbable grab attach mechanics.
public bool AttachIsKinematicObject()
- Parameters
- none
- Returns
bool- Is true if the grab attach mechanic sets the object to a kinematic state on grab.
The AttachIsKinematicObject method is used to determine if the object has kinematics turned on at the point of grab.
public bool AttachIsStaticObject()
- Parameters
- none
- Returns
bool- Is true if the grab attach mechanic is one of the static types likeClimbable.
The AttachIsStaticObject method is used to determine if the object is using one of the static grab attach types.
public bool AttachIsUnthrowableObject()
- Parameters
- none
- Returns
bool- Is true if the grab attach mechanic is of a type that shouldn't be considered thrown when released.
The AttachIsUnthrowableObject method is used to determine if the object is using one of the grab types that should not be thrown when released.
public void ZeroVelocity()
- Parameters
- none
- Returns
- none
The ZeroVelocity method resets the velocity and angular velocity to zero on the rigidbody attached to the object.
public void SaveCurrentState()
- Parameters
- none
- Returns
- none
The SaveCurrentState method stores the existing object parent and the object's rigidbody kinematic setting.
public void ToggleKinematic(bool state)
- Parameters
bool state- The object's rigidbody kinematic state.- Returns
- none
The ToggleKinematic method is used to set the object's internal rigidbody kinematic state.
public bool IsKinematic()
- Parameters
- none
- Returns
bool- Returns true if the rigidbody is set to kinematic and returns false if it's not.
the IsKinematic method returns whether the rigidbody is set to kinematic or not.
public List<GameObject> GetTouchingObjects()
- Parameters
- none
- Returns
List<GameObject>- A list of game object of that are currently touching the current object.
The GetTouchingObjects method is used to return the collecetion of valid game objects that are currently touching this object.
public GameObject GetGrabbingObject()
- Parameters
- none
- Returns
GameObject- The game object of what is grabbing the current object.
The GetGrabbingObject method is used to return the game object that is currently grabbing this object.
public GameObject GetSecondaryGrabbingObject()
- Parameters
- none
- Returns
GameObject- The game object of the secondary controller influencing the current grabbed object.
The GetSecondaryGrabbingObject method is used to return the game object that is currently being used to influence this object whilst it is being grabbed by a secondary controller.
public GameObject GetUsingObject()
- Parameters
- none
- Returns
GameObject- The game object of what is using the current object.
The GetUsingObject method is used to return the game object that is currently using this object.
public bool IsValidInteractableController(GameObject actualController, AllowedController controllerCheck)
- Parameters
GameObject actualController- The game object of the controller that is being checked.AllowedController controllerCheck- The value of which controller is allowed to interact with this object.- Returns
bool- Is true if the interacting controller is allowed to grab the object.
The IsValidInteractableController method is used to check to see if a controller is allowed to perform an interaction with this object as sometimes controllers are prohibited from grabbing or using an object depedning on the use case.
public void ForceStopInteracting()
- Parameters
- none
- Returns
- none
The ForceStopInteracting method forces the object to no longer be interacted with and will cause a controller to drop the object and stop touching it. This is useful if the controller is required to auto interact with another object.
public void ForceStopSecondaryGrabInteraction()
- Parameters
- none
- Returns
- none
The ForceStopSecondaryGrabInteraction method forces the object to no longer be influenced by the second controller grabbing it.
public void SetGrabbedSnapHandle(Transform handle)
- Parameters
Transform handle- A transform of an object to use for the snap handle when the object is grabbed.- Returns
- none
The SetGrabbedSnapHandle method is used to set the snap handle of the object at runtime.
public void RegisterTeleporters()
- Parameters
- none
- Returns
- none
The RegisterTeleporters method is used to find all objects that have a teleporter script and register the object on the OnTeleported event. This is used internally by the object for keeping Tracked objects positions updated after teleporting.
public void StoreLocalScale()
- Parameters
- none
- Returns
- none
the StoreLocalScale method saves the current transform local scale values.
public void ToggleSnapDropZone(VRTK_SnapDropZone snapDropZone, bool state)
- Parameters
VRTK_SnapDropZone snapDropZone- The Snap Drop Zone object that is being interacted with.bool state- The state of whether the interactable object is fixed in or removed from the Snap Drop Zone. True denotes the interactable object is fixed to the Snap Drop Zone and false denotes it has been removed from the Snap Drop Zone.- Returns
- none
The ToggleSnapDropZone method is used to set the state of whether the interactable object is in a Snap Drop Zone or not.
public bool IsInSnapDropZone()
- Parameters
- none
- Returns
bool- Returns true if the interactable object is currently snapped in a drop zone and returns false if it is not.
The IsInSnapDropZone method determines whether the interactable object is currently snapped to a drop zone.
public void SetSnapDropZoneHover(bool state)
- Parameters
bool state- The state of whether the object is being hovered or not.- Returns
- none
The SetSnapDropZoneHover method sets whether the interactable object is currently being hovered over a valid Snap Drop Zone.
public VRTK_SnapDropZone GetStoredSnapDropZone()
- Parameters
- none
- Returns
VRTK_SnapDropZone- The SnapDropZone that the interactable object is currently snapped to.
The GetStoredSnapDropZone method returns the snap drop zone that the interactable object is currently snapped to.
public bool IsDroppable()
- Parameters
- none
- Returns
bool- Returns true if the object can currently be dropped and returns false if it is not currently possible to drop.
The IsDroppable method returns whether the object can be dropped or not in it's current situation.
public bool IsSwappable()
- Parameters
- none
- Returns
bool- Returns true if the object can be grabbed by a secondary controller whilst already being grabbed and the object will swap controllers. Returns false if the object cannot be swapped.
The IsSwappable method returns whether the object can be grabbed with one controller and then swapped to another controller by grabbing with the secondary controller.
public bool PerformSecondaryAction()
- Parameters
- none
- Returns
bool- Returns true if the obejct has a secondary action, returns false if it has no secondary action or is swappable.
The PerformSecondaryAction method returns whether the object has a secondary action that can be performed when grabbing the object with a secondary controller.
VRTK/Examples/005_Controller_BasicObjectGrabbing uses the VRTK_InteractTouch and VRTK_InteractGrab scripts on the controllers to show how an interactable object can be grabbed and snapped to the controller and thrown around the game world.
VRTK/Examples/013_Controller_UsingAndGrabbingMultipleObjects shows multiple objects that can be grabbed by holding the buttons or grabbed by toggling the button click and also has objects that can have their Using state toggled to show how multiple items can be turned on at the same time.
The Interact Touch script is attached to a Controller object within the [CameraRig] prefab.
- Hide Controller On Touch: Hides the controller model when a valid touch occurs.
- Hide Controller Delay: The amount of seconds to wait before hiding the controller on touch.
- Global Touch Highlight Color: If the interactable object can be highlighted when it's touched but no local colour is set then this global colour is used.
- Custom Rigidbody Object: If a custom rigidbody and collider for the rigidbody are required, then a gameobject containing a rigidbody and collider can be passed into this parameter. If this is empty then the rigidbody and collider will be auto generated at runtime to match the HTC Vive default controller.
ControllerTouchInteractableObject- Emitted when a valid object is touched.ControllerUntouchInteractableObject- Emitted when a valid object is no longer being touched.
Adding the VRTK_InteractTouch_UnityEvents component to VRTK_InteractTouch object allows access to UnityEvents that will react identically to the Class Events.
OnControllerTouchInteractableObject- Emits the ControllerTouchInteractableObject class event.OnControllerUntouchInteractableObject- Emits the ControllerUntouchInteractableObject class event.
uint controllerIndex- The index of the controller doing the interaction.GameObject target- The GameObject of the interactable object that is being interacted with by the controller.
public void ForceTouch(GameObject obj)
- Parameters
GameObject obj- The game object to attempt to force touch.- Returns
- none
The ForceTouch method will attempt to force the controller to touch the given game object. This is useful if an object that isn't being touched is required to be grabbed or used as the controller doesn't physically have to be touching it to be forced to interact with it.
public GameObject GetTouchedObject()
- Parameters
- none
- Returns
GameObject- The game object of what is currently being touched by this controller.
The GetTouchedObject method returns the current object being touched by the controller.
public bool IsObjectInteractable(GameObject obj)
- Parameters
GameObject obj- The game object to check to see if it's interactable.- Returns
bool- Is true if the given object is of typeVRTK_InteractableObject.
The IsObjectInteractable method is used to check if a given game object is of type VRTK_InteractableObject and whether the object is enabled.
public void ToggleControllerRigidBody(bool state, bool forceToggle = false)
- Parameters
bool state- The state of whether the rigidbody is on or off.truetoggles the rigidbody on andfalseturns it off.bool forceToggle- Determines if the rigidbody has been forced into it's new state by another script. This can be used to override other non-force settings. Defaults tofalse- Returns
- none
The ToggleControllerRigidBody method toggles the controller's rigidbody's ability to detect collisions. If it is true then the controller rigidbody will collide with other collidable game objects.
public bool IsRigidBodyActive()
- Parameters
- none
- Returns
bool- Is true if the rigidbody on the controller is currently active and able to affect other scene rigidbodies.
The IsRigidBodyActive method checks to see if the rigidbody on the controller object is active and can affect other rigidbodies in the scene.
public bool IsRigidBodyForcedActive()
- Parameters
- none
- Returns
bool- Is true if the rigidbody is active and has been forced into the active state.
The IsRigidBodyForcedActive method checks to see if the rigidbody on the controller object has been forced into the active state.
public void ForceStopTouching()
- Parameters
- none
- Returns
- none
The ForceStopTouching method will stop the controller from touching an object even if the controller is physically touching the object still.
public Collider[] ControllerColliders()
- Parameters
- none
- Returns
Collider[]- An array of colliders that are associated with the controller.
The ControllerColliders method retrieves all of the associated colliders on the controller.
VRTK/Examples/005_Controller/BasicObjectGrabbing demonstrates the highlighting of objects that have the VRTK_InteractableObject script added to them to show the ability to highlight interactable objects when they are touched by the controllers.
The Interact Grab script is attached to a Controller object within the [CameraRig] prefab and the Controller object requires the VRTK_ControllerEvents script to be attached as it uses this for listening to the controller button events for grabbing and releasing interactable game objects. It listens for the AliasGrabOn and AliasGrabOff events to determine when an object should be grabbed and should be released.
The Controller object also requires the VRTK_InteractTouch script to be attached to it as this is used to determine when an interactable object is being touched. Only valid touched objects can be grabbed.
An object can be grabbed if the Controller touches a game object which contains the VRTK_InteractableObject script and has the flag isGrabbable set to true.
If a valid interactable object is grabbable then pressing the set Grab button on the Controller (default is Grip) will grab and snap the object to the controller and will not release it until the Grab button is released.
When the Controller Grab button is released, if the interactable game object is grabbable then it will be propelled in the direction and at the velocity the controller was at, which can simulate object throwing.
The interactable objects require a collider to activate the trigger and a rigidbody to pick them up and move them around the game world.
- Controller Attach Point: The rigidbody point on the controller model to snap the grabbed object to (defaults to the tip).
- Hide Controller On Grab: Hides the controller model when a valid grab occurs.
- Hide Controller Delay: The amount of seconds to wait before hiding the controller on grab.
- Grab Precognition: An amount of time between when the grab button is pressed to when the controller is touching something to grab it. For example, if an object is falling at a fast rate, then it is very hard to press the grab button in time to catch the object due to human reaction times. A higher number here will mean the grab button can be pressed before the controller touches the object and when the collision takes place, if the grab button is still being held down then the grab action will be successful.
- Throw Multiplier: An amount to multiply the velocity of any objects being thrown. This can be useful when scaling up the
[CameraRig]to simulate being able to throw items further. - Create Rigid Body When Not Touching: If this is checked and the controller is not touching an Interactable Object when the grab button is pressed then a rigid body is added to the controller to allow the controller to push other rigid body objects around.
ControllerGrabInteractableObject- Emitted when a valid object is grabbed.ControllerUngrabInteractableObject- Emitted when a valid object is released from being grabbed.
Adding the VRTK_InteractGrab_UnityEvents component to VRTK_InteractGrab object allows access to UnityEvents that will react identically to the Class Events.
OnControllerGrabInteractableObject- Emits the ControllerGrabInteractableObject class event.OnControllerUngrabInteractableObject- Emits the ControllerUngrabInteractableObject class event.
uint controllerIndex- The index of the controller doing the interaction.GameObject target- The GameObject of the interactable object that is being interacted with by the controller.
public void ForceRelease()
- Parameters
- none
- Returns
- none
The ForceRelease method will force the controller to stop grabbing the currently grabbed object.
public void AttemptGrab()
- Parameters
- none
- Returns
- none
The AttemptGrab method will attempt to grab the currently touched object without needing to press the grab button on the controller.
public GameObject GetGrabbedObject()
- Parameters
- none
- Returns
GameObject- The game object of what is currently being grabbed by this controller.
The GetGrabbedObject method returns the current object being grabbed by the controller.
public bool GetControllerVisibilityState()
- Parameters
- none
- Returns
bool- Returns true if the expected grabbed state of the controller visibility should be visible, and returns false if the expected state should be hidden.
The GetControllerVisibilityState method returns the current expected controller visibility state from the grabbed action.
VRTK/Examples/005_Controller/BasicObjectGrabbing demonstrates the grabbing of interactable objects that have the VRTK_InteractableObject script attached to them. The objects can be picked up and thrown around.
VRTK/Examples/013_Controller_UsingAndGrabbingMultipleObjects demonstrates that each controller can grab and use objects independently and objects can also be toggled to their use state simultaneously.
VRTK/Examples/014_Controller_SnappingObjectsOnGrab demonstrates the different mechanisms for snapping a grabbed object to the controller.
The Interact Use script is attached to a Controller object within the [CameraRig] prefab and the Controller object requires the VRTK_ControllerEvents script to be attached as it uses this for listening to the controller button events for using and stop using interactable game objects. It listens for the AliasUseOn and AliasUseOff events to determine when an object should be used and should stop using.
The Controller object also requires the VRTK_InteractTouch script to be attached to it as this is used to determine when an interactable object is being touched. Only valid touched objects can be used.
An object can be used if the Controller touches a game object which contains the VRTK_InteractableObject script and has the flag isUsable set to true.
If a valid interactable object is usable then pressing the set Use button on the Controller (default is Trigger) will call the StartUsing method on the touched interactable object.
- Hide Controller On Use: Hides the controller model when a valid use action starts.
- Hide Controller Delay: The amount of seconds to wait before hiding the controller on use.
ControllerUseInteractableObject- Emitted when a valid object starts being used.ControllerUnuseInteractableObject- Emitted when a valid object stops being used.
Adding the VRTK_InteractUse_UnityEvents component to VRTK_InteractUse object allows access to UnityEvents that will react identically to the Class Events.
OnControllerUseInteractableObject- Emits the ControllerUseInteractableObject class event.OnControllerUnuseInteractableObject- Emits the ControllerUnuseInteractableObject class event.
uint controllerIndex- The index of the controller doing the interaction.GameObject target- The GameObject of the interactable object that is being interacted with by the controller.
public GameObject GetUsingObject()
- Parameters
- none
- Returns
GameObject- The game object of what is currently being used by this controller.
The GetUsingObject method returns the current object being used by the controller.
public void ForceStopUsing()
- Parameters
- none
- Returns
- none
The ForceStopUsing method will force the controller to stop using the currently touched object and will also stop the object's using action.
public void ForceResetUsing()
- Parameters
- none
- Returns
- none
The ForceResetUsing will force the controller to stop using the currently touched object but the object will continue with it's existing using action.
VRTK/Examples/006_Controller_UsingADoor simulates using a door object to open and close it. It also has a cube on the floor that can be grabbed to show how interactable objects can be usable or grabbable.
VRTK/Examples/008_Controller_UsingAGrabbedObject which shows that objects can be grabbed with one button and used with another (e.g. firing a gun).
It is possible to automatically grab an Interactable Object to a specific controller by applying the Object Auto Grab script to the controller that the object should be grabbed by default.
The Object Auto Grab script is attached to a Controller object within the [CameraRig] prefab and the Controller object requires the VRTK_InteractGrab script to be attached.
- Object To Grab: A game object (either within the scene or a prefab) that will be grabbed by the controller on game start.
- Clone Grabbed Object: If this is checked then the Object To Grab will be cloned into a new object and attached to the controller leaving the existing object in the scene. This is required if the same object is to be grabbed to both controllers as a single object cannot be grabbed by different controllers at the same time. It is also required to clone a grabbed object if it is a prefab as it needs to exist within the scene to be grabbed.
VRTK/Examples/026_Controller_ForceHoldObject shows how to automatically grab a sword to each controller and also prevents the swords from being dropped so they are permanently attached to the user's controllers.
This class allows player movement based on grabbing of VRTK_InteractableObject objects that are tagged as Climbable. It should be attached to the [CameraRig] object. Because it works by grabbing, each controller should have a VRTK_InteractGrab and VRTK_InteractTouch component attached.
- Use Player Scale: Will scale movement up and down based on the player transform's scale.
- Use Gravity: Will allow physics based falling when the user lets go of objects above ground.
- Safe Zone Teleport Offset: An additional amount to move the player away from a wall if an ungrab teleport happens due to camera/object collisions.
PlayerClimbStarted- Emitted when player climbing has started.PlayerClimbEnded- Emitted when player climbing has ended.
Adding the VRTK_PlayerClimb_UnityEvents component to VRTK_PlayerClimb object allows access to UnityEvents that will react identically to the Class Events.
OnPlayerClimbStarted- Emits the PlayerClimbStarted class event.OnPlayerClimbEnded- Emits the PlayerClimbEnded class event.
uint controllerIndex- The index of the controller doing the interaction.GameObject target- The GameObject of the interactable object that is being interacted with by the controller.
VRTK/Examples/037_CameraRig_ClimbingFalling shows how to set up a scene with player climbing. There are many different examples showing how the same system can be used in unique ways.
extends VRTK_HeightAdjustTeleport
The dash teleporter extends the height adjust teleporter and allows to have the [CameraRig] dashing to a new teleport location.
Like the basic teleporter and the height adjustable teleporter the Dash Teleport script is attached to the [CameraRig] prefab and requires a World Pointer to be available.
The basic principle is to dash for a very short amount of time, to avoid sim sickness. The default value is 100 miliseconds. This value is fixed for all normal and longer distances. When the distances get very short the minimum speed is clamped to 50 mps, so the dash time becomes even shorter.
The minimum distance for the fixed time dash is determined by the minSpeed and normalLerpTime values, if you want to always lerp with a fixed mps speed instead, set the normalLerpTime to a high value. Right before the teleport a capsule is cast towards the target and registers all colliders blocking the way. These obstacles are then broadcast in an event so that for example their gameobjects or renderers can be turned off while the dash is in progress.
- Normal Lerp Time: The fixed time it takes to dash to a new position.
- Min Speed Mps: The minimum speed for dashing in meters per second.
- Capsule Top Offset: The Offset of the CapsuleCast above the camera.
- Capsule Bottom Offset: The Offset of the CapsuleCast below the camera.
- Capsule Radius: The radius of the CapsuleCast.
WillDashThruObjects- Emitted when the CapsuleCast towards the target has found that obstacles are in the way.DashedThruObjects- Emitted when obstacles have been crossed and the dash has ended.
Adding the VRTK_DashTeleport_UnityEvents component to VRTK_DashTeleport object allows access to UnityEvents that will react identically to the Class Events.
OnWillDashThruObjects- Emits the WillDashThruObjects class event.OnDashedThruObjects- Emits the DashedThruObjects class event.
RaycastHit[] hits- An array of objects that the CapsuleCast has collided with.
SteamVR_Unity_Toolkit/Examples/038_CameraRig_DashTeleport shows how to turn off the mesh renderers of objects that are in the way during the dash.
The Tag Or Script Policy List allows to create a list of either tag names or script names that can be checked against to see if another operation is permitted.
A number of other scripts can use a Tag Or Script Policy List to determine if an operation is permitted based on whether a game object has a tag applied or a script component on it.
For example, the Teleporter scripts can ignore game object targets as a teleport location if the game object contains a tag that is in the identifiers list and the policy is set to ignore.
Or the teleporter can only allow teleport to targets that contain a tag that is in the identifiers list and the policy is set to include.
Add the Tag Or Script Policy List script to a game object (preferably the same component utilising the list) and then configure the list accordingly.
Then in the component that has a Tag Or Script Policy List paramter (e.g. BasicTeleporter has Target Tag Or Script List Policy) simply select the list that has been created and defined.
- Operation: The operation to apply on the list of identifiers.
- Check Type: The element type on the game object to check against.
public enum OperationTypes- The operation to apply on the list of identifiers.Ignore- Will ignore any game objects that contain either a tag or script component that is included in the identifiers list.Include- Will only include game objects that contain either a tag or script component that is included in the identifiers list.public enum CheckTypes- The types of element that can be checked against.Tag- The tag applied to the game object.Script- A script component added to the game object.Tag_Or_Script- Either a tag applied to the game object or a script component added to the game object.
public bool Find(GameObject obj)
- Parameters
GameObject obj- The game object to check if it has a tag or script that is listed in the identifiers list.- Returns
bool- If the operation isIgnoreand the game object is matched by an identifier from the list then it returns true. If the operation isIncludeand the game object is not matched by an identifier from the list then it returns true.
The Find method performs the set operation to determine if the given game object contains one of the identifiers on the set check type. For instance, if the Operation is Ignore and the Check Type is Tag then the Find method will attempt to see if the given game object has a tag that matches one of the identifiers.
To test a scene it is often necessary to use the headset to move to a location. This increases turn-around times and can become cumbersome. The simulator allows navigating through the scene using the keyboard instead, without the need to put on the headset. One can then move around (also through walls) while looking at the monitor and still use the controllers to interact.
The Simulator script is attached to the [CameraRig] prefab. Supported movements are: forward, backward, strafe left, strafe right, turn left, turn right, up, down.
- Keys: Per default the keys on the left-hand side of the keyboard are used (WASD). They can be individually set as needed. The reset key brings the camera to its initial location.
- Only In Editor: Typically the simulator should be turned off when not testing anymore. This option will do this automatically when outside the editor.
- Step Size: Depending on the scale of the world the step size can be defined to increase or decrease movement speed.
- Cam Start: An optional game object marking the position and rotation at which the camera should be initially placed.
Adaptive Quality dynamically changes rendering settings to maintain VR framerate while maximizing GPU utilization.
Only Compatible With Unity 5.4 and above
The Adaptive Quality script is attached to the [CameraRig] game object.
There are two goals:
- Reduce the chances of dropping frames and reprojecting
- Increase quality when there are idle GPU cycles
This script currently changes the following to reach these goals:
- Rendering resolution and viewport size (aka Dynamic Resolution)
In the future it could be changed to also change the following:
- MSAA level
- Fixed Foveated Rendering
- Radial Density Masking
- (Non-fixed) Foveated Rendering (once HMDs support eye tracking)
Some shaders, especially Image Effects, need to be modified to work with the changed render scale. To fix them
pass 1.0f / VRSettings.renderViewportScale into the shader and scale all incoming UV values with it in the vertex
program. Do this by using Material.SetFloat to set the value in the script that configures the shader.
In more detail:
- In the
.shaderfile: Add a new runtime-set property valuefloat _InverseOfRenderViewportScaleand addvertexInput.texcoord *= _InverseOfRenderViewportScaleto the start of the vertex program - In the
.csfile: Before using the material (eg.Graphics.Blit) addmaterial.SetFloat("_InverseOfRenderViewportScale", 1.0f / VRSettings.renderViewportScale)
- Draw Debug Visualization: Toggles whether to show the debug overlay. Each square represents a different level on the quality scale. Levels increase from left to right, the first green box that is lit above represents the recommended render target resolution provided by the current
VRDevice, the box that is lit below in cyan represents the current resolution and the filled box represents the current viewport scale. The yellow boxes represent resolutions below the recommended render target resolution. The currently lit box becomes red whenever the user is likely seeing reprojection in the HMD since the application isn't maintaining VR framerate. If lit, the box all the way on the left is almost always lit red because it represents the lowest render scale with reprojection on. - Allow Keyboard Shortcuts: Toggles whether to allow keyboard shortcuts to control this script.
- The supported shortcuts are:
Shift+F1: Toggle debug visualization on/offShift+F2: Toggle usage of override render scale on/offShift+F3: Decrease override render scale levelShift+F4: Increase override render scale level
- Allow Command Line Arguments: Toggles whether to allow command line arguments to control this script at startup of the standalone build.
- The supported command line arguments all begin with '-' and are:
-noaq: Disable adaptive quality-aqminscale X: Set minimum render scale to X-aqmaxscale X: Set maximum render scale to X-aqmaxres X: Set maximum render target dimension to X-aqfillratestep X: Set render scale fill rate step size in percent to X (X from 1 to 100)-aqoverride X: Set override render scale level to X-vrdebug: Enable debug visualization-msaa X: Set MSAA level to X
- Msaa Level: The MSAA level to use.
- Scale Render Viewport: Toggles whether the render viewport scale is dynamically adjusted to maintain VR framerate. If unchecked, the renderer will render at the recommended resolution provided by the current
VRDevice. - Minimum Render Scale: The minimum allowed render scale.
- Maximum Render Scale: The maximum allowed render scale.
- Maximum Render Target Dimension: The maximum allowed render target dimension. This puts an upper limit on the size of the render target regardless of the maximum render scale.
- Render Scale Fill Rate Step Size In Percent: The fill rate step size in percent by which the render scale levels will be calculated.
- Scale Render Target Resolution: Toggles whether the render target resolution is dynamically adjusted to maintain VR framerate. If unchecked, the renderer will use the maximum target resolution specified by
maximumRenderScale. - Override Render Viewport Scale: Toggles whether to override the used render viewport scale level.
- Override Render Viewport Scale Level: The render viewport scale level to override the current one with.
public readonly ReadOnlyCollection<float> renderScales- All the calculated render scales. The elements of this collection are to be interpreted as modifiers to the recommended render target resolution provided by the currentVRDevice.public static float CurrentRenderScale- The current render scale. A render scale of1.0represents the recommended render target resolution provided by the currentVRDevice.public Vector2 defaultRenderTargetResolution- The recommended render target resolution provided by the currentVRDevice.public Vector2 currentRenderTargetResolution- The current render target resolution.
public static Vector2 RenderTargetResolutionForRenderScale(float renderScale)
- Parameters
float renderScale- The render scale to calculate the render target resolution with.- Returns
Vector2- The render target resolution forrenderScale.
Calculates and returns the render target resolution for a given render scale.
public float BiggestAllowedMaximumRenderScale()
- Parameters
- none
- Returns
float- The biggest allowed maximum render scale.
Calculates and returns the biggest allowed maximum render scale to be used for maximumRenderScale given the current maximumRenderTargetDimension.
public override string ToString()
- Parameters
- none
- Returns
string- The summary.
A summary of this script by listing all the calculated render scales with their corresponding render target resolution.
VRTK/Examples/039_CameraRig_AdaptiveQuality displays the frames per second in the centre of the headset view.
The debug visualization of this script is displayed near the top edge of the headset view.
Pressing the trigger generates a new sphere and pressing the touchpad generates ten new spheres.
Eventually when lots of spheres are present the FPS will drop and demonstrate the script.
In order to interact with the world beyond grabbing and throwing, controls can be used to mimic real-life objects.
A number of controls are available which partially support auto-configuration. So can a slider for example detect its min and max points or a button the distance until a push event should be triggered. In the editor gizmos will be drawn that show the current settings. A yellow gizmo signals a valid configuration. A red one shows that the position of the object should change or switch to manual configuration mode.
All 3D controls extend the VRTK_Control abstract class which provides common methods and events.
All 3D controls extend the VRTK_Control abstract class which provides a default set of methods and events that all of the subsequent controls expose.
- Interact Without Grab: If active the control will react to the controller without the need to push the grab button.
public ValueChangedEvent OnValueChanged- Emitted when the control is interacted with.
OnValueChanged- Emitted when the control is interacted with.
public float GetValue()
- Parameters
- none
- Returns
float- The current value of the control.
The GetValue method returns the current value/position/setting of the control depending on the control that is extending this abstract class.
public float GetNormalizedValue()
- Parameters
- none
- Returns
float- The current normalized value of the control.
The GetNormalizedValue method returns the current value mapped onto a range between 0 and 100.
public void SetContent(GameObject content, bool hideContent)
- Parameters
GameObject content- The content to be considered within the control.bool hideContent- When true the content will be hidden in addition to being non-interactable in case the control is fully closed.- Returns
- none
The SetContent method sets the given game object as the content of the control. This will then disable and optionally hide the content when a control is obscuring its view to prevent interacting with content within a control.
public GameObject GetContent()
- Parameters
- none
- Returns
GameObject- The currently stored content for the control.
The GetContent method returns the current game object of the control's content.
extends VRTK_Control
Attaching the script to a game object will allow the user to interact with it as if it were a push button. The direction into which the button should be pushable can be freely set and auto-detection is supported. Since this is physics-based there needs to be empty space in the push direction so that the button can move.
The script will instantiate the required Rigidbody and ConstantForce components automatically in case they do not exist yet.
- Connected To: An optional game object to which the button will be connected. If the game object moves the button will follow along.
- Direction: The axis on which the button should move. All other axis will be frozen.
- Activation Distance: The local distance the button needs to be pushed until a push event is triggered.
- Button Strength: The amount of force needed to push the button down as well as the speed with which it will go back into its original position.
OnPush- Emitted when the button is successfully pushed.
VRTK/Examples/025_Controls_Overview shows a collection of pressable buttons that are interacted with by activating the rigidbody on the controller by pressing the grab button without grabbing an object.
extends VRTK_Control
Transforms a game object into a chest with a lid. The direction can be auto-detected with very high reliability or set manually.
The script will instantiate the required Rigidbody, Interactable and HingeJoint components automatically in case they do not exist yet. It will expect three distinct game objects: a body, a lid and a handle. These should be independent and not children of each other.
- Direction: The axis on which the chest should open. All other axis will be frozen.
- Lid: The game object for the lid.
- Body: The game object for the body.
- Handle: The game object for the handle.
- Content: The parent game object for the chest content elements.
- Hide Content: Makes the content invisible while the chest is closed.
- Max Angle: The maximum opening angle of the chest.
VRTK/Examples/025_Controls_Overview shows a chest that can be open and closed, it also displays the current opening angle of the chest.
extends VRTK_Control
Transforms a game object into a door with an optional handle attached to an optional frame. The direction can be freely set and also very reliably auto-detected.
There are situations when it can be very hard to automatically calculate the correct axis and anchor values for the hinge joint. If this situation is encountered then simply add the hinge joint manually and set these two values. All the rest will still be handled by the script.
The script will instantiate the required Rigidbodies, Interactable and HingeJoint components automatically in case they do not exist yet. Gizmos will indicate the direction.
- Direction: The axis on which the door should open.
- Door: The game object for the door. Can also be an empty parent or left empty if the script is put onto the actual door mesh. If no colliders exist yet a collider will tried to be automatically attached to all children that expose renderers.
- Handles: The game object for the handles. Can also be an empty parent or left empty. If empty the door can only be moved using the rigidbody mode of the controller. If no collider exists yet a compound collider made up of all children will try to be calculated but this will fail if the door is rotated. In that case a manual collider will need to be assigned.
- Frame: The game object for the frame to which the door is attached. Should only be set if the frame will move as well to ensure that the door moves along with the frame.
- Content: The parent game object for the door content elements.
- Hide Content: Makes the content invisible while the door is closed.
- Max Angle: The maximum opening angle of the door.
- Open Inward: Can the door be pulled to open.
- Open Outward: Can the door be pushed to open.
- Snapping: Keeps the door closed with a slight force. This way the door will not gradually open due to some minor physics effect. Only works if either inward or outward is selected, not both.
VRTK/Examples/025_Controls_Overview shows a selection of door types, from a normal door and trapdoor, to a door with a cat-flap in the middle.
extends VRTK_Control
Transforms a game object into a drawer. The direction can be freely set and also auto-detected with very high reliability.
The script will instantiate the required Rigidbody, Interactable and Joint components automatically in case they do not exist yet. There are situations when it can be very hard to automatically calculate the correct axis for the joint. If this situation is encountered simply add the configurable joint manually and set the axis. All the rest will still be handled by the script.
It will expect two distinct game objects: a body and a handle. These should be independent and not children of each other. The distance to which the drawer can be pulled out will automatically set depending on the length of it. If no body is specified the current object is assumed to be the body.
It is possible to supply a third game object which is the root of the contents inside the drawer. When this is specified the VRTK_InteractableObject components will be automatically deactivated in case the drawer is closed or not yet far enough open. This eliminates the issue that a user could grab an object inside a drawer although it is closed.
- Connected To: An optional game object to which the drawer will be connected. If the game object moves the drawer will follow along.
- Direction: The axis on which the drawer should open. All other axis will be frozen.
- Body: The game object for the body.
- Handle: The game object for the handle.
- Content: The parent game object for the drawer content elements.
- Hide Content: Makes the content invisible while the drawer is closed.
- Snapping: Keeps the drawer closed with a slight force. This way the drawer will not gradually open due to some minor physics effect.
VRTK/Examples/025_Controls_Overview shows a drawer with contents that can be opened and closed freely and the contents can be removed from the drawer.
extends VRTK_Control
Attaching the script to a game object will allow the user to interact with it as if it were a radial knob. The direction can be freely set.
The script will instantiate the required Rigidbody and Interactable components automatically in case they do not exist yet.
- Connected To: An optional game object to which the knob will be connected. If the game object moves the knob will follow along.
- Direction: The axis on which the knob should rotate. All other axis will be frozen.
- Min: The minimum value of the knob.
- Max: The maximum value of the knob.
- Step Size: The increments in which knob values can change.
VRTK/Examples/025_Controls_Overview has a couple of rotator knobs that can be rotated by grabbing with the controller and then rotating the controller in the desired direction.
extends VRTK_Control
Attaching the script to a game object will allow the user to interact with it as if it were a lever. The direction can be freely set.
The script will instantiate the required Rigidbody, Interactable and HingeJoint components automatically in case they do not exist yet. The joint is very tricky to setup automatically though and will only work in straight forward cases. If there are any issues, then create the HingeJoint component manually and configure it as needed.
- Connected To: An optional game object to which the lever will be connected. If the game object moves the lever will follow along.
- Direction: The axis on which the lever should rotate. All other axis will be frozen.
- Min Angle: The minimum angle of the lever counted from its initial position.
- Max Angle: The maximum angle of the lever counted from its initial position.
- Step Size: The increments in which lever values can change.
VRTK/Examples/025_Controls_Overview has a couple of levers that can be grabbed and moved. One lever is horizontal and the other is vertical.
extends VRTK_Lever
This script extends VRTK_Lever to add spring force toward whichever end of the lever's range it is closest to.
The script will instantiate the required Rigidbody, Interactable and HingeJoint components automatically in case they do not exist yet. The joint is very tricky to setup automatically though and will only work in straight forward cases. If there are any issues, then create the HingeJoint component manually and configure it as needed.
- Spring Strength: Strength of the spring force that will be applied toward either end of the lever's range.
extends VRTK_Control
Attaching the script to a game object will allow the user to interact with it as if it were a horizontal or vertical slider. The direction can be freely set and auto-detection is supported.
The script will instantiate the required Rigidbody and Interactable components automatically in case they do not exist yet.
- Direction: The axis on which the slider should move. All other axis will be frozen.
- Min: The minimum value of the slider.
- Max: The maximum value of the slider.
- Step Size: The increments in which slider values can change. The slider supports snapping.
- Detect Min Max: Automatically detect the minimum and maximum positions.
- Min Point: The minimum point on the slider.
- Max Point: The maximum point on the slider.
VRTK/Examples/025_Controls_Overview has a selection of sliders at various angles with different step values to demonstrate their usage.
Manages objects defined as content. When taking out an object from a drawer and closing the drawer this object would otherwise disappear even if outside the drawer.
The script will use the boundaries of the control to determine if it is in or out and re-parent the object as necessary. It can be put onto individual objects or the parent of multiple objects. Using the latter way all interactable objects under that parent will become managed by the script.
- Control: The 3D control responsible for the content.
- Inside: The transform containing the meshes or colliders that define the inside of the control.
- Outside: Any transform that will act as the parent while the object is not inside the control.
VRTK/Examples/025_Controls_Overview has a drawer with a collection of items that adhere to this concept.