Porting Your Existing GameMaker Application to BlackBerry 10

by Retired on ‎05-16-2013 10:20 AM (5,972 Views)

Overview

 

For the purpose of this guide, we will take a look at the steps involved in exporting, packaging, and deploying one of the GameMaker: Studio demo applications, specifically Angry Cats: Space.

 

Untitled.png

 

The basic steps involved include:

  • Environment setup (one-time.)
  • GameMaker: Studio export to HTML5.
  • Adding a config.xml file.
  • Packaging/signing your HTML5 resources into a BlackBerry® 10 (BAR) file.

 

Prerequisites

 

GameMaker: Studio 1.1.964+ with HTML5 Module

At the time of writing this guide, we are using the noted GameMaker: Studio version. However, as long as you have the HTML5 module, this guide should still be applicable. The default, free release of this software does not include the HTML5 module and a license must be purchased to unlock this functionality. For more information, including system requirements, please visit the GameMaker website.

 

BlackBerry 10 WebWorks SDK (full documentation)

The BlackBerry® 10 WebWorks™ SDK provides a set of command-line tools to package an HTML5 project into a BlackBerry 10 application (BAR file), perform code signing, and deploy BAR files to BlackBerry 10 devices.

 

This SDK also provides JavaScript® APIs to leverage native, BlackBerry 10 functionality and can be downloaded here.

 

BlackBerry 10 Code Signing Keys (full documentation)

In order to deploy a BAR file to a BlackBerry 10 device, it must be signed with your own developer code signing keys. These keys validate that the application has not been modified since the time of packaging and adds a layer of security for both the developer and end users.

 

BlackBerry 10 code signing keys are free and can be requested here. There are a few important fields:

  • Ensure you select For BlackBerry® PlayBook™ OS and BlackBerry 10 and Higher.
  • The Company field can be set to your full name if you are not a part of an organization.
  • The Email field will be used to send you your code signing keys.
  • The PIN is a one-use password that you are creating. It will be required when registering your code signing keys.

 

Once the request is submitted, you should receive two (2) emails to your specified email address, each with a unique attachment:

  1. client-RDK-########.csj; and
  2. client-PBDT-########.csj

Where ######## refers to a unique ID associated with your code signing keys.

 

Save both CSJ files to the \dependencies\tools\bin subfolder of your BlackBerry 10 WebWorks SDK installation. Example:

 

...\BlackBerry 10 WebWorks SDK 1.0.4.11\dependencies\tools\bin

Open a Command-Prompt to the bin folder and run the following command to register your code signing keys:

 

blackberry-signer -register -csjpin CSJPIN -storepass STOREPASS client-RDK-########.csj client-PBDT-########.csj
  • CSJPIN refers to the PIN you created when requesting your code signing keys through the online form.
  • STOREPASS refers to a code signing password that you are now creating; this password will be required every time you package/sign a BlackBerry 10 application.
  • client-RDK-########.csj and client-PBDT-########.csj refer to the two files you received via email and have saved to the bin folder.

Once execution is complete, your PC will now be able to package/sign BlackBerry 10 applications. Please review the following for information on backing up your BlackBerry 10 code signing keys.

 

GameMaker to BlackBerry 10

This guide is targeted at developers who are developing / have developed GameMaker applications already and are looking to target the BlackBerry 10 platform with an HTML5 export. We will take a brief look at configuring one of the Demo projects and then go into detail on the BlackBerry 10 side of things.

 

Creating a GameMaker Project

 

1.  Launch GameMaker: Studio.

 

Untitled.png

 

2.  From the New Project dialog, select the Demos panel and open the Angry Cats: Space project.

 

Untitled.png

 

We will use this as the basis for our BlackBerry 10 project.

 

GameMaker Settings for BlackBerry 10

The majority of GameMaker projects won’t require additional configuration, however there are some tweaks worth consideration.

 

Enable WebGL Rendering

The BlackBerry 10 platform has full support for WebGL™. The <canvas> element on the BlackBerry 10 platform is inherently hardware accelerated for both the Canvas2D and WebGL contexts, however leveraging the WebGLRenderer can lead to additional performance boosts.

 

This can be done by navigating Global Game Settings > HTML5 > Graphics > Options > WebGL and selecting the Required value.

 

