android_frameworks_base/docs/html/training/tv/games/index.jd

page.title=Building TV Games
page.tags=tv, games, controller
helpoutsWidget=true
page.image=images/games/game-controller-buttons_2x_crop.png
page.metaDescription=How to bring your games to Android TV, including recommendations and examples.
page.article=true

@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>In this document</h2>
  <ol>
    <li><a href="#display">Display</a></li>
    <li><a href="#control">Input Devices</a></li>
    <li><a href="#manifest">Manifest</a></li>
    <li><a href="#gpgs">Google Play Game Services</a></li>
    <li><a href="#web">Web</a></li>
  </ol>
</div>
</div>

<p>
  The television screen presents a number of considerations that may be new to mobile game
  developers. These areas include its large size, its control scheme, and the fact that all players
  are viewing it simultaneously.
</p>


<h2 id="display">Display</h2>
<p>
  The two main things to keep in mind when developing games for the TV screen are its nature as a
  shared display and the need to design your game for a landscape orientation.
</p>


<h3 id="shared-display">Consider the shared display</h3>

<p>
  A living-room TV poses design challenges for multiplayer games, in that all players can see
  everything. This issue is especially relevant to games (such as card games or strategy games)
  that rely on each player’s possession of hidden information.
</p>

<p>
  Some mechanisms you can implement to address the problem of one player’s eavesdropping on
  another’s information are:
</p>

<ul>
  <li>A blinder on the screen to help conceal information. For example, in a turn-based game like a
    word or card game, one player at a time might view the display. When the player finishes a move,
    the game allows him or her to cover the screen with a blinder that blocks anyone from viewing
    secret information. When the next player begins a turn, the blinder opens to reveal his or her
    own information.
  </li>
  <li>A companion app, running on a phone or tablet, can enable a player to conceal information by
    serving as a second screen.
  </li>
</ul>


<h3 id="landscape-display">Support landscape display</h3>

<p>
  A TV is always sideways: You can’t turn it, and there is no portrait orientation. Always design
  your TV games to be displayed in landscape mode.
</p>


<h2 id="control">Input Devices</h2>

<p>
  TVs don't have touch interfaces, so it's even more important to get your controls right and make
  sure players find them intuitive and fun to use. Handling controllers
  also introduces some other issues to pay attention to, like keeping track of multiple
  controllers, and handling disconnects gracefully.
</p>

<h3 id="d-pad">Support D-pad controls</h3>

<p>
  Plan your control scheme around a directional pad (D-pad) control, since this control set is the
  default for Android TV devices. The player needs to be able to use a D-Pad in all aspects of the
  game&mdash;not just controlling core gameplay, but also navigating menus and ads. For this reason, you
  should also ensure that your Android TV game does not refer to a touch interface. For example, an
  Android TV game should not tell a player to "<em>Tap</em> here to continue."
</p>

<p>
  How you shape the player's interaction with the controller can be key to achieving a great user
  experience:
</p>

<ul>
  <li>
    <strong>Communicate Controller Requirements up Front</strong>. Use your Google Play description
    to communicate to the player any expectations about controllers. If a game is better suited to
    a gamepad with a joystick than one with only a D-pad, make this fact clear. A player who uses
    an ill-suited controller for a game is likely to have a subpar experience and penalize your
    game in the ratings.
  </li>
  <li>
    <strong>Use Consistent Button Mapping</strong>. Intuitive and flexible button mapping is key
    to a good user experience. For example, you should adhere to accepted customs by using the A button
    to <em>Accept</em>, and the B button to <em>Cancel</em>. You can also offer flexibility
    in the form of remappability. For more information about button mapping, see <a href=
    "http://developer.android.com/training/game-controllers/controller-input.html">Handling
    Controller Actions</a>.
  </li>
  <li>
    <strong>Detect Controller Capabilities and Adjust Accordingly</strong>. Query the controller
    about its capabilities in order to optimize the match between controller and game. For example,
    you may intend for a player to steer an object by waving the controller in the air. If a
    player's controller lacks accelerometer and gyroscope hardware, however, waving will not work.
    So, your game should query the controller and if motion detection is not
    supported, switch over to an alternative, available control scheme. For more information
    about querying controller capabilities, see <a href=
    "http://developer.android.com/training/game-controllers/compatibility.html">Supporting
    Controllers Across Android Versions</a>.
  </li>
