Home > Devices > Fire Phone

Using the Unity Plugin for Head Tracking and Shortcut Gestures

Introduction

The Amazon head-tracking and motion-gesture Unity plugin is a set of files that facilitate the use of head tracking and gesture recognition data within the Unity game engine. The plugin is available as part of the Fire Phone SDK add-on and is located in the Unity directory. For information on downloading the Fire Phone SDK add-on, see Setting up Your Development Environment.

When you import the head-tracking and motion-gesture Unity plugin, Unity overwrites existing files in your project with those in the plugin package. Before importing the Unity plugin, review the list of included files and compare this list with your current project to check for overlap or files that may have been removed since the previous version. If a file exists in both your project and the plugins, verify that any changes you have made locally are backed up somewhere outside of your project. After you import the Unity plugin, use your preferred file-merging software to compare and merge the differences between the files in the plugin and the files you had backed up locally.

To import the plugins:

  1. In Unity, click Assets, click Import Package, and then click Custom Package…
  2. Select amazon-headtracking-motiongestures.unitypackage from within the installed SDK add-on.
  3. Click Open.

To check whether head tracking and motion gestures are supported on a particular device, call HeadTrackingManager.IsAvailable and GestureManager.IsAvailable.

Adding Support for Receiving Head-Tracking Events

The HeadTrackingReceiver is a standalone script that can be added to any Unity GameObject to facilitate the registration process with the HeadTrackingManager. By default, it polls for the latest head-tracking data, based on the default HeadTrackingConfiguration. After this script is added to a GameObject, the value of HeadTrackingReceiver.lastEvent will represent the last received HeadTrackingEvent with data coordinates relative to the current ScreenOrientation. For an example of interacting with the HeadTrackingReceiver, refer to HeadTrackingSampleActivity.cs.

If you would like to control the polling configuration more directly or would prefer to create multiple pollers with varying configurations the functionality contained within HeadTrackingReceiver can easily be ported to additional scripts.

Head tracking event data should only be considered valid if HeadTrackingEvent.isTracking is true.

Adding Support for Receiving Gesture Events

The supported gesture events are peek, continuous peek, and tilt. Peek is a state in which the user’s head is out of the center range relative to the phone screen. This can be the result of a movement of the user’s head or a result of turning the device to one side. Continuous peek represents the user's head in any state from fully centered to full peek position and gives magnitude information for positions in between. Tilt is always a movement of the device itself, and it is a movement of one edge of the device away from the user and back again. This gesture must have both parts, the movement away and the movement back..

You can register for these gesture events independently for each Unity GameObject by either leveraging the GestureReceiver script or by implementing the GestureListener interface and interacting with the GestureManager directly.

The GestureReceiver is a standalone script that can be added to any Unity GameObject to facilitate the registration process with the GestureManager. By default, it will register for both tilt and peek events with the gesture directions listed for DEFAULT_TILT_DIRECTIONS and DEFAULT_PEEK_DIRECTIONS (relative to the current ScreenOrientation), respectively. Once added, the GestureReceiver continues to receive the latest gesture events, based on the registration values provided. The value of GestureReceiver.lastEvent represents the last received tilt or peek event relative to the current ScreenOrientation. For an example of interacting with the GestureReceiver, refer to GestureSampleActivity.cs.

If you would like to further control the types of gesture events received for each Unity GameObject, the functionality contained within GestureReceiver can easily be ported to additional scripts.

  1. Create a script that implements the GestureListener interface.
  2. Create an instance of the GestureManager and register for the relevant gesture events with the name of your GameObject.
  3. Attach the script to the GameObject specified in step 2.

All registered gesture events will be received through the provided callback in JSON String format. You can translate the data into a GestureEvent object by calling GestureEvent.GetGestureEventFromJSON with the provided string value.