On this page:


Supported headsets
These HMDs have been tested for use with the Vicon Unity plugin:
  • Oculus Rift / Rift S
  • HP Reverb
  • HTC Vive / Vive Pro*

* Due to the requirements of the HTC headsets, they must also be visible by an HTC Vive Base Station.

Unity projects that use the Vicon Unity plugin can only be built as 64-bit applications. When specifying the platform settings, ensure the correct architecture (x64) is selected, as shown in the following image:

Download the Vicon plugin for Unity

Before you begin:

  1. If you haven't already done so, download the plugin from https://vicon.com/downloads/third-party/unity.
  2. Open your Unity software.

Import and explore the supplied files

  1. Create or open a Unity project.
  2. In Windows Explorer double-click on the .unitypackage file. 



  3. The Import Unity Package dialog box is displayed, listing the contents of the package.

     

    • Plugins Contains Vicon Datastream libraries and dependencies that are needed for streaming subjects and headsets to Unity software.
    • Prefab Pre-built game objects with scripts attached, to make the setup process easier.
    • Scripts Contains scripts you can attach to Game Object as components (C# MonoBehavior scripts).

  4. To import these files into the Unity project, make sure that All is selected and click Import.
    All of the files you need are imported into a new folder called Vicon Unity Plugin.

     

  5. In the Project window, from the Assets panel, open the Vicon Unity Plugin folder.

     

  6. Open the Prefab folder to take a look at the prebuilt prefabs.



  7. In the Prefab folder, double-click the HMDPrefab folder to review its contents.
    HMDPrefab comprises two GameObjects:
    • An empty GameObject with the HMD script as a component. This is the script for HMD fusion of IMU data for Oculus, and Vicon positional tracking data.

       

      Note that the inspector may display warnings for this prefab. The HMD Script will not work until a project has been set up for VR, as explained later. For now, ignore these warnings and continue to the next step.

    • A camera object. This is used by the XR (Oculus) plugin to provide VR in the Unity software.

        

  8. Open the ViconDataStreamPrefab.
    This is an empty GameObject with the Vicon Data Stream Client script as a component.

     

    It is used to connect to the Vicon Data Stream server as a client.

  9. Return to the Vicon Unity Plugin folder and open the Scripts folder.



    The Scripts folder contains these scripts:
    • HMDScript For fusing Vicon and Oculus data
    • RBScript For streaming Vicon data onto a GameObject that is not rigged and does not contain any segment bones.
    • SubjectScript For streaming segment data onto a rigged skeleton. This includes single-segment props.
    • ViconDataStreamClient For creating a client to the Vicon Data Stream.

  10. Exit the Prefab folder.

Explore the sample scenes

Open and review the supplied example scenes:

ViconSubjectScriptExample

Open the first sample scene, ViconSubjectScriptExample.

If you have made changes to the scene, you are given the opportunity to save them. Unless you want to keep your changes, click Don't Save.

This scene contains two prefabs, showing how to use the Vicon plugin with a subject.

The ViconDataStreamPrefab has been placed in the scene to create the client connection.

A single character FBX has been brought into the scene. This character has the Subject Script added as a component.

ViconHMDScriptExample

Open the ViconHMDScriptExample scene.

This scene also contains the ViconDataStreamPrefab for client connection.

The HMDPrefab has also been added to show the example set up for HMD fusion.

Set up a project for VR (optional)

Before you begin, ensure you have downloaded the latest versions of SteamVR and Windows Mixed Reality for SteamVR.

  1. On the Edit menu, click Project Settings.



  2. In Package Manager, import SteamVR.



    When you import the SteamVR package, the recommended settings are displayed.



  3. Click Accept All to accept the settings and close the window.
    You may now need to restart the project.
  4. In the Project Settings, go to XR Plug-in Management and enable OpenVR Loader.



  5. In the Scenes folder, open the scene you want to work with. The following example shows the ViconHMDScriptExample scene.

Set up the ViconDataStream prefab

Before you begin, ensure that:

  • You have imported the ViconDataStream Unity package (see Import and explore the supplied files).
  • A ViconDataStreamPrefab exists in the current scene hierarchy. If it doesn't, drag a prefab (located in Assets > Vicon Unity Plugin > Prefab) into the scene OR open one of the example scenes (found in Assets > Scenes).

To set up the Vicon DataStream client:

  1. Ensure you have completed the above preparations.
  2. In the Hierarchy, find the ViconDataStreamPrefab dropdown and select the PoseProvider level.



  3. In the components section of the Inspector,  view the script attached to the ViconDataStreamPrefab.



  4. In the Host Name field, enter the IP address/host name for the Vicon application software server. (For more information about these settings, see Vicon DataStream Client (Script) settings below.)

  5. In the Port field, enter the port number.

  6. If using WiFi, ensure that Configure Wireless is selected.

  7. Click Play and navigate to the Console to check that the client connection has been successful..

Vicon DataStream Client (Script) settings

As described in Steps 3-6 above, before you can stream data from your Vicon software, you need to set up the ViconDataStream client. You do this to supply information about the way in which you want to stream data.

The following table describes the Vicon Data Stream Client settings.

SettingDescription
Host NameEnter the IP address or host name of the Vicon application server PC. For information on connecting two routers, see Multi-route connection.
Port Number

Set to 801 or 804:

  • Tracker: Set to 801. Full datastream output, which allows live and playback modes.
  • Evoke: Set to 804. Low latency output, particularly recommended for VR applications.
  • Shogun: Set to 804. Always Live data (because 801 would be MCP Review).
Subject FilterIf you need to reduce the amount of data sent over the network, select this option to restrict the data passed from the Vicon datastream into Unreal Engine to only the subjects named in this field. Enter one or more subject names, separating multiple names with a comma.
Use PreFetchSelect this option if WiFi performance is poor and multi-route connection is not possible. PreFetch enables the client to pre-request a frame of data, as opposed to the standard datastream mode of Push (which always sends data), reducing the size of latency spikes caused by unstable network connections.

Evoke users: Do not select this option if you're using a version of Evoke that is earlier than 1.1.2.
Is Retimed

If you select this option, subject data can be provided at a different rate from the Vicon system rate, to match that of the engine. It does this via interpolation and forward prediction of samples.

   Offset

If Is Retimed is selected, you can specify (in milliseconds) the amount of prediction that the retiming client will use, dependent on latency time from the Vicon server to client application. 0-3 ms is recommended (the default is 0.0).

Before entering a value, note that forward prediction may cause these issues:

  • When used with unstable and unpredictable WiFi connections, it can cause erratic behavior. Ensure your connection is stable.
  • If tracking is not consistent across the volume, it can also cause problems with poor data quality. Ensure tracking is good across the volume.
LogIf selected, log files are produced in .csv format in the <project root>/Assets/Logs folder, enabling you to review the data that is being received.
Configure WirelessIf selected, enables optimization of the on-board wireless adapter during Datastream connection.

Multi-route connection

Multi-route is a data streaming mode that enables you to simultaneously connect two routers (using two different WiFi channels) to create redundancy in the WiFi network. The client uses whichever frame arrives first from either connection.

Multi-route connection is useful for latency-critical applications such as VR. It is the recommended solution for very busy WiFi environments or when routers/access points experience interference. It ensures a robust and low latency stream of Vicon data to the client application.

For busy WiFi environments that experience interference or latency-critical applications, such as VR streaming, multi-route connection can dramatically improve performance.

To use multi-route connection:

  1. In the Host Name field, enter the IP address of the first adapter on the Vicon machine, followed by a semi-colon, and then the address of the second adapter.
  2. In the Port Number field, enter either 801 (for Tracker) or 804 (Evoke or Shogun).
  3. To check that your connection has been successful, in Unity, click Play.
  4. In the Console, check that the Datastream has connected using both IP addresses.

Set up the required scripts

This section explains how to set up the scripts that are needed.

Note
Unity uses Y-up and Z-forward axes. To adjust for the differences, change the rotations of any GameObject with animation to X -90 Y 90 Z 0.

Set up RBScript

The RBScript is a C# script that interacts with the ViconDataStreamScript. It takes single segment object data from the Datastream and maps it onto the transforms of a GameObject in Unity.

The RBScript must be attached to a GameObject with a transform component. In the following example, a simple Cube is used.

Note
Use this script only when you are mapping transforms from a Vicon-tracked object to a NON-skeletal object in Unity. For the best results, using a rigged skeletal object is recommended. This is particularly important when this script is used in conjunction with the SubjectScript as they will then operate consistently.

Before you begin, ensure that:

  • You have imported the ViconDataStream Unity package (see Import and explore the supplied files).
  • A ViconDataStreamPrefab exists in the current scene hierarchy. If it doesn't, drag a prefab (located in Assets > Vicon Unity Plugin > Prefab) into the scene OR open one of the example scenes (found in Assets > Scenes).

To set up the RB script:

  1. Ensure you have completed the above preparations.
  2. In the Unity project, open a new scene.
  3. In the scene Hierarchy, right-click in an empty space.
  4. From the menu, hover the mouse pointer over 3D Object and select Cube.



    A cube is created in the scene at 0,0,0.
  5. Select the cube.
  6. In the Inspector, click Add Component and in the dialog box, search for RBScript.



  7. Select the RBScript to be attached as a component to the GameObject. (By default, this script is found in Assets > Vicon Unity Plugin > Scripts).



  8. In the Object Name field, enter the Object name. This must match the object name being tracked and solved in the Vicon software.
  9. Select the button to the right of the Client field, and in the dialog box, select ViconDataStreamPrefab.

Set up the HMD script

Before you begin, ensure that:

  • You have imported the ViconDataStream Unity package (see Import and explore the supplied files).
  • A ViconDataStreamPrefab exists in the current scene hierarchy. If it doesn't, drag a prefab (located in Assets > Vicon Unity Plugin > Prefab) into the scene OR open one of the example scenes (found in Assets > Scenes).
  • A HMDPrefab exists in the scene hierarchy. If it doesn't, drag a prefab (located in Assets > Vicon Unity Plugin > Prefab) into the scene OR open one of the HMDScript example scenes (found in Assets > Scenes).

To set up the HMD script:

  1. Ensure you have completed the above preparations.
  2. In the Hierarchy, expand HMDPrefab. Locate Pose Provider and select it.



  3. In the Components section of the Inspector, locate the HMDScript attached to Pose Provider.



  4. In the Hmd Name field, enter the name of the HMD Object streaming from the Vicon application. (For more information on these settings, see HMD Script settings.)

  5. Select the button to the right of the Client field, and in the dialog box, select ViconDataStreamPrefab.



  6. Leave Log cleared, unless you want to record information for troubleshooting purposes.

HMD Script settings

The following table describes the HMD Script settings.

SettingDescription
Hmd NameThe name of the tracked Vicon Object
ClientThe ViconDataStreamPrefab (with attached ViconDataStreamScript) to successfully connect to the Vicon DataStream
LogIf selected, a CSV file is produced, enabling analysis of the fusion data between Vicon/VR. If you encounter problems, send this to Vicon Support.
Tip
When you're using SteamVR, the Edit Controller Bindings menu may be displayed.

 

To resolve this, navigate to Window > SteamVR input, click Save and Generate and then restart the project.

Set up the subject script

The SubjectScript is a c# script that interacts with the ViconDataStreamScript. It takes subject data from the Datastream and maps it onto the skeleton of the skinned mesh that it's attached to.

Before you begin, ensure that:

  • You have imported the ViconDataStream Unity package (see Import and explore the supplied files).
  • A ViconDataStreamPrefab exists in the current scene hierarchy. If it doesn't, drag a prefab (located in Assets > Vicon Unity Plugin > Prefab) into the scene OR open one of the example scenes (found in Assets > Scenes).
  • A Subject with a subject script attached exists in the scene hierarchy. If it doesn't, follow Step 3 in To set up SubjectScript below, OR open the SubjectScript example scene (Found in Assets > Scenes).

To import a character:

  1. Ensure you have completed the above preparations.
  2. In the Project panel, right-click on an empty space.
  3. From the menu, select Import New Asset.



  4. Locate the FBX character file with the skinned mesh and click Import.

Or, instead of importing a character, you can use the default character.

To use the default character:

  1. From the Assets folder, click and drag the character FBX into the scene Hierarchy.

To set up SubjectScript:

  1. From the scene Hierarchy, locate and select the character FBX game object.
  2. In the Inspector, click Add Component.
  3. In the dialog box, search for SubjectScript (by default in Assets > Vicon Unity Plugin > Scripts).



  4. When you select the SubjectScript, it is attached as a component to this game object.



  5. In the Subject Name field, enter the subject name that matches the skeletal subject streaming from Vicon software.
  6. Select the button to the right of the Client field, and in the dialog box, select ViconDataStreamPrefab.

Stream multiple subjects

Multiple subjects can stream simultaneously. If you're streaming a single character, you can duplicate the existing character.

  1. In the Hierarchy window, right-click on the character and then click Duplicate.



  2. For each new subject, in the Inspector, change the Subject Name.


    Important
    Remember that the names must exactly match the subject names in your Vicon application software.
  3. Click Play and observe the results.

If you are using a multiplayer networked game, you don't want to stream the data for each subject to every player. Each player needs only the data for their own subject.