# VR Add-On - Opsive Documentation
> Complete VR Add-On documentation, generated from the Opsive documentation source on 2026-08-07.
Documentation home: https://opsive.com/support/documentation/character-controller-vr-add-on/
## Contents
- [VR Add-On](#page-character-controller-vr-add-on)
- [Getting Started](#page-character-controller-vr-add-on-getting-started)
- [Setup](#page-character-controller-vr-add-on-setup)
- [Component Structure](#page-character-controller-vr-add-on-component-structure)
- [View Types](#page-character-controller-vr-add-on-view-types)
- [First Person VR](#page-character-controller-vr-add-on-view-types-first-person-vr)
- [Abilities](#page-character-controller-vr-add-on-abilities)
- [Arm Swing](#page-character-controller-vr-add-on-abilities-arm-swing)
- [Directional Rotate](#page-character-controller-vr-add-on-abilities-directional-rotate)
- [Finger Indicator](#page-character-controller-vr-add-on-abilities-finger-indicator)
- [Free Movement](#page-character-controller-vr-add-on-abilities-free-movement)
- [Grab and Move](#page-character-controller-vr-add-on-abilities-grab-and-move)
- [Move In Place](#page-character-controller-vr-add-on-abilities-move-in-place)
- [Trajectory Move](#page-character-controller-vr-add-on-abilities-trajectory-move)
- [Dash](#page-character-controller-vr-add-on-abilities-trajectory-move-dash)
- [Teleport](#page-character-controller-vr-add-on-abilities-trajectory-move-teleport)
- [Rotate With Head](#page-character-controller-vr-add-on-abilities-rotate-with-head)
- [Item Abilities](#page-character-controller-vr-add-on-item-abilities)
- [Flick Reload](#page-character-controller-vr-add-on-item-abilities-flick-reload)
- [Hold](#page-character-controller-vr-add-on-item-abilities-hold)
- [Slot Equip](#page-character-controller-vr-add-on-item-abilities-slot-equip)
---
# VR Add-On
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/)
The VR Add-On is a set of abilities, movement types, and view types allowing you to use a VR headset and hand controllers with your character controller. The VR Add-On supports both single and dual hand controllers (such as the controller for the Oculus Go and the touch controllers for the Oculus Rift). The VR Add-On has been tested on:
- Oculus Rift
- HTC Vive
- Oculus Go
Even if your target device hasn't been tested chances are it will work with just an updated button mapping. The VR Add-On supports both first and third person perspective. The VR Add-On uses Unity's native XR functions and does not require any specific plugins or assets to be imported.
### Limitations
The VR Add-On currently **does not** support the following:
- Physical interactions. This includes:
- Physically pulling back a bow
- Removing a clip with your free hand
- Opening a door by twisting a door handle
- First person full body awareness
- First/third person perspective switching
- PUN Multiplayer Add-On
### Folder Structure
The VR Add-On is imported into the Opsive/UltimateCharacterController/Add-Ons/VR folder. All of the VR scripts are located within the Scripts folder. The Demo folder contains the demo scene and the main Ultimate Character Controller demo scene must be imported in order for this demo scene to work.
---
# Getting Started
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/getting-started/)
In order to play the demo scene your project must first be setup to work with a VR device. See the Unity [VR documentation](https://docs.unity3d.com/Manual/VROverview.html) for instructions on how to enable VR for your project. Before playing the demo scene ensure you have also setup the correct button mappings for your device. You can do this from the Tools -> Opsive -> Ultimate Character Controller -> Add-Ons Manager and then selecting the Project tab.
### 
### One Handed Tracking
By default the demo scene is setup for a two handed tracking headset such as the Rift or the Vive. If you'd like to use a single handed tracking headset (such as the Oculus Go) you can enable _Free Roam_ under the VR Demo Manager component and then select _One Hand First Person_ for the _Free Roam Character_.
On the First Person VR View Type the _Parent Items VR Camera_ field should then be enabled.
### Lightmapping
In order to reduce the download size the demo scene does not contain any [lightmapping](https://docs.unity3d.com/Manual/Lightmapping.html). When the scene first opens it will appear dark and this can be corrected by [baking the scene](https://docs.unity3d.com/Manual/Lightmapping.html). If the lights are not baked before hitting play they will automatically be disabled.
---
# Setup
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/setup/)
https://www.youtube.com/watch?v=mKPNEKcpF-0 The VR Add-On editor options can be found under the Add-Ons Manager that can be accessed from the Tools -> Opsive -> Ultimate Character Controller -> Add-Ons Manager toolbar. When this manager opens there will be four toolbars:
The high level workflow is to first create your character through the standard character controller managers, and then add VR support by going through these managers. As an example, you'll first want to update the [standard button mappings](/support/documentation/ultimate-character-controller/getting-started/setup/project-update/) and then you'll want to add support for the VR button mappings.
### Project
The Project Setup tab will update the Unity [Input Manager](https://docs.unity3d.com/Manual/class-InputManager.html) to work with the selected headset. If your headset type is not listed you can manually add the button mappings for your particular configuration. If you have created the button mappings for a particular headset type that is not listed feel free to get in [contact with us](/support/) and we'll add that configuration to the next VR Add-On update.
### Scene
The Scene Setup tab will add the necessary scene components, configure the camera in order to work in VR, and add a VR UI. The Camera Controller component must first exist within the scene by running the [Camera Setup](/support/documentation/ultimate-character-controller/getting-started/setup/scene-setup/) editor script. The _Add VR UI_ button will add the UI prefab to the scene:
If you are working with a one handed tracking headset (such as the Oculus Go) the _Parent Items VR Camera_ toggle should be enabled on the [First Person VR](https://opsive.com/support/documentation/character-controller-vr-add-on/view-types/first-person-vr/) View Type.
### Character
https://www.youtube.com/watch?v=VEzq3GEVZPA The Character Setup tab will configure your existing first person character to work with VR. The character must first be created using the [Character Manager](/support/documentation/ultimate-character-controller/getting-started/setup/character-creation/). Third person characters do not need to be setup with this manager.
If you have selected the Two _Hand Tracking_ enum the _Right Hand_ and _Left Hand_ fields will be enabled. These fields require a hand GameObject to be specified. For the demo scene a mesh representing the character's hands were used:
### Item
The Item Setup tab will update the items to work with VR. This tab only needs to be used for first person characters who are using one or two hand tracking. Third person items do not need to be updated.
### One Hand Tracking
If you want to use one hand tracking (such as the Oculus Go) you can follow the same steps as above, with the exception that within the VR Character Manager you should select One instead of Two for the _Hand Tracking_ field. With a single hand the _Right Hand_ and _Left Hand_ fields will disappear.
### Two Handed Smooth Movement
There are a variety of styles for moving your first person character in the virtual world. In many cases the movement is done with a [VR ability](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/), but if you'd like to use the joystick for moving and rotating you can setup your character with the following configuration:
- Disable the _Block Input_ toggle on the First Person VR Movement Type.
- Enable the _Rotate with Character_ toggle on the First Person VR View Type.
- Set the _Motor Rotation_ Speed to 2 on the Ultimate Character Locomotion component.
- Disable all VR abilities on the Ultimate Character Locomotion component.
---
# Component Structure
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/component-structure/)
The VR Add-On is a collection of scripts that sit on top of the existing character controller structure. Most of the included scripts are new abilities but there are a few scripts which are independent of the ability system:
### Movement Types
The First Person VR Movement Type is designed to be used with a two-handed tracking system (such as the Rift or Vive). It allows for input to be blocked which then allows other abilities (such as the Teleporter) to do the character movement. Any of the existing third person movement types can be used for a third person VR character.
### View Types
The First Person VR View Type recognizes the VR camera as a child of the main Camera Controller GameObject. This view type will recenter the VR camera when the character teleports to a new location. Any of the existing third person view types can be used for a third person VR character.
### Hand Tracking
If the first person character is setup to be used with a two-handed tracking system then the Hand Handler component will be added to character GameObject. This component moves the Hand GameObjects to the same location as the player's physical hands. For single controller headsets (such as the Oculus Go) the Hand Tracker component will rotate the First Person Objects GameObject to be at the same angle as the player's hand.
### Items
The logic for the item system is very similar for VR characters as it is for non-VR characters. The two exceptions are the melee and throwable items. When these items are updated (through the [Item Setup](https://opsive.com/support/documentation/character-controller-vr-add-on/setup/) editor) the VR Melee Weapon and VR Throwable Item components will be added. These components track the hand velocity so it knows how much force to apply to the object when it is used.
### UI
The UI for VR games uses a world space canvas rather than the traditional screen space canvas. To account for this the Follow VR Camera Canvas component will move the world space canvas to be located in front of the VR camera. When this component is initialized it will search through all of the child UI Graphic components and change their material's _unity\_GUIZTestMode_ to [Always render](https://docs.unity3d.com/ScriptReference/Rendering.CompareFunction.Always.html).
---
# View Types
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/view-types/)
---
# First Person VR
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/view-types/first-person-vr/)
The First Person VR View Type works with the separate VR camera to position and orient the main camera GameObject. If _Detect Object Clipping_ is enabled the view type will prevent the VR camera from clipping with other objects. Consider the following situation:
In this screenshot the selected collider is the character. The cube on the left is an object that the character should not move through. Because the player can physically move within their play area there is an opportunity for the camera to move into the cube:
In this situation the the view type will move the camera GameObject to the right so it is no longer obstructing the collider. This works by casting a ray from the desired anchor position to the VR camera's position. The _Additional Raycast Buffer_ field will extend the length of the ray to prevent the camera from getting too close to the object.
### Recentering
The common way to recenter VR headsets in Unity is to call [InputTracking.Recenter](https://docs.unity3d.com/ScriptReference/XR.InputTracking.Recenter.html). When this function is called there isn't a callback so the view type doesn't know that it is being recentered. Ensure that the "OnRecenterTracking" [event](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) is sent immediately after the Recenter call so the view type will correctly readjust.
```csharp
public void Recenter()
{
InputTracking.Recenter();
EventHandler.ExecuteEvent("OnRecenterTracking");
}
```
### Inspected Fields
###### Look Direction Distance
The distance that the character should look ahead.
###### VR Camera
The camera which is used by the player's head.
###### Parent Items VR Camera
Should the items be parented to the VR camera? If false they will be parented to the main camera.
###### Rotate With Character
Should the camera GameObject rotate with the character?
###### Detect Object Clipping
Should the camera detect clipping between the character and the vr camera?
###### Additional Raycast Buffer
An additional magnitude to add on to the object clipping raycast.
---
# Abilities
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/)
---
# Arm Swing
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/arm-swing/)
The Arm Swing ability will move the character based on the player's arm swing. This ability mimics the motion that a person makes while running. The input vector will be set by this ability and it will then use the locomotion's acceleration/damping values to do the actual movement. The Arm Swing ability differs from the Move In Place ability by requiring both the left and right hands to be moving a minimum distance each frame. It also takes into account the total move distance compared to the Move In Place ability which only accounts for the vertical change.
### Setup
1. Select the + button in the ability list under the "Abilities" foldout of the Ultimate Character Locomotion component.
2. Add the "VR/Arm Swing" ability. The ability is a concurrent ability so it can be located anywhere within the ability list.
### Inspected Fields
###### Left Hand Swing
Specifies if the left hand contributes to the arm swing.
###### Right Hand Swing
Specifies if the right hand contributes to the arm swing.
###### Speed Multiplier
A multiplier to apply to the node movement value.
###### Max Input Value
The maximum value that can be set to the input vector.
###### Required Min Distance
The distance that each node is required to move in order for the movement to be valid.
---
# Directional Rotate
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/directional-rotate/)
The Directional Rotate ability will rotate the character a fixed degree based on joystick input. This ability can rotate the character based on the yaw or the pitch axis. If rotating along the pitch the character should have its gravity disabled. If the UIFade component is added to the scene then the ability will fade the screen for the _Fade Duration_.
### Setup
1. Select the + button in the ability list under the "Abilities" foldout of the Ultimate Character Locomotion component.
2. Add the "VR/Directional Rotate" ability. The ability should be positioned near the top of the ability list so it has priority over other abilities.
### Inspected Fields
###### Input Threshold
The input magnitude must be greater than the specified value in order to start rotating.
###### Fade Duration
The amount of time that it takes the UI to fade.
###### Degrees
The number of degrees that the character should rotate.
###### Pitch Rotation
Can the ability rotate the character along the pitch axis?
---
# Finger Indicator
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/finger-indicator/)
The Finder Indicator ability will set an animator parameter which plays an animation depending on the state of the finger for each hand. This ability is designed for a first person perspective with two handed tracking headsets. The Finger Indicator ability will always be active and it will continuously update the _Hand State Index_ and _Hand Grip Strength_ Animator parameters. These parameters are unique VR parameters that are only on the VR hand Animators. If you are creating your own Animator Controller for your VR hands ensure you have added these parameters:
The following finger states map to the Hand State Index parameter values:
| Finger State | Hand State Index |
| --- | --- |
| Hand Resting, Thumb Resting, Index Resting | 000 |
| Hand Resting, Thumb Resting, Index Extended | 001 |
| Hand Resting, Thumb Resting, Index Contracted | 002 |
| Hand Resting, Thumb Extended, Index Resting | 010 |
| Hand Resting, Thumb Extended, Index Extended | 011 |
| Hand Resting, Thumb Extended, Index Contracted | 012 |
| Hand Contracted, Thumb Resting, Index Resting | 200 |
| Hand Contracted, Thumb Resting, Index Extended | 201 |
| Hand Contracted, Thumb Resting, Index Contracted | 202 |
| Hand Contracted, Thumb Extended, Index Resting | 210 |
| Hand Contracted, Thumb Extended, Index Extended | 211 |
| Hand Contracted, Thumb Extended, Index Contracted | 212 |
### Setup
1. Select the + button in the ability list under the "Abilities" foldout of the Ultimate Character Locomotion component.
2. Add the "VR/Finger Indicator" ability. This ability should be positioned at the bottom of the ability list.
3. Ensure your hand Animator Controllers contain the _Hand State Index_ int parameter and the _Hand Grip Strength_ float parameter.
### Inspected Fields
###### Slot ID
The slot that should be used.
###### Prefix
The prefix of the event and input strings.
###### Inputs
Specifies the input mapping for all of the possible finger indicators.
---
# Free Movement
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/free-movement/)
The Free Movement ability will move the character in the same direction as the Player is looking. This ability is designed to be used when gravity is disabled.
### Setup
1. Select the + button in the ability list under the "Abilities" foldout of the Ultimate Character Locomotion component.
2. Add the "VR/Free Movement" ability.
3. Deselect the _Object Clipping Avoidance_ toggle on the First Person VR View Type.
4. Deselect the _Block Input_ toggle on the First Person Movement Type.
---
# Grab and Move
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/grab-and-move/)
The Grab and Move ability allows the player to grab onto an object and then throw themselves in the desired movement direction. This ability is designed for a first person perspective and should be used when gravity is disabled.
### Setup
1. Select the + button in the ability list under the "Abilities" foldout of the Ultimate Character Locomotion component.
2. Add the "VR/Grab and Move" ability. The ability should be positioned near the top of the ability list so it has priority over other abilities.
### Inspected Fields
###### Grab Layers
The layers that the character can grab onto.
###### Max Velocity History Frame Count
The number of frames that should be kept in determining the velocity of the character.
###### Force Multiplier
The amount to multiply the force by.
###### Frame Count
The number of frames to distribute the force over.
---
# Move In Place
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/move-in-place/)
The Move In Place ability will move the character based on the tracked nodes (can include the head, left hand, or right hand). This ability mimics the motion that a person makes while walking/running. The input vector will be set by this ability and it will then use the locomotion's acceleration/damping values to do the actual movement. The Move In Place ability differs from the Arm Swing ability in that it does not require the tracked node to move a minimum distance. It will instead average the total distance moved by all of the tracked nodes. It also only takes in account the vertical change whereas the Arm Swing ability accounts for changes on both the vertical and depth axis.
### Setup
1. Select the + button in the ability list under the "Abilities" foldout of the Ultimate Character Locomotion component.
2. Add the "VR/Move In Place" ability. The ability is a concurrent ability so it can be located anywhere within the ability list.
### Inspected Fields
###### Move With Head
Should the character move with the player's head bob?
###### Hand Movement Options
Specifies which of the player's hands should move the character:
- _Left Hand_: Move with the player's left hand.
- _Right Hand_: Move with the player's right hand.
- _Both Hands_: Move with the average over both of the player's hands.
- _None_: Do not move with the hand movement.
###### Speed Multiplier
A multiplier to apply to the vertical node movement value.
###### Max Input Value
The maximum value that can be set to the input vector.
---
# Trajectory Move
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/trajectory-move/)
The Trajectory Move ability is an abstract ability that is inherited by the [Teleport](/support/documentation/character-controller-vr-add-on/trajectory-move/teleport) and [Dash](/support/documentation/character-controller-vr-add-on/trajectory-move/dash) abilities. This ability draws the arc that is commonly indicates the location that can be moved to. The Teleport ability will move the character to the destination instantly, while the Dash ability will move the character based on a move speed. There are two pieces associated with the arc when it is drawn. The first piece is the actual arc and this uses a [Line Renderer](https://docs.unity3d.com/Manual/class-LineRenderer.html) to draw. The Line Renderer's material and properties can be changed to achieve a look that is designed for your project. The second piece is a directional indicator GameObject. This GameObject is optional and it contains the marker that indicates the surface that was hit. This indicator will be rotated in the direction that the character will be move towards (if _Allow Rotational Changes_ is enabled).
### Inspected Fields
###### Start Trajectory Offset
The offset of the trajectory start point.
###### Cast Radius
The radius of the cast when determining if a location is valid.
###### Allow Rotational Changes
Should the character be rotated based on the directional input?
###### Min Axis Magnitude
The minimum value of the axis in order for it to be considered a valid movement direction.
###### Perform Movement Button Name
The name of the button when the ability should perform its movement.
###### Perform Movement Magnitude
Perform the movement when the axis magnitude is less than the specified value. This is only used for Vive headsets.
###### Trajectory Object
The object which draws the trajectory.
###### Valid Location Color
Color that indicates a valid teleport location.
###### Invalid Location Color
Color that indicates an invalid teleport location.
###### Color Change Duration
Specifies the lerp duration for changing the color.
###### Surface Identifier
The transform used to indicate the surface. Can be null.
###### Surface Indicator Offset
The offset when positioning the surface indicator.
###### Adjust Surface Indicator Color
Should the surface indicator's material color be adjusted?
---
# Dash
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/trajectory-move/dash/)
The Dash ability extends the [Trajectory Move](https://opsive.com/support/documentation/character-controller-vr-add-on/trajectory-move/) ability by moving the character to the new location at the specified _Move Speed_. If a location is not valid then the character will not be moved. The character is moved as soon as the joystick's horizontal and vertical axis reaches 0.
### Setup
1. Select the + button in the ability list under the "Abilities" foldout of the Ultimate Character Locomotion component.
2. Add the "VR/Dash" ability. The ability should be positioned near the top of the ability list so it has priority over other abilities.
3. A default value for the Trajectory Object's [Line Renderer](https://docs.unity3d.com/Manual/class-LineRenderer.html) and Surface Indicator will be created. You'll likely want to customize this for your project.
### Inspected Fields
###### Move Speed
The speed at which the character moves towards the destination.
###### Arrived Distance
The character has arrived at their destination when the distance between the target position and character position is less than the specified value.
###### Arrived Rotation Delta
The character has arrived at their destination when the delta angle between the target rotation and character rotation is less than the specified value.
###### Movement State Name
The name of the state when the character is dashing to the destination location.
---
# Teleport
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/trajectory-move/teleport/)
The Teleport ability extends the [Trajectory Move](https://opsive.com/support/documentation/character-controller-vr-add-on/trajectory-move/) ability by moving the character to the new location instantly. If a location is not valid then the character will not be moved. The character is moved as soon as the joystick's horizontal and vertical axis reaches 0.
### Setup
1. Select the + button in the ability list under the "Abilities" foldout of the Ultimate Character Locomotion component.
2. Add the "VR/Teleport" ability. The ability should be positioned near the top of the ability list so it has priority over other abilities.
3. A default value for the Trajectory Object's [Line Renderer](https://docs.unity3d.com/Manual/class-LineRenderer.html) and Surface Indicator will be created. You'll likely want to customize this for your project.
---
# Rotate With Head
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/abilities/rotate-with-head/)
The Rotate With Head ability will rotate the character to face the same direction as the headset's rotation. This ability is designed to be used with a first person perspective.
### Setup
1. Select the + button in the ability list under the "Abilities" foldout of the Ultimate Character Locomotion component.
2. Add the "VR/Rotate With Head" ability. The ability is a concurrent ability but should be placed near the bottom of the ability list so it will be the last to update the character's rotation.
---
# Item Abilities
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/item-abilities/)
---
# Flick Reload
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/item-abilities/flick-reload/)
The Flick Reload ability is a subclass of [Reload](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/reload/) and it will activate the ability when a flick motion has occurred. A flick is considered a motion where the hand starts at a starting angle, rotates in a direction past a peak angle, and then rotates back to the original starting angle.
### Inspected Fields
###### Flick Direction
Specifies the type of flick required in order to start the ability.
###### Min Peak Angle
The size of the angle required in order for a flick to have occurred.
###### Max Flick Duration
The amount of time the entire motion must be executed in.
###### Angle Buffer
The threshold for how much the angle will give before the flick motion is reset.
---
# Hold
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/item-abilities/hold/)
The Hold Item Ability will hold the item in the character's hand for as long as the ability is active.
### Inspected Fields
###### Slot ID
The slot that should be held.
###### On Stop Action
Specifies which ability should start when the hold ability stops.
- _Drop_: The item should be dropped when the ability stops.
- _Use_: The item should be used when the ability stops.
- _None_: No abilities should start when the hold ability stops.
---
# Slot Equip
[View this page online](https://opsive.com/support/documentation/character-controller-vr-add-on/item-abilities/slot-equip/)
The Slot Equip Item Ability will equip an item to a specified slot. This is different from the [Equip Unequip](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/item-set/equip-unequip/) Item Ability in that it does not use the Item Set Manager to determine which slot to equip to.
### Inspected Fields
###### Default Item Types
The ItemTypes that should be set when the inventory is otherwise unequipped, one element for each slot.
###### Item Type State Names
Maps the name of the state that should activate when the ItemType is equipped.
###### Append Slot Index
Should the slot index be appended to the end of the ItemType State Name? As an example if this field is enabled then the states Pistol, PistolSlot0, and PistolSlot1 will be set.