Mapping input from controllers

Step 9 of 13 |30 mins

Interaction overview

Synchronisation and interaction

Overview of the Immerse SDK input system

For controller input to work, a UnityXRConfig component must be attached to the App Object. This Configuration component is responsible for mapping the correct input to SDK functionality. It is added automatically when the scene is set up.

The UnityXRConfig component, uses a strategy pattern to support different VR hardware types.

Input Modules

Each supported hardware platform will have its own implementation of InputModule , which is the common base class for controller input. This abstract base class includes all of the hooks for the Immerse input system. Implementations for these in the Immerse SDK are provided with the following concrete classes:

These input modules handle the logic determing which button maps to what SDK functionality. It also allows the controller to be vibrated.

When the SDK initialises, it creates the local avatar representing the connected VR user. During the avatar initialisation both of the user's hands are created, which represent the controllers. During this process, the SDK will use the UnityXRConfig component and initialise each hand by calling the AttachInputModule method, passing in a reference to the ControllerLocal component for that hand. This method acts as a factory for the Input modules and will return the correct hardware specific instance for that hand.

Local and Remote Avatars

The SDK will always create a local avatar representing the local connected VR user. When other VR users join, the SDK creates remote avatars to represent them too. Local avatars will have access to the VR hardware and use physics, whereas the remote ones will only have meshes and always animate using the messages received from their corresponding users over the network.


SDK Class References


// 1. You can look up the local user, and find it's avatar
var localUser = Session.Users.LocalUser;
Avatar avatar = ImmerseSDK.Avatars.Avatar.Find(localUser);

// 2. You can use a specialised helper method
var avatar = ImmerseSDK.Avatars.Avatar.FindLocal() as AvatarLocal;

Hand strategy

For the InputModule implementations, another strategy pattern is used for each hand, derived from UnityXRHandStrategy. These hand strategies provide a mapping from specific buttons (Unity's input system). Again, different platforms will have different layouts and support for features. These strategies define which Unity input buttons/axis are used; for instance, the grip button, or the trigger button, for each of the supported platforms.


To remap the functionality of the trigger button, change the InputModule implementation, not the UnityXRHandStrategy components.

Controller Classes

The Immerse SDK will add a ControllerLocal component to each of the local avatar's hands. This component provides access to the following information about the controller:

  • position and rotational information
  • access to the InputModule
  • access to the VelocityCalculator , which continuously calculates velocity of the controller and can be read if necessary
// Specify the left hand
Hands hand = Hands.Left;

// Find avatar
Avatar avatar = Avatar.FindLocal();
if (avatar == null)

// Find controller and vibrate it if it exists
ControllerLocal controller = avatar.GetController(hand) as ControllerLocal;
if (controller != null)

Creating personalised mappings

Sometimes a controller mapping might need to be changed. For instance, the controller Grip instead of the Trigger should be used on all supported platforms. This can be done easily with the input system:

  1. Derive a new class from an existing Input Module.
  • Override the method that provides the functionality that needs to change For instance, the HandGrab and HandRelease methods controls interaction.
public override bool HandGrab()
   if (HandStrategy == null)
     return false;

   string axisName = HandStrategy.GetGripAxis();
   return IsAxisPressed(axisName, GrabThresholdDown, ref _grabbed, ref _grabbedFrame, _releasedFrame);

public override bool HandRelease()
  if (HandStrategy == null)
    return false;

  string axisName = HandStrategy.GetGripAxis();
  return IsAxisReleased(axisName, GrabThresholdUp, ref _grabbed, _grabbedFrame, ref _releasedFrame);
  1. Repeat the above step for each hardware platform.
  • Once Input Modules have been created for each platform, override the default XRConfig class and return instances of your own Input Modules, instead of the defaults. Specifically, override the AttachInputModule method.
public virtual InputModule AttachInputModule(ControllerLocal controller, VRHardwareType hardwareType)
    InputModule module = null;

    switch (hardwareType)
        case VRHardwareType.HTCVive:
            module = controller.gameObject.AddComponent<UnityXRViveInputModule>();
  1. After creating a custom XRConfig class, use it to replace the default one on the App Object.

The new mapping should now be ready to test in the Editor.

Advanced Options

The Controller input system can be configured inside unitys project settings Edit > Project Settings and selecting Immerse > Controller

Controller settings page as seen inside Unity's Project settings

Cursor Size
Size of the cursor in Dialogs and other UI elements
Radius Of Effect For EngageRadius (in meters) for object detection, measured from the interaction point on the controller.
Auto Point DistanceThe distance (in meters) from an engageable or interactable object, which will trigger the 'auto point state' on a user's hands.
Min Trigger Value For HandUiMinimum amount of trigger press before HandUI will not be displayed
Should Outline Engage ObjectWhen checked, a coloured outline will appear around an engageable object. If unchecked, no outline will appear.
Use Avatar Color For OutlineWhen checked, the EngageObject's outline will reflect the user's avatar colour. If unchecked, the ColorForForOutline property will be used.
Outline ColorColour to be used for EngageObject Outline
Outline Line ThicknessThinkness for the EngageObject Outline
Haptic Feedback On PickUpEnable/Disable haptic feedback when an object is picked up.
Haptic Feedback On DropEnable/Disable haptic feedback when an object is dropped.
Haptic Feedback On SnapEnable/Disable haptic feedback when the object is snapped
Haptic Feedback Duration SecondsDuration of the haptic vibration in seconds

Interaction overview

Synchronisation and interaction

Updated 3 months ago

Mapping input from controllers

Step 9 of 13 |30 mins

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.