maestro-sdk-docs

Maestro Unity SDK Guide

This guide is for Maestro devices using external tracking systems. See this guide for the Alpha models

The Unity SDK can be downloaded here.

The SDK contains scripts for controlling the Maestro device, as well as three example scenes demonstrating some interactions.

This version is built to be tracking agnostic, but for the sake of simplicity the current SteamVR plugin is included. This aspect of the included content may be updated through the Unity Asset Store.

Setup

First you will need to run the Maestro Alpha installer, which will handle creating configuration files needed for the Maestro to work. This is described under “Initial Setup” and “Configuration” here

Once you have configuration files installed and the Unity Maestro SDK Unity Package imported into a Unity project, an example rig prefab “[MaestroIndexRig]” will be available under Assets/Maestro/Prefabs. This is an example configuration set up to allow Maestro haptics while using the Valve Index’s motion and finger tracking.

The Maestro SDK encourages but does not require two layers definitions used for interactions, which by default are named “GrippedObject” and “IgnoreWhileGripped”. These names can be changed per MaestroHand under Advanced Configuration.

Additional setup is required for the Sandbox scene, which is as follows:

Included Scenes

Sandbox

A haptic sandbox with a variety of interactions, including picking up objects, pushing buttons, using a hammer, and finger painting.

By default, the user starts in a void where they are prompted to scan both hands to spawn the rest of the scene. This functionality can be disabled simply by disabling the “HandScanner” object in the main hierarchy.

Additionally, this scene requires two new input axes to be defined “Clear” and “Lock”, which clear the paint canvas and regenerates the hand scanner, respectively.

Hoops

A scene demonstrating two-hand pickups in the form of a basketball shootaround.

The user is given a silo that can generate endless basketballs, and a small lever to control the distance from the hoop. Additionally, pressing on the touchpad of the Index controllers will generate a basketball directly in front of the user.

Escape

A low-visibility scene where the user must escape a room with doors at both ends. By default the first door approached breaks, forcing the player to navigate to the other door.

Functionality

There are two major portions of the Maestro’s haptics:

Maestro device connectivity is controlled by either a RightMaestroGloveBehaviour or LeftMaestroGloveBehaviour. These scripts have a boolean that shows whether the system detects a connected device for the corresponding hand.

All major haptic functionality is controlled by four scripts: MaestroHand, FingerTipCollider, MaestroInteractable, and HapticResponse. In order to have the hand able to pick up an object:

The FingerTipCollider script is necessary for interactions to properly occur, however they are spawned by the MaestroHand script and as such require no setup. The configuration for the other scripts are as follows:

MaestroHand

Should be placed on the main hand skeleton, beneath either a RightMaestroGloveBehaviour or LeftMaestroGloveBehaviour. Requires an AudioSource that will play a noise on successful pickup.

Hand Configuration

Defines the key hand locations and size.

Advanced Configuration

More complex interaction variables that should only be adjusted when necessary

Debug

Outputs various information useful for debug. Also exposes one boolean:

MaestroInteractable

Must be placed on any game object that requires haptics. The main three fields are:

This script also defines a few events that may be used to easily create complex interactions

Additionally, these other options may be used for differing behavior

HapticResponse

Abstract class that extends the functionality of MaestroInteractable. Automatically detected by MaestroInteractable when placed beneath it in the hierarchy. Provides a single abstract function GetResponse(MaestroInteractable) that is called on FixedUpdate. An example HammerResponse is provided under Assets/Maestro/Responses.

FingerTipCollider

Must be placed on each fingertip and in the center of the palm. Spawned and set up automatically by MaestroHand.

Please contact us at support@contactci.co with any questions.