DEV Community

Cover image for Introducing the Input SDK for Amazon Appstore
Amazon Appstore Developers profile image Giovanni Laquidara
Giovanni Laquidara for Amazon Appstore Developers

Posted on • Updated on

Introducing the Input SDK for Amazon Appstore

by Gio Laquidara

Imagine a skilled game developer successfully launches a popular game for Android. The mobile game features intuitive touch controls and engaging gameplay. There are hundreds of positive reviews in the appstore, and user growth is the current priority.

There's now a sizable opportunity to expand the game to PCs through Amazon Appstore for Windows 11 and the Windows Subsystem for Android (WSA). However in order to support Android apps on PCs, the existing touch screen controls need to now work with mouse and keyboard inputs which can pose refactoring challenges. How can you ensure the best user experience for PC gamers? To understand how to support keyboard and mouse inputs in existing touch-based game or app, read my recent suggestions in this developer article on mapping inputs.

The Amazon Input SDK enhances the user experience by providing display on-screen information for the available inputs for specific actions in games. This article will show how to use the Input SDK to help users understand how to navigate and interact using mouse and keyboard inputs.

Help Screen

Whether you prefer native Android development or building with Unity, we have you covered. The Amazon Input SDK comes in two versions:

  1. Amazon Input SDK (Java/Kotlin)
  2. Amazon Input SDK for Unity

The following sections cover how integrate both flavors of the Input SDK.

Amazon Input SDK (Java/Kotlin)

Let's start by exploring the usage of the Amazon Input SDK for Java/Kotlin.

To begin using the SDK in your app, add the Amazon Input SDK to the dependencies section of your app-level build.gradle file:

  dependencies {
      ...
      implementation 'com.amazon.device.inputmapping:inputsdklib:1.0.0'
  }
Enter fullscreen mode Exit fullscreen mode

The main component of this SDK is the InputMappingProvider.

When a user requests a help screen, the SDK will use this provider to present the control-action map. The first step in using this SDK is to implement the InputMappingProvider interface and return your input map in the onProvideInputMap method.

class CustomInputMapProvider: InputMappingProvider {

    override fun onProvideInputMap(): InputMap {
        // returns the input map
    }
}
Enter fullscreen mode Exit fullscreen mode

Once you have implemented this interface, you can register your input mapping provider through the Input static class.

override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val inputMappingClient = Input.getInputMappingClient(this)
        inputMappingClient.inputMappingProvider = CustomInputMapProvider();
    }
Enter fullscreen mode Exit fullscreen mode

The active input mapping provider is not affected by the activities lifecycle events and remains valid across different activities. However, you can change it whenever you prefer by using the InputMappingClient and setting a different input mapping provider.

After defining the input mapping provider, you can simply call the following method

TriggerHandler.getInstance().showHelp(this, "My App");
Enter fullscreen mode Exit fullscreen mode

This will display the help screen to guide users on how to play your game.

Now let's dive into the details of the Input Map.

Image description

An InputMap is the collection of your app's input-action mappings InputAction arranged in groups InputGroup.

An input action refers to an event that corresponds to an action performed within the app. This action can be associated with a single key or a combination of keys. For instance, in the given example, the action "Jump" is linked to the pressing of the space key, while the action "Move" is associated with the movement of the mouse.

val jumpInputAction = InputAction.create(
            "Jump",
            MyGameActions.JUMP.ordinal, // MyGameActions here is an enumeration in the game
            InputControls.create(
                listOf(KeyEvent.KEYCODE_SPACE),
                emptyList()
            )
        )

val move = InputAction.create(
            "Move",
            MyGameActions.MOVE.ordinal,
            InputControls.create(
                emptyList(),
                listOf(InputControls.MOUSE_MOVEMENT)
            )
        )
Enter fullscreen mode Exit fullscreen mode

Each input action must be linked to a specific input group. Each input group consists of a label and a collection of input actions categorized within the group. In the previous section, we defined various input actions, and now we can illustrate this concept with an example. Let's create an input group called "Basic Movement," which includes the defined input actions from the previous section:

var movementGroup = InputGroup.create("Basic Movement", 
        listOf(move, jumpInputAction)
)
Enter fullscreen mode Exit fullscreen mode

After defining all the necessary groups, you can pass them to the InputMap.create method to return the input map for your app:

return InputMap.create(
    listOf(moveGroup, gameControls),
    MouseSettings.create(true, true)
)
Enter fullscreen mode Exit fullscreen mode

