Python Game Programming By Example: A pragmatic guide for developing your own games with Python

You will need Python 3.4 with Tcl / Tk 8.6 installed on your computer. The latest branch of this version is Python 3.4.3, which can be downloaded from https://www.python.org/downloads/. Here, you can find the official binaries for the most popular platforms, such as Windows and Mac OS. During the installation process, make sure that you check the Tcl/Tk option to include the library.

The code examples included in the book have been tested against Windows 8 and Mac, but can be run on Linux without any modification. Note that some distributions may require you to install the appropriate package for Python 3. For instance, on Ubuntu, you need to install the python3-tk package.

Once you have Python installed, you can verify the version by opening Command Prompt or a terminal and executing these lines:

$ python --version
Python 3.4.3

After this check, you should be able to start a simple GUI program:

$ python
>>> from tkinter import Tk
>>> root = Tk()
>>> root.title('Hello, world!')
>>> root.mainloop()

These statements create a window, change its title, and run indefinitely until the window is closed. Do not close the new window that is displayed when the second statement is executed. Otherwise, it will raise an error because the application has been destroyed.

We will use this library in our first game, and the complete documentation of the module can be found at https://docs.python.org/3/library/tkinter.html.

The Breakout game starts with a paddle and a ball at the bottom of the screen and some rows of bricks at the top. The player must eliminate all the bricks by hitting them with the ball, which rebounds against the borders of the screen, the bricks, and the bottom paddle. As in Pong, the player controls the horizontal movement of the paddle.

The player starts the game with three lives, and if they miss the ball's rebound and it reaches the bottom border of the screen, one life is lost. The game is over when all the bricks are destroyed, or when the player loses all their lives.

This is a screenshot of the final version of our game:

We will start out game by creating a top-level window as in the simple program we ran previously. However, this time, we will use two nested widgets: a container frame and the canvas where the game objects will be drawn, as shown here:

With Tkinter, this can easily be achieved using the following code:

import tkinter as tk

lives = 3
root = tk.Tk()
frame = tk.Frame(root)
canvas = tk.Canvas(frame, width=600, height=400, bg='#aaaaff')
frame.pack()
canvas.pack()
root.title('Hello, Pong!')
root.mainloop()

Through the tk alias, we access the classes defined in the tkinter module, such as Tk, Frame, and Canvas.

Notice the first argument of each constructor call which indicates the widget (the child container), and the required pack() calls for displaying the widgets on their parent container. This is not necessary for the Tk instance, since it is the root window.

However, this approach is not exactly object-oriented, since we use global variables and do not define any new classes to represent our new data structures. If the code base grows, this can lead to poorly organized projects and highly coupled code.

We can start encapsulating the pieces of our game in this way:

import tkinter as tk

class Game(tk.Frame):
    def __init__(self, master):
        super(Game, self).__init__(master)
        self.lives = 3
        self.width = 610
        self.height = 400
        self.canvas = tk.Canvas(self, bg='#aaaaff',
                                width=self.width,
                                height=self.height)
        self.canvas.pack()
        self.pack()

if __name__ == '__main__':
    root = tk.Tk()
    root.title('Hello, Pong!')
    game = Game(root)
    game.mainloop()

Our new type, called Game, inherits from the Frame Tkinter class. The class Game(tk.Frame): definition specifies the name of the class and the superclass between parentheses.

If you are new to object-oriented programming with Python, this syntax may not sound familiar. In our first look at classes, the most important concepts are the __init__ method and the self variable:

In the preceding snippet, we introduced the if __name__ == '__main__' condition, which is present in many Python scripts. This snippet checks the name of the current module that is being executed, and will prevent starting the main loop where this module was being imported from another script. This block is placed at the end of the script, since it requires that the Game class be defined.

See the chapter1_01.py script, which contains this code. Since no external assets are needed, you can place it in any directory and execute it from the Python command line by running chapter1_01.py. The main loop will run indefinitely until you click on the close button of the window, or you kill the process from the command line.

This is the starting point of our game, so let's start diving into the Canvas widget and see how we can draw and animate items in it.

So far, we have the window set up and now we can start drawing items on the canvas. The Canvas widget is two-dimensional and uses the Cartesian coordinate system. The origin—the (0, 0) ordered pair—is placed in the top-left corner, and the axis can be represented as shown in the following screenshot:

Keeping this layout in mind, we can use two methods of the Canvas widget to draw the paddle, the bricks, and the ball:

Each of these calls returns an integer, which identifies the item handle. This reference will be used later to manipulate the position of the item and its options. The **options syntax represents a key/value pair of additional arguments that can be passed to the method call. In our case, we will use the fill and the tags option.

