OpenVR Actions


Actions are a set of values that can be bound to controller inputs through SteamVR. Since different systems can have different controllers, instead of tying events in a project made for VR to specific hardware events (A-Button, Side Trigger etc.), which not all controllers may have, StreamVR abstracts these events into 'Actions'. For sample 'select', or 'grab'. Then using the SteamVR controller binding UI, features/buttons of the specific controller hardware can be used to trigger/control these exposed events. The available Actions for a project are defined through it's Action Manifest, which is a json file that described and arbitrary amount of actions and their types (vec1, vec3, boolean, pose, skeleton). TouchDesigner defines a default list of actions and are available to be bound through the SteamVR Binding tool. These are defined in Samples/OpenVR/BasicActions.json.

For Basic These these are what are defined, with an explanation of their default binding on HTC Vive Controller:

  • Hand Pose: Transform matrix, bound to the transform of the controller.
  • Trigger: Boolean value, bound to if the trigger is fully pulled.
  • Squeeze: Float value, bound to the current pulled position of the trigger.
  • Grip: Boolean value, bound to the grip buttons (on the side).
  • Trackpad: X/Y value, bound to the position of finger on the trackpad.
  • Trackpad Click: Boolean value, bound to the trackpad button.
  • Trackpad Touch: Boolean value, bound to the trackpad touch.
  • Joystick: X/Y value, bound on the HTC Vive Controller.
  • Joystick Click: Boolean value, bound on the HTC Vive Controller.
  • A Button: Boolean value, bound to the Application Menu button.
  • B Button: Boolean value, bound to the System button.
  • Skeleton: Infered hand skeleton shape backed on what the controller can detect

We also provide a more complex action manifest tailored more towards the amount of actions you can get from a Valve Index controller, in Samples/OpenVR/ComplexActions. This can be used instead by turning on "Custom Actions" and selecting ComplexActions.json as your Action Manifest.

The OpenVR documentation for Action Manifests is available here..

Currently, TouchDesigner does not support multiple Action Sets, and the only action set provided must be named "/actions/default".

Along with those JSON values, we also parse the .json file ourselves and extract some other optional information. At the top level "td_app_key" can be set to a string such as "basic.touchdesigner.exe". This essentially names your running process from SteamVR's point of view, so you can have specific bindings to that action manifest. Without that set, the bindings for your actions will be tied to "system.generated.touchdesigner.exe", and multiple projects will all use the same bindings. For each defined action, an optional "td_chan_name" can be provided which will specify what the CHOP channel name prefix should be for the channels(s) this action generates. Without that entry provided, it will use the suffix of the action name, removing the "/actions/default/in/" prefix from it. You may see "td_legacy_chan_name" in some .json files, but new files should not use that entry. Look at the existing Action Manifests provided in Samples/OpenVR as a way to get started with making your own Action Manifest.


Bindings are what ties the actual hardware events a controller supports to actions. For example tying the action "open" to the "A-Button" on a controller. TouchDesigner provides a default binding for the HTC Vive and Valve Index Controllers, but these bindings can be overridden. Bindings for a variety of other devices can also be added.

To add/edit bindings: Start TouchDesigner and ensure OpenVR is in used by it. Open "Devices" -> "Controller Settings -> Manage Controller Bindings", TouchDesigner using the custom "td_app_key" in the current action manifest should be shown in the "Manager Controller Bindings For:". Change "Active Controller Binding" to "Custom" and then select "Edit this binding". This will open up the binding editing page for TouchDesigner. For each hardware event your controller supports, you can select an action to be tied to it.


Default Bindingsedit

When creating a new action manifest, you can provide default bindings for it. These are specified in the "default_bindings" section of the action manifest. They must reference a bindings .json file that is in a directory either next to or in a subdirectory under where the action manifest is. It can't point somewhere else on the drive. Example default binding files are located in Samples/OpenVR/bindings. Note that the "app_key" entry in these binding files should match the "td_app_key" value in the action manifest, so they are known to be default bindings for that action manifest.