Game development HOWTO

This document describes how to use the Pygame library for Python to create a new Game activity for the OLPC (Sugar) platform. Its intention is to allow a Python programmer who wants to learn (or already knows) Pygame to integrate their Pygame application into a Sugar-hosted activity using the OLPCGames Pygame wrapper.

This HOWTO is current as of December 2007.

Requirements

This HOWTO assumes that you know the basics of computer programming, how to navigate a file-system, and how to edit files on your machine. It also assumes that you will largely learn Pygame programming through the large number of available Pygame references and tutorials. We focus here on how to integrate your Pygame games into the Sugar environment.

Components

• Pygame -- this is a Python wrapper around the Simple Direct-media Layer (SDL) library. It is used for lots of games coded in Python and can run on most machines (including Windows, Mac and Linux). If you are running on an OLPC-XO, Pygame should already be available. If not, use your system's package manager to install the Pygame distribution.
  • The slides from Noah's lecture at the start of the game jam are online at (both PDF and PowerPoint form).
  • Mac setup instructions
• OLPCGames -- the OLPC Sugar specific library which provides the glue code that lets your Pygame game run inside a Sugar activity. It also gives you access to the various "special" features in the Sugar environment, such as the mesh network and the camera. If you are on an OLPC-XO, you can download the current OLPCGames distribution and unpack it.
  • Note: The OLPCGames Pygame wrapper requires at least build 432 to work for version 1.0 and at least an Update.2 build (649) for version 1.1 and above. See the reference manual at Pygame wrapper. See also Game development.

Environment

You will need a working Sugar Developers environment. If you are working directly on an OLPC-XO, you will need to know how to use a standard text editor, such as vi or nano, which are available within the "Terminal" activity in your activity toolbar.

• You'll need to set aside a few hours to learn vi before you start this HOWTO if you don't already know it and want to use it well)
• Nano is often considered easier to learn immediately because the major commands are all spelled out at the bottom of the screen (where you need to remember the vim commands yourself)

If you are working in an emulated environment, or a sugar-jhbuild environment, you can use whatever text editor you prefer to create the files we will be working on. There are many text editors with some Python support, and full IDEs are also available.

Skeleton Setup

To start, you will likely want to download the OLPCGames 1.2 source package. This package includes a skeleton script that lets you generate a new OLPCGames-based Pygame Activity with a single command.

Getting the Skeleton Script

To install the package, you will need to download the .zip or .tar.gz to your machine and extract it with either of:

unzip OLPCGames-1.2.zip

or

tar -zxf OLPCGames-1.2.tar.gz

which will create a directory named OLPCGames-1.2. Change to the skeleton directory:

cd OLPCGames-1.2/skeleton 

And run the command:

./buildskel.py activityname "My Activity Name"

to create a new generic activity instance.

Installing and Testing

To test that you have your environment properly configured, we'll restart sugar and attempt to run the newly created (empty) activity. Change to the new activity directory (activityname.activity) and run:

python setup.py dev

when you restart Sugar you should have a new activity in your Activity bar named "My Activity Name". Clicking on this activity should result in dark blue screen with a toolbar at the top of the window.

Testing Outside Sugar

The run.py script in the skeleton project is where you skeleton activity currently points for its "mainloop", particularly the "main" function within it. When you are just starting you you'll likely want to work within run.py to create new code and experiment. run.py is actually set up to be used as a python script via:

python run.py

which will run on a non-Sugar environment (i.e. a normal Linux, Windows or Mac desktop with Pygame installed). You may, however, have to configure your system to have the current working directory in the Python path (this is the default on Sugar systems, including emulators and sugar-jhbuild shells).

Customising the Skeleton

Your Sugar-specific activity values are stored in two main locations; the activity.py file and the activity directory. The pydoc for the PyGameActivity class describes the various attributes/settings available for your Activity object. These include changing the file-name and method-name for your mainloop function, and changing the title of your activity.

The activity directory is used by Sugar to find things such as your svg icon, translated names and the like. See Activity Bundles for details.

Getting Started with Pygame

At this point, your OLPC Sugar activity is running as a host for a simple Pygame event loop. The code in run.py does some trickery to make the event loop reasonably efficient, by limiting the number of frames rendered per second using a "pygame.time.Clock()" instance. It also uses a complex iteration mechanism:

for event in [ pygame.event.wait() ] + pygame.event.get( ):

which allows your activity to go completely quiet if there are no pending events, but still processes all pending events before issuing a "display.flip()" command. None of that is OLPC or Sugar specific, incidentally, it's just good practice to reduce your processing load when running on an OLPC machine.

• Note: the event iteration mechanism reduces the cpu-load from 99% to 0.7 - 4% in our tests versus a simple pygame.event.get() loop.

Reference Links

• Pygame wrapper pydoc -- the OLPCGames wrapper's reference manual and pydoc, you'll want to familiarize yourself with this to understand what's different on the OLPC platform from regular Pygame
• Pygame Tutorials -- a wiki-based collection of tutorials for learning Pygame programming
• 5-part Tutorial -- a fairly extensive tutorial on Pygame usage
• Pygame Documentation -- the official collection of Pygame documentation, you will need this to get any Pygame programming done
• If you are new to game and GUI programming, you may wish to use a Pygame GUI engine to simplify creating buttons, text entry boxes and the like.

The following Games/Activities use OLPCGames and can serve as example code (note that these projects are not yet finished):

• Story Builder -- Environment for creating story modules to be used in MaMaMedia, uses the PGU GUI library extensively
• Productive -- A Real-time Strategy game written explicitly for the OLPC platform. Includes networking via the mesh module (and raw Telepathy primitives). Graphics are via raw Pygame coding.

If you have questions, suggestions or problems, please feel free to post to the OLPC Game Development mailing list. This is a relatively low-traffic list with lots of Pygame users on it. Alternately, IRC channels are available on freenode as #pygame, #sugar and #olpc-content if you want more conversational support. Lastly, User:Mcfletch is the current maintainer of the wrapper. Contact him if you get stuck, but be aware he tends to be spread a bit thin, the mailing list is generally a better avenue.

Troubleshooting

Ensure you are using at least an Update.2 (first manufacturing release) Sugar environment. Also ensure you are using a recent version of OLPCGames.

Check your log files. On modern Sugar, use the Log Viewer activity to view the log for your activity. Open this activity and find your activity in the list of activity instances on the left. The numeric suffixes increase as you run your activity multiple times.