Game development HOWTO: Difference between revisions
No edit summary |
(better categories) |
||
(69 intermediate revisions by 23 users not shown) | |||
Line 1: | Line 1: | ||
{{Developers}} |
|||
This HOWTO is current as-of the first OLPC Game Jam at Olin College on June 8, 2007. Please update it as you learn. |
|||
<< [[Tutorials]] |
|||
This document describes how to use the [[Pygame]] library for Python for [[game development]] -- to create a new game [[activity]] for OLPC's [[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]]. |
|||
==Development Environment== |
|||
If you are looking to create a slightly more limited Activity, you may want to check out [[Pippy]]'s Pygame capabilities. |
|||
This HOWTO is current as of December 2007. More recent notes are available at [[Porting pygame games to the XO]] (from March 2008). |
|||
You don't need a laptop for simple Pygame development. When creating your Pygame game, use this boilerplate: |
|||
= Requirements = |
|||
import pygame |
|||
pygame.init() |
|||
def main(): |
|||
# Start Pygame displays... |
|||
# screen = pygame.display.set_mode((600,600)) |
|||
while True: |
|||
# Pygame event loop. |
|||
pass |
|||
if __name__=="__main__": |
|||
main() |
|||
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. |
|||
The 'main' method will be called by the activity wrapper later on, so it must be called 'main'. |
|||
== Components == |
|||
If you want to test on a laptop, you could set up an [[emulated environment][Emulating the XO]]. Or you could check out a laptop from the organizers at the game jam and use that. |
|||
* [[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. |
|||
To make your game run as an Activity, check out the existing Pygame activities from Coderanger's Subversion repository: |
|||
** The [http://dev.laptop.org/~coderanger/ slides from Noah's lecture] at the start of the game jam are online at (both PDF and PowerPoint form). |
|||
** [[Pygame/Mac setup instructions]] |
|||
* [[Pygame wrapper|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 [http://dev.laptop.org/~mcfletch/OLPCGames/ 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 == |
|||
svn co https://coderanger.net/svn/projects/olpc/games olpcgames |
|||
You will need a working Sugar [[Developers/Setup|Developer's]] 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. |
|||
The steps you need to follow are: |
|||
* You'll need to set aside a few hours to [http://www.eng.hawaii.edu/Tutor/vi.html 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. |
|||
* cp -r TicTacToe.activity MyActivity.activity |
|||
* Put your Pygame program into the directory and remove tictactoe.py |
|||
* Edit activity.py. game_name should be set to the name of your Pygame program (i.e., a python module to load and call main() on). Edit other files and fields relating specifically to Tic-Tac-Toe and change them to your game name. |
|||
* Get your game onto your laptop or emulated environment, in the /home/olpc/Activities folder (see below) |
|||
* Restart X on the laptop via ctrl+alt+erase |
|||
* Journal starts up on boot; you may want to kill it with alt+C to return to the Sugar startup screen |
|||
* Run your activity by clicking its icon at the bottom of the Frame. (Mouse to a corner of the screen to see the Frame.) |
|||
= Skeleton Setup = |
|||
There are several possible ways to get the game onto the laptop. |
|||
To start, you will likely want to download the [http://dev.laptop.org/~mcfletch/OLPCGames/ OLPCGames source package]. This package includes a skeleton script that lets you generate a new OLPCGames-based Pygame Activity with a single command. |
|||
If you're using an emulated environment, simply copy it to your shared folder if you have one. (You could even check out the olpcgames directory into the emulated environment's Activities folder, which is convenient.) |
|||
== Getting the Skeleton Script == |
|||
If you have a network, you can copy it via SCP. |
|||
To install the package, you will need to download the .zip or .tar.gz to your machine and extract it with either of: |
|||
If you have a USB stick, copy the Activity onto the usb stick on your PC and unmount it (if your USB stick's filesystem doesn't support symbolic links, you will need to copy the 'olpcgames' directory to each of the .activity subdirectories that you intend to run). Put it into the XO. Enter the Developer console using alt+0. Go to Terminal. Mount the drive: 'mkdir -p /media/sda1; mount /dev/sda1 /media/sda1' and then copy the activity and the 'olpcgames' directory (if not symlinked) to your Activities directory. |
|||
unzip OLPCGames-1.4.zip |
|||
Remember, the first time you run an activity, X needs to be restarted before it will be findable through the GUI. |
|||
or |
|||
==Hardware== |
|||
tar -zxf OLPCGames-1.4.tar.gz |
|||
The [[Pygame]] page has some information on hardware. |
|||
which will create a directory named OLPCGames-1.4. Change to the skeleton directory: |
|||
===Camera=== |
|||
cd OLPCGames-1.4/skeleton |
|||
The camera only works through GTK, so you cannot simply modify your Pygame code. This is not a recipe -- more like some ideas of how you might get it working. |
|||
Make sure that your python file has the required permissions to be used. |
|||
Get the source of the Camera activity through the [[Red Hat Activities download page] [http://olpc.download.redhat.com/activities/]] and unzip it (.xo files are just zip files) |
|||
chmod a+x buildskel.py |
|||
You want the module 'glive.py'. This module implements live camera streaming inside GTK. Look at how the Camera activity uses it, and at the takePic method. That's how you get a picture out of the camera. You'll need to put in some hooks to analyze it somehow. Good luck. |
|||
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. Type Esc to exit. |
|||
== 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'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). |
|||
== Customizing 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 [http://www.vrplumber.com/sugar-docs/olpcgames.activity.html#PyGameActivity 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. You should now, largely, be able to use standard Pygame code to produce graphics, play sounds, and process input. |
|||
== Pygame Examples and Tutorials == |
|||
Example Activities: |
|||
* [http://dev.laptop.org/git?p=projects/games-misc;a=blob;f=FileTest.activity/run.py;hb=HEAD Journal/File Test] -- example of using the [[Journal]] to save/restore state for an activity |
|||
* [http://dev.laptop.org/git?p=projects/games-misc;a=blob;f=cameratest.activity/run.py;hb=HEAD Camera Test] -- example of using the <code>olpcgames.camera</code> module [http://dev.laptop.org/~mcfletch/testactivities/cameratest-1.xo XO] |
|||
* [http://dev.laptop.org/git?p=projects/games-misc;a=blob;f=soundtest.activity/run.py;hb=HEAD Sound Test] -- example showing simple multi-channel sound usage [http://dev.laptop.org/~mcfletch/testactivities/soundtest-1.xo XO] |
|||
* [http://dev.laptop.org/git?p=projects/games-misc;a=blob;f=svgspritetest.activity/run.py;hb=HEAD SVG Sprite Test] -- example showing use of the <code>olpcgames.svgsprite</code> module [http://dev.laptop.org/~mcfletch/testactivities/svgspritetest-1.xo XO] |
|||
* [http://dev.laptop.org/git?p=projects/games-misc;a=blob;f=videotest.activity/run.py;hb=HEAD Video Test] -- example showing use of the [[GStreamer]]-based <code>olpcgames.video</code> module [http://dev.laptop.org/~mcfletch/testactivities/videotest-2.xo XO] |
|||
''Tutorials'': |
|||
* [http://www.pygame.org/wiki/tutorials Pygame Tutorials] -- a wiki-based collection of tutorials for learning Pygame programming |
|||
* [http://rene.f0o.com/mywiki/PythonGameProgramming 5-part Tutorial] -- a fairly extensive tutorial on Pygame usage |
|||
* [http://www.pygame.org/docs Pygame Documentation] -- the official collection of Pygame documentation, you will need this to get any Pygame programming done |
|||
* [[Game templates]] -- serves as a starting point for creating Pygame games |
|||
*[[OLPCGames#Activities|OLPCGames-based Activities]] can often be read to find sample code. |
|||
== Reference Links == |
|||
* [[Pygame wrapper]] [http://www.vrplumber.com/sugar-docs/olpcgames.html 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 |
|||
* If you are new to game and GUI programming, you may wish to use a [http://www.pygame.org/wiki/gui Pygame GUI engine] to simplify creating buttons, text entry boxes and the like. |
|||
= Support = |
|||
If you have questions, suggestions or problems, please feel free to post to the [http://lists.laptop.org/listinfo/games 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. |
|||
= Reducing CPU Load = |
|||
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: |
|||
events = pausescreen.get_events() |
|||
for event in events: |
|||
which allows your activity to go completely quiet if there are no pending events for a given time, but still processes all pending events in a timely manner. |
|||
You can see the code that implements this in the olpcgames.pausescreen module. None of that machinery 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. |
|||
* Read more about [[Monitoring System Load]] |
|||
== Eliminating Mouse-move Events == |
|||
If your activity does not use MOUSEMOTION events it is possible to reduce the overall number of events processed (you can combine this with using a <code>pygame.event.wait()</code> event loop as well. Keep in mind that with this optimization you cannot do mouse-over highlighting or the like. |
|||
An example code structure might look like this: |
|||
import sys |
|||
import pygame |
|||
from pygame.locals import * |
|||
def main(): |
|||
window = pygame.display.set_mode((400, 225)) |
|||
pygame.event.set_blocked(MOUSEMOTION) |
|||
pygame.init() |
|||
while True: |
|||
for event in [ pygame.event.wait() ] + pygame.event.get( ): |
|||
print event |
|||
if event.type == KEYUP: |
|||
# Quit on 'q' |
|||
if event.key == 113: sys.exit(0) |
|||
if __name__=="__main__": |
|||
main() |
|||
== Extending PyGame with C++ == |
|||
===Mesh or Connection to Internet=== |
|||
See [[Extending PyGame with C++]] for instructions on how to mix Python and C++ code for better performance. |
|||
You'll want to discover peers and communicate with them through Tubes. More information about Tubes will be forthcoming, but note that it's very unstable on the laptops we have, so you should not really rely on it. (You can of course use IP networking, but the mesh API is unlikely to be available for this conference.) |
|||
=Troubleshooting= |
|||
For this weekend the most reliable internet connection has been to connect to the ap called 'OLIN_GUEST' with the WEP key on the blackboard. We tried to use a wired MAC that advertised an Access Point, but the connections from the XO were not stable. |
|||
Ensure you are using at least an Update.2 (first manufacturing release) Sugar environment. Also ensure you are using a recent version of OLPCGames. |
|||
You may find that the XO needs to be upgraded to q2c12.rom firmware and nand432.img nand. Some people were having trouble getting the WEP key to work with the 406 nand. |
|||
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. |
|||
[[Category: |
[[Category:Python]] |
||
[[Category:HowTo]] |
[[Category:HowTo]] |
||
[[Category: |
[[Category:Developing games]] |
Latest revision as of 10:39, 20 November 2008
<< Tutorials
This document describes how to use the Pygame library for Python for game development -- to create a new game activity for OLPC's 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.
If you are looking to create a slightly more limited Activity, you may want to check out Pippy's Pygame capabilities.
This HOWTO is current as of December 2007. More recent notes are available at Porting pygame games to the XO (from March 2008).
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).
- Pygame/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 Developer's 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 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.4.zip
or
tar -zxf OLPCGames-1.4.tar.gz
which will create a directory named OLPCGames-1.4. Change to the skeleton directory:
cd OLPCGames-1.4/skeleton
Make sure that your python file has the required permissions to be used.
chmod a+x buildskel.py
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. Type Esc to exit.
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'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).
Customizing 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. You should now, largely, be able to use standard Pygame code to produce graphics, play sounds, and process input.
Pygame Examples and Tutorials
Example Activities:
- Journal/File Test -- example of using the Journal to save/restore state for an activity
- 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
Tutorials:
- 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
- Game templates -- serves as a starting point for creating Pygame games
- OLPCGames-based Activities can often be read to find sample code.
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
- 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.
Support
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.
Reducing CPU Load
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:
events = pausescreen.get_events() for event in events:
which allows your activity to go completely quiet if there are no pending events for a given time, but still processes all pending events in a timely manner.
You can see the code that implements this in the olpcgames.pausescreen module. None of that machinery 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.
- Read more about Monitoring System Load
Eliminating Mouse-move Events
If your activity does not use MOUSEMOTION events it is possible to reduce the overall number of events processed (you can combine this with using a pygame.event.wait()
event loop as well. Keep in mind that with this optimization you cannot do mouse-over highlighting or the like.
An example code structure might look like this:
import sys import pygame from pygame.locals import * def main(): window = pygame.display.set_mode((400, 225)) pygame.event.set_blocked(MOUSEMOTION) pygame.init() while True: for event in [ pygame.event.wait() ] + pygame.event.get( ): print event if event.type == KEYUP: # Quit on 'q' if event.key == 113: sys.exit(0) if __name__=="__main__": main()
Extending PyGame with C++
See Extending PyGame with C++ for instructions on how to mix Python and C++ code for better performance.
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.