From 15edcda56ba12ad04a286f4d07f2b6fe0b1c5e38 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Sun, 5 Oct 2014 17:04:13 -0700 Subject: [PATCH] docs: migrate Android TV games page to TV training section Change-Id: Ic6be9deaac5ad2516dba288c0c3d059e3c7a6118 --- docs/html/preview/tv/games/index.jd | 186 ------------------ docs/html/training/training_toc.cs | 6 + docs/html/training/tv/games/index.jd | 282 +++++++++++++++++++++++++++ 3 files changed, 288 insertions(+), 186 deletions(-) delete mode 100644 docs/html/preview/tv/games/index.jd create mode 100644 docs/html/training/tv/games/index.jd diff --git a/docs/html/preview/tv/games/index.jd b/docs/html/preview/tv/games/index.jd deleted file mode 100644 index 68d2d8bb50960..0000000000000 --- a/docs/html/preview/tv/games/index.jd +++ /dev/null @@ -1,186 +0,0 @@ -ikpage.title=Games on TV -page.tags="controller" - -@jd:body - -
-
-

In this document

-
    -
  1. Display
    2. -
  2. Input Devices
    3. -
  3. Manifest
    4. -
  4. Google Play Game Services
    5. -
  5. Web
    6. -
-
-
- -

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.

- - -

Display

-

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.

-

Shared display

-

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.

-

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

- -

Landscape display

-

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.

- -

Input Devices

-

TVs don't have touch interfaces, so it's even more important to get your controls right and make - sure that players find them intuitive and fun to use. The separation of controller from device also -introduces some other issues to pay attention to, like keeping track of multiple players' -controllers, and handling disconnects gracefully.

-

D-pad

-

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–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 cannot tell a -player to Tap to skip.

-

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

-

Back-button behavior

-

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 > Game pause screen > Game -main screen > Android home screen.

-

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 Navigation with Back and -Up. To learn about implementation, refer to Providing Proper -Back Navigation.

-

Handling multiple controllers

-

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 on how to implement controller-number -identification, see Input Devices) on the Android developer site.

-

Handling disconnects

-

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.

-

The dialog should also offer troubleshooting tips (for example, a pop-up dialog telling the player to -"Check your Bluetooth connection"). For more information on implementing input-device support, see Supporting Game -Controllers". Specific information about Bluetooth connections is at Bluetooth.

- -

Manifest

- -

- Games are displayed in a separate row from regular apps in the launcher. Android TV uses the - android:isGame attribute to differentiate games from non-game apps. Set this value - to true in your game's app manifest, as shown in the following code example: -

- -
-<application>
-  ...
-  < meta-data android:name="isGame" android:value="true" >
-  ...
-</application>
-
- - -

Game Controllers

- -

- 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: -

- -
-  <uses-feature android:name="android.hardware.gamepad"/>
-
- -

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

- -
-  <uses-feature android:name="android.hardware.gamepad" android:required="false"/>
-
- -

For more information about manifest entries, see - App Manifest. -

- - -

Google Play Game Services

-

If your game integrates Google Play Game Services, you should keep in mind a number of -considerations pertaining to achievements, sign-on, saving games, and multiplayer play.

-

Achievements

-

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 on -Achievements and how to implement them, see Achievements in -Android.

-

Sign-in

-

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 Implementing Sign-in on -Android.

-

Saving

-

We highly recommend using Play Services Cloud Save 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 same game-save information from his or her account.

-

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 Settings screen. For -specifics on implementing Cloud Save, see Cloud Save in Android.

-

Multiplayer experience

-

A game offering a multiplayer experience must allow at least two players to enter a room. For -further information on multiplayer games in Android, see the Real-time -Multiplayer and Turn-based Multiplayer documentation on the Android developer -site.

- -

Web

-

We discourage including web browsing in games for Android TV. The television set is not well-suited for browsing, either in terms of display or control scheme.

-