</ul>


<h3 id="back-button">Provide appropriate Back-button behavior</h3>

<p>
  The Back button should never act as a toggle. For example, do not use it to both open and close a
  menu. It should only navigate backward, breadcrumb-style, through the previous screens the player
  has been on, for example: Game play &gt; Game pause screen &gt; Game main screen &gt; Android
  home screen.
</p>

<p>
  Since the Back button should only perform linear (backward) navigation, you may use the back
  button to leave an in-game menu (opened by a different button) and return to gameplay. For more
  information about design for navigation, see <a href=
  "http://developer.android.com/design/patterns/navigation.html">Navigation with Back and Up</a>.
  To learn about implementation, refer to <a href=
  "http://developer.android.com/training/implementing-navigation/temporal.html">Providing Proper
  Back Navigation</a>.
</p>


<h3 id="button-independence">Use appropriate buttons</h3>

<p>Not all game controllers provide Start, Search, or Menu buttons. Be sure your UI does not depend
upon the use of these buttons.</p>

<h3 id="multiple-controllers">Handle multiple controllers</h3>

<p>
  When multiple players are playing a game, each with his or her own controller, it is important to
  map each player-controller pair. For information about how to implement controller-number
  identification, see <a href=
  "http://developer.android.com/reference/android/view/InputDevice.html#getControllerNumber">Input
  Devices</a>.
</p>


<h3 id="handle-disconnect">Handle controller disconnects</h3>

<p>
  When a controller is disconnected in the middle of gameplay, the game should pause, and a dialog
  should appear prompting the disconnected player to reconnect his or her controller.
</p>

<p>
  The dialog should also offer troubleshooting tips (for example, a pop-up dialog telling the
  player to "Check your Bluetooth connection"). For more information about implementing input-device
  support, see <a href=
  "http://developer.android.com/training/game-controllers/controller-input.html">Handling Controller
  Actions</a>. Specific information about Bluetooth connections is at <a href=
  "http://developer.android.com/guide/topics/connectivity/bluetooth.html">Bluetooth</a>.
</p>


<h3 id="ControllerHelp">Show controller instructions</h3>

<p>If your game provides visual game control instructions, the
controller image should be free of branding and include only <a
href="{@docRoot}training/game-controllers/controller-input.html#button"
>buttons compatible with Android</a>.</p>

<p>For sample images of an Android-compatible controller, download the
<a href="http://storage.googleapis.com/androiddevelopers/design/android_tv_gamepad_template-2014-10.zip"
>Android TV Gamepad Template (ZIP)</a>.
It includes a white controller on black background and a black controller on white background
(shown in figure 1), as a PNG file and an Adobe&reg; Illustrator&reg; file.</p>

<img itemprop="image" src="{@docRoot}images/games/game-controller-buttons_2x.png" width="700"
     srcset="{@docRoot}images/games/game-controller-buttons_2x.png 2x,
             {@docRoot}images/games/game-controller-buttons.png 1x" />
<p class="img-caption"><b>Figure 1.</b> Example controller instructions using the
<a href="http://storage.googleapis.com/androiddevelopers/design/android_tv_gamepad_template-2014-10.zip"
>Android TV Gamepad Template (ZIP)</a>.




<h2 id="manifest">Manifest</h2>

<p>There are a some special things games should include in the Android manifest.</p>

<h3 id="Launcher">Show your game on the home screen</h3>
<p>
  The Android TV home screen displays games in a separate row from regular apps.
  To make your game appear in the list of games, set the
  <a href="{@docRoot}guide/topics/manifest/application-element.html#isGame">
  {@code android:isGame}</a> attribute to <code>"true"</code> in your app manifest's
  <a href="{@docRoot}guide/topics/manifest/application-element.html"><code>&lt;application&gt;</code>
  </a> tag. For example:
