Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.
Appstore Blogs

Appstore Blogs

Want the latest?

appstore topics

Recent Posts

Archive

Showing posts tagged with GameController

April 10, 2014

Jesse Freeman

Add Remote and Game Controller Support to Your Amazon Fire TV Game in ­10 Steps

One of the most exciting prospects of publishing your game on Amazon Fire TV is that you can run Android games directly on the TV. If you are already building games for Android, you can use the same codebase you currently have, and make that game playable on Amazon Fire TV.

One thing to consider is how to add support for user input from the newly announced Amazon Fire TV remote and Amazon Fire game controller. Luckily, basic controller support is already built into Android.  You can leverage the Android input device APIs and the game controller API from the Amazon Fire TV SDK to get your game ready to publish in no time. Here are the top ten things you should do in order to get your game ready for Amazon Fire TV customers.

1. Think Remote First

An Amazon Fire TV remote is included with every Amazon Fire TV. That means at the very least, your app should support simple four-way navigation and selection input from the remote itself. Let’s take a look at the button layout:

 As you can see above, the remote has a standard set of navigational buttons and a single selection button in the center. That is your player’s primary means of input.  The remote also has some additional proprietary buttons including home, back and menu buttons which respond exactly how you would expect them to on any Android device. I highly suggest referring to the Guidelines for Controller Behavior for our recommendations around supporting the Amazon Fire TV remote in your game.

Also consider that the Amazon Fire TV remote is the most common input device users of Fire TV use. By designing games that will take advantage of the remote, you increase your chances of appealing to a broader audience. While you can publish games that only use the Amazon Fire game controller to the store, keep in mind that not everyone has a game controller -- those games that leverage the remote input will have a broader audience appeal.

2. Navigating the UI with a Remote

Now that we have gone through basic remote input, let’s look at how to implement the user flow in your game’s navigation. When it comes to basic UI, I simply focus on supporting 6 core inputs you receive from the Amazon Fire TV remote:

Action

Amazon Remote Button

Amazon Game Controller Button

Other Game Controller Button

Behavior

Select/
Main Action

D-Pad Center

A

A

Select the item in focus, confirm menu options or prompts, or perform the main game action.

Cancel/Back

Back

Back

B

B

Cancel the current operation, or return to the previous screen.

 

Intercept this action to provide confirmation dialogs ("Are you sure you want to quit?")

Up

Down

Left

Right

D-Pad

D-Pad

Left Stick

D-Pad

Left Stick

Move the input focus in the appropriate direction.

 

On game controllers, the left stick should have the same behavior as the D-Pad.

It is critical that you design your UI with the remote in mind. This means putting the starting focus at the correct location in the UI. This is often the most likely object your users will interact with first. Let’s look at a simple weapons store screen in Super Resident Raver and see how the UI flow works with basic directional input events:

 

Here you can see the game places the player’s focus in the store area, at number one. From there, the player can move DOWN to buy something via the Buy button, or continue moving down to the Continue button to move to the next screen. When the player is inside the actual store area, they can move from item to item using the LEFT or RIGHT navigation buttons. If they move up from the top of the item area or down from the Continue button, the focus moves to the Quit Button and the entire UI makes a full circle.

Not only should it be clear where the player can navigate to, but the game should also make sure that UI flow never lets the player get stuck or makes the user keep back tracking to find the operations they want, or missed when moving around too quickly.

3. Capturing Remote Key Events

Android has built-in support for D-Pad key events. These function similarly on the Amazon Fire TV as they did in the past when Android phones had rocker D-Pads. Let’s walk through a quick example of how to actually implement this in your own game. Just like you would support this in any Android project, simply override the onKeyDown() method in your View and use a switch statement to test the key code value that gets passed in.

Here we have some basic logic that captures the main input events from the Amazon Fire TV remote.

@Override
public boolean onKeyDown(int keyCode, KeyEvent event){
    boolean handled = false;
 
    switch (keyCode){
        case KeyEvent.KEYCODE_DPAD_CENTER: case KeyEvent.KEYCODE_BUTTON_A:
                // ... handle selections
                handled = true;
                break;
        case KeyEvent.KEYCODE_DPAD_UP:
                // ... handle up action
                handled = true;
                break;
        case KeyEvent.KEYCODE_DPAD_RIGHT:
                // ... handle right action
                handled = true;
                break;
        case KeyEvent.KEYCODE_DPAD_DOWN:
                // ... handle down action
                handled = true;
                break;
        case KeyEvent.KEYCODE_DPAD_LEFT:
                // ... handle left action
                handled = true;
                break;
     }
     return handled || super.onKeyDown(keyCode, event);
}

Now we have the building blocks for moving through our game’s UI, and we can also use this code for simple movement in a game. In addition, you can build upon this foundation by adding support for the Amazon Fire game controller.

4. Adding Controller Support

Amazon Fire TV supports up to seven Bluetooth gamepads at the same time. Here is the key layout for the optional Amazon Fire TV game controller.

