Pygame Tutorials
Line By Line Chimp

by Pete Shinners
pete@shinners.org

Revision 2.1, January 9, 2001



Introduction

In the pygame examples there is a simple example named, "chimp". This example simulates a punchable monkey moving around a small screen with promises of riches and reward. The example itself is very simple, and a bit thin on errorchecking code. This example program demonstrates many of pygame's abilities, like creating a graphics window, loading images and sound files, rendering TTF text, and basic event and mouse handling.
 
The program and images can be found inside the standard source distribution of pygame. For version 1.3 of pygame, this example was completely rewritten to add a couple more features and correct error checking. This about doubled the size of the original example, but now gives us much more to look at, as well as code the I can recommend reusing for your own projects.

This tutorial will go through the code block by block. Explaining how the code works. There will also be mention of how the code could be improved and what errorchecking could help out.
 
This is an exellent tutorial for people getting their first look at the pygame code. Once pygame is fully installed, you can find and run the chimp demo for yourself in the examples directory.

(no, this is not a banner ad, its the screenshot)
Chimp Screenshot
Full Source


Import Modules

This is the code that imports all the needed modules into your program. It also checks for the availability of some of the optional pygame modules.

import os, sys
import pygame
from pygame.locals import *

if not pygame.font: print 'Warning, fonts disabled'
if not pygame.mixer: print 'Warning, sound disabled'

First, we import the standard "os" and "sys" python modules. These allow us to do things like create platform independent file paths.

In the next line, we import the pygame package. When pygame is imported it imports all the modules belonging to pygame. Some pygame modules are optional, and if they aren't found, their value is set to "None".

There is a special pygame module named "locals". This module contains a subset of pygame. The members of this module are commonly used constants and functions that have proven useful to put into your program's global namespace. This locals module includes functions like "Rect" to create a rectangle object, and many constants like "QUIT, HWSURFACE" that are used to interact with the rest of pygame. Importing the locals module into the global namespace like this is entirely optional. If you choose not to import it, all the members of locals are always available in the pygame module.

Lastly, we decide to print a nice warning message if the font or sound modules in pygame are not available.

Loading Resources

Here we have two functions we can use to load images and sounds. We will look at each function individually in this section.

def load_image(name, colorkey=None):
    fullname = os.path.join('data', name)
    try:
        image = pygame.image.load(fullname)
    except pygame.error, message:
        print 'Cannot load image:', name
        raise SystemExit, message
    image = image.convert()
    if colorkey is not None:
        if colorkey is -1:
            colorkey = image.get_at((0,0))
        image.set_colorkey(colorkey, RLEACCEL)
    return image, image.get_rect()

This function takes the name of an image to load. It also optionally takes an argument it can use to set a colorkey for the image. A colorkey is used in graphics to represent a color of the image that is transparent.

The first thing this function does is create a full pathname to the file. In this example all the resources are in a "data" subdirectory. By using the os.path.join function, a pathname will be created that works for whatever platform the game is running on.

Next we load the image using the pygame.image.load function. We wrap this function in a try/except block, so if there is a problem loading the image, we can exit gracefully. After the image is loaded, we make an important call to the convert() function. This makes a new copy of a Surface and converts its color format and depth to match the display. This means blitting the image to the screen will happen as quickly as possible.

Last, we set the colorkey for the image. If the user supplied an argument for the colorkey argument we use that value as the colorkey for the image. This would usually just be a color RGB value, like (255, 255, 255) for white. You can also pass a value of -1 as the colorkey. In this case the function will lookup the color at the topleft pixel of the image, and use that color for the colorkey.

def load_sound(name):
    class NoneSound:
        def play(self): pass
    if not pygame.mixer:
        return NoneSound()
    fullname = os.path.join('data', name)
    try:
        sound = pygame.mixer.Sound(fullname)
    except pygame.error, message:
        print 'Cannot load sound:', wav
        raise SystemExit, message
    return sound

Next is the function to load a sound file. The first thing this function does is check to see if the pygame.mixer module was imported correctly. If not, it returns a small class instance that has a dummy play method. This will act enough like a normal Sound object for this game to run without any extra error checking.

This function is similar to the image loading function, but handles some different problems. First we create a full path to the sound image, and load the sound file inside a try/except block. Then we simply return the loaded Sound object.

