Interact with Virtual World

This chapter introduces the interaction features provided by VotanicXR. The VotanicXR Interaction is a high-level interaction system. It provides a framework that enables user to interact with virtual objects in the VR environment. The core of this system consists of a set of base Interactor and Interactable components, and an interaction manager that links interactor and interactable together. This chapter introduces how to set-up the interactable objects and interactors.

Interaction Tutorial Scene

The related materials and example scene are in Assets > Votanic > VotanicXR_Tutorial > Tutorial04_Interaction > Resources.

Interaction in VotanicXR

In VotanicXR, all interactions happen when an Interactor performs a type of interaction with an Interactable GameObject. When an interaction is triggered, a command or a Unity Event is invoked that can be used to perform different actions in the VotanicXR application.

The Interactor

There are three types of Interactor in VotanicXR: Wand, Vision, and Collider. The table below summarises the details of each Interactor:

Interactor Description Available Interaction Type
Wand The Wand is the most common interactor in VotanicXR. It resembles the user’s hand(s) in the VR world.
By default, it is represented by a ray beam object or a glove in VotanicXR.		 Object command actions: Grab, Pick, Drop, Trigger, Ungrab

Event triggers: Select, Select Stay, Deselect, Up, Down, Press, Hold
Vision The Vision interactor makes use of the user’s line-of-sight to interact with the VR world.
Interaction can be triggered when the user looks at an Interactable.		 Event triggers: Look, Look Repeat, Look Stay, Look Exit
Collider The Collider interactor triggers an event when active collider of interactor game objects collides with another collider. Event triggers: Collider Enter, Collider Stay, Collider Exit

The Interactable

A GameObject having both the V Gear_Interactable (Script) component and a collider component is available for interaction in VotanicXR. For all the interactable GameObject, VotanicXR has a few built-in basic interactions, as well as a number of event triggers available for building custom interactions.

To set up an interactable object, right click on the GameObject in in Hierarchy window and select vGear > Component > Interactables+. The V Gear_Interactable (Script) component will be added to the game object, exposing it for interaction with the interactor in VotanicXR. In case the game object does not already have a collider component, a box collider will be automatically added to the game object as well.

Basic Interaction

There are three types of pre-defined interaction actions that will interact with the Wand interactor. The interaction can be triggered when user’s Wand or Glove approach an interactable object. The colour of the Wand or Glove (outline) reveals the object’s availability for interaction:

White colour: the wand is enabled and waiting for interaction

Green colour: the wand is touching an interactable object and ready for interaction

Red colour: the wand is interacting with the interactable object

Grey colour: the wand is disabled

The pre-defined interaction actions are: Grab, Pick, and Climb. The table below briefly summarizes the effects of each action:

Interaction Action Description Example
Grab Grab action imitates the user grabbing an object. It requires holding the Grab button or sending the Grab command continuously.

The interactable object will follow the movement of the Wand when user holds the Grab button or triggers the Grab command on a grabbable object.
Pick Pick action picks up an object and automatically carries it on the user’s hand.

The interactable object will follow the movement of the user’s hand when picked up. The pick up and carry is initiated by pressing the Pick button or triggering the Pick command once on a pickable object; and pressing the Grab button or triggering the Grab command once to release the object.
Climb The climb action imitates the situation which the user is applying force to an extremely heavy object.

The user transform will follow the transform of the interactable object when the climb action is enforced. If the user tries to move the wand while grabbing a climbable object, the user transform will move in opposite direction of the wand movement.

The climb action is initiated by holding the Grab button or triggering the Grab command on a climbable object.

The interaction actions are pre-configurured to different key on various input devices to accommodate cross-platform compatibility. The default command input mappings are shown in the table below for your reference. Optionally, you can always customise the mappings for each application using the VotanicXR Configurator.

Command Keyboard / Mouse in PC Mode Vive Controller Other Supported Input Devices
Grab Left Shift Grab Button Button[1] of the 1st and 2nd controller recognized by VotanicXR
Pick

No mapping by default

No mapping by default

No mapping by default
Climb Left Shift Grab Button Button[1] of the 1st and 2nd controller recognized by VotanicXR

