Players have to move and tilt their phone along with the game’s music …, Play also seems to use the handset’s vibration function in some manner.

Oh yeah, I’ll just bet it does!

I’ve often though that there’s a lot of untapped potential in historical games, and maybe smaller efforts like this one are a better way of leveraging the wealth of material that’s available than, say, more traditional ‘epic’ style games like Age of Empires.

First things are to get the libraries set up, this was pretty well covered in the last couple of posts, but the actual steps I took (in brief) are:

1. checked out PBE from subversion, it’s hosted at http://code.google.com/p/pushbuttonengine/ and there are instructions there on how to get it;
2. copied the 5 main projects from pushbuttonengine/Projects/Engine into my workspace;
3. added build.xml and build.properties files, and set up the dependencies in them;
4. created a new project called PlayWithYourPeas and set up the dependencies and build files; and finally
5. set up a pbeproj file by copying an existing file and modifying it.

At this stage I’m almost ready to start cranking out some code! But first, I need to copy all of the artwork that I’m going to use, so I grabbed the zip file from danc’s site and opened it up, then created an Assets/Images folder and moved all of the images apart from the mock-up to there. I also created Levels and Sounds folders in my Assets folder, as I’ll need them later on.

Now I can finally start writing code. For this project I’m going to stick to plain ActionScript3 files: no Flex or MXML as I’d like to keep the gradient of my learning curve down to a reasonable angle!

Looking over the documentation and sample projects I can see that there are four main files that I need to create for my game: components, levels, resources, and the main file which, in my case, is going to be PlayWithYourPeas.as. I can start be just creating each file (⌘N → AS Class... if you’re using FDT, or however you normally create a new ActionScript 3 class in your own set-up). I’ll go through each file in turn and explain what it’s for and what I’ve put in it.

Levels

The first class I’ll look at is called Levels, in the Levels.as file. Go ahead and create it now if your following along and haven’t already done so.

The level information in PBE is all loaded from an XML based level description file, but there needs to be something to hook that into the rest of the game, and that’s what this class is for. It just has a single class with a constructor and the following code

1
2
3
4
5
6
7
8

public class Levels {
   public function Levels() {
      LevelManager.Instance.AddLevelFileReference(
         "../Assets/Levels/level-01.pbelevel", 0);
      LevelManager.Instance.AddGroupReference("Everything", 0);
      LevelManager.Instance.Start();
   }
}

The first line tells PBE where to find my level file (I’ll describe it’s contents later on); the next line tells PBE whereabouts in the file to start loading things from, and the last line starts the loading process.

The second line is important because you can have a huge amount of stuff in your levels file and not everything needs to be loaded at the same time, a single file can contain multiple game levels, allowing them to share resources. Game levels are simple numbers as far as the engine is concerned, so you add everything to your level description file and then set up a group (see below) that contains just the relevant bits and pieces needed for each actual game level. The second line says that ‘level 0 uses all the things described in the group named “Everything”’.

One last thing to note about this file: the name level-01 that I’ve chosen for my level description file is a bit different from the examples that are bundles with PBE; this is because I want to be able to keep the initial download size for my game as small as possible and so will want to break things up into different levels that can be loaded asynchronously in the background - this way the player will get a fast start-up and quick loading of new levels. This game will be too small for this to matter, but I’d like to try to start off with good habits then I don’t need to change them later on!

Resources

This is just a list of all of the resources (images, sounds, the level description, and so on) that will be included in the game initially; i.e. will be packaged up into the SWF or Air installer. As an aside, I’m going to optimise this for the SWF version of the game, I’ll handle bundling up additional resources into the Air installer via the build scripts; although, as with the levels file, for a game this small it makes no difference.

Initially I’m going to set up my resources so that they include the level description file (it needs to be references here as well) and the background image.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

public class Resources {
   [Embed(source="../Assets/Levels/level-01.pbelevel",
          mimeType='application/octet-stream')]
   private var _level:Class;
   [Embed(source="../Assets/Images/Background.png",
          mimeType='application/octet-stream')]
   private var _background:Class;
   public function Resources() {
      ResourceManager.Instance.RegisterEmbeddedResource(
         "../Assets/Levels/level-01.pbelevel",
         XMLResource,
         new _level() as ByteArray);
      ResourceManager.Instance.RegisterEmbeddedResource(
         "../Assets/Images/Background.png",
         ImageResource,
         new _background() as ByteArray);
   }
}

The two private variables here basically hooks to hang the Embed metadata from. Note that they both need to be octet streams, if you try to use something more intuitive (say application/xml for the level description and image/png for the background) it won’t work, as the PBE class that loads them basically just deals with things in terms of raw byte arrays.

The code in the constructor tells PBE how to handle the data in the octet steams: XMLResource and ImageResource are class names, the _level class is created by the engine based on the metadata that you pass in, so the new _level() is just using the Class as an object factory here.

Since all of the use of these is internal to the engine (we just tell it what to do, no actual code required) this isn’t a problem. Even so, hopefully in a future (i.e. post 1.0) version of the engine it’ll be possible to use smarter mime types and have the resource loaders do some automatic conversion as a result; it’s be nice to be able to declare something of type application/vnd.mycoolxsd+xml and have it accessible as an ActionScript XML instance (via the E4X support in AS3).

And There’s More…

OK, this has run on for a wile now so I’m going to finish this up in another post tomorrow, but to whet your appetite here’s a screenshot of what I’ve got so far:

Cool, huh? Well, everybody’s got to start somewhere, but it does demonstrate an import feature: the timer in the top right hand corner is a custom component that I’ve written and then added via the level description file, this is neat as it’s a standard component that I’ll be able to reuse in other games.

I’ll cover the other two files (components and the main game file) as well as the custom component in my next post in this series…

I’ve started off with a fairly vanilla Eclipse Java installation, v3.4.2, with the subversion plug-ins and Oxygen XML for eclipse. The 2 options that I’ve looked at for Flash development are

• AXDT - an open source plug-in; and

• FDT - a commercial offering from a company in Germany.

I’m going with FDT at the moment as it seems much more feature complete, it comes with a 30-day trial period so I guess I’ll have to decide if it’s worth the money after that, the biggest problems it has are a lack of documentation and poor support from the parent company, on the upside there seems to be a vibrant and helpful community of users. It’s also massively overpriced, but that seems to be par for the course with small German software vendors (EJ Technologies, I’m looking at you…).

I’m using the the build files described in a previous post, and have set up a custom schema for editing PBE level files.

The other neat tool that I’ve found is the Monster Debugger, which has a nice logging UI and the ability to inspect objects at run-time, it can also dynamically invoke methods, to a fairly limited extent (Flash IDE’s are about 30 years behind Lisp in this respect, even the JVM can do limited hot code replacement).

I should probably do a round up of useful links as well, as the Flash community in general seems to be really helpful and there’s loads of good stuff out there.

Update (2009-05-24): added an XSD version of the file, this handles unparsed content gracefully, useful for components.

Update (2009-05-24): updated the build files to work better with pure AS3 projects (i.e. with no MXML files).