</p>

<pre class="fragment">
&lt;application
    ...
    android:isGame="true"
    ...
&gt;
</pre>


<h3 id="gamepad">Declare support for game controllers</h3>

<p>
  Games controllers may not be available or active for users of a TV device. In order to properly
  inform users that your game requires (or just supports) a game controller, you must include
  entries in the app manifest. If your game requires a game controller, you must include the
  following entry in your app manifest:
</p>

<pre>
  &lt;uses-feature android:name="android.hardware.gamepad"/&gt;
</pre>

<p>
  If your game uses, but does not require, a game controller, include the following feature
  entry in your app manifest:
</p>

<pre>
  &lt;uses-feature android:name="android.hardware.gamepad" android:required="false"/&gt;
</pre>

<p>For more information about manifest entries, see
  <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">App Manifest</a>.
</p>


<h2 id="gpgs">Google Play Game Services</h2>

<p>
  If your game integrates <a
  href="https://developers.google.com/games/services/">Google Play Game services</a>,
  you should keep in mind a number of
  considerations pertaining to achievements, sign-in, saving games, and multiplayer play.
</p>


<h3 id="achievements">Achievements</h3>

<p>
  Your game should include at least five (earnable) achievements. Only a user controlling gameplay
  from a supported input device should be able to earn achievements. For more information about
  achievements and how to implement them, see <a href=
  "https://developers.google.com/games/services/android/achievements">Achievements in Android</a>.
</p>


<h3 id="sign-in">Sign-in</h3>

<p>
  Your game should attempt to sign the user in on launch. If the player declines sign-in several
  times in a row, your game should stop asking. Learn more about sign-in at <a href=
  "https://developers.google.com/games/services/training/signin">Implementing Sign-in on
  Android</a>.
</p>


<h3 id="saving">Saving</h3>

<p>
  Use Google Play Services <a href=
  "https://developers.google.com/games/services/common/concepts/savedgames">Saved Games</a> to store
  your game save. Your game should bind game saves to a specific Google account, so as to be
  uniquely identifiable even across devices: Whether the player is using a handset or a TV, the
  game should be able to pull the game-save information from the same user account.
</p>

<p>
  You should also provide an option in your game's UI to allow the player to delete locally and
  cloud-stored data. You might put the option in the game's <code>Settings</code> screen. For
  specifics on implementing saved games using Play Services, see <a href=
  "https://developers.google.com/games/services/android/savedgames">Saved Games in Android</a>.
</p>


<h3 id="multiplayer-ux">Multiplayer experience</h3>

<p>
  A game offering a multiplayer experience must allow at least two players to enter a room. For
  further information about multiplayer games in Android, see the <a href=
  "https://developers.google.com/games/services/android/realtimeMultiplayer">Real-time
  Multiplayer</a> and <a href="">Turn-based Multiplayer</a> documentation on the Android developer
  site.
</p>

<h3 id="exit">Exit</h3>

<p>Provide a consistent and obvious UI element that lets the user exit the game gracefully. This
element should be accessible with the D-pad navigation buttons. Do this instead of relying on the
Home button to provide an exit, as that is not consistent nor reliable across different controllers.</p>


<h2 id="web">Web</h2>

<p>
  Do not enable web browsing in games for Android TV. Android TV does not support a web browser.
</p>

<p class="note">
  <strong>Note:</strong> You can use the {@link android.webkit.WebView} class for logins to
  services like Google+ and Facebook.
</p>

<h2 id="networking">Networking</h2>

<p>Games frequently need greater bandwidth to provide optimum performance, and many users prefer
ethernet to WiFi to provide that performance. Your app should check for both WiFi and ethernet
connections. If your app is for TV only, you do not need to check for 3G/LTE service as you would
for a mobile app.</p>