Pygame wrapper

  For Developers

<< API Reference

OLPCGames sources in projects/games-misc Tickets all - active - new Mike Fletcher Download

The Pygame wrapper for the OLPC Sugar platform is called OLPCGames. The Game development HOWTO describes how to use the wrapper to quickly create a skeletal Activity which has a basic Pygame event loop. This page explores the differences between standard Pygame programming and OLPCGames-mediated Pygame programming.

The automatically generated Pydoc documentation for OLPCGames is the canonical reference work for the documentation.

Getting the wrapper

You can either download the wrapper as a .zip or .tar.gz

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

or you can check it out of the git repository on dev.laptop.org (note, do not attempt this on an XO or other space-constrained device, GIT downloads the entire history of the project, which is over 120MB in this case).

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, mesh, and pangofont. The wrapper also replaces certain Python modules (e.g. pygame.event with 'eventwrap' (which can also be imported separately)), so we document those here too.

Activities

The following Activities use OLPCGames and can serve as example code, (note that some of these projects may not be finished yet):

• 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.
• Maze -- Maze navigation game

• Camera Test -- example of using the olpcgames.camera module XO
• Sound Test -- example showing simple multi-channel sound usage XO

• SVG Sprite Test -- example showing use of the olpcgames.svgsprite module XO

• Video Test -- example showing use of the GStreamer-based olpcgames.video module XO

Differences from Pygame

The SDL Pygame wrapper allows for nested Pygame windows using a separate thread. It forwards GTK events and converts them to Pygame events. Games under the wrapper may not work exactly the same way and porting is not completely seamless -- you should be aware of a few OLPC-specific caveats:

• You cannot set the display mode using pygame.display.set_mode. You must set it in the wrapper boilerplate instead (see Game development HOWTO).

• It is not recommended that you use the regular Pygame.font text drawing. You can use the wrapper to draw text using the 'olpcgames.pangofont' module instead which supports proper internationalization. See Pangofont.

• The event module is shadowed by Eventwrap and some methods may not work exactly the same. Certain methods in pygame.mouse and pygame.key are also shadowed.

• There's no CD-ROM on OLPC-XOs, so the 'cdrom' module isn't generally useful.

Keyboard and Mouse

Keyboard and mouse work approximately as they do under Pygame. We simulate repeated key-down events when a key is held down for a period in order to simulate Pygame's operation.

The "gamepad" buttons on the left and right of the screen come in as Numpad number keys (i.e., pygame.K_KP1 through pygame.K_KP9):

D-Pad (left of screen)             Gamepad (right of screen)
  
      8                                    9       O
    4   6                                7   1   []  V
      2                                    3       X

The D-pad (directional pad) mappings make sense as the traditional arrow keys on the numeric keypad of 101-key keyboards. The gamepad mappings make sense when you realize that 9/3 are page-up/page-down and 7/1 are home/end. The d-pad has 8 directions of articulation. You detect the diagonals by looking for two keys pressed at the same time.

When designing your interfaces keep in mind that an OLPC-XO in tablet mode only has the eight "keys" above available (as well as a resize-and-rotate key, but that's already mapped by the operating system).

Keep in mind that your activities will need to be localized into many languages, so binding, for instance "p" to "produce" is sub-optimal. If possible provide a run-time configuration, or at least a localization-time configuration mechanism (such as a configuration file) that lets more natural keys be chosen for each language's keyboard.

OLPC-XO (B4) Hardware Notes

The D-Pad control is usable for general control operations, but it is not a precise/fast control device as seen on gaming console controllers. It often slips from a cardinal direction to the adjacent intermediate direction (i.e. from left to left+up). You should not expect a traditional "platformer" game to be played with this control without some heuristics to clean up the input.

The checkmark button (K_KP1) is far easier to click than the X button, so "click" for "fire" should likely be the checkmark rather than the X. (Which makes sense to English users, at least). The Game pad buttons are small and close enough that asking a user to rapidly switch between them will likely result in a lot of multiple-button push events. Again, some heuristic code would be needed to clean up the input.

Cursors

See Sugar Standard Icons for instructions on how to create and use a standard Sugar cursor within Pygame-based games. The arrow and hand cursor there should likely be sufficient for most games.

Antialiased Lines

The bit-depth chosen by the wrapper (16 bit on OLPC-XOs, normally) tends to make antialiased lines fail. The reason this is so hasn't been extensively investigated, so it's not known whether this is a hard-and-fast limitation, or just an optimization hint.

Journal Integration

OLPCGames produces events to tell you about Journal save/restore requests:

• pygame.USEREVENT
  • code = olpcgames.FILE_READ_REQUEST (OLPCGames 1.6+)
    • filename -- the filename to be read
    • metadata -- metadata object (dictionary like)
  • code = olpcgames.FILE_WRITE_REQUEST (OLPCGames 1.6+)
    • filename -- the filename to be read
    • metadata -- metadata object (dictionary like)

which are generated to allow you to save/restore to/from the Journal/Datastore on the OLPC.

Window Resizing

Window resizing doesn't work yet (i.e., resizing windows via the screen rotate button), but we will try to get this working soon.

Module Reference

The pydoc-generated documentation for the OLPCGames package serves as the canonical reference work at this point.

Customizing the Toolbar

If you want to add stuff to the standard toolbar you can override build_toolbar in your PyGameActivity subclass like this:

import pygame
import olpcgames
from sugar.graphics.toolbutton import ToolButton
from gettext import gettext as _

...

    def build_toolbar( self ):
        """Build our Activity toolbar for the Sugar system."""
        toolbar = super( MyActivityClass, self ).build_toolbar()
        
        # Add a button
        mybutton = ToolButton('activity-mybutton')  # put the icon file here: MyGame.activity/icons/activity-mybutton.svg
        mybutton.set_tooltip(_('Something'))
        mybutton.connect('clicked', self._mybutton_cb)
        toolbar.insert(mybutton, 2)
        mybutton.show()
        
        return toolbar

    def _ mybutton_cb(self, button):
        pygame.event.post(olpcgames.eventwrap.Event(pygame.USEREVENT, action='mybutton'))

Then in your event handler do this:

    if event.type == pygame.USEREVENT:
        if event.action == 'mybutton':
            self.dosomething()
        else:
            print "Unknown user event action:", event.action