Python is an excellent language for rapid application development and prototyping. With Pygame, a wrapper built around SDL, the same can be true for games. In addition, because its built on top of Python and SDL, Pygame is highly portable. The only downside is it can be too slow for some computationally intensive types of games. If your game is too slow, the particular sub-routine(s) bringing down your execution speed can be rewritten in C/C++.

This article is intended to be a short introduction and by no means covers all there is to know about Pygame. Using a simple Space Invaders-type game, I present what I feel are the fundamentals of Pygame.

The first step in creating our game is to import Pygame and the other modules we need:

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

We need the os module for tasks related to opening files; the random module is needed for the AI of our enemy sprites, as we will see later. We then run import pygame, which imports all available Pygame modules from the Pygame package. The final line is optional and puts a subset of the most frequently used Pygame functions and constants into the global name space.

It may seem like we are skipping ahead here, but the last line of our program calls our main function, so we might as well get it out of the way now.

if __name__ == '__main__': main()

Next, we create our main function. The basic steps we are going to follow for our main function are initializing modules, loading game resources, preparing game objects and entering the game loop.

def main():
  random.seed()
  pygame.init()

random.seed() is called to initialize the random number generator. Optionally, one parameter can be given to random.seed(), and this parameter can be any hashable object. If the parameter is omitted or is listed as None, the system time is used.

pygame.init() attempts to initialize all the Pygame modules for you. All the Pygame modules do not need to be initialized, but this command automatically initializes the ones that do. Alternatively, you can initialize each Pygame module by hand.

Most modules have a quit() function that cleans up the module, but there is no need to call it manually, as there is with SDL. Pygame calls these functions automatically and exits cleanly when Python finishes.

The next part of our main function is creating the display surface. The surface is one of, if not the most, important elements of Pygame. A surface is like a canvas on which you can draw lines, images and so on. Surfaces can be any size, and you can have as many of them as you want. The first of the following three code lines creates the display surface. I have found that running the game in a window rather than in full screen mode is a good idea during development. This way, if your game crashes for some reason, you don't have to worry about the screen resolution being incorrect, among other possible problems. In the case that your game is played in a window rather than full-screen mode, the second line sets the title bar caption. The third line makes the mouse cursor invisible over the game window.

  screen = pygame.display.set_mode((640, 480), FULLSCREEN)
  pygame.display.set_caption('Space Game')
  pygame.mouse.set_visible(False)

To play the game in a window, remove the FULLSCREEN option as follows:

  screen = pygame.display.set_mode((640, 480))

Before we can create our background, we need to create a function to load images for us. For those new to programming, the load_image and the load_sound functions should be placed above the main function. Our function load_image takes the name of the image file as a parameter and, optionally, a color key. The color key tells Pygame that all pixels of a particular color should be transparent. In our game, we keep all of our images and sounds in a directory called data. The command os.path.join creates the complete path to our file, in a platform-independent manner. Then, we try to open the file.

From here, we convert our images to SDL's internal format, which greatly increases the speed at which images are blitted. This is so because SDL does not have to do the conversion on the fly every time the image is blitted. We then set the color key of the image, if we have one. If the color key is -1, the color of the pixel in the top left corner is used. Finally, we return the image and the rectangular object containing it.

def load_image(file_name, colorkey=None):
  full_name = os.path.join('data', file_name)

  try:
    image = pygame.image.load(full_name)
  except pygame.error, message:
    print 'Cannot load image:', full_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()

Next, we load the background image using the function we just defined. We then blit the image to our screen surface.

  background_image, background_rect = load_image('stars.bmp')
  screen.blit(background, (0,0))

We now create our function for loading the required sounds. Our function load sound takes the name of the file we want to load as the only parameter. The first thing we do is create a dummy class called 'No_Sound' that has a play method that does nothing. We then check if the mixer was imported and initialized correctly. If not, we return our dummy class. Then, we form our path to the file in the same way as was done for the load_image function. If the file exists, we load it; otherwise, we print a message to the terminal and return our dummy class. If we have made it to the end of the function without any problems, we return our sound object.

def load_sound(name):
  class No_Sound:
    def play(self): pass

  if not pygame.mixer or not pygame.mixer.get_init():
    return No_Sound()

  fullname = os.path.join('data', name)
  if os.path.exists(full_name) == False:
    sound = pygame.mixer.Sound(fullname)
  else:
    print 'File does not exist:', fullname
    return No_Sound

  return sound