Note: You can use the {@link android.webkit.WebView} class for logins to services like Google+ and -Facebook.

- diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 44e31d73314c5..12685ba39143e 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -913,6 +913,12 @@ include the action bar on devices running Android 2.1 or higher." +
  • + + Building TV Games +
    • + diff --git a/docs/html/training/tv/games/index.jd b/docs/html/training/tv/games/index.jd new file mode 100644 index 0000000000000..29b055beec318 --- /dev/null +++ b/docs/html/training/tv/games/index.jd @@ -0,0 +1,282 @@ +page.title=Building TV Games +page.tags="controller" +page.article=true + +@jd:body + +
    +
    +

    In this document

    +
      +
    1. Display
      2. +
    2. Input Devices
      3. +
    3. Manifest
      4. +
    4. Google Play Game Services
      5. +
    5. Web
      6. +
    +
    +
    + +

    + 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. +

    + + +

    Display

    +

    + 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. +

    + + +

    Shared display

    + +

    + 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. +

    + +

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

    + + + + +

    Landscape display

    + +

    + 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. +

    + + +

    Input Devices

    + +

    + TVs don't have touch interfaces, so it's even more important to get your controls right and make + sure that players find them intuitive and fun to use. The separation of controller from device + also introduces some other issues to pay attention to, like keeping track of multiple players' + controllers, and handling disconnects gracefully. +

    + +

    D-pad

    + +

    + 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–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 Tap here to skip. +

    + +

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

    + + + + +

    Back-button behavior

    + +

    + 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 > Game pause screen > Game main screen > Android + home screen. +

    + +

    + 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 Navigation with Back and Up. + To learn about implementation, refer to Providing Proper + Back Navigation. +

    + + +

    Handling multiple controllers

    + +

    + 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 on how to implement controller-number + identification, see Input + Devices. +

    + + +

    Handling disconnects

    + +

    + 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. +

    + +

    + The dialog should also offer troubleshooting tips (for example, a pop-up dialog telling the + player to "Check your Bluetooth connection"). For more information on implementing input-device + support, see Handling Controller + Actions. Specific information about Bluetooth connections is at Bluetooth. +

    + + +

    Manifest

    + +

    + The Android TV launcher home screen displays games in a separate row from regular apps. The TV + framework uses the android:isGame manifest attribute to differentiate games from + non-game apps. Set this value to true in your game's app manifest, as shown in the + following code example: +

    + +
    +<application>
+  ...
+  < meta-data android:name="isGame" android:value="true" >
+  ...
+</application>
+
    + + +

    Game Controllers

    + +

    + 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: +

    + +
    +  <uses-feature android:name="android.hardware.gamepad"/>
+
    + +

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

    + +
    +  <uses-feature android:name="android.hardware.gamepad" android:required="false"/>
+
    + +

    For more information about manifest entries, see + App Manifest. +

    + + +

    Google Play Game Services

    + +

    + If your game integrates Google Play Game Services, you should keep in mind a number of + considerations pertaining to achievements, sign-in, saving games, and multiplayer play. +

    + + +

    Achievements

    + +

    + 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 on + achievements and how to implement them, see Achievements in Android. +

    + + +

    Sign-in

    + +

    + 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 Implementing Sign-in on + Android. +

    + + +

    Saving

    + +

    + We highly recommend using Play Services Saved Games 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. +

    + +

    + 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 Settings screen. For + specifics on implementing saved games using Play Services, see Saved Games in Android. +

    + + +

    Multiplayer experience

    + +

    + A game offering a multiplayer experience must allow at least two players to enter a room. For + further information on multiplayer games in Android, see the Real-time + Multiplayer and Turn-based Multiplayer documentation on the Android developer + site. +

    + + +

    Web

    + +

    + We discourage enabling web browsing in games for Android TV. The television set is not + well-suited for browsing, either in terms of display or control scheme. +

    + +

    + Note: You can use the {@link android.webkit.WebView} class for logins to + services like Google+ and Facebook. +