The x0 and y0 coordinates indicate the top-left corner of the previous screenshot, and x1 and y1 are indicated in the bottom-right corner.

For instance, we can call canvas.create_rectangle(250, 300, 330, 320, fill='blue', tags='paddle') to create a player's paddle, where:

We will invoke other Canvas methods to manipulate the items and retrieve widget information. This table gives the references to the Canvas widget that will be used in this chapter:

You can check out a complete reference of the event syntax as well as some practical examples at http://effbot.org/tkinterbook/tkinter-events-and-bindings.htm#events.

Before we start drawing all our game items, let's define a base class with the functionality that they will have in common—storing a reference to the canvas and its underlying canvas item, getting information about its position, and deleting the item from the canvas:

class GameObject(object):
    def __init__(self, canvas, item):
        self.canvas = canvas
        self.item = item

    def get_position(self):
        return self.canvas.coords(self.item)

    def move(self, x, y):
        self.canvas.move(self.item, x, y)

    def delete(self):
        self.canvas.delete(self.item)

Assuming that we have created a Canvas widget as shown in our previous code samples, a basic usage of this class and its attributes would be like this:

item = canvas.create_rectangle(10,10,100,80, fill='green')
game_object = GameObject(canvas,item) #create new instance

print(game_object.get_position())
# [10, 10, 100, 80]
game_object.move(20, -10)
print(game_object.get_position())
# [30, 0, 120, 70]
game_object.delete()

In this example, we created a green rectangle and a GameObject instance with the resulting item. Then we retrieved the position of the item within the canvas, moved it, and calculated the position again. Finally, we deleted the underlying item.

The methods that the GameObject class offers will be reused in the subclasses that we will see later, so this abstraction avoids unnecessary code duplication. Now that you have learned how to work with this basic class, we can define separate child classes for the ball, the paddle, and the bricks.

class Ball(GameObject):
    def __init__(self, canvas, x, y):
        self.radius = 10
        self.direction = [1, -1]
        self.speed = 10
        item = canvas.create_oval(x-self.radius, y-self.radius,
                                  x+self.radius, y+self.radius,
                                  fill='white')
        super(Ball, self).__init__(canvas, item)

class Paddle(GameObject):
    def __init__(self, canvas, x, y):
        self.width = 80
        self.height = 10
        self.ball = None
        item = canvas.create_rectangle(x - self.width / 2,
                                       y - self.height / 2,
                                       x + self.width / 2,
                                       y + self.height / 2,
                                       fill='blue')
        super(Paddle, self).__init__(canvas, item)

    def set_ball(self, ball):
        self.ball = ball

    def move(self, offset):
        coords = self.get_position()
        width = self.canvas.winfo_width()
        if coords[0] + offset >= 0 and \
            coords[2] + offset <= width:
            super(Paddle, self).move(offset, 0)
            if self.ball is not None:
                self.ball.move(offset, 0)

class Brick(GameObject):
    COLORS = {1: '#999999', 2: '#555555', 3: '#222222'}

    def __init__(self, canvas, x, y, hits):
        self.width = 75
        self.height = 20
        self.hits = hits
        color = Brick.COLORS[hits]
        item = canvas.create_rectangle(x - self.width / 2,
                                       y - self.height / 2,
                                       x + self.width / 2,
                                       y + self.height / 2,
                                       fill=color, tags='brick')
        super(Brick, self).__init__(canvas, item)

    def hit(self):
        self.hits -= 1
        if self.hits == 0:
            self.delete()
        else:
            self.canvas.itemconfig(self.item,
                                   fill=Brick.COLORS[self.hits])

Now that the organization of our items is separated into these top-level classes, we can extend the __init__ method of our Game class:

class Game(tk.Frame):
    def __init__(self, master):
        super(Game, self).__init__(master)
        self.lives = 3
        self.width = 610
        self.height = 400
        self.canvas = tk.Canvas(self, bg='#aaaaff',
                                width=self.width,
                                height=self.height)
        self.canvas.pack()
        self.pack()

        self.items = {}
        self.ball = None
        self.paddle = Paddle(self.canvas, self.width/2, 326)
        self.items[self.paddle.item] = self.paddle
        for x in range(5, self.width - 5, 75):
            self.add_brick(x + 37.5, 50, 2)
            self.add_brick(x + 37.5, 70, 1)
            self.add_brick(x + 37.5, 90, 1)

        self.hud = None
        self.setup_game()
        self.canvas.focus_set()
        self.canvas.bind('<Left>',
                         lambda _: self.paddle.move(-10))
        self.canvas.bind('<Right>',
                         lambda _: self.paddle.move(10))

    def setup_game(self):
           self.add_ball()
           self.update_lives_text()
           self.text = self.draw_text(300, 200,
           'Press Space to start')
           self.canvas.bind('<space>',
           lambda _: self.start_game())

