PyGame Implementation Specification
 What this document is about
We want to enable game development in a way that allows a variety of levels of use.
- Beginners who want to experiment with game development techniques in a simple environment. This document does not consider this case.
- Slightly more advanced beginners and students who are starting to experiment with Python but might need a lot of handholding. This document is not primarily concerned with this case but may discuss it.
- Advanced students and game developers who want to code in Python and can handle an API and the API documentation. The rest of this document discusses this case.
- Hardcore professional game developers wanting to build games that push the limits of the OLPC and want to code in C or C++. This is discussed elsewhere: SDL Implementation
 Choice of API: PyGame
The overwhelming leader for Python game development is PyGame. PyGame is built upon SDL, which is a cross-platform library supporting a variety of game-related interfaces, including graphics, sound, video, and input devices. SDL has been implemented on a very wide variety of hardware.
PyGame works on most major computer systems and has been in use for some time. Some commercial games have shipped with PyGame, and a whole lot of tutorials and sample code, as well as open source games, have been written using PyGame.
In a world where we would like end users to be building their own games and developing for the OLPC environment, PyGame will give those users a leg up with all of the available material for game development. See Content and OLPC on open source software.
If you're thinking of developing games in Python for the OLPC, please start by prototyping them in PyGame. At the moment, there is no guarantee that the code will run unmodified, but the port should be simple.
 API details
(undergoing editing and not yet finished)
 PyGame standard modules that will or should be included
- Cursors -- manages the hardware cursor. We may not need/want to support the load_xbm module; instead we may want to add support for a standard image file format supported by the tools on the XO.
- Display -- required support for setting up a display, but the number of modes is limited and the fullscreen option should be ignored. Existing PyGame code that tries to set up displays intelligently should still work if it was coded correctly, but all roads should probably lead to the same display setup result.
- Draw -- line and shape drawing. Antialiased color lines may need special attention because of the characteristics of the display.
- Event -- event handling. In the long run, we want to integrate this into Sugar so that the events play nice with Sugar / GTK.
- Font -- we want some font handling to support the platform fonts, but I don't know the platform story on this. We'll make it easy to use the platform's fonts from within this API.
- Image -- we'll support loading and processing images from whatever file formats are supported by standard platform libraries. We especially want to make sure it's easy to use the file formats created by the tools on the platform.
- Key -- we'll support the keyboard, including the game keys.
- Mixer -- this is the sound mixer, supporting sound loading and playback for certain standard formats. Again, we should make sure we can play formats that can be created on the device, and remove support for formats that are too big or obscure.
- Mouse -- obviously, we'll support the trackpad. Can the graphics tablet be supported by the same API?
- Music -- This supports streaming of larger sound files and mod files through the mixer. We should look at this carefully in terms of mod support -- what, if anything, can be or should be eliminated?
- Overlay -- Overlay is how video streams are supported in SDL. It may be the way we want to support display of images from the camera (or from other cameras over the mesh), but we may need additional or different support in order to be able to make use of the video for input, or for video manipulation.
- Pygame -- This is the initialization and teardown code, and must be fully supported.
- Rect -- Basic Rect object, no changes needed or wanted.
- Scrap -- interface to the system clipboard, and it would be nice to make it support (at some level) whatever Sugar is going to do along these lines. Worst case, it should be able to store and retrieve its own data formats so that a game that provides copy and paste through this mechanism will still work, even if it doesn't interoperate.
- Sprite -- The sprite system will be critical; we probably don't need changes in PyGame around sprites but we may need to work to make sure that the underlying SDL support makes the best possible use of the hardware. B3 units will contain a blitter and we should ensure that its capabilities are exposed to the sprite system.
- Surface -- Similar to sprites, we want to make sure we make the best possible use of the hardware available. This means testing the various surface modes to make sure that the right things happen for both performance and functionality, and then documenting how people can get the best performance out of the device.
- Time -- Basic time support, and no changes are anticipated.
- Transform -- Straightforward, useful, and unchanged, unless there are performance issues specific to the OLPC platform.
 PyGame standard modules that will not or may not be included
- Cdrom -- manages CD drives; we don't have a CD so no need or value for this API.
- Joystick -- There's no joystick-like device on the system, but do we want to have support available for external USB joysticks? Could we?
- Movie -- I don't think this is intended to be supported by the system, but even if it is we may want to leave it as a separate module.
- Surfarray -- Same drill as Sndarray -- if we have numeric, we should have this.
- Sndarray -- This is an interface to Python's Numeric module for sound manipulation. If we have Numeric, this should work, and might be very useful.
 Additional items that are not in PyGame but need support
- Mesh Networking -- easy way to search for neighbors and establish connections; two-player game setup should be trivial.
- Video camera as input device -- using the camera to get various types of information:
- average gray level, used for things like a theremin
- a histogram of colors
- track an area of constant color (can be a fun way to input things)
- Use the camera to get some sort of tilt / pan information (games like Marble Madness)
- Track pad as graphic input device (absolute rather than mouse)
- Mesh network signal strength information -- is this available? Could it be used, say, for a game of hide and seek?
<more to come -- kentquirk>