The InputMap.create() method allows you to define the mouse settings applicable to the app.

Specifically, you can enable the adjustment of the mouse sensitivity and invert the Y-axis:

MouseSettings.create(boolean adjustableSensitivity, boolean invertedYAxis)
Enter fullscreen mode Exit fullscreen mode

Unity SDK

If you are using Unity for your game and want to use the Amazon Input SDK, here are the steps to integrate the SDK into your Unity projects:

  1. Download the Amazon Input SDK for Unity here. The download includes the .unitypackage file and a sample app.

  2. From the Assets menu, select Import Package > Custom Package.

  3. Browse for amazon.device.inputmapping.unitypackage and select it.

  4. Select all the files in the subsequent import dialog and click Import.

  5. Go to Preferences > External Tools. In the Android section, uncheck Gradle installed with Unity and choose the required Gradle version for your project. We recommend Version 5.6.4.

  6. Go to Project settings > Player, select the Android tab, and expand the Publishing settings section.
    In the Build section, click the checkbox for Custom Launcher Gradle Template as shown in the following image.

Custom launcher Gradle Option

  1. Add the following dependencies in the dependency section of the Gradle launcher template file 
implementation 'com.android.support.constraint:constraint-layout:2.0.4'
implementation 'com.android.support:recyclerview-v7:28.0.0'
Enter fullscreen mode Exit fullscreen mode

After setting up the Input SDK for your Unity Project, you are ready to use the main component that provides the input map on request: the InputMappingProvider interface.

Implement this interface and the Amazon Input SDK for Unity will be able to show the input mapping when a user requests a help screen:


// C# example for Unity
private class CustomInputMappingProvider : InputMappingProvider
{
    public InputMap OnProvideInputMap()
    {
        // create an input map
        return inputMap;
    }
}
Enter fullscreen mode Exit fullscreen mode

To use your custom Input Mapping Provider, you need to register it by calling SetInputMappingProvider of the InputMappingClient, as shown in the code below.


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

After registering it you will be able to show the help screen with the mapping to the user calling

TriggerHandler.ShowHelp("My App");
Enter fullscreen mode Exit fullscreen mode

The Input Map

The input map returned from the OnProvideInputMap of your CustomInputMappingProvider will contains all the mapping key events/mouse click to input actions.

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
        )
);
Enter fullscreen mode Exit fullscreen mode

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
        )
);
Enter fullscreen mode Exit fullscreen mode

You will have to group all the desired actions in a InputGroup

An input group has a group label and a list of input actions that belong to the group. 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
    }
);
Enter fullscreen mode Exit fullscreen mode

You can then collect all your groups of input and pass it to the InputMap creation. The input map also contains the mouse settings that are applicable for the app, such as allowing the adjustment of the sensitivity of the mouse or inverting the Y Axis (in the following code false and true respectively).

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

You are ready not to return your input map from the OnProvideInputMap of your InputMappingProvider

Wrap up

By integrating the Amazon Input SDK in touch games on Android, you can provide clear instructions to players on how to use keyboard and mouse inputs effectively on devices with keyboard and mice. This will help ensure a smooth transition from touch controls to PC inputs and enhance the overall user experience.

To know more about Amazon Input SDK head over to our docs.

Stay updated

For the latest Amazon Appstore developer news, product releases, tutorials, and more:

📣 Follow @AmazonAppDev and our team on Twitter

📺 Subscribe to our Youtube channel

📧 Sign up for the Developer Newsletter

About the author

Giovanni ("Gio") Laquidara is a Senior Dev Advocate at Amazon, where he works on supporting developers around the world using the Amazon Appstore across many devices.

Previously, Gio worked as a software engineer building mobile apps, real-time defence systems, and VR/AR experiences. For fun, Gio enjoys low level programming, IoT hacking, and command line apps ⌨️✨.

You can connect with Gio on Twitter, Linkedin, and giolaq.dev.

Top comments (0)

Read next

rt68 profile image

Staying Motivated to Code Amidst Uncertainty: Practical Tips

Ran Tu -

polinaeliana profile image

Simple multicoloured background and highlighted button in HTML & CSS

Polina Eliana -

kwnaidoo profile image

Why MongoDB is not great for complex reporting?

Kevin Naidoo -

sundarbadagala081 profile image

React Custom Hooks (useCounter)

sundarbadagala -