Since controller support is built into Android, if you have previously worked with adding controllers to your Android game, working with Fire TV controllers will be very familiar. Leverage the default onKeyDown() method for the controller buttons just like we used for the remote, and use onGenericMotionEvent() for capturing the joystick’s movement events. This is a key concept to understand since it means if you build your game to support navigation or in-game control via the built-in KeyEvent handler, you won’t have much additional work to do in order to capture the analog movement events from the controller that are not part of the remote.

Let’s look at the two  methods in Android for handling the Amazon Fire game controller events. The first is exactly the same as what we use for the Amazon Fire TV remote support:

@Override
public boolean onKeyDown(int keyCode, KeyEvent event){
    boolean handled = false;
 
    switch (keyCode){
        case KeyEvent.KEYCODE_BUTTON_X:
                // ... handle x button 
                handled = true;
                break;
            }
     return handled || super.onKeyDown(keyCode, event);
}

When it comes to dealing with movement input from the joystick, the second override we can make to capture those events are part of the View’s onGenericMotionEvent() method like this:

@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);
           
    return true || super.onGenericMotionEvent(event);
}

You can see the full list of controller input events here. As you may have noticed from the reference table, especially with the D-Pad controls, there are primary and secondary events. While the most granular way of getting analog movement input from a game controller is the MotionEvent, the secondary event is a useful fallback that allows you to support the Amazon Fire TV remote and Amazon game controller at the same time. Another example of this is the A button which has a secondary event of KEYCODE_DPAD_CENTER.

If your game only supports the D-Pad, take advantage of the onKeyDown() method and listen for the secondary event types while ignoring overriding onGenericMotionEvent(). Likewise you can simply listen to KEYCODE_DPAD_CENTER events ignore KEYCODE_BUTTON_A events for the controller’s A button. This ensures that your game works with the included Amazon Fire TV remote and also the optional Amazon Fire game controller. The only caveat is that if you listen to both primary and secondary events you may get multiple events saying the same thing so be prepared to handle that in your code.

5. Using the GameController API

Using the built-in event handlers is helpful for Android-based games that use of Views, some games may use a custom engine or need more direct access to the current input event on a frame by frame basis. The GameController API, part of the Amazon Fire TV’s SDK offers the following things:

  • Methods to associate game controllers with the player numbers as defined by the Amazon Fire TV.
  • Methods to query controller state at any time.
  • Input event constants specific to gamepads.
  • Behavior to enable you to process gamepad input events on a per-frame basis (that is, within a game loop).

To use the GameController API simply import the correct classes from the SDK:

import com.amazon.device.gamecontroller.GameController;
import com.amazon.device.gamecontroller.GameController.DeviceNotFoundException;
import com.amazon.device.gamecontroller.GameController.PlayerNumberNotFoundException;
import com.amazon.device.gamecontroller.GameController.NotInitializedException;

From there you will have to initialize the GameController in your onCreate() method:

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    //...
    //Initialize GameController with the context to attach to the game controller service
    GameController.init(this);
}

If you don’t initialize the GameController before accessing any of its APIs, it throws a NotInitializedException exception. Once you know it is properly initialized, you can begin using it. Here are some important APIs to get more granular data over each controller’s input state:

  • Getting GameController Objects by Player - simply use GameController.getControllerByPlayer() and supply the player number for access to that particular controller. There is a constant you can use to iterate through all the controllers called GameController.MAX_Players, which is capped at 4 by default.
  • Test for Key Down - Once your have the reference to the player’s controller you can call getKeyValue() on it and pass in a constant such as GameController.BUTTON_TRIGGER_LEFT to see if that key is pressed. It will return a true or false value.
  • Get Axis Value - Likewise you can also access the analogue stick by calling getAxisValue() on the reference to the player’s controller and supply a constant such as GameController.AXIS_STICK_LEFT_X to return a float value you can use to determine the direction it is being pushed in.
  • Testing Changes In Value - Finally you can test if a change has occurred since the last frame by calling getAxisValue() and supplying a constant such as GameController.AXIS_STICK_LEFT_Y. This will return a Boolean to help you decide if you need to apply a new change in the game.

While the above code is simply here to illustrate how this works, I suggest going through the GameController API documentation to see more sample code that you can use in your own game. Also, make sure you check out the GameController Event Constants as well.

6. Supporting Multiple Controllers

Now that we have covered the basics of the GameController API, let’s talk about multi-player games on the Amazon Fire TV. While you can connect up to seven Bluetooth game controllers to the Amazon Fire TV, only four of those controllers are assigned to player numbers in the GameController API. Getting the player’s number from the API is an easy way to manage your game’s players. You can use this by calling GameController.getPlayerNumber() and supply an Android Device ID to get the player number for that device. Likewise, there is a helper method to get you the Android Device ID if you call GameController.getDeviceID() and pass in a player number. You can iterate through all the devices by using the GameController.MAX_PLAYERS constant.

