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.

We’re just two months away from BlackBerry Live 2013 and we’re psyched that BlackBerry Live and BlackBerry Jam Americas are combining like the Wonder Twins to bring you the biggest BlackBerry event ever.  I’ve had the privilege to attend BlackBerry Live (well, BlackBerry World, and before that WES) in the past – and it has always been amazing for me to meet our carrier, retailer, and enterprise partners and see how they work with BlackBerry. With the addition of you, our developer community, the circle is complete.

Today, we’re sharing the first group of sessions for BlackBerry Jam Americas at BlackBerry Live. The BlackBerry Z10 and BlackBerry Q10 will both be available in multiple markets around the globe – and we’ve tailored the content to help you make the most out of your development investment in BlackBerry 10 and continue to show you our commitment of being the leader in mobile computing.

View the developer conference session catalog. Here’s a quick sample –

JAM03 - Built for BlackBerry: Performance tuning for Cascades Applications
One of the key criteria for Built for BlackBerry recognition is performance. An application must be smooth in function, fast in response, and display little or no lag time. In this session, we’ll focus on tuning your Cascades application to get the best possible performance. We’ll look at the 10 most common performance mistakes and how to avoid them.

JAM08 - Built for BlackBerry: How to Go from Rejected to Approved
Built for BlackBerry is a set of criteria that identify applications that are taking full advantage of the BlackBerry 10 system and providing the user an enhanced productivity or entertainment experience. Not all applications or games that are submitted to Built for BlackBerry receive approval. Currently, only 10% of the applications that are submitted make the grade. In this session, we’ll look at real world examples of applications or games that initially fell short for Built for BlackBerry approval but with some changes and additions, made it over the bar.

JAM05 - Built for BlackBerry: System Integration with Payment Services
To qualify for Built for BlackBerry, your application must integrate with a BlackBerry 10 service. In today’s application and game market, one of the common monetization strategies is to provide the core application or game for free then allow items the user can purchase within the application or game. BlackBerry 10 offers Payment Services to enable in app purchases. In this session, we’ll look at an overview of Payment Services integration and work through examples for both WebWorks and Cascades.

More sessions will be added over the next few weeks – so now is the time to register for BlackBerry Live 2013. Head on over to the site and see the options today!

Register by March 22 to take advantage of the Early Bird Rate and gain access to all the valuable content the conference has to offer. Plus, if you attended a BlackBerry conference in the past year, you could save an additional $150 USD with the Alumni Discount.

Hurry, the Early Bird Offer ends March 22, 2013.

Now that the dust is settling from this weekend’s Last Chance Port-A-Thon, we’re excited to announce that over 19,000 applications were submitted to BlackBerry World over the weekend. This continues to show an overwhelming level of commitment from developers to the BlackBerry 10 platform.

We’ve heard your questions and concerns about the Built for BlackBerry deadline. The fact is, the volume of apps being submitted for review and entry into the program has been remarkable. Due to that large volume of apps, we are extending the deadline:

• Apps that have been submitted on or before 8pm EST on January 21^st,2013 may qualify for the $10k Developer Commitment if the developer agrees to the official terms and conditions and passes Built for BlackBerry testing.
• Developers may apply for Built for BlackBerry review and the $10k Developer Commitment offer in the BlackBerry World Vendor Portal by 8pm ET Feb 18^th
• The qualifying sale dates for the 10k Commitment is 12:01am ET, March 4 2013 to 11:59pm ET, March 3 2014

Don’t forget to review the Built for BlackBerry criteria before you apply and just a friendly reminder that BlackBerry App Generator and Android apps do not qualify for Built for BlackBerry or the $10k Commitment.

The BlackBerry 10 Community Port-A-Thon will start on noon ET January 11, 2013 and run for 36 hours.  This is also going to be a virtual event, so it is up to you to decide where you would like to join us from.

Get Rewarded

The more you port and build the greater your rewards*:

