Gamepad support

As you develop your games and other apps for BlackBerry 10, you have the choice of supporting several different input methods. You can (and should) support touch input using the touch screen, but you have other options as well. You might choose to support tilt and rotation (for example, for a racing game or physics-based puzzle game) or respond to gestures that users make. You could even support some of the more unusual sensors that are available on the device, such as the light sensor or gravity sensor. To learn more about the sensors that you can use, see the sensor library and the BlackBerry Platform Services (BPS) library in the API reference.

One of the most popular input methods for games is a game controller or gamepad. A controller can often be the ideal way to play certain types of games, and many users enjoy the feeling of control and the tactile experience of playing games using a controller. BlackBerry 10 provides support for controllers using the Screen Graphics Subsystem library.

If you want to get started right away and look at some example code that shows you how to handle input from controllers, see Tutorial: Create the Gamepad application.

Why provide gamepad support?

Beyond the benefits of being able to customize your game specifically for use with a controller, there are other reasons why you should consider providing gamepad support. In the BlackBerry World storefront, there's a dedicated section for gamepad-enabled apps. If your game meets the requirements for gamepad support (which are outlined below), your game appears in this section when you submit it to BlackBerry World.

Your game is also identified as gamepad-enabled using a special banner. This banner lets users know that your game is designed specifically with gamepad support in mind, which can increase the visibility and discoverability of your game and potentially increase your revenue.

Finally, letting users play your game using a gamepad can extend and adapt to users' home lives. For example, if a user connected a BlackBerry 10 device to a TV, ensuring that your game supports a gamepad could provide a comparable experience to playing a console game.

Supported gamepad controllers

BlackBerry 10 supports several popular controllers. When a supported controller is connected to a BlackBerry 10 device, input from the controller is mapped to constants in the Screen library. For example, when a user presses up on the directional pad (D-pad) or joystick, the SCREEN_DPAD_UP_GAME_BUTTON constant represents this input.

There are two types of controllers that you can connect to a BlackBerry 10 device, each with its own requirements.

Bluetooth controllers

These types of controllers connect wirelessly to a BlackBerry 10 device and are compatible with the Bluetooth Human Interface Device (HID) profile. Users can pair one of these controllers with a BlackBerry 10 device and use it as an input method for your game. To learn more about how to pair Bluetooth enabled devices with BlackBerry 10 devices, see the BlackBerry Manuals.

Users can pair these controllers with the following BlackBerry 10 devices that are running BlackBerry 10 OS version 10.1 or later:

  • BlackBerry Z30 smartphone
  • BlackBerry Z10 smartphone
  • BlackBerry Q10 smartphone
  • BlackBerry Q5 smartphone

MOGA Pro Controller

This controller closely resembles the controllers for many modern consoles. It includes a D-pad, two analog joysticks, six face buttons (plus a power button), two shoulder buttons, and two analog triggers. It also includes a flip-up holder (the MOGA Arm) to hold a smartphone or other mobile devices.

Support is also provided for the MOGA Hero Power Controller and MOGA Pro Power Controller. Learn more ›

Logo showing MOGA.

USB controllers

These types of controllers connect to a BlackBerry 10 device using a USB connection. To use these controllers, users must have a Micro USB OTG to USB 2.0 adapter. This adapter converts a standard USB 2.0 connection to the micro USB connection that's used by BlackBerry 10 devices.

Users can connect these controllers with the following BlackBerry 10 devices that are running BlackBerry 10 OS version 10.2 or later:

  • BlackBerry Z30 smartphone

Logitech gamepads

This family of controllers includes a D-pad, two analog joysticks, either seven or eight face buttons, two shoulder buttons, and two analog triggers.

Support is provided for the Logitech F310 Gamepad. Learn more ›

Support is also provided for the Logitech F710 Wireless Gamepad. This controller uses the same layout as the Logitech F310 Gamepad but includes an extra face button. It also uses a nano-receiver that connects to a USB port for wireless functionality. Learn more ›

Logo showing Logitech.

Microsoft Xbox 360 Controller

This controller is designed for use with the Xbox 360 console. It includes a D-pad, two analog joysticks, seven face buttons, two shoulder buttons, and two analog triggers. Learn more ›

Support is also provided for the Microsoft Xbox 360 Wireless Controller. This controller uses the same layout as the Microsoft Xbox 360 Controller. It also requires a Microsoft Xbox 360 Wireless Gaming Receiver for wireless functionality. Learn more ›

Logo showing Xbox.

Razer Sabertooth

This controller closely resembles the Microsoft Xbox 360 Controller. It includes a D-pad, two analog joysticks, nine face buttons, two shoulder buttons, and two analog triggers. Learn more ›

Logo showing Razer.

Unsupported gamepad controllers

There are several controllers that aren't officially supported in BlackBerry 10, but they may still work. You shouldn't design your game with these types of controllers in mind, but it can be useful to know that your users may try to use these controllers with your game.

Many gamepad-enabled games don't support these gamepads. Certain games require analog input, which these controllers don't support.


This controller includes a D-pad, six face buttons, and two shoulder buttons. It also includes a universal adjustable holder that's used to hold a smartphone or other mobile devices. Learn more ›

Logo showing Gametel.

Nintendo Wii Remote

This controller is designed for use with the Nintendo Wii system, but it can be paired with a BlackBerry 10 device. This controller includes a D-pad and six face buttons (plus a power button). Learn more ›

Logo showing Wii.

Requirements for gamepad-enabled compliance