Untitled.png

 

Rescale to the Device Screen Size

With a small workaround, you can ensure that your project is being programmatically scaled to the viewport of the BlackBerry 10 device you are deploying to. We’ll leverage the existing objControl object which can be modified by opening the object via double-click.

 

Untitled.png

 

The first change will be to add the following code to the create event.

 

Untitled.png

Spoiler
global.gameheight = view_hport[0];
global.gamewidth = view_wport[0];

This will create two global level variables that store our viewport dimensions. We'll use these in the next section to ensure our viewport is sized correctly.

 

The second change is to the step event, where we add the following code.

 

Untitled.png

Spoiler
if( ( browser_height!=global.gameheight ) ||
( browser_width!=global.gamewidth ) ) {
      global.gameheight = browser_height;     global.gamewidth = browser_width;     view_hport[0]=global.gameheight;     view_wport[0]=global.gamewidth;     window_set_size(global.gamewidth,global.gameheight);
}

Here, we're ensuring that the browser dimensions are the same as our viewport dimensions. If they are not, then we'll store the browser dimensions as our new global values, and then initialize the viewport to match what the browser is providing.

 

It is good to keep in mind that the BlackBerry® Z10 (full touch) has an aspect ratio of 15:9 (1280x768 pixels) while the BlackBerry® Q10 (keyboard) has an aspect ratio of 1:1 (720:720 pixels.)

 

Future BlackBerry 10 devices have been standardized as follows.

  • Full touch: 16:9 (1280x720 pixels)
  • Keyboard: 1:1 (720x720 pixels)

 

Exporting to HTML5

With our project-specific modifications in place, we’re now ready to export our project; luckily GameMaker: Studio makes this very easy on us. First, ensure that the Target for your export is set to HTML5 in the main toolbar.

 

Untitled.png

 

You can either click the Create Executable for Target icon  or you can navigate File > Create Application… which will prompt you to select a destination folder for your export. In our case, we will be exporting to a ...\GameMaker\AngryCatsSpace folder on our desktop.

 

Untitled.png

 

Clicking Save will kick off the export process and, once complete, we can view the resulting HTML5 export on our file system.

 

Untitled.png

 

This puts us 90% of the way to a BlackBerry 10 application.

 

BlackBerry 10 config.xml (full documentation)

In order to package an HTML5 project into a BlackBerry 10 project, you are required to have a config.xml file that exists at the root of your project. In our case, we need to create config.xml in our AngryCatsSpace folder alongside index.html.

 

The most basic config.xml file would look as follows.

 

<?xml version="1.0" encoding="utf-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
          xmlns:rim="http://www.blackberry.com/ns/widgets"
          version="1.0.0.0"
          id="A_UNIQUE_APP_ID">
 
     <name>AngryCatsSpace</name>
     <author>Erik Oros</author>
     <content src="index.html" />
     <icon src="icon-114.png" />
</widget>
  • version represents the current version of this application. This must be incremented any time you submit a new version of this application to the BlackBerry® World™ storefront.
  • id represents a unique identifier for your application. Best practices recommend a reverse domain format. Example: com.oros.sampleapp
  • name specifies the display name of your application on the user’s device.
  • author represents the creator of the application.
  • content represents the entry point into your application. If you have exported your HTML5 project under the default settings, this should be index.html.
  • icon represents a path to the application icon that will be displayed on the user’s device. Best practices recommend an image with 114x114 dimensions.

 

Optional  BlackBerry 10 Configuration

The standard config.xml file will allow you to package/sign your HTML5 project and create a BlackBerry 10 application.

 

However, there are a few common settings that you may want to include in your application. Note that the order of elements isn’t particularly important as long as they are contained inside the root <widget> element.

 

Orientation Lock (full documentation)

You can lock your application to portrait or landscape mode by including the blackberry.app feature in your config.xml. Example:

 

    <feature id="blackberry.app">
        <param name="orientation" value="landscape" />
    </feature>

 

White-listing External Resources (full documentation)

The majority of your GameMaker resources will be self-contained, however if your application does pull in any resources from external URLs (scripts, images, etc.) then you will need to white-list those URLs within your config.xml.

 

Example, if you were pulling an image from:

 

http://docs.google.com/myFiles/myimage.png

 Then you would need to add the following access element.

 