• Port  one (1) – five (5) approved apps – $100 per eligible app –to  a maximum of 20 paid applications per Vendor
• Port five (5) – ten (10) approved apps – THE FIRST TWO HUNDRED (200) QUALIFIED PARTICIPANTS receive one (1) BlackBerry Dev Alpha Device plus $100
• Port ten (10) or more approved apps -  THE FIRST TEN (10) QUALIFIED PARTICIPANTS one (1) paid trip to BlackBerry Jam Europe to celebrate  the launch of BlackBerry 10 with us plus a Dev Alpha Device as well as $100!!!
• Additionally for those that did not receive a BlackBerry Dev Alpha, or Trip to BlackBerry Jam Europe, we will be conducting a random draw for one hundred (100) BlackBerry 10 Dev Alphas and ten (10) trips to BlackBerry Jam Europe.  All those who meet the criteria for a Dev Alpha  Device or the Trip but were not one of the firs 200 or 10 , respectively, to qualify, are eligible for the respective draws.

Get Ready to Port

Take advantage of the tips below to get a head start before you join the event.

Here’s what you need to get prepared ahead of time.

1. Register as a Vendor at BlackBerry World if you haven’t already.
2. Request signature keys. Make sure that you select for BlackBerry® PlayBook™ OS and BlackBerry 10 and higher. Downloading in advance is strongly recommended as the time involved to do so could prevent you from earning rewards.
3. Load up your laptop BlackBerry tools and plug-ins. Make sure you have your full source code file readily available too.
4. Make sure you have your images and icons ready to go.

Register

Submit your apps into BlackBerry World before BlackBerry 10 launches. Register for the Community Port-A-Thon for BlackBerry 10 today!

Have Questions? See our FAQ.

* A total of $500,000USD is available for distribution. To qualify for a Reward, you must register on the website at http://developer.blackberry.com/offers/communityportathon and submit your App into the BlackBerry World Vendor Portal between 12:00:01 pm on January 11, 2013 and 11:59:59pm ET on January 12, 2013. Any apps submitted outside this time frame are not eligible for this Reward program. Only those apps that have been approved through BlackBerry World and RIM will be considered towards a Reward. No purchase necessary to be eligible for the draw.  The odds of winning the draw depend on the number of eligible Vendors entered.  Skill-testing question applies to Canadian residents.  Limit one (1) Dev Alpha Device and one (1) Trip per person. Cash rewards limited to 20 per Vendor regardless of reward category.    See the Official Terms and Conditions for complete details.

Ant has been around a long time so it really needs no introduction. Inspiration for this build script came initially from Addy Osmani’s blog on creating a build script for web applications, and later from reviewing the HTML5 Boilerplate’s Ant-Build-Script project. This script is much more specific to BlackBerry WebWorks development and should serve as a great starting point for any developer wanting to introduce a build script to their WebWorks development cycle.

Ant scripts are great for a lot of reasons. Designed for build systems, with simple XML syntax, it’s been around long enough to get a lot of support from IDE’s and to have extensions and tutorials written for it. While there are newer build script tools available, Ant is a good, reliable tool. The IDE integration will be popular with many developers as well, since Eclipse and it’s variants work well with Ant. My current favorite is Sublime Text 2 which has superb build script integration: when set to Ant, pressing ctrl-b will run the default build in the current file’s directory. Besides working with your IDE, build scripts can do all sorts of repeatable operations for you, which can automate routine steps, saving time and maintaining consistency between builds. An obvious requirement for teams, but still a real time saver when working solo.

When I set out to create this script, I wanted something with a wide range of flexibility but also something simple that I could just drop into a project and have it build. I also wanted to be able to update some settings in one place when something changed but support project specific build targets. Lastly, I thought it would be pretty cool to do some Lint checking and code compression at the same time. The result is up here on Github and takes a two part approach. There is a main set of targets and associated tools that goes in one spot and a build.xml file that can be dropped into a WebWorks project. The main file you will setup once and only change when new SDKs are installed. The project file you will put a copy in each project and define a few simple properties to customize the build. Full instructions are included in the Github Readme.

Give it a try today and see what you think. Once you’ve done so, I’d really like to see some forks and pull requests that add additional targets. What are the tools that you would like to see included?

[YouTube link for mobile viewing]

“Patrick: ‘I’ve asked you about porting to other platforms, have you had this kind of success on other platforms?’

Danny: ‘I can say in complete honesty definitely not. We’ve never been able to get going on a brand new platform with zero lines of code as quickly as we were on BB10.’”

[ YouTube link for mobile viewing ]