Pygame wrapper

The Pygame wrapper is called olpcgames. For a tutorial on how to use it, see Game development HOWTO. This is the reference manual.

Getting the wrapper

Eventually, the wrapper will be a part of the standard build. Before then, you need to get it from Git:

git clone git://dev.laptop.org/projects/games-misc

The 'olpcgames' directory is the package in question. Submodules you can access are activity, canvas, camera, and pangofont. The wrapper also replaces certain Python modules (python.event) with 'eventwrap' (which can also be imported separately), so we document those here too.

Activity

The olpcgames.activity module encapsulates creation of a Pygame activity. Your Activity should inherit from this class. Simply setting some class attributes is all you need to do in a class inheriting from olpcgames.activity.PyGameActivity in order to get Pygame to work.

class PyGameActivity(activity.Activity):
        
    game_name = None
    game_title = 'PyGame Game'
    game_handler = None
    game_size = (units.grid_to_pixels(16),
                 units.grid_to_pixels(11))
    pygame_mode = 'SDL'

You need to set these:

game_name: This is a string containing the name of the module and, optionally a colon followed by the name of the main method (example: "tictactoe:main"). If there's no main method specified it defaults to "main". In this example, the wrapper code will import the module named "tictactoe" and call main() on it. That is expected to enter a Pygame main loop (which makes some call into pygame.event periodically, see Pygame wrapper#Eventwrap).

game_title: This is the string containing the title of the game, as it appears in the Sugar toolbar at the top of activities.

game_size: Pixel resolution of your game window. This is not changeable at runtime. This needs to match whatever you pass to pygame.display.set_mode(), and you cannot call set_mode() later with a different size.

These are optional:

pygame_mode can be set to 'Cairo' if you want experimental Cairo pygame support. In this case you need to include 'pygamecairo' module accessible from your game. This is not recommended as Cairo is quite slow.

game_handler is a deprecated synonym for game_mode.

Canvas

The canvas submodule handles wrapping events and initializing SDL inside the container.

class PyGameCanvas(gtk.EventBox):
    pass

There's nothing you probably need to interact with in the canvas submodule.

Eventwrap

The 'eventwrap' module is a replacement for pygame.event. It has much of the same interface (see [[1]]). See the doc-strings of these methods for full documentation; I'll point out the differences here:

There is an install() method which installs eventwrap in place of pygame.event, so that unaware Pygame applications will use this event queue rather than the native Pygame one. Performance is mostly unaffected, and this event queue is more versatile than Pygame's. Thus, we do this for all Pygame games as part of the Activity wrapper.

This event queue does not support getting events only of a certain type. You need to get all pending events at a time, or filter them yourself. You can, however, block and unblock events of certain types, so that may be useful to you. Set_grab doesn't do anything (you are not allowed to grab events). Sorry.