Porting pygame games to the XO

Introduction

This tutorial attempts to guide you through taking an existing (finished) Pygame game and producing an “Activity” for the OLPC Sugar platform. For information on how to make a Pygame game, see http://pygame.org. Our final goal is an OLPC Activity bundle (a .xo file) which can be automatically installed on a Sugar platform or an XO laptop. You can download the finished project from the following SVN repository: svn://www.imitationpickles.org/melons/branches/olpc

The tutorial was created by Phil Hassey during the process of porting the “Watermelons” game to the OLPC platform and checked/shinified by Mel Chua. Read it with a light-hearted, game-friendly voice...

Installing the OLPC goodies

1. Get a Sugar environment running on your computer. If you have an XO, you're done (though you may want to upgrade to the latest stable build before proceeding, see Olpc-update) – if you don't have an XO, read on.
2. If you're running Windows, download the OLPC QEMU emulator quick-start package at Emulating_the_XO/Quick_Start/Windows and follow the instructions. (Note: The files are big. If you're doing this in a group, get an USB key, save the files there, and pass it around to save bandwidth and sanity.)
3. If you're running Ubuntu or Debian, there are packages available; instructions are here (the one for Ubuntu Gutsy is particularly easy to use – this is probably the most painless install method for getting Sugar on a non-XO machine at the time of this writing, March 2008).
4. If you're running something else, the Developers/Setup page may have some information for you.

Logging into the (Virtual) OLPC

1. Read the appropriate “how to use an OLPC” documentation, the OLPC Sugar software doesn't work much like most other GUI shells on any platform - http://www.laptop.org/en/laptop/start/
2. You get to choose a name for your laptop and a color to display.
3. You can press ALT-F, which does something like “add a frame to the screen”
4. Play around with Sugar for a while. Start some activities; note how they display in Home view, in the Journal, what resolution the graphics display at, and so forth – also (if you have an actual XO) how the keyboard, trackpad, and other physical aspects of the laptop affect playability.

Running your game on the XO

1. First we need to make sure your Pygame game works on the XO (it should). to do this, in Sugar, open the Terminal activity (it’s the $-in-a-box icon).
2. Download your game onto the XO / emulator (anywhere). If you're using your own computer, we'll assume you already know how to get files onto it. If you're using an XO, you can...
   1. Put your game on a USB stick and plug it into the XO, then open the Journal activity (it looks like a book) and drag files from the stick to your XO
   2. Use wget
   3. If you happen to use subversion for your code (you may want to create branch for the Sugar version of the game first...):

become_root # note: this is a special command instead of 'su'
yum install subversion
svn co <your-game's-repository>