We now can load our four sound effects using the function we just defined. We make shot 1 global, because it can be called from within our enemy sprite class.

  explode1 = load_sound("explode1.wav")
  explode2 = load_sound("explode2.wav")
  global shot1
  shot1 = load_sound("silent.wav")
  shot2 = load_sound("fx.wav")

Next, we create and initialize three different counters. The first one is required so as to know when the player has been killed, but the last two are needed only for our end-of-game stats.

  numberof_hits = 0
  numberof_shots = 0
  enemy_killed = 0

Now we create the player's ship sprite, all of the sprite groups and the enemy sprites present at the beginning of the game.

Pygame groups have containers used to hold sprites. There are several different classes of groups, each having different methods and properties. The group type that I use most is RenderClear, because it allows for the rendering of all sprites in the group as well as the clearing of them.

First, we create an instance for our Ship class, which we will define momentarily. Then, we create a group called playership_sprite that contains our ship object. Next, we create a group that holds all of our bomb sprites. The bomb_sprite group is empty, as there is no bomb sprite instances created until we actually fire. We then create our enemyship_sprites group and add three instances of class Enemy to it. The Enemy class takes the x-coordinate of the sprite as an argument to the init function; we will define this class momentarily as well. We then create our ebomb_sprite group, which stands for "enemy bomb". We also want the group to be accessible globally so we can access it from our enemy ship class.

  ship = Ship()
  playership_sprite = pygame.sprite.RenderClear(ship)
  bomb_sprites = pygame.sprite.RenderClear()

  enemyship_sprites = pygame.sprite.RenderClear()
  enemyship_sprites.add(Enemy(212))
  enemyship_sprites.add(Enemy(320))
  enemyship_sprites.add(Enemy(428))

  global ebomb_sprites
  ebomb_sprites = pygame.sprite.RenderClear()

We now define our sprite classes. As a reminder for those new to programming, the class definitions should be placed above the main function. All of our sprite classes consist of only to methods. The __init__ method is called when an instance of the class is created, and the update method is called every time we iterate over the game loop.

The first class we our going to define is the Ship class. In all of our sprite classes we want to inherit the Pygame sprite class, and in our init function we call the Pygame sprite __init__ function. We then load our image and set the center of our sprite to (320,450), which is the start location of the player's ship. Next, we set the number of pixels the image should move with each turn to zero.

class Ship(pygame.sprite.Sprite):
  """This class is for the players ship"""
  def __init__(self):
    pygame.sprite.Sprite.__init__(self) #call Sprite initalizer
    self.image, self.rect = load_image('ship.bmp', -1)
    self.rect.center = (320,450)
    self.x_velocity = 0
    self.y_velocity = 0

Now we move on to our update function. All we have to do in our update function is move the position of the sprite and then check to see if it has gone out of bounds. The move_ip method moves the rect object by a given offset. If the sprite has moved our of bounds, it is placed back inside the boundaries. The boundaries are approximately the bottom half of the screen.

  def update(self):
    self.rect.move_ip((self.x_velocity, self.y_velocity))

    if self.rect.left < 0:
      self.rect.left = 0
    elif self.rect.right > 640:
      self.rect.right = 640

    if self.rect.top <= 260:
      self.rect.top = 260
    elif self.rect.bottom >= 480:
      self.rect.bottom = 480

The enemy ship class is a little more complicated, as the update method contains the AI component of the enemy sprite. The class inherits the Pygame sprite class and calls the sprite init function as per usual. The init function takes the starting x position of the sprite. We then load the image of our enemy ship. The center of the rect object is set to the x value given and the y value to 120. The distance variable is used in the AI to know how many turns the ship should move in the same direction. The x and y velocities are initialized to zero, as they are in the player's ship class.

class Enemy(pygame.sprite.Sprite):
  """This class is for the enemy ships"""
  def __init__(self, startx):
    pygame.sprite.Sprite.__init__(self) #call Sprite intializer
    self.image, self.rect = load_image('eship.bmp', -1)
    self.rect.centerx = startx
    self.rect.centery = 120
    self.distance = 0
    self.x_velocity = 0
    self.y_velocity = 0

As I mentioned earlier, the update function contains the AI for our enemy sprites. This particular AI is based heavily on random numbers. The AI is quite simple but works well enough for our purposes in such a simple game. The AI works as follows. If the remaining distance our sprite has to move is zero, it selects a new random distance. The distance is how many iterations through the main game loop the sprite moves in the same direction. Then, a random x and y velocity is selected. It is possible that both the x and y velocities would both be zero, in which case the sprite would stand still for the number of turns indicated by the distance variable. We then move the rect object containing the sprite and decrease the distance remaining by one.

