Marmalade SDK Mobile Game Development Essentials

The menu option called Overview takes you to a page where you can see your personal details along with a summary of the number of licenses and users you have set up under your account. From this screen, there are buttons that allow you to update your profile, modify registered user information, buy new licenses, and manage existing ones.

Clicking the Profile option in the My Account menu or clicking on the Update Profile Information button on the profile overview screen will display a page that allows you to alter information such as your name, contact information, address, and account login password. There is also a checkbox that allows you to sign up for e-mail news updates from Marmalade.

Clicking the Licenses link in the My Account menu or clicking on the button labeled Manage on the overview screen will take you to a page where you can upgrade the level of your license or buy further licenses for new team members.

The Manage Licenses section at the bottom of this page shows all the currently active licenses in your account, and also allows you to release a license that is currently in use so that it can be transferred to another computer.

Releasing a license is useful if you need to work on a different computer for some reason, or if you have a new development computer that you wish to transfer your license to. You can release a license as often as you like, but a single license can only be used on a single computer at a time.

If you are working in a team then you will obviously need more than one Marmalade license, but you also need to manage who has access to those licenses. Clicking on the Users option in the My Account menu or clicking on the Manage Users button on the overview page allows you to do this.

This page shows a list of all the users assigned to your account, and also has an Invite Users section that allows you to add new users to your account. Enter their e-mail addresses in the boxes provided, and click the Send invite button to send them a mail telling them how to activate their own Marmalade account.

Let's make a start on our "Hello World" project. Create a new directory to hold the project files, and then create a file called Hello.mkb in this directory and enter the following into it:

#
# Main MKB file for Hello project
#

# Modules used by this project
subprojects
{
  iwgx
}
 
# The files that make up the project (source, data etc.)
files
{
  [SourceCode]
  (source)

  Main.cpp
}

# Settings to configure the deployment process 
deployments
{
  name="Hello"
  caption="Hello World"
}

The first section of Hello.mkb is the subprojects section, which lists all the additional code modules used by our application. In this instance, a code module is a library that can be added to our project either as a group of C or C++ source files or, alternatively, as pre-compiled, linkable object files accompanying header files. In the previous example, there is just one, iwgx, which is the Marmalade code module responsible for rendering graphics.

All the higher level modules within Marmalade are referenced in this manner, and you can also use this system to create your own modules to enable code re-use across projects. To create a subproject module we use an MKF file, which amounts to a little more than an MKB file with a different file extension! When we add an entry to the subprojects list, the Marmalade makefile builder script will search for a suitable MKF file that describes each subproject. We'll see detailed examples of how to do this later in the book.

The next section is labeled files, and this is where we list all the source code files for our project. It is possible to split your source files up into different directories. To make it easy, you simply put the directory name in brackets ((source) in our example) and then list all the source files in the directory below.

It is also possible to group the related files together into subsections, which we do using square brackets ([SourceCode] in our example). Any source files below this will be added to that section and will then appear in a separate folder in the Visual C++ Solution Explorer. There is no need for the directory and group names to match, and indeed you can have more than one directory in a group if you so wish.

Finally we have the deployments section, which is where various settings are made that control the process of deploying our application to different device types.

In our example we are making two settings. The name setting provides the filename of our final executable and is also used in file and directory names created for us by Marmalade, while caption sets the name that will appear under the application's icon when installed on a device.

Both the aforementioned settings are examples of general settings that apply across all device types, but there are also a great many other settings available, which are specific to particular platforms, such as iOS or Android. A full list of these can be found in the Marmalade Documentation help file that is installed as part of the Marmalade SDK, and we'll also be looking at this in Chapter 8, Supporting a Wide Range of Devices, of this book along with the additional sections of the MKB file that have not yet been shown for this example.

The use of whitespace in the MKB file is pretty much up to your own personal preference. Though most of the Marmalade examples tend to indent entries within blocks, tabs or spaces can also be used.

Comments can also be added using the hash (#) character. Everything after the hash character till the end of the current line is then considered a comment.

We may now use the MKB file for our project but we still can't do anything with it yet, as we've told Marmalade that there is a source file called Main.cpp, which doesn't exist yet. If we were to try and use the MKB file to build the project, we would get an error reported about this missing file, so let's create it.

You will recall that we said that our Main.cpp file would reside in a directory called source in the MKB file, so first create this new subdirectory in the project directory. Now, create a file called Main.cpp in the source directory and enter the following into it:

//---------------------------------------------------------
// Learning Mobile Game Development with Marmalade
// Chapter 1 - Hello
//---------------------------------------------------------
 
// Marmalade SDK includes
#include "IwGx.h"
#include "s3eConfig.h"
#include "s3eDevice.h"
 
//---------------------------------------------------------
// Main entry point
//---------------------------------------------------------
int main()
{
  // Initialise Marmalade modules
  IwGxInit();
 
  // Set a default message, then check the ICF file to see if
  // a proper message has been specified
  char lMessage[S3E_CONFIG_STRING_MAX] = "Hello!";
  s3eConfigGetString("APP", "Message", lMessage);

  // Set screen clear colour to black
  IwGxSetColClear(0, 0, 0, 255);

  // Draw text at double default size
  IwGxPrintSetScale(2);
 
  // Loop until we receive a quit message
  while (!s3eDeviceCheckQuitRequest())
  {
    // Allow device to process its internal events
    s3eDeviceYield(0);
 
    // Clear the screen
    IwGxClear();
 
    // Display our message on screen
    IwGxPrintString(10, 10, lMessage);
 
    // Flush IwGx draw buffers to screen
    IwGxFlush();
 
    // Swap screen double buffer
    IwGxSwapBuffers();
  }
 
  // Terminate Marmalade modules
  IwGxTerminate();

  return 0;
}

The code should be fairly simple to follow, but here is a quick breakdown.

First we reference the include files to allow us to use the parts of Marmalade that are necessary for our application, and then we create our main entry point function main. This is equivalent to the main() function in a standard C or C++ program, except that it takes no parameters as Marmalade does not accept command-line parameters. It's quite hard to specify command-line parameters on mobile devices, so there really isn't any need!

The first thing our application needs to do is initialize Marmalade's rendering module with a call to IwGxInit(), which will initialize the screen and set up standard behavior such as double buffering of the display.

Next we allocate a character buffer that will contain the message that we will be displaying on screen. We initialize it to a default message to make sure that there is something to be shown, but we then use a call to the s3eConfigGetString function to see if another message has been specified in the application's configuration file, which will be explained in more detail shortly.

The following call to IwGxSetColClear sets the desired screen background color to black, and then the call to IwGxPrintSetScale tells Marmalade to display text using its built-in font (which is quite small in size) at double its default resolution.

We now enter our main processing loop that will continue until the s3eDeviceCheckQuitRequest function returns a true value, which will happen if the user quits the application or if the device sends a quit request to the application for any reason.

The first line of our main loop is a call to s3eDeviceYield. This is a very important function that must be called at regular intervals during our application, to allow the device's OS to perform important tasks such as handling events—user inputs, incoming phone calls, and so on. Under most circumstances, a single call to this function in the main loop is sufficient.

The value passed to s3eDeviceYield is the maximum time (in milliseconds) that our application will yield to the OS for. Normally this value is set to zero, which yields long enough for the device to process the events, but will return control to our application as soon as all the events have been processed.

Next, we call IwGxClear to clear the screen and then use IwGxPrintString to display a message on the screen. IwGxFlush causes the Marmalade engine to then process all our drawing requests to yield a final screen image that we can then display to the world using IwGxSwapBuffers.

Finally, outside the main loop, we call IwGxTerminate to shut down Marmalade's rendering engine, and finally return zero to indicate that our application was completed without any errors.

One of the directories created by the MKB file will be named build_hello_vcxx, where the "xx" part is dependent on the version of Visual C++ you are using.

This directory is Marmalade's working directory and is where all the object files created during building are stored. It will also be the home to our deployment packages when it comes to making device builds.

A Visual C++ solution file created from the MKB file also lives in this directory, and while you can use these files to switch between projects, you should never add files or change project settings using the options in the Visual C++ IDE.

The MKB file will also generate a directory called data, and this is where Marmalade requires you to place any files that your application will need to load, such as images, 3D model data, sound files, and others. While you can create this directory and these files yourself, and it will not cause a problem, we might as well let the makefile builder do it for us!

If you take a look inside the data directory, you will see that the build process has also created two more files called app.icf and app.config.txt. These files are used to configure your application and are explained in the following sections.

[APP]
Message      The message we want to display on screen

[APP]
Message="Hello World"

[APP]
{OS=ANDROID}
Message="Hello Android!"
{}
 
{OS=BADA}
Message="Hello Bada!"
{}
 
{OS=IPHONE}
Message="Hello iOS!"
{}

{OS=QNX}
Message="Hello BlackBerry!"
{}
 
{OS=WINDOWS}
Message="Hello Windows!"
{}

Let's start by looking at how to install an Android build.

The Android package file for the "Hello World" project is called Hello.apk, and to install it we first need to copy it to an Android device. This can be done by copying the file to an SD card, or if your device has built-in storage memory, copying the file into that.

Before we can install our package, we first need to make sure that the Android device will allow us to do so. Go into your device's Settings program and select the Applications option. Here there is an Unknown sources option, which allows us to install our own packages. Make sure this option is ticked.

Next find the file manager application on your device. Different devices may have different names for this application, but it often has an icon with a picture of a filing cabinet folder on it. Navigate the directories to find the location where you copied the Hello.apk file, then tap on the file's entry in the list.

The screen will change to show a big list of things that the application is asking to access, along with the Install and Cancel buttons. Click on the Install button and the package will be installed. You can then choose the Open button to start your application, or the Done button if you don't want to run it now. Click on Open and we should then be greeted with our Hello Android! message.

If you've tried to create an iOS build of the "Hello World" project, you will have noticed that it currently fails to complete with a signing error. This is because you will need to provide Marmalade with some certificate files, which can only be generated by becoming a registered Apple developer.

Joining the iOS Developer Program currently costs $99 per year, and you can find more details about it at the following web page:

https://developer.apple.com/programs/which-program/

Once you've signed up, you'll be able to access the iOS Dev Center that will then allow you to create the required certificates. Normally you would require an Apple Mac to generate these certificates, but, handily, Marmalade provides a small utility called the iPhone Sign Request Tool that gets around this issue. Here is what you need to do:

There is more information on this process in the Marmalade Documentation help file, and there are also How To tabs on most of the iOS Provisioning Portal pages explaining the processes involved, although most of these assume that you are using an Apple Mac to generate the various files.

With all those hurdles negotiated, we can then use Marmalade System Deployment Tool to generate a properly signed iOS install package, which will be named Hello.ipa. Now to get it installed onto a device!

It is possible to use iTunes to install your builds, but be warned that it tends to be a little bit of hit and miss as to whether it will work. Sometimes iTunes does not recognize that a new build is available and needs to be synched to the device. In my experience, a more reliable option is to use the iPhone Configuration Utility , which is a freely available Apple tool that can be downloaded from the following URL:

http://support.apple.com/kb/DL1466

First of all, you need to let the iPhone Configuration Utility know about your provisioning profile. Click on Provisioning Profiles in the far left pane and then click on the Add button in the toolbar. Navigate to the provisioning profile file you created in step 9 and click the Open button to add it to the list of available profiles. Alternatively, you can drag-and-drop the file into the list from Windows Explorer.

Next, click on the Applications entry in the left-hand panel and then click on the Add button. Find the Hello.ipa file in the deployment's release directory and click on OK to add it to the list of known applications, or again you can drag-and-drop the file from Windows Explorer into the list.

Now connect your iOS device to your computer using a USB cable. It should appear in the bottom of the left-hand pane after a short delay. Click on the name of your device and you should see five tabs appear in the main panel. Click the Provisioning Profiles tab and then click on the Install button next to your provisioning profile. Once done, this button will change to become a Remove button.

Our next step is to install the application itself, so click on the Applications tab to see a list of all applications that are either installed on the device already, or which can be installed. Find the entry labeled Hello and click on its Install button, which will change to read Remove once the application is installed.

After all that, we can finally run our application by finding its icon on the device and tapping on it. You should see the message Hello iOS!, which I admit may seem like something of an anticlimax after going through such a drawn-out process.

Marmalade can also deploy to BlackBerry QNX devices, the best known of which is the PlayBook tablet. In order to deploy to PlayBook, we need to do some setup work first. In the steps that follow, there are some commandlines that need to be entered. In these commandlines there are some arguments enclosed in angled brackets. After each set of commands, there is a table explaining what to replace the angle-bracketed arguments with.

The build should now be installed on the device, so breathe a sigh of relief and then look for its icon in the applications list. Touch the icon to run the program, and you should be greeted with the merry little message Hello BlackBerry!

Installing a build on to a Bada device is one example where using the Package, Install and Run option in Marmalade System Deployment Tool is actually a very good idea, as it is not possible to copy the package to a Bada device manually to install it.

To begin with, you need to install some device drivers for your Bada device so that the deployment tool can connect to it. Marmalade does ship with some drivers for Bada, but working out which of the three possible drivers matches your device can be hard to work out. For this reason, it is better to first install the Samsung Kies utility, which comes with a number of drivers and will install the correct one for you automatically. You can download Kies from the following web address:

http://www.samsung.com/uk/support/usefulsoftware/KIES/JSP

After installing Kies, connect your device to your computer with a USB cable and run the deployment tool. When you get to the platform selection page, you will see that there are four possible options for Bada. You must select the correct one for your device, which is based on both the version of Bada your device has and also its screen resolution.

Having chosen the correct Bada platform option, click on the Next Stage > button and then choose Package, Install and Run in the drop-down box at the top of the window. Click on the Deploy All button and an install package will be made, which is installed on to your device and executed, and you should then see the Hello Bada! message in all its monochrome glory!