These pre-defined interaction actions, as well as detailed behaviour, can be set by toggling the Climb Setting and Grab Setting parameters in the V Gear_Interactable (Script) component.

Note: due to the nature of the actions, climb and pick are mutually exclusive actions. When both the climb and the pick options are selected in the interactables settings, the pickable option will be automatically disabled in runtime.

The following section introduces how to configure the three types of basic interactions.

Grab Interaction

  1. Right click on the GameObject Interactable gameObjects > Chair. Then select vGear > Component > Interactables+. A component V Gear_Interactables will be added to the GameObject.

  2. In V Gear_Interactables component, enable [Setting] > Grab Setting > Grabbable property

  3. In play mode, the GameObject Chair can be grabbed when user holds the Grab button.

  4. Optional. User would be able to throw the object if the Grab button is released while the wand object is in motion.

Pick Interaction

The Pick command is not enabled by default in VotanicXR. To enable the Pick interaction, it is required to first configure the Pick command to an input method first.

  1. In Project window, double click the setting_Interaction.vxrs in Assets > VotanicXR > VotanicXR_Tutorial > Tutorial04_Interaction > Resources to open the VotanicXR Configurator. Then, select the Commands tab, and Click the + Button in Build-in Commands.

  2. Select Pick in Command Name, and then Click Create button.

  3. In the Built-in Commands list, select the Pick command, then under the Selected Input Properties, select ButtonDown in Type property and input 0 in Key property.

  4. Save the config, close the VotanicXR Configurator and go back to Unity.

  5. Right click on the GameObject Interactable gameObjects > Vase. Then select vGear > Component > Interactables+. A component V Gear_Interactables will be added to the GameObject.

  6. In V Gear_Interactables component, enable [Setting] > Grab Setting > Pickable property.

  7. In play mode, the Vase GameObject can be picked when user press the trigger button. User can press Grab button once to release the object.

  8. Optional. While the Pick action is in force, user can switch to Grab action by pressing and holding the Grab button.

Climb Interaction

  1. Right click the GameObject Interactable gameObjects > Flying Shield. Then select vGear > Component > Interactables+. A component V Gear_Interactables will be added to the GameObject.

  2. In V Gear_Interactables component, enable [Setting] > Climb Setting > Climb Object property. Optionally, check the X, Y, Z property in [Setting] > Climb Setting to enable the relative movement of the user transform in the corresponding direction when grabbing the object.

  3. In play mode, when user hold the Grab button on the Flying Shield GameObject, the user will follow the movement of the Flying Shield.

Advanced Interaction

In addition to the basic interactions, VotanicXR has altogether 17 Interactive event triggers for developers to extend the usage of their application. Besides, developers can register their own function to each event.

Event Trigger Interactor Triggered by Corresponding Command Triggering Condition
Grab Wand Grab button Grab Holding the grab button or trigger grab command
Pick Pick button Pick Pressing  the picking button or trigger pick command once
Drop Grab button Drop or Ungrab Releasing the grab button. Both drop or ungrab command will trigger drop event.

By default, drop command has not bind to any buttons.
Select Wand tool - When the tip of the wand collides with the interactable object
Select Stay The tip of the wand continuously touches the collider of the interactable object. This event will be triggered once per frame
Deselect When the tip of the wand exits the interactable object
Up Trigger button Trigger The user releases the trigger button
Down The user presses down the trigger button
Press The user presses and holds the trigger button. This event will be triggered once per frame
Hold The user presses and holds the trigger button for a custom duration. This event will be triggered once with a custom duration
Look Vision User’s Head direction - The user looks at the interactable object
Look Repeat The user looks at the interactable object continuously for a custom duration. This event will be triggered once with a custom duration
Look Stay The user looks at the interactable object continuously. This event will be triggered once per frame
Look Exit The user looks away from the interactable object
Collider Enter Collider Other GameObject collider - The interactable object enters and collides with other GameObject colliders
Collider Stay The interactable object is touching the other GameObject’s collider. This event will be triggered once per frame
Collider Exit The interactable object leaves other GameObject’s collider

Set up Interaction using Unity Event