From here, we check to see if the sprite has moved out of bounds; if it has, it is the placed back in bounds. The boundaries basically are the top half of the screen. This ensures that enemy ships stay on the top half and the player says on the bottom, so we don't have to worry about collision detection between ships.

The last part of our AI component is firing. A random number is selected between 1 and 60; if the number 1 is selected the enemy ship fires. Firing is done by adding another enemy bomb sprite to the ebomb group. The new bomb is passed its starting location, which is the horizontal center and the bottom of the enemy ship. Last but certainly not least, the shot sound effect is played.

  def update(self):
    #movement
    if self.distance == 0:
      #random distance from 3 to 15 turns
      self.distance=random.randint(3,15)
      #random x,y velocity form -2 to 2
      self.x_velocity=random.randint(-2,2)
      self.y_velocity=random.randint(-2,2)    

    self.rect.move_ip((self.x_velocity, self.y_velocity))
    self.distance -= 1
    if self.rect.left < 0:
      self.rect.left = 0
    elif self.rect.right > 640:
      self.rect.right = 640

    if self.rect.top <= 0:
      self.rect.top = 0
    elif self.rect.bottom >= 220:
      self.rect.bottom = 220


    #random 1 - 60 determines if firing
    fire=random.randint(1,60)
    if fire == 1:
      ebomb_sprites.add(Ebomb(self.rect.midbottom))
      shot1.play()

Seeing as we are in the process of defining our sprites, we might as well create the last two. The bomb and enemy bomb classes are similar and probably could have been combined into one class. I decided to keep them separate for the sake of simplicity and clarity, which I felt to be more important aspects of this tutorial. In both classes the sprite initalizer is called, the appropriate image is loaded and the start position set. In the update method, we check if the player's bomb has gone off the top of the screen, and in the case of the enemy bomb, we see if it has gone off the bottom. If the bomb has gone off screen, the sprite deletes itself with the kill method. If the bomb still is on screen, it is moved four pixels up or down, respectively.

class bomb(pygame.sprite.Sprite):
  """This class is for the players weapons"""
  def __init__(self, startpos):
    pygame.sprite.Sprite.__init__(self) #call Sprite intializer
    self.image, self.rect = load_image('fire.bmp', -1)
    self.rect.center = startpos

  def update(self):
    if self.rect.bottom <= 0:
      self.kill()
    else:
      self.rect.move_ip((0, -4))


class Ebomb(pygame.sprite.Sprite):
  """This class is for the players weapons"""
  def __init__(self, startpos):
    pygame.sprite.Sprite.__init__(self) #call Sprite intializer
    self.image, self.rect = load_image('efire.bmp', -1)
    self.rect.midtop = startpos

  def update(self):
    if self.rect.bottom >= 480:
      self.kill()
    else:
      self.rect.move_ip((0, 4))

Let's get back to our main function. We now can create our game loop, but before we do, we must create two variables. The first one, running, is used as the condition for the while loop. To end the loop and thus exit the game, all we have to do is set the running value to zero. The other variable, counter, is used to see if it is time to add another enemy ship to the game. We then start the loop and add a delay of ten milliseconds to make sure that the game doesn't run too quickly. If you are using an older computer, the delay might be too long and should be lowered accordingly.

  running = 1
  counter = 0
  while running:
    pygame.time.delay(10)

The first thing we want to do in our loop is check for and cycle through any user events. The QUIT can be created many different ways, such as clicking the close button on the window frame if you're not playing in full-screen mode. All the other events come from the keyboard and are pretty self explanatory. In the case of the user pressing the f key, a new bomb sprite is added to the player's bomb group. The number of shots is increased by one, and this information is part of the game stats printed to the terminal window at the end of the game. We then play the shot sound affect.

for event in pygame.event.get():
      if event.type == QUIT:
        running = 0
      elif event.type == KEYDOWN:
        if event.key == K_ESCAPE:
          running = 0
        elif event.key == K_LEFT:
          ship.x_velocity = -2
        elif event.key == K_RIGHT:
          ship.x_velocity = 2
        elif event.key == K_UP:
          ship.y_velocity = -2
        elif event.key == K_DOWN:
          ship.y_velocity = 2
        elif event.key == K_f:
          bomb_sprites.add(bomb(ship.rect.midtop))
          numberof_shots += 1
          shot2.play()
      elif event.type == KEYUP:
        if event.key == K_LEFT:
          ship.x_velocity = 0
        elif event.key == K_RIGHT:
          ship.x_velocity = 0
        elif event.key == K_UP:
          ship.y_velocity = 0
        elif event.key == K_DOWN:
          ship.y_velocity = 0