Game Object Classes

Here we create two classes to represent the objects in our game. Almost all the logic for the game goes into these two classes. We will look over them one at a time here.

class Fist(pygame.sprite.Sprite):
    """moves a clenched fist on the screen, following the mouse"""
    def __init__(self):
        pygame.sprite.Sprite.__init__(self) #call Sprite initializer
        self.image, self.rect = load_image('fist.bmp', -1)
        self.punching = 0

    def update(self):
        "move the fist based on the mouse position"
        pos = pygame.mouse.get_pos()
        self.rect.midtop = pos
        if self.punching:
            self.rect.move_ip(5, 10)

    def punch(self, target):
        "returns true if the fist collides with the target"
        if not self.punching:
            self.punching = 1
            hitbox = self.rect.inflate(-5, -5)
            return hitbox.colliderect(target.rect)

    def unpunch(self):
        "called to pull the fist back"
        self.punching = 0

Here we create a class to represent the players fist. It is derived from the Sprite class included in the pygame.sprite module. The __init__ function is called when new instances of this class are created. The first thing we do is be sure to call the __init__ function for our base class. This allows the Sprite's __init__ function to prepare our object for use as a sprite. This game uses one of the sprite drawing Group classes. These classes can draw sprites that have an "image" and "rect" attribute. By simply changing these two attributes, the renderer will draw the current image at the current position.

All sprites have an update() method. This function is typically called once per frame. It is where you should put code that moves and updates the variables for the sprite. The update() method for the fist moves the fist to the location of the mouse pointer. It also offsets the fist position slightly if the fist is in the "punching" state.

The following two functions punch() and unpunch() change the punching state for the fist. The punch() method also returns a true value if the fist is colliding with the given target sprite.

class Chimp(pygame.sprite.Sprite):
    """moves a monkey critter across the screen. it can spin the
       monkey when it is punched."""
    def __init__(self):
        pygame.sprite.Sprite.__init__(self) #call Sprite intializer
        self.image, self.rect = load_image('chimp.bmp', -1)
        screen = pygame.display.get_surface()
        self.area = screen.get_rect()
        self.rect.bottomright = self.area.bottomright
        self.move = 9
        self.dizzy = 0

    def update(self):
        "walk or spin, depending on the monkeys state"
        if self.dizzy:
            self._spin()
        else:
            self._walk()

    def _walk(self):
        "move the monkey across the screen, and turn at the ends"
        newpos = self.rect.move((self.move, 0))
        if not self.area.contains(newpos):
            self.move = -self.move
            newpos = self.rect.move((self.move, 0))
            self.image = pygame.transform.flip(self.image, 1, 0)
        self.rect = newpos

    def _spin(self):
        "spin the monkey image"
        center = self.rect.center
        self.dizzy += 12
        if self.dizzy >= 360:
            self.dizzy = 0
            self.image = self.original
        else:
            rotate = pygame.transform.rotate
            self.image = rotate(self.original, self.dizzy)
        self.rect = self.image.get_rect()
        self.rect.center = center

    def punched(self):
        "this will cause the monkey to start spinning"
        if not self.dizzy:
            self.dizzy = 1
            self.original = self.image

The chimp class is doing a little more work than the fist, but nothing more complex. This class will move the chimp back and forth across the screen. When the monkey is punched, he will spin around to exciting effect. This class is also derived from the base Sprite class, and is initialized the same as the fist. While initializing, the class also sets the attribute "area" to be the size of the display screen.

The update function for the chimp simply looks at the current "dizzy" state, which is true when the monkey is spinning from a punch. It calls either the _spin or _walk method. These functions are prefixed with an underscore. This is just a standard python idiom which suggests these methods should only be used by the Chimp class. We could go so far as to give them a double underscore, which would tell python to really try to make them private methods, but we don't need such protection. :)

The walk method creates a new position for the monkey by moving the current rect by a given offset. If this new position crosses outside the display area of the screen, it reverses the movement offset. It also mirrors the image using the pygame.transform.flip function. This is a crude effect that makes the monkey look like he's turning the direction he is moving.

