A Fast Introduction to Pygame

Pygame is a cross-platform game library written in Python. It is the most used library to write games using Python. This tutorial aims to get you started using the Pygame library. After finishing this tutorial you will be able to craft simple Pygame applications, and will be in position of understanding complex Pygame applications written by others. I assume the reader has at least a basic understanding of Python.

If you don’t have Python and/or Pygame installed, make sure you first read this tutorial.

Overview

Pygame is composed of various modules, each dealing with a specific set of tasks. For example, the display module deals with the display window and screen, the draw module provides functions to draw shapes, and the key module works with the keyboard. These are just some of the modules of the library. The pygame documentation contains documentation for all modules.

First, we call pygame.display.set_mode() to create the window. This function takes as the first parameter, a tuple that specifies the window dimensions. The return value of this function will be used later to draw into the window. Next, we set a title to the window.

Step 4: Initialize game objects

In this step we load images, load sounds, do object positioning, set up some state variables, etc. In this tutorial, we will not cover image and sound processing.

Step 5: Start the Game Loop

The Game Loop is one of most fundamental pieces of any game. It is just a loop where we continuously handle events, check for input, move objects, and draw them. Each iteration of the loop is called a frame. When designing a game loop we must make sure each frame takes exactly the same time on any machine. This avoids the game to run at different speeds depending on the speed of the machine.

To have a smooth animation the game loop must run at least at 30 frames per second (FPS). To lock the frame rate, we use a pygame.time.Clock() object. Below is a basic structure of a game loop:

First, we create the clock object that will be used to lock the frame rate. Next, we start the loop, and then call clock.tick() to lock the frame rate to 50 FPS. Then, we process the event queue, checking if a QUIT event is pending. This event normally happens when the user closes the window. So, if we catch a QUIT event we call sys.exit() to quit the application.

Next we clear the screen calling screen.fill(). If you remember, we created the screen variable in Step 3. The fill() function takes as the first parameter the color to fill the window with. Colors in Pygame are represented as RGB tuples.

Then, we should write code to check for input, move objects, and draw objects. When we draw things into the window, they are not immediately displayed. So, in the last line of the game loop we call pygame.display.flip() to display all the drawings in the window.

If you assemble together all the lines of code presented in each step, and run them, you will get just a black window. In the next section, we will see an example of a Pygame application that moves a box horizontally in the screen, bouncing off the screen borders.

First of all, we import the built-in sys module and the pygame module. Next we define BLACK and WHITE color constants. Then we initialize pygame, and setup the window. After that, we create a clock object, and initialize the box object. We use box_x to track the position of the box, and box_dir to track the direction (left / right) .

Next, we enter the game loop. First, we call clock.tick(50) to lock the frame rate at 50 FPS. Then, we process the event queue, quitting the application if QUIT event is found. After that, we clear the screen with BLACK color. Next, we move the box, making it bounce if it hits the window borders. Then, we draw the box calling pygame.draw.rect(), and finally call pygame.display.flip() to update the window.