(in my case: "svn co svn://www.imitationpickles.org/melons/trunk melons" but that's probably more information than you really needed)

1. Try running your game from within the Terminal activity by typing “python your-game-file.py” (or whatever you usually use to run your game from the command line).
2. If it runs, that's great (and hey, that was easy). You're now ready to wrap your game into an Activity.

But wait – before you do, make sure your main file (the your-game-file.py that you call with “python your-game-file.py” when running the game) has a main() function and the “if __name__ == ‘__main__’: main()” pattern (instead of just having it in the top level of your file). We'll see why this is important for wrapping shortly.

• If your game doesn't run in Sugar, check to make sure it runs under Pygame outside Sugar (on your “normal” computer). If it runs outside of Sugar but not within Sugar, that's odd, and you should head to the IRC channel and ask for help (#olpc and/or #pygame at irc.freenode.net – see http://wiki.laptop.org/go/IRC if you're new to IRC).

Building your activity wrapper

1. On your XO (or your Sugar emulator), download the latest version of the OLPCGames wrapper at http://dev.laptop.org/~mcfletch/OLPCGames/ (the current one as of this writing, March 2008, is version 1.6). Put it into your home folder and unzip it. One sequence of commands that does this is shown below.

   cd ~

   wget http://dev.laptop.org/~mcfletch/OLPCGames/OLPCGames-1.6.tar.gz

   tar -xvf OLPCGames-1.6.tar.gz

2. Move into the OLPCGames-1.6/skeleton directory.

   cd OLPCGames-1.6/skeleton

3. Run the buildskel.py script. You'll need to know four things to do this:
   1. The name of your game (a short one) – in this case, “melons”. (We'll call this GAME_NAME).
   2. A human-readable name for your game (can be longer) – in this case “Watermelons,” but your game name and its human-readable name can be identical. (We'll call this HUMAN_READABLE_NAME).
   3. The name of your main module. If you run your game from the command line using “python your-main-file.py” this is “your-main-file” - in this case, “main” (because we use “python main.py”). (We'll call this MAIN_MODULE_NAME).
   4. The name of the main function within your name file. This is also usually “main”. (We'll call this MAIN_FUNCTION_NAME).
4. The command to run is

   python buildskel.py –n GAME_NAME –t HUMAN_READABLE_NAME –m MAIN_MODULE_NAME:MAIN_FUNCTION_NAME

   • In the case of watermelons...

     python buildskel.py –n melons –t “Watermelons” –m main:main

5. You should now have an activity folder named “GAME_NAME.activity” - in our example, “melons.activity”. Go into that folder.

   cd melons.activity

Wrapping Your Game

1. If your game includes a setup.py file (which it should – it's good development practice), we'll sadly have to replace it by the one provided by OLPCGames. Delete or rename your current setup.py file to setup.py.old or something. Now...
2. Copy the contents of your game folder into the activity folder (which should at this point be your current working directory). In our case...

   cp -r ~/melons/* .

   (Note: you may want to do the reverse of this command, copying the Activity skeleton into your existing program's directory).
3. If you didn't follow the first step and overwrote the folder's setup.py with your game's setup.py, that's ok; we can recover.
   • ONLY if you've overwritten the setup.py file!

     cp ../skel.activity/setup.py ./olpc-setup.py

4. Now you're ready to register your game as an activity.

   python olpc-setup.py dev

5. We need to restart Sugar...
   • On the XO, click Alt-Ctrl-Erase
   • On a non-XO (Sugar emulator), just restart the emulator
6. You should now find a hammer (the default OLPCGames icon) in the bottom of the frame in Home view, nestled alongside the other Activity icons.

Testing Your Game

1. Click the icon (hammer) of your game.
2. If it works, rejoice.
3. If it doesn't work, (or even if it does work – it's still a good idea to see the logs, especially if you ) start up the Log Viewer Activity (it looks like three bullet-pointed list items in a box).
4. In the Log Viewer Activity, click on your game. It is probably named “org.laptop.community.GAME_NAME-NUMBER.log” where GAME_NAME is the name of your game and NUMBER is the version number (usually 1). In our case, this is “org.laptop.community.melons-1.log”.
5. You should see a traceback. Use it for debugging as needed.

Saving game data

1. Although my game ran, I noticed that some errors were in the log. Apparently the OLPC laptop has some security restrictions such that python cannot write to your game's working directory. If your game likes to save things, you’ll have to use the OLPCGames API to get your “save game” directory.
2. Watermelons writes out a record of how the game was played and high scores, so I’ll fix that... You’ll want to start up the Terminal Activity again and fix those bits of code. (To switch between tasks on the OLPC laptop press F3/Home to get back to Home view, and choose the other activity (Log Viewer vs Terminal) or, if you have an actual XO, use Alt-Tab to cycle between running programs.) Here's what I had to put in mine (game.py).

# begin code snippet - more code above
import olpcgames.util, os
fname = os.path.join(olpcgames.util.get_activity_root(),’data’,’melons.hs’)
# end code snippet - more code below

You can write to that folder now.

Creating your icon

1. Download inkscape from www.inkscape.org - it's available for most platforms
2. You can start from an existing icon, like this one or the one that is inside your activity folder.
3. These Sugar folks are a bit picky about their Icons, specifications and all that, so read OLPC_Human_Interface_Guidelines/The_Sugar_Interface/Icons
4. After you have created your new compliant and rather excessively inspiring icon, you must alter it so that it will change colors within sugar. Read Making_SVG_Icons_for_Sugar
5. Save your finished icon into (your project)/activity/activity.svg
6. Restart sugar (your laptop) and you’ll have the new icon!! Yaay!

Building your package!

1. Emulators? Who cares about emulators, we want to see our code on a cute little laptop!
2. If you want to check the whole package into svn, you’ll need to:

   mv olpcgames olpcgames-x

   mkdir olpcgames

   cp –r olpcgames-x/* olpcgames

   This makes a local copy of the olpcgames package for your game to include in its repository
3. Add in all the other stuff .. (left as an exercise to the reader, *.py, etc)
4. Edit MANIFEST.in and add in stuff like
   1. recursive-include data *
   2. TODO: add in recursive exclusion of .svn files somehow!
   3. or whatever data folders you have in your game
5. Build the MANIFEST file from your cool MANIFEST.in file now:

   python olpcgames/buildmanifest.py

   And then...

   python olpc-setup.py dist

   • (or if you were a bad person and didn’t have your own setup.py, just do):

     python setup.py dist

Play on a Little Computer

If you have an XO, you can test your game on it now.

1. Copy the .xo file that is in the CWD, named “melons-1.xo” to your web server
2. On the XO use wget to get your game and save it into ~/Activities
3. You may need to create the Activities folder first

   cd Activities

   unzip melons-1.xo

4. Restart the XO... again.
5. Your game should be installed! Let the good times roll!! Spend a few hours playing with it.

Cross platform issues

If you want to have your game run on both the OLPC and “regular “ machines, you might want to copy the skeleton into your code, instead of the code into the skeleton, that way you still have your .svn directories.

Detecting if you are using the OLPC

try:
   import olpcgames, olpcgames.util
   if not olpcgames.ACTIVITY: raise RuntimeError
   # Do something for the OLPC
except (RuntimeError,ImportError):
# do something as you would usually do that something

Other issues

If your game is not exactly the same resolution as the OLPC – it won’t be centered. If reasonable, change your game resolution to the OLPC res. If not, don’t worry – they are working on fixing it so that your game view will be properly centered on the screen!