<access uri="http://google.com" subdomains="true" />

 

Packaging to BlackBerry 10 (full documentation)

At this point, we should have the following completed.

  • Downloaded and installed the BlackBerry 10 WebWorks SDK.
  • Requested and registered BlackBerry 10 code signing keys.
  • Exported our GameMaker: Studio project to HTML5.
  • Created a config.xml document for our exported HTML5 project.

All that remains now is to run the command that packages our HTML5 resources (HTML, JavaScript, CSS, images, etc.) into a BlackBerry 10 application. To do this, we will need to open a command prompt and navigate to the root BlackBerry 10 WebWorks SDK folder.

 

C:\Program Files\Research In Motion\BlackBerry 10 WebWorks SDK 1.0.4.7

 The command that we want to execute is as follows.

 

bbwp PATH_TO_PROJECT -g STOREPASS -d
  • PATH_TO_PROJECT is a path to the root folder of your project.
  • STOREPASS is the code signing password that you created when you registered your CSJ files.
  • -d is an optional flag to enable remote debugging. When creating a release version of your application (i.e. to be distributed to end users) this should be omitted.

Combined, this should resemble the following example.

 

bbwp "C:\Users\eoros\Desktop\GameMaker\AngryCatsSpace" -g signpass01 -d

Once this command completes, the resulting output should look as follows:

 

[BUILD]   Populating application source
[BUILD]   Parsing config.xml
[BUILD]   Generating output files
[INFO]    Info: Package created: C:\Users\eoros\Desktop\GameMaker\simulator\AngryCatsSpace.bar
[INFO]    Info: Package created: C:\Users\eoros\Desktop\GameMaker\device\AngryCatsSpace.bar
[INFO]    Info: Bar signed.
[BUILD]   BAR packaging complete

Two BAR files get generated in this process. The bolded line specifies the BAR file you should be using; specifically the one created in the device subfolder.

 

C:\Users\eoros\Desktop\GameMaker\device\AngryCatsSpace.bar

 

Deploying to BlackBerry 10 (full documentation)

Now that we have our device BAR file, there are a few options available. If you do not have a BlackBerry 10 device for testing, you can deploy to the BlackBerry 10 simulator, which is a free tool, to test your application.

 

The alternative is to deploy to a live BlackBerry 10 device. To do so, you will need to complete a few steps:

  1. On your BlackBerry 10 device, navigate Settings > Security and Privacy > Development Mode and ensure that Enable Development Mode is set to On.
  2. Connect your BlackBerry 10 device to your PC via USB.
  3. Execute the blackberry-deploy command.

To execute the blackberry-deploy command, open a Command-Prompt and navigate to the \dependencies\tools\bin subfolder of your BlackBerry 10 WebWorks SDK installation. Example:

 

...\BlackBerry 10 WebWorks SDK 1.0.4.11\dependencies\tools\bin

It is easiest if you copy your BAR file to this folder as well. The blackberry-deploy command looks as follows.

 

blackberry-deploy -installApp -password PASS -device 169.254.0.1 -package AngryCatsSpace.bar
  • PASS represents the device password you set when Development Mode was enabled.
  • 169.254.0.1 represents the IP address of your device; this is the standard USB IP address but you can also use a Wi-Fi® IP address. The Wi-Fi IP address can be found under Settings > About > Network.
  • AngryCatsSpace.bar represents the path to your device BAR file.

Alternatively, you can leverage tools such as the PlayBook App Manager Chrome Extension to manage the applications on your device. This tool provides a simple drag/drop interface for loading BAR files to your device.

 

Submitting to the BlackBerry World Storefront

Before you can distribute your application (BAR file) through BlackBerry World, you will need to register for a BlackBerry World vendor account; this process is entirely free, as is submitting applications. For applications that are sold through BlackBerry World, there is a 70:30 revenue sharing model in place, in favour of the developer.

 

To register for a BlackBerry World vendor account, please visit the registration page and register for / sign in with your BlackBerry ID. Once you complete your vendor registration, it may take 24-48 hours before your vendor account is approved; prior to this you will not be able to log into the vendor portal.

 

Once your vendor account is approved, you’re ready to start submitting applications. For more information on submitting to the BlackBerry World storefront, please refer to this video tutorial.