The spin method is called when the monkey is currently "dizzy". The dizzy attribute is used to store the current amount of rotation. When the monkey has rotated all the way around (360 degrees) it resets the monkey image back to the original unrotated version. Before calling the transform.rotate function, you'll see the code makes a local reference to the function simply named "rotate". There is no need to do that for this example, it is just done here to keep the following line's length a little shorter. Note that when calling the rotate function, we are always rotating from the original monkey image. When rotating, there is a slight loss of quality. Repeatedly rotating the same image and the quality would get worse each time. Also, when rotating an image, the size of the image will actually change. This is because the corners of the image will be rotated out, making the image bigger. We make sure the center of the new image matches the center of the old image, so it rotates without moving.

The last method is punched() which tells the sprite to enter its dizzy state. This will cause the image to start spinning. It also makes a copy of the current image named "original".

Initialize Everything

Before we can do much with pygame, we need to make sure its modules are initialized. In this case we will also open a simple graphics window. Now we are in the main() function of the program, which hat color for the colorkey.

def load_sound(name):
    class NoneSound:
        def play(self): pass
    if not pygame.mixer:
        return NoneSound()
    fullname = os.path.join('data', name)
    try:
        sound = pygame.mixer.Sound(fullname)
    except pygame.error, message:
        print 'Cannot load sound:', wav
        raise SystemExit, message
    return sound

Next is the function to load a sound file. The first thing this function does is check to see if the pygame.mixer module was imported correctly. If not, it returns a small class instance that has a dummy play method. This will act enough like a normal Sound object for this game to run without any extra error checking.

This function is similar to the image loading function, but handles some different problems. First we create a full path to the sound image, and load the sound file inside a try/except block. Then we simply return the loaded Sound object.

Game Object Classes

Here we create two classes to represent the objects in our game. Almost all the logic for the game goes into these two classes. We will look over them one at a time here.

class Fist(pygame.sprite.Sprite):
    """moves a clenched fist on the screen, following the mouse"""
    def __init__(self):
        pygame.sprite.Sprite.__init__(self) #call Sprite initializer
        self.image, self.rect = load_image('fist.bmp', -1)
        self.punching = 0

    def update(self):
        "move the fist based on the mouse position"
        pos = pygame.mouse.get_pos()
        self.rect.midtop = pos
        if self.punching:
            self.rect.move_ip(5, 10)

    def punch(self, target):
        "returns true if the fist collides with the target"
        if not self.punching:
            self.punching = 1
            hitbox = self.rect.inflate(-5, -5)
            return hitbox.colliderect(target.rect)

    def unpunch(self):
        "called to pull the fist back"
        self.punching = 0

Here we create a class to represent the players fist. It is derived from the Sprite class included in the pygame.sprite module. The __init__ function is called when new instances of this class are created. The first thing we do is be sure to call the __init__ function for our base class. This allows the Sprite's __init__ function to prepare our object for use as a sprite. This game uses one of the sprite drawing Group classes. These classes can draw sprites that have an "image" and "rect" attribute. By simply changing these two attributes, the renderer will draw the current image at the current position.

All sprites have an update() method. This function is typically called once per frame. It is where you should put code that moves and updates the variables for the sprite. The update() method for the fist moves the fist to the location of the mouse pointer. It also offsets the fist position slightly if the fist is in the "punching" state.

The following two functions punch() and unpunch() change the punching state for the fist. The punch() method also returns a true value if the fist is colliding with the given target sprite.

class Chimp(pygame.sprite.Sprite):
    """moves a monkey critter across the screen. it can spin the
       monkey when it is punched."""
    def __init__(self):
        pygame.sprite.Sprite.__init__(self) #call Sprite intializer
        self.image, self.rect = load_image('chimp.bmp', -1)
        screen = pygame.display.get_surface()
        self.area = screen.get_rect()
        self.rect.bottomright = self.area.bottomright
        self.move = 9
        self.dizzy = 0

    def update(self):
        "walk or spin, depending on the monkeys state"
        if self.dizzy:
            self._spin()
        else:
            self._walk()

    def _walk(self):
        "move the monkey across the screen, and turn at the ends"
        newpos = self.rect.move((self.move, 0))
        if not self.area.contains(newpos):
            self.move = -self.move
            newpos = self.rect.move((self.move, 0))
            self.image = pygame.transform.flip(self.image, 1, 0)
        self.rect = newpos

    def _spin(self):
        "spin the monkey image"
        center = self.rect.center
        self.dizzy += 12
        if self.dizzy >= 360:
            self.dizzy = 0
            self.image = self.original
        else:
            rotate = pygame.transform.rotate
            self.image = rotate(self.original, self.dizzy)
        self.rect = self.image.get_rect()
        self.rect.center = center

    def punched(self):
        "this will cause the monkey to start spinning"
        if not self.dizzy:
            self.dizzy = 1
            self.original = self.image