If your game supports more than four players, you can manage controllers and player numbers manually. For most games though, four is a great experience for local multi-player and you will find that the Amazon Fire TV is more than capable of keeping up with the action. While you can also do remote multi-player via standard networking APIs, keep in mind that you will have to manage that system separately from the game running on the Amazon Fire TV.

7. Handling Interruptions In Your Game

Your game should be prepared to handle interruptions. At the very least, make sure you support Android’s native onPause() and onResume() methods in your View. This is critical when the following events or situations happen:

·         Remote or Controller Drops - if you lose the connection to the main input of the device, possibly due to a battery or connection issue, you want to make sure your game is able to pause itself immediately. You should also build in some simple way to test that the controller is still active. This is critical in multi-player games; if one player drops you need to immediately pause the game.

·         User Presses the Home Button - if the user presses the home button on the controller, no event is raised, but onPause() is called. Your game exits back to the home screen.

·         User Performs a Search - once the user tries to perform a search, the event cannot be intercepted and onPause() will be called in your View.

·         User Presses the GameCircle Button - this immediately takes the user to the GameCircle dashboard while in your game.

It’s also important to capture ‘back’ events and handle exiting the game from a ‘back’ button properly. If you are on the home screen of your game and you receive a back button event, your game should prompt the user if they actually want to quit.

8. Building Controller Friendly UI

Each interactive UI element should have the following states:

  •           Enabled
  •           Disabled
  •           Highlighted
  •           Selected

These states are critical to helping your player understand where they currently are in the UI and also what action they can do. Sometimes you may need to have multiple states such as Disabled Selected in the case of the Resident Raver store scenario where it’s possible to select an item that can’t be purchased just to see what the price is.

On the same topic, it’s also important to take the Highlight state of the other UI elements into consideration. Here is a screenshot with the main UIs Selected states visible.  The selected state moves as the player moves around from main UI element to main UI element.

Finally, no matter what you end up designing, make sure there is consistency in each button state so that the player can intuitively understand where they are on the screen and what they need to do next.

9. Handling Joystick Dead Zone

Like all controllers, the joystick needs to be properly calibrated. Many things can happen that may mess-up the alignment of the joystick. At the very least, you need to account for adding a joystick dead zone to ignore joystick movements that are not large enough to cause an actual require a movement event to be recognized. Here is an example of how you can calculate this by using the GameController API.

gameController = GameController.getControllerByPlayer(1)
float x = gameController.getAxisValue(GameController.AXIS_STICK_LEFT_X);
float y = gameController.getAxisValue(GameController.AXIS_STICK_LEFT_Y);
float value = (float) Math.sqrt(x * x + y * y);

Here the formula returns a value between 0 and 1. You can choose how aggressively you want to ignore controller drift. A good place to start is somewhere above 0.25f - 0.35f. Test that the value is greater than your allowed dead zone value before applying the movement. In addition to this, I also suggest allowing the user to recalibrate their joystick in the options menu. Nothing is more frustrating than an unresponsive or “sticky” joystick control in a game.

10. Clearly Display What the Controls Are

Before any of my games start, I always show a screen with the game’s controls. While most people skip right over this, there will be a few who stop to read it in order to figure out what they will need to do in the actual game.

This also means making sure you remove any reference to touch controls, especially if you ported the game over from mobile. Also make sure you remove on screen pause buttons and sound buttons. Sound in your game should be managed via the TV’s remote. The only exception is if you have two separate user configurable volumes for the sounds effects and music which I would still keep in as long as it can be modified via the remote or controller directly.

Wrapping Up

There is a lot to consider as you begin to add support for the Amazon Fire TV remote and Amazon Fire game controllers to your game. It helps to take a step back and map out how this should all work. Having poor controls in your game will not go over well with your players, so nailing tight, responsive, and intuitive controls is critical to launching a successful game on the Amazon Fire TV. Also,look to other similar TV based gaming experiences for inspiration on how your UI and game controls should work.

For More Information

Amazon Fire TV Remote Input: Learn how to handle input from the Amazon Fire TV remote.

Amazon Fire Game Controller Input: Learn how to handle input from game controllers (both the Amazon Fire game controller and other game controllers).

GameController API: The Fire TV SDK includes a utility API for games to help you manage game controller input. This API includes the ability to associate player numbers with controllers and to manage input events on a frame-based basis.

Identifying Controllers: Users may pair up to seven Bluetooth controllers to the device at a time. Learn how to identify different controllers paired with the system and interpret input from those controllers.

Controller Behavior Guidelines: For consistency with the Fire TV user interface and across different apps we suggest you implement the guidelines in this document for controller behavior.

Controller Image Assets: If your app or game provides instructions or help screens for how to use a controller, you may freely use the controller images and button hints on this page in your app.

 

- Jesse Freeman (@jessefreeman)

 

Want the latest?

appstore topics

Recent Posts

Archive