This initialization is more complex that what we had at the beginning of the chapter. We can divide it into two sections:

Our new add_ball and add_brick methods are used to create game objects and perform a basic initialization. While the first one creates a new ball on top of the player's paddle, the second one is a shorthand way of adding a Brick instance:

    def add_ball(self):
        if self.ball is not None:
            self.ball.delete()
        paddle_coords = self.paddle.get_position()
        x = (paddle_coords[0] + paddle_coords[2]) * 0.5
        self.ball = Ball(self.canvas, x, 310)
        self.paddle.set_ball(self.ball)

    def add_brick(self, x, y, hits):
        brick = Brick(self.canvas, x, y, hits)
        self.items[brick.item] = brick

The draw_text method will be used to display text messages in the canvas. The underlying item created with canvas.create_text() is returned, and it can be used to modify the information:

    def draw_text(self, x, y, text, size='40'):
        font = ('Helvetica', size)
        return self.canvas.create_text(x, y, text=text,
                                       font=font)

The update_lives_text method displays the number of lives left and changes its text if the message is already displayed. It is called when the game is initialized—this is when the text is drawn for the first time—and it is also invoked when the player misses a ball rebound:

    def update_lives_text(self):
        text = 'Lives: %s' % self.lives
        if self.hud is None:
            self.hud = self.draw_text(50, 20, text, 15)
        else:
            self.canvas.itemconfig(self.hud, text=text)

We leave start_game unimplemented for now, since it triggers the game loop, and this logic will be added in the next section. Since Python requires a code block for each method, we use the pass statement. This does not execute any operation, and it can be used as a placeholder when a statement is required syntactically:

    def start_game(self):
        pass

See the chapter1_02.py module, a script with the sample code we have so far. If you execute this script, it will display a Tkinter window like the one shown in the following figure. At this point, we can move the paddle horizontally, so we are ready to start the game and hit some bricks:

Now that we have placed all of our game objects, we can define the methods that will be executed in the game loop. This loop runs indefinitely until the game ends, and each iteration updates the position of the ball and checks the collision that occurs.

With the Canvas widget, we can calculate what the items that overlap with the given coordinates are, so for now, we will implement the methods that are responsible for moving the ball and changing its direction.

Let's start with the movement of the ball and the conditions for recreating the bouncing effect when it reaches the canvas borders:

    def update(self):
        coords = self.get_position()
        width = self.canvas.winfo_width()
        if coords[0] <= 0 or coords[2] >= width:
            self.direction[0] *= -1
        if coords[1] <= 0:
            self.direction[1] *= -1
        x = self.direction[0] * self.speed
        y = self.direction[1] * self.speed
        self.move(x, y)

The update method does the following:

For instance, if the ball hits the left border, the coords[0] <= 0 condition evaluates to true, so the x-axis component of the direction changes its sign, as shown in this diagram:

If the ball hits the top-right corner, both coords[2] >= width and coords[1] <= 0 evaluate to true. This changes the sign of both the components of the direction vector, like this:

The logic of the collision with a brick is a bit more complex, since the direction of the rebound depends on the side where the collision occurs.

We will calculate the x-axis component of the ball's center and check whether it is between the lowermost and uppermost x-axis coordinates of the colliding brick. To translate this into a quick implementation, the following snippet shows the possible changes in the direction vector as per the ball and brick coordinates:

        coords = self.get_position()
        x = (coords[0] + coords[2]) * 0.5
        brick_coords = brick.get_position()
        if x > brick_coords[2]:
            self.direction[0] = 1
        elif x < brick_coords[0]:
            self.direction[0] = -1
        else:
            self.direction[1] *= -1

For instance, this collision causes a horizontal rebound, since the brick is being hit from above, as shown here:

On the other hand, a collision from the right-hand side of the brick would be as follows:

This is valid when the ball hits the paddle or a single brick. However, the ball can hit two bricks at the same time. In this situation, we cannot execute the previous statements for each brick; if the y-axis direction is multiplied by -1 twice, the value in the next iteration of the game loop will be the same.

We could check whether the collision occurred from above or behind, but the problem with multiple bricks is that the ball may overlap the lateral of one of the bricks and, therefore, change the x-axis direction as well. This happens because of the ball's speed and the rate at which its position is updated.