The below example is to illustrate adding Select and Deselect event trigger on a Rock GameObject and trigger a custom function.

  1. Create a RockInteraction script and attach it to the Interactable Objects > Rock GameObject.

  2. In the RockInteraction script, add two functions as below.

    public void OnWandSelectOnRock()
{
    GetComponent<Renderer>().material.color = new Color(Random.value, Random.value, Random.value);
}

public void OnWandDeselectOnRock()
{
    GetComponent<Renderer>().material.color = Color.white;
}

  3. Add interactable+ on the Rock GameObject.

  4. In the V Gear_Interactables component, configure the Interaction Type to Select and add a Unity Event. In the event item, drag the Rock GameObject to the event and select OnWandSelectOnRock

  5. Multiple interactions can be defined in the V Gear_Interactables. We add the Deselect event in the [Additional Setting] > Interactions and bind the event to the OnWandDeselectOnRock function.

  6. Finally, check the result in the play mode.

Set up Interaction using Custom Command

Instead of registering functions to the Interaction, the Interaction can send a custom command and receive that command via API vGear.Cmd.Received("Command").

The below example is to configure the GameObject Barrel to use the Select and Deselct Interactions. A custom command will be sent out and received by a GameObject SceneController.

  1. Right click the Interactable Objects > Barrel GameObject and add a Interactables+ script.

  2. In V Gear_Interactables component, select Interaction Type, and input the commands in the Command property as follow.

  3. Create an empty GameObject SceneController and a new script CommandController, then attach the script to the SceneController.

  4. Use API vGear.Cmd.Received("OnWandSelectOnBarrel") and vGear.Cmd.Received("OnWandDeselectOnBarrel") to receive the command.

    void Update()
{        
    if (vGear.Cmd.Received("OnWandSelectOnBarrel"))
    {
        GameObject.Find("Barrel").GetComponent<Renderer>().material.color 
            = new Color(Random.value, Random.value, Random.value);
    }    
    if (vGear.Cmd.Received("OnWandDeselectOnBarrel"))
    {
        GameObject.Find("Barrel").GetComponent<Renderer>().material.color = Color.white;
    }
}

  5. In the play mode, when press on the barrel, the color of the barrel will be updated per each command received.

Other Interaction Examples

Interaction with vision

The Vision Interaction can be used to trigger interactions between user's line-of-sight and interactable gameObjects. The relevant interaction types are Look, Look Repeat, Look Stay and Look Exit.

  1. Right Click the Interaction Object > Bird House GameObject and click Interactable+ component.

  2. Create a BirdHouseInteraction script and attach to the Bird House GameObject.

  3. In the script, create a function as below.

    public void DisableBirdHouse()
{
    GetComponent<Renderer>().enabled = false;
}

  4. In Bird House GameObject, set the interaction in the V Gear_Interactables(Script) as below.

    Interaction Type: Look

    Unity event: add an event and select the last created function

  5. Play the scene and see the effect

Interaction with collider

The Collider Interactor can be used to trigger interactions between a game object with collider and other interactable gameObjects. The relevant interaction types are Collider Enter, Collider Stay and Collider Exit.

  1. Right Click the Interaction Object > Area GameObject and click Interactable+ component.

  2. Create a AreaInteraction script and attach to the Area GameObject.

  3. In the script, create a function as below.

    public void AreaChangeColor()
{
    GetComponent<Renderer>().material.color = new Color(Random.value, Random.value, Random.value, .5f);
}
public void AreaRestoreColor()
{
    GetComponent<Renderer>().material.color = Color.white;
}

  4. In Area GameObject, set the interaction in the V Gear_Interactables(Script) as below.

    Interaction Type: Collider

    Unity event: add an event and select the last created function

  5. Play the scene and see the effect.

  6. Optional. The Collider Detection property can be used to limit the interactor object that is able to interact with the interactable object. Below is an example collider detection option added to the Area interactable. We give 2 conditions on the interactor object: 1. the name of the GameObject equals Chair and in layer 30; OR 2. the GameObject is in layer 28. The interactor must fulfil either one of these conditions to interact with the Area interactable.