How to develop gaming apps using the Xperia™ PLAY gamepad

Before developers begin designing mobile games for Xperia™ PLAY, it is important to understand the different hardware keys for the device. The following information provides an overview of the hardware keys, along with a set of high-level gamepad recommendations and guidelines for game developers. This guidance may be help to developers are not familiar with developing mobile games that use hardware keys. This article also includes the key code and scancode mapping for the Xperia™ PLAY, which provides a handy reference for developing games according to standard hardware key functionality. The Xperia™ PLAY brings a new level of smartphone with the ultimate gaming experience, and these guidelines will ensure that developers create hardware-based gamepad functionality that complements soft key functionality, and overall consistent game play for all Xperia PLAY mobile games.

Hardware keys overview

The following illustration shows the different hardware keys for the Xperia™ PLAY.

Key codes and scancodes

Any key press on a mobile device is described by a sequence of key events. Each key event is generally accompanied by a key code (getKeyCode()) and a scancode (getScanCode()). Key codes are defined in the KeyEvent class. Scancode constants are raw, device-specific codes obtained by the OS.

The following table provides a list of Xperia™ PLAY hardware keys and their corresponding key code values, Android™ key codes, and the recommended action that the key should perform.

Table 1. Xperia PLAY key codes

Hardware key	Key code value	Android key code constant	Recommended Action
key	84	KEYCODE_SEARCH	Search or browse.
key	82	KEYCODE_MENU	Open menu.
key			Home.
key	4	KEYCODE_BACK	Go back or return to previous screen/menu.
button	23	KEYCODE_DPAD_CENTER	In menus, should confirm. Function is game specific.
button	4	KEYCODE_BACK	In menus, should go back. Function is game specific.
button	99	KEYCODE_BUTTON_X	Function is game specific.
button	100	KEYCODE_BUTTON_Y	Function is game specific.
button	19	KEYCODE_DPAD_UP	Function is game specific.
button	20	KEYCODE_DPAD_DOWN	Function is game specific.
button	21	KEYCODE_DPAD_LEFT	Function is game specific.
button	22	KEYCODE_DPAD_RIGHT	Function is game specific.
button	82	KEYCODE_MENU	Open menu.
Select button	109	KEYCODE_BUTTON_SELECT	Select.
Start button	108	KEYCODE_BUTTON_START	Start.
L button	102	KEYCODE_BUTTON_L1	Left trigger. Improves gaming experience. Function is game specific.
R button	103	KEYCODE_BUTTON_R1	Right trigger. Improves gaming experience. Function is game specific.
Volume up	24	KEYCODE_VOLUME_UP	Increse game volume
Volume down	25	KEYCODE_VOLUME_DOWN	Decrease game volume.
Touchpad			Information on how to use the touchpad can be found in the Touchpad article.

More information about Android key codes can be found in the description of the android.view.KeyEvent class at http://developer.android.com/reference/android/view/KeyEvent.html.

X and Circle button keycodes swapped in select regions

Depending on your region, the X button and Circle button on your Xperia™ PLAY may be switched. Use the method below to detect whether or not the X button and Circle button have been swapped.

The default behavior (the method below returns false) is for the X button to send KEYCODE_DPAD_CENTER and the Circle  button to send ALT + KEYCODE_BACK. 

The swapped behavior (the method below returns true) is for the Circle button to send KEYCODE_DPAD_CENTER and the X button to send ALT + KEYCODE_BACK.

Method:

The keycode swap can be detected by checking the Key Character Map for the display label of KEYCODE_DPAD_CENTER.  There is a simple method, shown in the code example below, to detect if the display label of the KEYCODE_DPAD_CENTER is the WHITE_CIRCLE (hex 0x25CB) and therefore the change has been made. This check is important so that in the localization text, the correct button can be referenced for instructions and tutorials, and so that the buttons function as designed in gameplay.

    private final char DEFAULT_O_BUTTON_LABEL = 0x25CB;   //hex for WHITE_CIRCLE

    private boolean isXOkeysSwapped() {
        boolean flag = false;
        int[] ids = InputDevice.getDeviceIds();

        for (int i= 0; ids != null && i<ids.length; i++) {
            KeyCharacterMap kcm = KeyCharacterMap.load(ids[i]);
            if ( kcm != null && DEFAULT_O_BUTTON_LABEL ==
                   kcm.getDisplayLabel(KeyEvent.KEYCODE_DPAD_CENTER) ) {
                flag = true;
                break;
            }
        }
        return flag;
    }

As you may or may not know, the Playstation’s X and O buttons have opposite actions depending on the region.  In Japan for example, O is select and X is back; however, in the United States, X is select and O is back.  To adhere to user expectations, the Xperia™ PLAY will follow this trend and swap the keycodes that are reported by the X and O keys in regions where this is appropriate, based on the Playstation’s behavior in that region.

You can download a zip file of the full code example here.

Differentiating between the Circle button and Back key

In order to differentiate between the Circle button and the Back key, which use the same key code, the developer needs to check whether or not the ALT button is enabled or disabled. When the Circle button is pressed, ALT is enabled; when the Back key is pressed, ALT is disabled.

Here is the code snippet:

public boolean onKeyDown(int keyCode, KeyEvent event) {if (keyCode == KeyEvent.KEYCODE_BACK) { // Remember both circle and back key provide same keycode
if(!event.isAltPressed()) { //check alt to differentiate between BACK and CIRCLE

//Do something (May be quit the game)
Log.i(“Back Key pressed”, “You pressed BACK key”);

}else {

//Do something else in the game
Log.i(“Circle Key pressed”, “You pressed CIRCLE key”);

}

return false;

}

return super.onKeyDown(keyCode, event);

}

More information

• Read more and download a tutorial on how to access the touch pad on the Xperia™ PLAY>>>.
• Download the full code example for checking for X and O button swap in Xperia™ PLAY.
• Read more about the Xperia™ PLAY on Sony Ericsson Developer World>>>.
• Download the Android NDK>>>.
• Download the NativeActivity class>>>.
• Learn more about the Xperia™ PLAY on consumer website.
• Check out the full list of Xperia™ game developer recommendations.