Amazon Input SDK for Unity
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
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.
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
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.
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 anInputMappingProvider
to this instance ofInputMappingClient
.ClearInputMappingProvider()
: removes the currently assignedInputMappingProvider
and makes it null.
Input
This class is used to provide an InputMappingClient
through the following method:
GetInputMappingClient()
: returns the currentInputMappingClient
.
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 dialoguiMode
- the theme setting, valid values areUIMode.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 areUIMode.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 themeDARK
- use dark themLIGHT
- use light theme
Last updated: Mar 05, 2024