With the upcoming release of BlackBerry Q10, there’s never been a better time to bring over your BlackBerry Z10 game and start monetizing on the new form factor. In this post, I will be talking about various porting considerations and best practices to help you get started and ensure that your game runs the best on Q10.

Let’s start off with the hardware differences:

The BlackBerry Q10 uses the same chipset and GPU as BlackBerry Z10 variant B with Qualcomm Snapdragon MSM8960 and Adreno 225. The main differences that you need to consider are aspect ratio, screen size, orientation and physical keyboard.

Aspect Ratio

If you have designed your game around the 16:9 or 15:9 aspect ratio, you will need to evaluate how to layout your game content to adapt to the 1:1 aspect ratio. There are various approaches you can take to accomplish this. You might be tempted to take the easy approach of simply scaling your game screen to 1:1 aspect ratio by using letter boxing. This approach is not recommend as it could negatively impact user experience of your game.  Since The BlackBerry Q10 has a smaller screen compared to the BlackBerry Z10, you will significantly reduce the game interaction area and waste precious screen space that could otherwise be utilized for game content such as HUD or controls. For a landscape game, one approach you could take to solve this is to use a comprise aspect ratio such as 16:11.  For the BlackBerry Z10, display more content on the sides and for the BlackBerry Q10 display more content at the top and bottom.

Similarly for a portrait game (9:15 or 9:16), you can display more content at top and bottom on the BlackBerry Z10 and more content at the sides on the BlackBerry Q10. In the below example, Bejeweled 2 displays the time progress bar at the bottom on the BlackBerry Z10 and on the side on the BlackBerry Q10.

If you are using any aspect ratio specific static assets such as backgrounds, images and splash screen, they will need to be scaled accordingly. For the standard splash screen, the BlackBerry Native SDK allows you to manage multiple device specific splash screens in the same bar-descriptor. For the BlackBerry Q10 you can add a 720×720 splash screen by editing the bar-descriptor using the IDE or a text editor. Here’s an example:

<splashScreens>
        <image>splash_1280_768.png</image>
        <image>splash_720_720.png</image>
</splashScreens>
      <asset path="assets">assets</asset>
      <asset path="icon.png">icon.png</asset>
      <asset path="/Users/pratiksapra/assets/splash_1280_768.png">splash_1280_768.png</asset>
      <asset path="/Users/pratiksapra/assets/splash_720_720.png">splash_720_720.png</asset>

Once you do this, correct splash screen will be automatically chosen depending on the device your game is launched on.

Next, if your game uses overlay controls such as virtual joysticks, UI elements and menus, you will need to reposition them as needed. The best approach is to lay them out relative to screen width and height thus making them aspect ratio independent. Below is an example of a flexible UI layout used in Bard’s Tale that works on both aspect ratios.

Screen Size

The BlackBerry Q10 features a 3.1” screen surrounded by a gesture sensitive bezel. If your game uses on-screen controls, it’s important to place them away from the bottom edge of the screen to prevent accidental swipes. An accidental swipe-up gesture during game play will thumbnail your game and cause unnecessary interruption for the user.

Optimizing your game controls is also really important. For example, If your game uses dual virtual joystick control scheme, I would recommend reducing this to just one on-screen joystick.  Due to smaller screen size, the user might end up covering most of the screen when controlling both joysticks using two fingers. We will talk about a solution to this in the later part of this post.

Orientation

The BlackBerry Z10 supports portrait as the default orientation. If you are setting the orientation in the bar-descriptor for your game, you might be wondering whether this would work on the BlackBerry Q10 without the overhead of creating a separate binary with a different bar-descriptor. To make your life easy, we have made sure that both portrait and landscape orientation settings map to portrait orientation on the BlackBerry Q10. The below example shows how your game would be oriented on the BlackBerry Z10 and the BlackBerry Q10 based on the bar-descriptor orientation setting.

Input

The BlackBerry Q10 features a physical keyboard so your game needs to be aware of this. If your game contains any buttons to activate the virtual keyboard, you should make sure they are removed or disabled when the game is running on the BlackBerry Q10. Unlike the virtual keyboard, the physical keyboard is always there and can be utilized as an input mechanism.    You can combine keyboard input with touch screen to offer an intuitive and robust input scheme for your game. For example if you want to optimize the dual virtual joystick input mechanism for the BlackBerry Q10, you can substitute one of the joysticks with keyboard input. Or if your game only requires gamepad style input you can use the keyboard as a gamepad.

Integrating keyboard input in your game is super easy. To accomplish this, in your main event loop simply handle the SCREEN_EVENT_KEYBOARD event and check for the keydown value. Here’s a code snippet on how to do this:

if (screen_get_domain() == domain) {

        screen_event_t screen_event = screen_event_get_event(event);

        int screen_val;
        screen_get_event_property_iv(screen_event, SCREEN_PROPERTY_TYPE, &screen_val);

        switch (screen_val) {
        case SCREEN_EVENT_MTOUCH_TOUCH:
//handle touch events

        case SCREEN_EVENT_KEYBOARD:
            screen_get_event_property_iv(screen_event, SCREEN_PROPERTY_KEY_FLAGS, &screen_val);

            if (screen_val & KEY_DOWN) {
                screen_get_event_property_iv(screen_event, SCREEN_PROPERTY_KEY_SYM,&screen_val);

                fprintf(stderr, "The '%c' key was pressed\n", (char)screen_val);

                switch (screen_val) {
                case KEYCODE_W:
                    // Handle Up
                    break;
                case KEYCODE_A:
                    // Handle Left
                    break;
                case KEYCODE_Z:
                    // Handle Down
                    break;
                case KEYCODE_D:
                    // Handle Right 
                    break;
                case KEYCODE_L:
                    //Button A
                    break;
                case KEYCODE_P:
                    //Button B
                    break;
                case KEYCODE_K: 
                    //Button X
                    break;
                case KEYCODE_O:
                    // Button Y
                    break;
                default:
                    break;
                }
            }
            break;
        }

Tools & Deployment

To get started, you will need the latest BlackBerry Native SDK 10.1, which includes BlackBerry Q10 support. If you are running an older version please upgrade by visiting http://developer.blackberry.com/native.

To deploy your game on BlackBerry World, follow the regular process for creating a new release in the Vendor Portal. In the supported devices screen, make sure you select BlackBerry Q10.

Known Issues

There are two known issues with earlier versions of 10.1 device software that you need to be aware of.

• Audio – In-game audio playback results in complete loss of device audio and a reboot is required to restore audio.
• Orientation – If the orientation is set to landscape in the bar-descriptor, the app splash screen and system dialogs such as volume are incorrectly oriented.

Both of these issues have been fixed in the latest 10.1 device software posted at the below link so if you are running an older build please upgrade.

https://developer.blackberry.com/blackberry10devalpha/devalpha_update.html

I hope you found the information included in this post useful.  If you have any questions or feedback please leave a comment below or reach out to me directly on Twitter @pratiksapra.

With the upcoming (and much anticipated) release of the BlackBerry Q10, Android developers can now target the first qwerty-keyboard device to be released on the BlackBerry 10 mobile computing platform. The even better news for developers is that they can also port their existing BlackBerry 10 Android apps running on the BlackBerry Z10 and BlackBerry PlayBook tablet to also include support for the BlackBerry Q10 within the same release build.

While the BlackBerry Runtime for Android Apps has a built-in screen manager which will scale the application to the screen size of the device, it’s always best to build your app specific to the device you are targeting to ensure it looks presentable to end-users.

BlackBerry Z10

For developers, the key difference between the BlackBerry PlayBook, BlackBerry Z10 and BlackBerry Q10 would be in regard to screen sizes. The all-touch BlackBerry Z10 features a resolution of 1280 x 768 (15:9) on a 4.2-inch, 356 PPI screen. Android resources are pulled in from the res/drawable-xhdpi project folder.

BlackBerry Z10 screenshot: 1280×768 background image from res/drawable-xhdpi/device.png

BlackBerry Q10

The BlackBerry Q10 boasts a 330 PPI screen but with a resolution of 720 x 720 on a 3.1” screen (1:1 aspect ratio). When targeting the BlackBerry Q10, Android developers can leverage the res/drawable-small-square project folder.

BlackBerry Q10 screenshot: 720×720 background image from res/drawable-small-square/device.png

BlackBerry PlayBook

In addition to the BlackBerry Z10 and BlackBerry Q10 models above, the BlackBerry PlayBook also supports Android apps. With a 7” screen resolution of 1024 x 600, this qualifies the BlackBerry PlayBook as an mdpi device pulling in resources from the res/drawable-mdpi project folder.

BlackBerry PlayBook screenshot: 1024 x 600 background image from res/drawable-mdpi/device.png

ADT Project Structure

Both the BlackBerry Z10 and BlackBerry Q10 support icons with a size of 114 x 114 pixels (BlackBerry PlayBook: 86 x 86 pixels) which should be placed within their respective res/drawable project folders as well. Within the same Android project you can target both of the BlackBerry 10 form factors within the same release build by following these standard Android best practices.

Single Android project structure for BlackBerry Z10, BlackBerry Q10 & BlackBerry PlayBook

You can repackage your Android APK to the BlackBerry BAR file format using the new v1.5.2 SDK, and test/debug using device simulators for the BlackBerry Z10 (BlackBerry 10 Dev Alpha B), BlackBerry Q10 (BlackBerry Dev Alpha C) and BlackBerry PlayBook  tablet available within our Android tooling page. Other pages which you should find useful would be our documentation page for the BlackBerry Plug-in for ADT and the Android API Support page.

BlackBerry World Submission

After testing your Android application and repackaging it into the BAR file format, you can submit your app to the BlackBerry World storefront via the following steps:

1. Log into the vendor portal
2. Select Manage products
3. Add a new release
4. Set ‘supported devices’ appropriately based on BlackBerry Q10, BlackBerry Z10 and/or BlackBerry PlayBook support for your app. If the app supports more than one device you can choose to select multiple devices for the same release build (BAR file). On the contrary, you can also upload specific file bundles (BARs) for each BlackBerry 10 device.

Supported BlackBerry 10 devices within the BlackBerry World vendor portal

Some of us like the big screen and some love the physical keyboard. The BlackBerry 10 platform embraces both form factors. As developers, we have a few more things to consider when targeting different form factors. The aim should be to create the best app for each type of device.

The BlackBerry 10 Native Beta SDK contains both the BlackBerry Z10 and the BlackBerry Q10 simulators and you can download them here.

In this article, we’ll describe what application developers must consider when bringing their BlackBerry Z10 applications to the BlackBerry Q10. The following topics will be discussed:

1. Differences in form factor and their impact
2. Strategy to leverage the Cascades framework and tooling to develop for both form factors effectively
3. How to deploy to BlackBerry World and what to consider

These topics are discussed in much more detail in the online documents and can be found here.

Differences in form factor and their impact

With just a bit of planning and foresight, developers can leverage the tooling, the framework and the platform to easily support both form factors.

What are some of the options to consider? Before moving forward, we need to first understand the differences.

Hardware Differences:

BlackBerry Z10

• Display screen size: 1280 x 768 pixels
• Aspect ratio: 15:9 portrait view
• Pixels per inch: 356

BlackBerry Q10:

• Display screen size: 720 x 720 pixels
• 1:1 aspect ratio
• 330 PPI

There are certain things that the Cascades framework will provide when developing for both form factors.

Items handled by Cascades:

• Core component scaling (including the action items, action bar and menus)
• Asset scaling (see section 2.4 for more details)
• Dock and Stack Layouts
• Theme switching (bright and light)
• Alphabetic scroll bar
• Non-sticky title
• Navigation shortcuts
• Keyboard over shortcut API

As mentioned before, the framework will take the app a long way towards the BlackBerry Q10 form factor, but it won’t handle everything. In particular, developers should consider the following items.

Items handled by the apps:

• Addition/removal of static title bars
• Simplification of title bars or smaller assets
• Custom component scaling
• Background bitmaps
• Absolute layouts (If you use them, you have work to do here)
• Selection of theme
• App specific shortcuts
• Re-layout of view (in some cases you need to re-design the layout for the best User Experience on a smaller screen)

More information on screen size implications can be found here.

Screen Theme (Bright vs. Dark and what it means)

By default the BlackBerry Z10 Cascades applications uses the bright theme. The BlackBerry Q10 device on the other hand, prefers the dark theme due to the OLED screen. The framework will automatically select the theme for each device. However, if you have static assets, you’ll need to provide the dark theme alternatives using the static asset selector (see section 2.3) or ensure that your assets convert well to the dark theme. You should also reference the Designing for OLED displays document in the UX guidelines.

EXTRA BlackBerry Q10 only: Keyboard Shortcuts and Key Listeners

Physical keyboard BlackBerry users are used to a certain standard of having convenient shortcuts provided.

There are certain system shortcuts that come pre-built in the framework and developers can attach these to their applications.

Developers are also free to create their own shortcuts that make sense for their particular application.

All about Keyboard Shortcuts and a sample can be found here.

Listeners can also be used to listen to any key pressed on the keyboard. More information on this can be found here.

Strategy to leverage the Cascades framework and tooling to develop for both form factors effectively

Since the full touch device is the first launched device, most developers will be bringing their full touch applications to the physical keyboard devices.

Say you have your full touch BlackBerry 10 application developed in Cascades and choose to ignore the physical keyboard device in your development. What would that mean?

The Cascades framework was designed with both form factors in mind, so most likely your application will more or less run. The Cascades framework will layout the controls for you, the graphics will scale accordingly.

However, such an app will not provide the best user experience on the QWERTY form factor.

Since we strive for the best overall user experience, as developers we need to follow some best practices.

What are some of the key points to consider when developing?

1. Embrace relative layouts so that the framework can help you with arranging your components relative to the boundary of the screen and regardless of the device screen size.
2. Avoid on-screen clutter by using margins and space quotas. By using space quotas effectively you can designate the proportion of space that each component uses relative to another. This creates a layout that adapts to a different screen resolution.
3. Leverage the Momentics IDE asset selector feature to dynamically select different assets for different screen resolutions. This includes both QML files and images. This approach will allow you to create a single binary that dynamically adapts to different screen sizes by choosing the correct asset. You can select assets based on different screen size as well as a different theme!
4. For more info on this approach see: Assets/Tooling/Project setup
5. Create images that scale uniformly. The technique of nine-slicing lets you create such images. This method will ensure that should you re-use the same image on different screen resolutions, these images will scale properly and without distortions.
6. In some cases, should you choose to create a separate binary for the BlackBerry Q10 device you can do so. In this case, you can specify the necessary layouts, images and assets only for that device. Should you choose to do so, you’d be maintaining two separate builds and must deploy them separately (see Section #3).

Here is a graphical summary of the points discussed:

Bonus: Please be sure to check that your loading screen scales properly. If it does not, you’ll need to provide a scalable or different image.

Deploying to BlackBerry World

Deploying to BlackBerry World for the BlackBerry Q10 is quite easy. Here are the steps you’ll need to follow:

1. Log into vendor portal
2. Go to Manage products
3. Add a new release
4. Set ‘supported devices’ to BlackBerry Q10. If the .bar supports more you can do that as well, or also have different file bundles for different devices

Regarding item #4. Here is the guiding principle.

If your app contains one binary (BAR) file for both the BlackBerry Q10 and BlackBerry Z10 and you followed the practices above and selected to support both devices with one build, then all you need to do is have your application support both devices in the table below.

If however, you’ve created a separate new build that’s targeting the BlackBerry Q10 only. You’ll need to make sure that the new BAR file you’ve submitted only selects the BlackBerry Q10 device. If you have any questions, let us know in the comments!

The excitement of last week’s launch of BlackBerry 10 still hasn’t worn off around these parts. We feel it in the air. We are at the brink of something new in the world of mobile computing. As you know, we here at BlackBerry have been working tirelessly to get to this point, the global launch of BlackBerry 10.  But the launch of BlackBerry 10 is just the beginning.  There is still so much more to do, and the team here is already starting on the next steps.  The first of these is adding support for the BlackBerry Q10 and its physical keyboard into our BlackBerry WebWorks SDK and the Ripple Emulator.

Luckily, from a WebWorks perspective, everything you need is already on the BlackBerry 10 operating system.  The two major areas where the BlackBerry Q10 and the BlackBerry Z10 are the physical keyboard and the screen size.

For the physical keyboard, the system takes care of handling the input for you and piping it into your app just as if it came from the virtual keyboard on a BlackBerry Z10.  However, the traditional BlackBerry user is also very used to having actions be triggerable from the keyboard when not actually performing text input.  Think of clicking ‘r’ in the Inbox on a BlackBerry OS device in order to trigger a Reply action.  If you wish to provide your user keyboard shortcuts within your application, you can use the standard HTML5 onkeypress event.  Set a listener on the appropriate HTML elements, process the key stroke and trigger the action.

In terms of the screen size, HTML5 standard approaches in responsive design are more than adequate to allow you to layout the UI of your application appropriately in different screen resolutions.  The major difference we have from a system perspective is related to some key User experience decisions made for the smaller screen size, and that the WebWorks platform handles for you.  For example, the context menu on the BlackBerry Z10 automatically triggers an overflow UI if there are more than seven items in the menu.  For the BlackBerry Q10 it will do this for four or more items.  The BlackBerry Q10, due to its OLED display, also uses true black in some UI elements to be more efficient.  These are just some examples, but I want to reiterate that all of this is supported out of the box by the web platform that is part of the latest BlackBerry 10 OS builds, so you will not actually see a BlackBerry WebWorks SDK refresh for BlackBerry Q10 support. There is a BlackBerry WebWorks refresh in the works to add a few new APIs, but we’ll talk about that soon in a different post.

What you will find is a refresh to Ripple to allow you to select the BlackBerry Z10 or the BlackBerry Q10 for emulation when targeting the BlackBerry 10 platform.  This will allow you to emulate and test your layout against the different screen sizes of the devices and ensure your design will work for both devices.  If you already have Ripple installed, you should see an update come in automatically.  If you don’t already have Ripple you can get it here.  Enjoy!