Amazon Input SDK for Unity

Important: Amazon Appstore on Windows 11 will no longer be supported after March 5, 2025. Read the blog for more information.

Tip: Share your thoughts by using the feedback button on the side of the page.

With the Amazon Input SDK for Unity, you can show your users help dialogs that explain how to use your app with a keyboard and mouse. This can provide a pleasant and useful experience to users who don't typically interact with your app using a keyboard and mouse. Before following this guide, make sure you have enabled keyboard and mouse support in your app.

If you are not using Unity, see Amazon Input SDK.

Requirements
Add the Input SDK to your project
Create the input map
API reference

Requirements

The Amazon Input SDK for Unity requires a minimum Unity editor version of 2021.3 or above.

Add the Input SDK to your project

Download the Amazon Input SDK for Unity here.

The download includes the .unitypackage file and a sample app.

Import the Input SDK .unitypackage file into your Unity project. Follow these steps:

From the Assets menu, select Import Package > Custom Package.
Browse for and select Amazon.Device.InputMapping-1.0.1.unitypackage.
Select all the files in the subsequent import dialog and click Import.

If you are using Gradle templates in your Unity project for Android, you might want to configure the Gradle templates for Unity. To configure Gradle templates for Unity, use the following steps in Unity version 2019.3 or later.

Go to Preferences > External Tools. In the Android section, uncheck Gradle installed with Unity and choose the required Gradle version for your project. Version 5.6.4 or later is recommended.
Go to Project settings > Player, select the Android tab, and expand Publishing settings. In the Build section, click the checkbox for Custom Launcher Gradle Template as shown in the following image.
Click image to enlarge

Add the following required dependencies in the dependency section of the Gradle launcher template file, or to your Android project if you export your Unity project as an Android project.

implementation 'com.android.support.constraint:constraint-layout:2.0.4'
implementation 'com.android.support:recyclerview-v7:28.0.0'

Create the input map

Tip: If your app uses the Unity Input System for input control, use the Amazon Input SDK for Unity Input System plugin to set up help dialogs with less effort.

With the Amazon Input SDK for Unity, you'll map key events and mouse clicks to input actions, group those actions into input groups, and create an input map from the input groups, as indicated in the following diagram.

Input from a keyboard maps to an Input Action. Multiple Input Actions are grouped together to form an Input Group. Multiple Input Groups form an Input Map.

Define an input action

An input action is an event corresponding to an app action. The input action can be mapped to a key or a combination of keys. In the following example, the "Jump" action is mapped to the space key.

var jump = InputAction.Create(
        "Jump",
        Actions.JUMP, //where Actions is an enumeration for the game actions
        InputControls.Create(
                new[] 
                {
                    AndroidKeyCode.KEYCODE_SPACE
                },
                null
        )
);

Here, the "Move Left" action is mapped to the left key on the numeric keypad and "Move Right" is mapped to the right key on the numeric keypad.

var moveLeft = InputAction.Create(
        "Move Left",
        Actions.MOVE_LEFT,
        InputControls.Create(
                new[]
                {
                    AndroidKeyCode.KEYCODE_NUMPAD_LEFT
                },
                null
        )
);

var moveRight = InputAction.Create(
        "Move Right",
        Actions.MOVE_RIGHT,
        InputControls.Create(
                new[]
                {
                    AndroidKeyCode.KEYCODE_NUMPAD_RIGHT
                },
                null
        )
);

var freeLook = InputAction.Create(
        "Free look", 
        Actions.FREE_LOOK,
        InputControls.Create(
            null,
            new[]
            {
                MouseAction.MouseMovement
            }
        )
);

Define an input group

An input group is a group of multiple input actions. An input group has a group label and a list of input actions that belong to the group. Each InputAction must be associated with an InputGroup. The following example shows a "Basic Movement" input group created with the input actions defined in the previous section.

InputGroup movementInputGroup = InputGroup.Create("Basic Movement",
    new[]
    {
        jump, moveLeft, moveRight, freelook
    }
);

Build an input map

An input map is the collection of input groups for the app. The input map also contains the mouse settings that are applicable for the app. After you have defined all the input actions and grouped them into input groups, create the input map like in this example.

var inputMap = InputMap.Create(
    new[]
    {
        movementInputGroup
    },
    MouseSettings.Create(false, true)
);

Create an input mapping provider

To provide the input map on request, implement the InputMappingProvider interface. The Amazon Input SDK for Unity invokes the input mapping provider when a user requests a help screen.

private class CustomInputMappingProvider : InputMappingProvider
{
    public InputMap OnProvideInputMap()
    {
        // create an input map
        return inputMap;
    }
}

Register an input mapping provider

There can only be one active input map at a time. When a user accesses the help screen, they are shown the currently active input map. Register an input mapping provider as the active input mapping provider through the Input static class as shown in the following example.

 void Start()
{
    var _inputMappingClient = Input.GetInputMappingClient();
    _inputMappingClient.SetInputMappingProvider(new CustomInputMappingProvider());
}

Display the help screen

To display the help screen, the Appstore recommends displaying a visual element to the user that, when clicked, opens the help screen. You can place the visual indicator either within the game window, or in a separate screen, such as a preferences or controls page. Display the help screen using the TriggerHandler.ShowHelp() method as shown.

TriggerHandler.ShowHelp("My App");

API reference

Browse this section for an introduction to some of the APIs in the Amazon Input SDK for Unity. For a complete API reference, see the Amazon Input SDK for Unity API Reference.

InputControls

InputControls.Create(IList<int> androidKeycodes, IList<int> mouseActions)

The InputControls object contains a list of keyboard keys and a list of mouse actions. The object is created using the static method InputControls.Create().

The InputControls.Create() method returns a new InputControls object. Use an InputControls object to create an InputAction.

InputAction

InputAction.Create(string actionLabel, int uniqueId, InputControls inputControls)

The InputAction object contains a label, a unique ID and an InputControls object. The object is created using the static method InputAction.Create().

The InputAction.Create() method returns a new InputAction object. Use InputAction objects to create an InputGroup.

InputGroup

InputGroup.Create(string groupLabel, IList<InputAction> inputActions)

The InputGroup object contains a label and a list of InputAction objects. The object is created using the static method InputGroup.Create().

The InputGroup.Create() method returns a new InputGroup object. Use an InputGroup along with MouseSettings to create an InputMap.

MouseSettings

MouseSettings.Create(bool allowMouseSensitivityAdjustment, bool invertMouseMovement)

The MouseSettings object contains boolean mouse settings for adjustable sensitivity and inverted axis. The object is created using the static method MouseSettings.Create().

The MouseSettings.Create() method returns a new MouseSettings object. Use MouseSettings along with InputGroup to create an InputMap.

InputMap

InputMap.Create(IList<InputGroup> inputGroups, MouseSettings mouseSettings)

The InputMap object contains a list of InputGroup objects, and a MouseSettings object. The object is created using the static method InputMap.Create().

The InputMap.Create() method returns a new InputMap object. Return an InputMap from your InputMappingProvider implementation.

InputMappingProvider

The InputMappingProvider interface provides the onProvideInputMap() method. In your implementation, override this method to return an InputMap. The InputMap data will be displayed when a user accesses the help screen.

InputMappingClient

The InputMappingClient allows you to manage the InputMappingProvider and provides the following methods:

SetInputMappingProvider(InputMappingProvider inputMappingProvider): assigns an InputMappingProvider to this instance of InputMappingClient.
ClearInputMappingProvider(): removes the currently assigned InputMappingProvider and makes it null.

Input

This class is used to provide an InputMappingClient through the following method:

GetInputMappingClient(): returns the current InputMappingClient.

TriggerHandler

This class provides a method to display the help dialog and contains the following methods:

ShowHelp(string title): shows the input help dialog box. Takes the following parameters.
- title - the title of the app to display on the dialog
ShowHelp(string title, UIMode uiMode): shows the input help dialog box with a specified theme (light or dark). Takes the following parameters.
- title - the title of the app to display on the dialog
- uiMode - the theme setting, valid values are UIMode.AUTO, UIMode.LIGHT, UIMode.DARK
SetUiMode(UIMode uiMode): sets the theme for the dialog box. Takes the following parameters.
- uiMode - the theme setting, valid values are UIMode.AUTO, UIMode.LIGHT, UIMode.DARK

UIMode

This is an enum that defines the constants you can use to set the theme on the help dialog. The constants are:

AUTO - follow system theme
DARK - use dark them
LIGHT - use light theme

Last updated: Mar 05, 2024