To causes the game to last longer and encourage the player to work quickly, every 200 times through the loop we add another enemy ship at the center of the top half of the screen as shown below.

    counter += 1
    if counter >= 200:
      enemyship_sprites.add(Enemy(320))
      counter = 0

Clearing all the sprites from the screen is easy with the clear method, because our sprite groups are of the type RenderClear. The clear method takes two arguments. The first is the surface from which you want to clear the sprites, and the second argument is the surface that should be used as the background.

    ebomb_sprites.clear(screen, background_image)
    enemyship_sprites.clear(screen, background_image)
    bomb_sprites.clear(screen, background_image)
    playership_sprite.clear(screen, background_image)

We call the update method on all of our sprite groups, which in turn calls the update method of each sprite in that group. As we recall, the update method moves all of our sprites and makes any AI decisions required.

    bomb_sprites.update()
    playership_sprite.update()
    ebomb_sprites.update()
    enemyship_sprites.update()

Now that all of our sprites have been moved to their new positions, we can check for collisions between the player's bombs and enemy sprites, as well as for collisions between enemy bombs and the player's ship.

The group collidemethod returns a dictionary of all sprites in the first group that collide with sprites from the second group. The indices of the dictionary are the sprites in the first group that collide, and the value is a list of sprites which which they collides. The group collidemethod take four arguments. The first two are the groups you want to check to see if they have colliding sprites, and the last two arguments are used if you want the colliding sprites to be deleted. For our example, we want both the player's bomb and the enemy it collided with to be destroyed, so the last two values are 1 and 1. If you didn't want either of the sprites to be deleted, set their corresponding values to 0.

For every collision between the players bombs and an enemy ship, we play the explode sound effect and increase the enemy-killed stat by one. Next, we check if the enemy sprite group is empty. If it is, we print a message to the terminal that includes the game stats and sets the running variable to zero so that the game loop exits on the next iteration through the game loop.

    #See if players bombs hit any enemy ships
    for hit in pygame.sprite.groupcollide(enemyship_sprites, bomb_sprites, 1, 1):
      explode1.play()
      enemy_killed += 1
    if enemyship_sprites.sprites() == []:
      print "You Win!!!!"
      print "Shot fired:",numberof_shots
      print "Hits taken:",numberof_hits
      print "Enemy killed", enemy_killed
      running = 0;

Detecting collisions between enemy bombs is accomplished through a similar process. One important thing to note here is we automatically delete enemy bombs that collide, but we do not delete the player's ship; hence, the last parameter in the group collide method is a 0. For every hit we increase the number of hits by one and play our explode sound effect. If the number of hits is three or more, we print a message to the terminal, and we set the running variable to zero.

    for hit in pygame.sprite.groupcollide(ebomb_sprites, playership_sprite, 1, 0).keys():
      numberof_hits += 1
      explode2.play()
    if numberof_hits >= 3:
      print "You lose :("
      print "Shot fired:",numberof_shots
      print "Hits taken:",numberof_hits
      print "Enemy killed", enemy_killed
      running = 0;

Now that we have gotten rid of all the sprites that should be removed from game play, we can redraw the screen. Calling the draw method on each of the sprite groups draws the sprites in that group to the specified surface, which in our case is the screen. The display.flip method is used with double buffing. Double buffering is where all drawing is done to a hidden buffer and then the hidden buffer is swapped with the draw buffer. This increases drawing speeds, as unseen layers need not be drawn to the screen. If double buffering is not supported by your hardware, drivers and so on, it can be simulated by Pygame.

    ebomb_sprites.draw(screen)
    bomb_sprites.draw(screen)
    enemyship_sprites.draw(screen)
    playership_sprite.draw(screen)

    pygame.display.flip()

The last part of our main function, which is outside of our loop, is to pause three seconds before exiting so that the player can see the final screen. I also reset the screen so it is in a window. Doing so is not necessary, but I have had some problems with certain development environments, most notably IDLE, and resetting the screen helps in avoiding some small problems.

  pygame.time.delay(3000)
  screen = pygame.display.set_mode((640, 480))

As you can see, Pygame makes game development fun and easy. For more information, check out the Pygame Web. The full source code and image files used in this article can be found here.