Developer Console

Game Controller Input (Fire TV)

Amazon Fire TV game controllers (as well as other controllers that conform to the Bluetooth HID gamepad profile) have specific buttons, Android motion, and key event constants. Use this information to capture input events in your app.

For guidelines on button behavior for all supported controllers, see Controller Behavior Guidelines. For information on handling input for Fire TV remote controls, see Amazon Fire TV Remote Control Input.

Buttons

The current version of the Fire TV Game Controller has these buttons:

The previous version of the Game Controller has these buttons:

Capturing Input

Game controllers used with Amazon Fire TV generate Android KeyEvent events for digital button presses (such as the A button), and MotionEvent events for analog control movement (such as a joystick action).

You can handle simple button input with standard Android event listener interfaces and callbacks (onClick(), onFocusChange(), and so on).

To capture specific button press events in your View, override input event handlers such as onKeyDown().

Test for the input constants from the KeyEvent class to capture specific keys. For example, to capture a press from the A button, use this code:

@Override
public boolean onKeyDown(int keyCode, KeyEvent event){
    boolean handled = false;

    switch (keyCode){
        case KeyEvent.KEYCODE_BUTTON_A:
                // ... handle selections
                handled = true;
                break;
     }
     return handled || super.onKeyDown(keyCode, event);
}

To capture motion events, override the onGenericMotionEvent() event in your View. Use the input constants from the MotionEvent class to determine which control generated the movement, and the events in the MotionEvent class such as getAxisValue() to determine the values for the motion:

@Override
public boolean onGenericMotionEvent(MotionEvent event){
    // get changes in value from left joystick
    float deltaX = event.getAxisValue(MotionEvent.AXIS_X);
    float deltaY = event.getAxisValue(MotionEvent.AXIS_Y);

    if (deltaX > 0.5 && deltaY > 0.5) {
        // do something
        handled = true;
    }

    return handled || super.onGenericMotionEvent(event);
}

Primary and Secondary Input Events

Some game controller actions on Amazon Fire TV devices may raise more than one input event for a single action. For example, the D-Pad on the Amazon Fire Game Controller is an analog directional control (producing motion events), but a digital control on the Fire TV remote controls (producing key events).

Similarly, the selection action is the A button on a game controller, but it is the D-Pad center button on Fire TV remotes. Some game controller actions on Amazon Fire TV first raise a primary input event (usually a motion event). Then, if those events are not handled by your app, they raise a second input event (usually a key event). Both of the primary and secondary input events are listed in the Input Event Reference table below.

Secondary input events can help you simplify the process of handling game controller input. If your app is interested only in button and D-Pad events from a game controller, the secondary events enable you to ignore motion events altogether and only deal with key events.

Similarly, because the A button generates both KEYCODE_BUTTON_A and KEYCODE_DPAD_CENTER, if your app supports the center D-Pad button on the Fire TV remotes, you do not have to also test for the A button.

Note that your app may behave as if it is receiving double input if you do not properly handle the primary input events. Make sure your input event handlers return true if you have captured and handled an event. The secondary input event is not generated if the first has been captured.

Input Event Reference

The following table describes the motion and key event constants for each game controller button, the suggested user experience behavior for those buttons, and the default behavior of those buttons in the Amazon Fire TV user interface.

Digital buttons report key events (KeyEvent), and analog controls report motion events (MotionEvent). See (../fire-tv/controller-behavior-guidelines.html) for information on suggested behavior for controller input in your app.

The events listed in the Secondary Event column are raised in addition to the events in the MotionEvent or KeyEvent columns, if your app does not handle that primary event. See Primary and Secondary Input Events (above) for information on these secondary events.

In this table, a game is an app that was submitted to the Amazon Appstore in the games category and installed onto the device from the Amazon Appstore.

Game Controller Button MotionEvent KeyEvent Secondary Event Default Behavior
Home none none none For games, display a "Game Paused" dialog. For all other apps, return the user to Home.
Back none KEYCODE_BACK none Return the user to the previous operation or screen (Activity).
Menu none KEYCODE_MENU none Invoke the Android context menu (OptionsMenu).
A none KEYCODE_BUTTON_A KEYCODE_DPAD_CENTER Select the item with the current focus.
B none KEYCODE_BUTTON_B KEYCODE_BACK Go back to the previous screen (Activity) (Same as Back).
X none KEYCODE_BUTTON_X none Do nothing.
Y none KEYCODE_BUTTON_Y none Do nothing.
Left (D-Pad) Right (D-Pad) AXIS_HAT_X (>0 is right) none KEYCODE_DPAD_LEFT KEYCODE_DPAD_RIGHT Move the focus left or right in the user interface.
Up (D-Pad) Down (D-Pad) AXIS_HAT_Y (>0 is down) none KEYCODE_DPAD_UP KEYCODE_DPAD_DOWN Move the focus upward or downward in the user interface.
Left Stick (Left/Right) AXIS_X (>0 is right) none KEYCODE_DPAD_LEFT KEYCODE_DPAD_RIGHT (if movement is >.5) Move the focus in the user interface in the given direction.
Left Stick (Up/Down) AXIS_Y (>0 is down) none KEYCODE_DPAD_UP KEYCODE_DPAD_DOWN (if movement is >.5) Move the focus in the user interface in the given direction.
Left Stick Press none KEYCODE_BUTTON_THUMBL none Play/Pause.
Right Stick (Left/Right) AXIS_Z (>0 is right) none none Do nothing.
Right Stick (Up/Down) AXIS_RZ (>0 is down) none none Do nothing.
Right Stick Press none KEYCODE_BUTTON_THUMBR none Play/Pause.
Play/Pause (Fire Game Controller 1st Generation Only) none KEYCODE_MEDIA_PLAY_PAUSE none Play/Pause.
Rewind (Fire Game Controller 1st Generation Only) none KEYCODE_MEDIA_REWIND none Rewind.
Fast Forward (Fire Game Controller 1st Generation Only) none KEYCODE_MEDIA_FAST_FORWARD none Fast forward.
Left Trigger (L2) AXIS_BRAKE none none Volume Up.
Left Shoulder (L1) none KEYCODE_BUTTON_L1 none Rewind.
Right Trigger (R2) AXIS_GAS none none Volume Down.
Right Shoulder (R1) none KEYCODE_BUTTON_R1 none Fast Forward.

Last updated: Oct 29, 2020