The chimp class is doing a little more work than the fist, but nothing more complex. This class will move the chimp back and forth across the screen. When the monkey is punched, he will spin around to exciting effect. This class is also derived from the base Sprite class, and is initialized the same as the fist. While initializing, the class also sets the attribute "area" to be the size of the display screen.

The update function for the chimp simply looks at the current "dizzy" state, which is true when the monkey is spinning from a punch. It calls either the _spin or _walk method. These functions are prefixed with an underscore. This is just a standard python idiom which suggests these methods should only be used by the Chimp class. We could go so far as to give them a double underscore, which would tell python to really try to make them private methods, but we don't need such protection. :)

The walk method creates a new position for the monkey by moving the current rect by a given offset. If this new position crosses outside the display area of the screen, it reverses the movement offset. It also mirrors the image using the pygame.transform.flip function. This is a crude effect that makes the monkey look like he's turning the direction he is moving.

The spin method is called when the monkey is currently "dizzy". The dizzy attribute is used to store the current amount of rotation. When the monkey has rotated all the way around (360 degrees) it resets the monkey image back to the original unrotated version. Before calling the transform.rotate function, you'll see the code makes a local reference to the function simply named "rotate". There is no need to do that for this example, it is just done here to keep the following line's length a little shorter. Note that when calling the rotate function, we are always rotating from the original monkey image. When rotating, there is a slight loss of quality. Repeatedly rotating the same image and the quality would get worse each time. Also, when rotating an image, the size of the image will actually change. This is because the corners of the image will be rotated out, making the image bigger. We make sure the center of the new image matches the center of the old image, so it rotates without moving.

The last method is punched() which tells the sprite to enter its dizzy state. This will cause the image to start spinning. It also makes a copy of the current image named "original".

Initialize Everything

Before we can do much with pygame, we need to make sure its modules are initialized. In this case we will also open a simple graphics window. Now we are in the main() function of the program, which hat color for the colorkey.

def load_sound(name):
    class NoneSound:
        def play(self): pass
    if not pygame.mixer:
        return NoneSound()
    fullname = os.path.join('data', name)
    try:
        sound = pygame.mixer.Sound(fullname)
    except pygame.error, message:
        print 'Cannot load sound:', wav
        raise SystemExit, message
    return sound

Next is the function to load a sound file. The first thing this function does is check to see if the pygame.mixer module was imported correctly. If not, it returns a small class instance that has a dummy play method. This will act enough like a normal Sound object for this game to run without any extra error checking.

This function is similar to the image loading function, but handles some different problems. First we create a full path to the sound image, and load the sound file inside a try/except block. Then we simply return the loaded Sound object.

Game Object Classes

Here we create two classes to represent the objects in our game. Almost all the logic for the game goes into these two classes. We will look over them one at a time here.

class Fist(pygame.sprite.Sprite):
    """moves a clenched fist on the screen, following the mouse"""
    def __init__(self):
        pygame.sprite.Sprite.__init__(self) #call Sprite initializer
        self.image, self.rect = load_image('fist.bmp', -1)
        self.punching = 0

    def update(self):
        "move the fist based on the mouse position"
        pos = pygame.mouse.get_pos()
        self.rect.midtop = pos
        if self.punching:
            self.rect.move_ip(5, 10)

    def punch(self, target):
        "returns true if the fist collides with the target"
        if not self.punching:
            self.punching = 1
            hitbox = self.rect.inflate(-5, -5)
            return hitbox.colliderect(target.rect)

    def unpunch(self):
        "called to pull the fist back"
        self.punching = 0

Here we create a class to represent the players fist. It is derived from the Sprite class included in the pygame.sprite module. The __init__ function is called when new instances of this class are created. The first thing we do is be sure to call the __init__ function for our base class. This allows the Sprite's __init__ function to prepare our object for use as a sprite. This game uses one of the sprite drawing Group classes. These classes can draw sprites that have an "image" and "rect" attribute. B