We will simplify this by assuming that a collision with multiple bricks at the same time occurs only from above or below. That means that it changes the y-axis component of the direction without calculating the position of the colliding bricks:

        if len(game_objects) > 1:
            self.direction[1] *= -1

With these two conditions, we can define the collide method. As we will see later, another method will be responsible for determining the list of colliding bricks, so this method only handles the outcome of a collision with one or more bricks:

    def collide(self, game_objects):
        coords = self.get_position()
        x = (coords[0] + coords[2]) * 0.5
        if len(game_objects) > 1:
            self.direction[1] *= -1
        elif len(game_objects) == 1:
            game_object = game_objects[0]
            coords = game_object.get_position()
            if x > coords[2]:
                self.direction[0] = 1
            elif x < coords[0]:
                self.direction[0] = -1
            else:
                self.direction[1] *= -1

        for game_object in game_objects:
            if isinstance(game_object, Brick):
                game_object.hit()

Note that this method hits every brick instance that is colliding with the ball, so the hit counters are decreased and the bricks are removed if they reach zero hits.

Finally, we have built the functionality needed to run the game loop—the logic required to update the ball's position according to the rebounds, and restart the game if the player loses one life.

Now we can add the following methods to our Game class to complete the development of our game:

    def start_game(self):
        self.canvas.unbind('<space>')
        self.canvas.delete(self.text)
        self.paddle.ball = None
        self.game_loop()

    def game_loop(self):
        self.check_collisions()
        num_bricks = len(self.canvas.find_withtag('brick'))
        if num_bricks == 0:
            self.ball.speed = None
            self.draw_text(300, 200, 'You win!')
        elif self.ball.get_position()[3] >= self.height:
            self.ball.speed = None
            self.lives -= 1
            if self.lives < 0:
                self.draw_text(300, 200, 'Game Over')
            else:
                self.after(1000, self.setup_game)
        else:
            self.ball.update()
            self.after(50, self.game_loop)

The start_game method, which we left unimplemented in a previous section, is responsible for unbinding the Spacebar input key so that the player cannot start the game twice, detaching the ball from the paddle, and starting the game loop.

Step by step, the game_loop method does the following:

The check_collisions method links the game loop with the ball collision method. Since Ball.collide receives a list of game objects and canvas.find_overlapping returns a list of colliding items with a given position, we use the dictionary of items to transform each canvas item into its corresponding game object.

Remember that the items attribute of the Game class contains only those canvas items that can collide with the ball. Therefore, we need to pass only the items contained in this dictionary. Once we have filtered the canvas items that cannot collide with the ball, such as the text displayed in the top-left corner, we retrieve each game object by its key.

With list comprehensions, we can create the required list in one simple statement:

objects = [self.items[x] for x in items if x in self.items]

The basic syntax of list comprehensions is the following:

new_list = [expr(elem) for elem in collection]

This means that the new_list variable will be a list whose elements are the result of applying the expr function to each elem in the list collection.

We can filter the elements to which the expression will be applied by adding an if clause:

new_list = [expr(elem) for elem in collection if elem is not None]

This syntax is equivalent to the following loop:

new_list = []
for elem in collection:
    if elem is not None:
        new_list.append(elem)

In our case, the initial list is the list of colliding items, the if clause filters the items that are not contained in the dictionary, and the expression applied to each element retrieves the game object associated with the canvas item. The collide method is called with this list as a parameter, and the logic for the game loop is completed.

Open the chapter1_complete.py script to see the final version of the game, and run it by executing chapter1_complete.py, as you did with the previous code samples.

When you press the spacebar, the game starts and the player controls the paddle with the right and left arrow keys. Each time the player misses the ball, the lives counter will decrease, and the game will be over if the ball rebound is missed again and there are no lives left:

In our first game, all the classes have been defined in a single script. However, as the number of lines of code increases, it becomes necessary to define separate scripts for each part. In the next chapters, we will see how it is possible to organize our code by modules.

In this chapter, we built out first game with vanilla Python. We covered the basics of the control flow and the class syntax. We used Tkinter widgets, especially the Canvas widget and its methods, to achieve the functionality needed to develop a game based on collisions and simple input detection.

Our Breakout game can be customized as we want. Feel free to change the color defaults, the speed of the ball, or the number of rows of bricks.

However, GUI libraries are very limited, and more complex frameworks are required to achieve a wider range of capabilities. In the next chapter, we will introduce Cocos2d, a game framework that helps us with the development of our next game.