When you develop your game, there are several things that you need to do so that your game is recognized as a compliant gamepad-enabled app. Your game must meet the following criteria:

  • Your game must include the use_gamepad permission in the bar-descriptor.xml file of your project. This permission indicates that your game fully supports the use of a gamepad and it allows your app to be featured as "gamepad-enabled" in BlackBerry World. Without this permission, your game might not receive the attention and recognition it deserves. This permission also enables certain platform capabilities that are designed for gamepad support, so it's important to include this permission when your game supports a gamepad.

    You can add this permission by selecting the Gamepad check box on the Application tab in the bar-descriptor.xml editor, or you can add it inside a <permission> element on the Source tab. To learn more about permissions and the bar-descriptor.xml file, see The bar-descriptor.xml file.

  • The entire game and all UI elements must support the use of a gamepad. In other words, users must be able to access all of your game's features (such as playing the game and navigating menus) using only the gamepad.

  • Your game must be preconfigured and ready to play with a default set of button mappings. It can be a good idea to let users change the default button mappings using a settings or options screen in your game, but when users start your game for the first time, they should be able to play it immediately using the gamepad.

Best practices

Although your game needs to meet only the criteria above to be considered gamepad-enabled, there are a few other best practices that you should strongly consider when you design your game.

Provide a button that opens your game's menu. One of the face buttons on the game controller should open the menu for your game. Many controllers include a button near the middle of the controller that's typically used for this purpose. Depending on the controller, this button might be labeled differently:

  • On the MOGA Pro Controller, Logitech gamepads, and others, this button is the Start menu button.

Regardless of the label for this button, it usually corresponds to either the SCREEN_MENU1_GAME_BUTTON or SCREEN_MENU2_GAME_BUTTON enumeration value. Your game should use these values to detect when a menu button is pressed and display the menu in response. For more information about this enumeration value, as well as values that correspond to other buttons on a controller, see Screen game controller buttons in the API reference.

In the Screen API, there are four enumeration values that correspond to menu button presses:


It's not always easy to determine which value corresponds to the menu button on a particular controller. To make sure that your game supports the widest range of controllers, consider creating only a single menu that users can open by pressing any of the menu buttons on the controller. If your game requires two menu buttons, use SCREEN_MENU2_GAME_BUTTON for your primary menu, because this value typically corresponds to the Start menu button on supported controllers. Then, use SCREEN_MENU1_GAME_BUTTON for the secondary menu; this value usually corresponds to the Select menu button.

Only certain controllers include additional menu buttons, and you can make these additional buttons available for users to remap by including an options screen in your game. If you know you're designing your game for use with a specific controller, you can use the enumeration values in the Screen API to customize your control scheme and provide the exact user experience you want.

Use the A button to select items and confirm choices, and use the B button to cancel selections and go back. If you've ever played a game using a controller, you may notice that one or two of the face buttons are the most accessible and are in easy reach of your thumb while you're holding the controller. These buttons are often referred to as the A button and B button (although they may not be labeled as such on the controller itself), and correspond to the SCREEN_A_GAME_BUTTON and SCREEN_B_GAME_BUTTON enumeration values, respectively.

Depending on the controller, the exact positions of the A button and B button might differ. However, these buttons are always mapped to enumerated values based on their relative positions on the controller. For example, consider a generic layout of four face buttons on the right side of a controller. On most controllers, the buttons are arranged in a diamond formation. The button at the bottom of the diamond always corresponds to the SCREEN_A_GAME_BUTTON value, and the button on the right always corresponds to the SCREEN_B_GAME_BUTTON value.

Diagram showing a generic set of face buttons and the mappings to the enumeration values in the Screen API.

Typically, the A button is used for positive actions, such as selecting items and confirming choices. The B button is used for negative actions, such as canceling selections and going back to the previous screen. Users who play games using other controllers have come to expect this behavior, so you can make it easier for them to start playing your game by using these mappings in your game.

You should also consider adding a visual cue or other element to make it easy for users to see what item they're selecting on the screen. For example, you could add a pointer to the screen that the user can control using the D-pad or analog joystick, and then let the user select items using the pointer and the A button. Or you could use a visual effect to add focus highlighting to the current menu item, clearly indicating which item will be selected when the user presses the A button.

Support the D-pad as an alternative to the analog joystick. Some controllers include both a D-pad and analog joysticks. Users might prefer to use one control method instead of the other, so you should provide support for both methods in your game if possible.

Consider providing keyboard controls on devices with a physical keyboard. Certain devices, such as the BlackBerry Q10 smartphone, include both a physical keyboard and a touch screen. To make your game accessible to users who don't have a controller, consider supporting keyboard input that's equivalent to controller input. For example, you could support the W, A, S, and D keys for movement, and you could use the L and O keys as the A button and X button, respectively.

For more tips on designing games for the BlackBerry Q10 smartphone, see Tips For Bringing Your BlackBerry Z10 Game To The BlackBerry Q10 on the Inside BlackBerry Developer Blog website.

Device image showing a possible mapping of gamepad controls to keyboard keys on the BlackBerry Q10 smartphone.

Provide a configuration screen in your game. Users may want to remap the controls of your game to suit their preferences. For example, a user might want to remap the B button to a button on the controller that's more comfortable or accessible. To let users play your game in the way they prefer, you should provide a configuration screen that lets users change the button mappings on the controller that they're using.

Screen shot showing an example of a controller settings screen.

Consider placing this screen in your game's menu so that users don't need to navigate back to the Settings app on the device to change button mappings. If your game supports keyboard controls, you should allow users to customize these controls right in your game as well.

Last modified: 2015-05-07

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus