Widget Workshop's Forum Nokia Blog

Developing our first widget: Bombus

mobileradicals — Thu, 20 Sep 2007 12:33:32 +0300

Firstly, sorry for the delay in writing up the next installment of our S2F blog - we found it difficult to develop and blog simultaneously. So, with that in mind, let's start with a confession:

The game's already finished! It's called Bombus, and as promised, it's a side-scrolling arcade game.

Here's a video showing the gameplay:

Whilst developing the game we took notes, but to do each blog entry justice (by including a write-up after the end of each step) would have resulted in delaying the completion date significantly.

However, we now have some free time to write down our experiences, and more importantly, share some code. So whilst this might go against the S2F ethos slightly, we hope you can forgive us and hopefully seeing how the game turned out will help.

1. Getting started

Our first step was to download the SDK from the WidSets wiki. The wiki is an invaluable source of information containing general development guides as well as scripting and configuration documentation. The WidSets developer forum also proved useful as members of the WidSets team seem to visit often and are quick to offer help and advice.

The SDK consists of a set of command-line tools for compiling, invoking the emulator, uploading widgets etc (WidSets SDK wiki article). We used UltraEdit as our IDE, which is essentially a powerful text-editor. The SDK contains a syntax highlighting file for UltraEdit which helps with code readability. With the SDK installed, we encountered our first minor problem: widgets are distributed centrally from the WidSets server, so in order to login and subsequently upload/publish widgets, a connection to the server is necessary. Here at Lancaster University, we sit behind a proxy server, so we had to define our connection settings before we could connect.

So instead of:

> devkit login username password

We had to use:

> devkit --proxy wwwcache.lancs.ac.uk:8080 --auth user1 pass1 login user2 pass2

Where user1 and pass1 are our proxy authentication details and user2 and pass2 are our WidSets username and password (the proxy need only needs to be defined once). To register a developer account at WidSets, we visited http://dev.widsets.com/install - currently this link isn’t easy to find on the main site. N.B. The WidSets developer client is different to the regular client.

After following the guides on the wiki, checking out a few of the examples and with the scripting, configuration and stylesheet documentation open in the browser, we were ready to start.

We used the Hello World (found in examples/hello_world) example as the starting template for our own widget. Copying all the files from this directory to our working directory (bombus/) allowed us to bootstrap the development. The wiki provides a good overview of the files to are need to make up a widget here.

Here's what the first version of Bombus looked like...

Not much of a game yet, but we can get an idea of where our game content will be (on the blue canvas). The important files used to create this version are listed below.

Configuration file (widget.xml):

<?xml version="1.0" encoding="utf-8"?>
<widget spec_version="2.0">
  <info>
    <name>Bombus</name>
    <version>0.1</version>
    <author>Widget Workshop</author>
    <shortdescription>
      A one button side scrolling arcade game
    </shortdescription>
    <longdescription>
      Guide Bombus through the cave.
    </longdescription>
    <tags>
      bombus game arcade side scrolling one button
    </tags>
  </info>
  <parameters>
    <parameter
      type="string"
      name="widgetname"
      description="Name of widget"
      help="This is the name of the widget"
      editable="false"
      visible="true">
      Bombus
    </parameter>
  </parameters>
  <resources>
    <code src="bombus.he"/>
    <stylesheet src="style.css"/>
    <img src="mobile_radicals.png" scale="false" />
  </resources>
  <layout minimizedheight="3em">
    <view id="viewMini">
      <label class="outerFrame">Bombus</label>
    </view>
    <view id="viewMain">
      <script id="gameView" />
    </view>
  </layout>
</widget>

Helium script (bombus.he):

class {
    
  // Command IDs
  const int CMD_BACK = 1;
  const int CMD_NEW_GAME = 10;
  const int CMD_INSTRUCTIONS = 11;
  const int CMD_ABOUT = 12;
  
  // Member vars.
  Shell gameShell;
  Flow gameFlow;
  Canvas gameCanvas;

  // Menu items (mapped to softkeys)
  MenuItem BACK = new MenuItem(CMD_BACK, "Back");
  MenuItem OPTIONS = new MenuItem(OPEN_MENU, "Options");

  // Create options menu (using chaining)
  Menu MENU = new Menu()
    .add(CMD_NEW_GAME, "New game")
    .add(CMD_INSTRUCTIONS, "Instructions")
    .add(CMD_ABOUT, "About");

  // Push shell onto screen
  void showShell(Shell shell) {
    int w, int h = getScreenSize();
    slideIn(-w, 0, w, h, shell);
  }
  
  // Pop shell off screen
  void hideShell(Shell shell) {
    int w, int h = getScreenSize();
    slideOut(w, 0, w, h, shell);
  }

  // Called for each view element
  Component createElement(
    String viewId, String elementId, Style s, Object o) {
    
    if(elementId.equals("gameView")) {
      
      gameFlow = new Flow(getStyle("outerFrame"));
      gameCanvas = new Canvas(getStyle("default"));
      gameCanvas.setPreferredSize(-50, -50);
      gameFlow.add(gameCanvas);

      return gameFlow;

    }
    return null;
  }

  // Create minimized view
  void startWidget() {
    setMinimizedView(createView("viewMini", null));
  }

  void stopWidget() {} // Stop

  // Create maximized view when the widget is opened
  Shell openWidget() {
    gameShell = new Shell(createView("viewMain", null));
    showShell(gameShell); // Show main shell
    return null; // We've already push shell into view
  }

  // Release resources
  void closeWidget() {
    gameCanvas = null;
    gameFlow = null;
    gameShell = null;
  }

  // Paint the gameCanvas
  void paint(Component c, Graphics g, Style s, int w, int h) {
    g.setColor(0x0000FF);
    g.fillRect(0, 0, w, h);
    g.setColor(0xFFFFFF);
    g.drawString(
      "Our canvas!", w / 2,  h / 2, HCENTER | TOP);
  }

  // Get the menu
  Menu getMenu(Shell shell, Component source) {
    return MENU;
  }

  // Softkey event handler
  MenuItem getSoftKey(Shell shell, Component focused, int key) {
    if(key == SOFTKEY_OK)
      return OPTIONS;
    else if(key == SOFTKEY_BACK)
      return BACK;
    return null;
  }


  // Key event handler
  boolean keyAction(Component source, int op, int code) {
    return false; // Key event not consumed
  }

  // Action event handler
  void actionPerformed(Shell shell, Component source, int action) {
    
    switch(action) {
      case CMD_NEW_GAME:
        break;
      case CMD_INSTRUCTIONS:
        break;
      case CMD_ABOUT: // Display 'about' info.
        setBubble(
          getImage("mobile_radicals.png"),
          "Bombusnmobileradicals.com");
        break;
      case CMD_BACK:
        // Pop shell
        hideShell(shell);
        break;
    }
  }
}

Stylesheet (style.css):

outerFrame {
  align: hcenter vcenter;
  background: solid #000000;
  color: #FFFFFF;
  width: 100%;
}

Please note, blogs after this will not post complete source listings, but instead provide important fragments that demonstrate key game concepts.

Game On (down the widget rabbit hole)

mobileradicals — Sat, 25 Aug 2007 12:56:04 +0300

Since announcement of the blog, we have been having conversations on what to develop as our first widget. Our initial thoughts were to develop some form of photo viewer for m3Dcam, feeding in to the latest photos submitted to the site. This represents the functionality of a typical widget (accessing RSS text/image feeds). However, we’ve decided it would be more interesting (for us at least) to develop a widget that is not represented by those currently available; a side scrolling arcade game. When we last checked, the only other example of a real-time (RT) game was a Breakout clone (screenshot shown right).

There are a few factors that might explain the lack of this type of game:

The WidSets framework is compatible with a wide-range of mobile phones (most phones supporting MIDP 2.0/CLDC 1.0+). This includes fairly basic phones that are now a few years old, so they might be lacking in resources that real-time games are so keen to consume, such as processor cycles and memory. WidSets widgets are distributed centrally, and are only made available for download if they are deemed as robust and generally suitable for public use by the WidSets team. A greedy widget could potentially compromise the stability and responsiveness of the Java ME based WidSets framework, so may be rejected on this basis.
Creating a real-time game is not a trivial undertaking on any platform and the WidSets framework is tailored more toward applications that make use of internet connectivity rather than (real-time) games.

So whilst most widgets are understandably oriented toward accessing internet information and services, we think there’s a case to be made for more diverse (and trivial) widgets, such as games. So why use the WidSets framework instead of creating a Java ME game? The answer is simple; distribution. Independent developers, like us, can create widgets which are catalogued and available for download (via the library widget) alongside those created by larger, more established companies/organisations and it’s more likely a widget will be downloaded on merit rather than because of a connection to a popular IP, brand, or due to marketing/affiliation etc. Whilst we intend our game to be single-player affair, we could take advantage of some the inherent connectivity of WidSets by perhaps implementing a shared high-score table.

Having decided on creating a game, the next step is our design criteria. Different phones have different performance characteristics. The three main factors which will determine how level our playing field is are; screen resolution (1), input mechanism (2) and framerate (3). So, with this in mind, how are we going to keep the experience consistent across different phone models, which is necessary in order to compare the scores of different users?

In order to cater for different resolutions, we’ll use graphics primitives such as lines, rectangles and triangles. In this way, we can easily scale the graphics in proportion to the display dimension in way that’s not feasible using bitmap graphics. Instead of considering this as a limitation, we’ll try and use this as a feature by recreating a retro vector game look and feel. Drawing graphics primitives is also generally a lot faster than drawing bitmapped graphics.
Different phone models have different keypad layouts, ergonomics, number of keys etc. We’ll accommodate for this by using a single button interface to control the game. Nokia themselves are proponents of single-button games and have produced an interesting article entitled Turn Limitations into Strength: One Button Games.
Anyone who remembers playing an old real-time DOS game with no framerate limiter will appreciate how machine performance can affect a game’s difficulty. To mitigate for this, we’ll base the movement of our game objects on the time difference between frames (delta). Essentially, we’re scaling movement in the same way that we’re scaling our graphics.

One last consideration: as the WidSets framework is currently based on CLDC 1.0, there’s no floating point support in Helium script (i.e. floats or doubles). We’ll make use of fixed-point arithmetic to overcome this.

In the next blog, we will start building up the basic framework for the game, posting source code along the way (Helium script).

Start of the Widget Workshop (or taking the red widget pill)

mobileradicals — Thu, 16 Aug 2007 19:40:17 +0300

Welcome to our (Paul Coulton and Will Bamford’s) new Start2Finish blog called Widget Workshop. This will be an evolutionary series of blogs revealing our experiences developing a range of widgets from a standing start of no prior experience. In other words, we are 'Widget Virgins'. We say evolutionary, as we don’t really have any firm plans of what we are going to develop and principally want to explore as many of the capabilities as possible and hopefully demonstrate the power of the technology.

Besides the basic intro to the project we thought we would start by clearing up the difference between WidSets widgets and S60 Widgets (Web Run-Time). There are obvious similarities in terms of ease of distribution and likely use, but we also want to explore the differences between these technologies from a developer's perspective, so let’s start with a brief overview of each technology (a more comprehensive discussion/comparison is available here and here).

WidSets Widgets

This is essentially a Java-based platform. Widgets can be developed using the WidSets Studio, a very easy to use online visual editor for developing simple widgets in a matter of minutes. However, these widgets are essentially limited to picking up RSS feeds (for displaying text and photos). To create custom functionality, developers need to delve into Helium script, a ‘Java like’ language for controlling all aspect of a widget’s behaviour. We need to download the WidSets SDK to create Helium-powered widgets.

S60 Widgets

These are lightweight mobile browser applications developed using familiar, standards-based web technologies such as (x)HTML, CSS, JavaScript, and even advanced AJAX. In order to run S60 Widgets, the phone needs the run-time installed (future S60 phones will have this installed as standard).

At the present we will be developing WidSets widgets for the workshop, although we hope to cover both in the future when we get access to a suitable phones for development and/or Nokia’s Web Run-Time SDK is released.

We hope you will help, hinder, make suggestions for widgets (preferably fun ones) or just observe our efforts.

Cheers