Eli Bendersky's website - Pygame tutorial

Writing a game in Python with Pygame. Part IV

2009-02-13T17:18:13-08:00

This is part IV of the "Writing a game in Python with Pygame" tutorial.

Back to the Creeps

After a digression into the exciting world of path-finding in the previous part, we're now back to our "Creeps" game. Here's a screenshot of our final product for this part:

As you can see, things look quite different now. Indeed, there's a lot of changes in the code, and a lot of new features were added for this part [1].

Here's a brief summary of what we'll go over today:

Making creeps look prettier, especially when rotated
Major code refactoring into classes with well-defined responsibilities
Separation of "GUI elements" from the game logic
Handling transparency
Drawing walls
Incorporating the path-finding code to create directed movement for the creeps

As you see, this is a lot of material, and indeed I feel very content with the amount of code written for this section. The final product is a very complete simulation having all the elements to turn into many kinds of games.

The code

The full code for this section can be taken from here. Make sure you download and run it (execute creeps.py) before reading the rest of this tutorial.

Prettier creeps

I've re-created the creep images using the amazing Inkscape tool. Inkscape allows to draw vector-graphics (SVG), so it's much better suited than plain pixel-banging .png for drawing figures for games. I've included the source .svg files for the creep images in the images/ directory of the code package.

But my biggest problem with the creeps of the previous parts was how creeps rotated by 45 degrees look. While rotating a square image perfectly in multiples of 90 degrees is simple, multiples of 45 are much tougher. When the image is small, there's a big change it will come up ugly, because the rotation can't perfectly convey all the information stored in it. And indeed, when I just let Pygame to rotate the images 45 degrees for me, it didn't look very pretty.

So I've taken a different path this time. I rotated the images to 45 degrees in Inkscape (which does it perfectly because it stores them as vector graphics), and now there are two images for each creep: one pointing "east" and one pointing "north-east". Given these two, with rotations by 90 degrees I can achieve all 8 possible multiples of 45 degrees. You will notice in the code that Creep now accepts a pair of images as an argument, and unpacks them:

# base_image_0/45 hold the original images, un-rotated
#
self.base_image_0 = creep_images[0]
self.base_image_45 = creep_images[1]

Now the image rotation is done as follows:

# Make the creep image point in the correct direction.
# Note that two images are used, one for diagonals
# and one for horizontals/verticals.
#
# round() on the angle is necessary, to make it
# exact, despite small deviations that may result from
# floating-point calculations
#
if int(round(self.direction.angle)) % 90 == 45:
    self.image = pygame.transform.rotate(
        self.base_image_45, -(self.direction.angle + 45))
elif int(round(self.direction.angle)) % 90 == 0:
    self.image = pygame.transform.rotate(
        self.base_image_0, -self.direction.angle)
else:
    assert False

If the creep's current direction is an odd multiple of 45 degrees, the 45-degree image is used for rotations. Otherwise the 0-degree image is used.

This way all creeps look pretty now rotated in whichever direction.

Code refactoring

The creeps code after part II wasn't exactly production quality. It was what experimentation-code usually looks like, and except the Creep class, it wasn't very well organized.

If you look at the code now, the situation is different. I've separated it to several classes, and moved out related functionality into separate files. A lot of the code that was just dispersed in the main file was collected into the Game class, which is responsible for creating and running the game.

Another interesting change was the addition of the Timer class (in utils.py). Timer mimics the behavior or timers in event-driven systems like GUI toolkits. You create it with an interval and a callback function. Then, as time passes you should update it with the amount of time passed (just like calling the update of creeps to let them compute their position), and the timer will call the callback periodically (with the supplied period).

A good example of the use of the timer is in the SimpleAnimation class (simpleanimation.py) which we use to show how creeps "explode" when their life bar reaches 0. The constructor of the animation creates two timers:

self.scroll_timer = Timer(scroll_period, self._advance_img)
self.active_timer = Timer(duration, self._inactivate, True)

The scroll timer is responsible for scrolling through the animation's images periodically, while the active timer is responsible for inactivating the animation after its duration has passed (it's also a one-shot timer, which means it only acts once).

This is a good example of decoupling. Timer takes care of the common task of keeping time and doing events periodically, so now "user" code like SimpleAnimation doesn't have to implement time keeping explicitly itself.

Another example of the usage of Timer is in the Game class. Feel free to explore how creep_spawn_timer is used to periodically "spawn" new creeps into the game.

GUI "widgets"

If you've ever programmed GUIs, you've undoubtedly run into the term "widget". A widget is a generic graphical GUI element that you see on the screen and can sometimes interact with. Text boxes are widgets, buttons are widgets, scroll boxes, tables, labels are widgets, etc.

Pygame is not a GUI toolkit. It's a more low-level tool that specializes in graphics - efficient drawing on the screen. This, together with the concept of time, is all one really needs to create widgets, though, and indeed several GUI libraries for Pygame sprang up.

Rather than using a ready-made library, I've decided to create just the primitives I need for the creeps game. See widgets.py for two useful widget classes that I use for drawing framed boxes and message boards.

The classes are very simple - each has a constructor and a draw method, along with other utility methods [2].

By taking out these utilities into a separate file as widget classes, I've achieved another goal of refactoring - keeping logically separate code in different files. Now the main code can create boxes and message boards at its will, without worrying too much about how they're implemented.

Handling transparency

You've surely noticed by now that creeps come out from a semi-transparent square in the upper-left corner of the screen and disappear into a similar square in the bottom-right corner.

These squares are drawn transparently as follows:

def draw_portals(self):
    entrance_sf = pygame.Surface((self.entrance_rect.w, self.entrance_rect.h))
    entrance_sf.fill(Color(80, 200, 80))
    entrance_sf.set_alpha(150)
    self.screen.blit(entrance_sf, self.entrance_rect)

    exit_sf = pygame.Surface((self.exit_rect.w, self.exit_rect.h))
    exit_sf.fill(Color(200, 80, 80))
    exit_sf.set_alpha(150)
    self.screen.blit(exit_sf, self.exit_rect)

The "magic" here is done with the set_alpha method of a Surface. Alpha in graphics nomenclature means the measure of transparency of a color - how much it will be blended into its background when drawn.

Note that these "portals" are drawn after the creeps are drawn. Can you figure out why? (see exercise 1).

Drawing walls

Since we're making our creeps avoid obstacles using path-finding, we should have some obstacles, right? Obstacles in our game are "walls", and are kept in the dictionary self.walls inside the Game object. The walls are drawn onto the screen as follows:

def draw_walls(self):
    wallcolor = Color(140, 140, 140)

    for wall in self.walls:
        nrow, ncol = wall

        pos_x = self.field_rect.left + ncol * self.GRID_SIZE + self.GRID_SIZE / 2
        pos_y = self.field_rect.top + nrow * self.GRID_SIZE + self.GRID_SIZE / 2
        radius = 3

        pygame.draw.polygon(self.screen, wallcolor,
            [   (pos_x - radius, pos_y), (pos_x, pos_y + radius),
                (pos_x + radius, pos_y), (pos_x, pos_y - radius)])

        if (nrow + 1, ncol) in self.walls:
            pygame.draw.line(self.screen, wallcolor,
                (pos_x, pos_y), (pos_x, pos_y + self.GRID_SIZE), 3)
        if (nrow, ncol + 1) in self.walls:
            pygame.draw.line(self.screen, wallcolor,
                (pos_x, pos_y), (pos_x + self.GRID_SIZE, pos_y), 3)

First, a polygonal "blob" is drawn in the center of the grid square [3] where the wall is located. Then, the neighbor squares are examined (see exercise 2). If a neighbor has a wall in it too, the two are connected by a thick line, making an appearance of a real wall.

Creep, find thy way!

It's a good time to review part III of the tutorial now, because I assume you already know what's explained there (namely, what path-finding is, and how I've implemented it).

Implementing path-finding for the game

Two classes were important in my implementation of path-finding on a rectangular grid:

GridMap, which represents a rectangular grid, providing methods to set which squares are blocked and cost functions for the path-finding code.
PathFinder, a generic, efficient A* path-finder that receives an abstract representation of the game graph (via successors and cost functions) and computes optimal paths from point to point on that graph.

For creeps, I've created a proxy class named GridPath that encapsulates the interaction with the path-finding code completely, providing a convenient interface for the creeps. It's only 50 lines of code or so, most of it comments and doc-strings, so you can easily understand it.

Here's the constructor:

def __init__(self, nrows, ncols, goal):
    self.map = GridMap(nrows, ncols)
    self.goal = goal

    # Path cache. For a coord, keeps the next coord to move
    # to in order to reach the goal. Invalidated when the
    # grid changes (with set_blocked)
    #
    self._path_cache = {}

You can see that it uses GridMap under the hood to implement the rectangular map with its costs and successor function.

The main trick that makes GridPath cool is caching. I wouldn't want to re-compute the path for each creep to the goal 30 times a second, why should I, if the game field rarely if ever changes?

Instead, path results are cached, and GridPath answers one simple question - "where to next from here?". When one creep asks it, in all likeness another creep will ask it at one time or another, so it makes sense to cache the results.

Here it is:

def get_next(self, coord):
    """ Get the next coordinate to move to from 'coord'
        towards the goal.
    """
    # If the next path for this coord is not cached, compute
    # it
    #
    if not (coord in self._path_cache):
        self._compute_path(coord)

    # _compute_path adds the path for the coord to the cache.
    # If it's still not cached after the computation, it means
    # that no path exists to the goal from this coord.
    #
    if coord in self._path_cache:
        return self._path_cache[coord]
    else:
        return None

When asked the question, it first checks the cache. If the cache already contains the answer, it is returned. Otherwise the path is recomputed and added to the cache (see method _compute_path for that). At this point, if the path is again not in the cache it means there isn't any valid path from this point.

But what if the game field changes? - you might (rightly) ask. No problems, in this case the cache is just invalidated (cleared) and new questions will cause it to be filled again (set_blocked clears the cache).

The actual result of this is that path computations hardly take any time. Only when the map is changed, the path is recomputed (which takes several milliseconds). In all other cases, the result is returned instantly from the cache.

Smarter movement for creeps

The Creep class needed to undergo some minor changes to incorporate path-finding. The main change is in the _compute_direction method, that replaces the method that just randomly changed the direction of the creep once in a while.

Here is its:

def _compute_direction(self, time_passed):
    """ Finds out where to go
    """
    coord = self.game.xy2coord(self.pos)

    if self.game.is_goal_coord(coord):
        self._die()
    else:
        x_mid, y_mid = self.game.coord2xy_mid(coord)

        if (    (x_mid - self.pos.x) * (x_mid - self.prev_pos.x) < 0 or
                (y_mid - self.pos.y) * (y_mid - self.prev_pos.y) < 0):
            next_coord = self.game.next_on_path(coord)

            self.direction = vec2d(
                next_coord[1] - coord[1],
                next_coord[0] - coord[0]).normalized()

Most of the code is straightforward. The creep first finds out where it is (by asking the Game object to translate its position into a coordinate on the game map). Then, it checks whether it has reached its goal. If it did, the creep dies. Otherwise, it computes where to turn, if a turn is required.

This is one of the trickiest parts of the code, so it warrants special attention.

Recall [4] that the creep keeps its position on the screen in self.pos. It's done in a "centered way", meaning that the center of the creep's image is located at self.pos, and its actual body is around it. To simulate realistic movement through the grid, I want the creeps to move through the grid's centers (i.e. the whole body of the creep to fit into a grid square before a turn is made).

Here's a diagram for clarification:

Imagine that the red dot represents the center of the creep which has just entered a new grid square. Suppose that it has entered from the upper-left neighbor of this square. Also, suppose that the path-finding code tells the creep to continue to the neighbor below this square. How will the creep move?

Well, if it continuously checks for a change of direction, the creep will start moving down right away, so it will move on the edges of the squares, and not inside them (see exercise 3). This results in unrealistic movement and interference with walls. How can this be fixed?

I've had several ideas while developing the code, but most of them didn't work out. One that does work, can be described with this diagram:

Assume an imaginary cross through the middle of the square. We can detect when the creep passes from one quadrant of the cross to another quite simply, so we have a way of knowing when it's about in the center of the square. This is the idea actually implemented in the second part of _compute_direction, and as you can see in the game itself, it works nicely. You can turn the grid on (Ctrl-g) and see how nicely the creeps move through the centers of the squares.

Conclusion

As always, please check the exercises in the bottom of the tutorial. Even if you don't actually implement the solutions, at least read the questions and try to understand what is being asked.

Our creeps code is now quite a complete simulation, incorporating many of the elements of game programming:

Graphics
Keeping and updating game state
Movement
Path-finding
User interaction
Events

I personally feel that I've learned a lot about Pygame by writing it, and hope that you have too. At this point, I'm not sure whether I'll continue this tutorial, because I don't know if I want to pursue the topic further. Perhaps if someone suggests an interesting enough future direction for it, I'll be motivated enough to continue.

For now, thanks for reading!

Exercises

Try to change the relative drawing order of creeps and portals. What do you see? Can you explain why this happens?
In draw_walls only the neighbors to the east and to the south are examined. Is this always enough to connect all walls? Why?
Simplify the code of _compute_direction so that the creeps won't wait for getting to the middle of a square for turning. How does it look now on the screen? Which is better?
Note that the wall-collision code has been removed from the Creep class. Can you figure out why it's no longer required?
Note that no new creeps spawn as old ones disappear. Can you modify the code so that disappearing creeps will be replaced by new ones?
Change the message board to announce how many creeps have safely reached the exit portal.
Think up some game ideas that could be implemented relatively easily based on the creeps code base. Let me know if you come up with something interesting.

[1]	Which is why it took so long to publish it!

[2] For more dynamic widgets, an update method can be added that will be called by the event loop (just like the update of timers and creeps is called), and on the basis of the information sent to update the widget can update its internal state and draw something different the next time draw is called.

[3] Note that we've divided the "playing field" into a rectangular grid for drawing walls and assisting pathfinding. GRID_SIZE = 20 is a constant in Game that specifies that each grid square is 20 x 20 pixels in size. The methods xy2coord and coord2xy_mid convert to and from the grid coordinates to actual pixel coordinates on the screen. You can see this grid by clicking Ctrl+g while the game is running.

[4]	Look at the code now. Do a search of `self.pos` in the `Creep` code to see how the position is computed and used.

Writing a game in Python with Pygame. Part III

2009-01-09T15:45:43-08:00

This is part III of the "Writing a game in Python with Pygame" tutorial.

A digression

This part will be a digression from the first two, in the sense that it won't deal with the "Creeps" simulation we've been developing so far. Rather, we'll explore pathfinding - an important "artificial intelligence" technique for games. Pathfinding will be crucial for the future development of our game, so I'm spending a whole part on it.

I'll start by presenting my implementation of the A* pathfinding algoritm. The implementation is generic, and has nothing to do with our game. I assume a basic acquaintance with computer-science algorithms and data structures here, so depending on your background you may find it a bit dense. Don't worry, you can skip it entirely without any real loss - you'll be able to understand the rest of the tutorial.

Next, I'll show a useful Pygame-based demo of the algorithm at work - this is recommended even if you don't want to dive into the implementation of the algorithm, as it ties the algorithm with our game.

Here's a teaser screenshot:

The code

The code for this part can be downloaded from here. It contains the implementation of the pathfinding algorithm and the demo Pygame application.

Pathfinding

Pathfinding is one of the most important aspects of game AI (Artificial Intelligence). I'll quote Wikipedia:

Pathfinding in this context concerns the way in which a moving entity finds a path around an obstacle; the most frequent context is real time strategy games (in which the player directs units around a play area containing obstacles), but may also be first person shooters. Pathfinding has grown in importance as games and their environments have become more complex.

Consider a game character controlled by the computer (AI) that wants to get from one place to another. Assuming it can't just instantly teleport itself to the destination, how does it know which way to go ?

Pathfinding is the answer. And the most popular and well-known algorithm for pathfinding is called A* (A-star). This is the algorithm I'm going to implement in Python and integrate into a Pygame demo in this part.

A*

I have no intention of teaching A* in this tutorial. Others have done it already, and there are wonderful introductions, full of nice diagrams, online. Two I recommend highly are (in this order): Patrick Lester's A* Pathfinding for Beginners and Amit's A* Pages. Patrick's article is sufficient for you to understand the algorithm and the rest of my tutorial. Amit's is a great resource if you want to learn more about the algorithm. I'm sure there are many other articles online - just Google the subject.

...time passes as you engorge yourself with A* knowledge...

Oh, so you know how A* works now! That's really cool, so let's proceed with the tutorial. I'll just post a short reminder, for those who've learned about A* before and can't be bothered to read a full tutorial: A* is a greedy best-first search algorithm. From the start node, it starts considering nodes that could lead it to the goal, judging them by relative merit - the cost to get to them plus an estimated cost to get to the goal from them (more on this heuristic estimation later). All the nodes that are still to be considered are kept in an open list, and all the nodes with which the algorithm is done (i.e. explored all their successors) are kept in a closed list. At each "step" the cheapest node from the open list is considered as the next one, and all its successors are added to the open list (where they're sorted by cost), unless they're already there. If a node is already in an open list but now a cheaper path was found to reach it, its cost in the open list is updated. This goes on until the algorithm runs into the goal node, at which point it declares success and returns the path. That's about it, in short. If you've just finished the A* tutorial, or are familiar with A* from before, the previous paragraph should sound very familiar. If you still don't understand it and want to understand my implementation, I recommend you to read the tutorial again.

PathFinder

In the code for this part you'll find the file pathfinder.py with the class PathFinder. This is the class implementing path finding in Python. The class is well documented and if you understand how A* works you should have no trouble with it. There are just two points I want to clarify before we get into the code.

Representing graphs and costs

PathFinder is a generic class that doesn't care how you represent your graph, and how you represent and compute the costs of moving from place to place. It lets you specify this information by passing functions into its constructor (this is a good time to have the code of PathFinder open in an editor).

To understand the terminology, consider this graph:

A graph consists of nodes [1] (the circles) and edges (the arrows). For our pathfinding needs, we're interested in finding out paths from one node to another, through several edges and intermediary nodes. The costs associated with the movement will be marked as numbers on the edges. For instance, we can move in one step from node C to node B, and it will cost us 7 [2]. We can further move from B to D for a cost of 5, so the total cost for movement from C to D bia B is 12.

So how does PathFinder know how your graph looks? Very simple, you just specify it with the successors function passed in as an argument. The successors of a node are all the nodes that can be reached from this node in a single step. For example, in the graph above, the successors of A are C and B, the successor of B is D, and D has no successors.

PathFinder also knows about the costs because you provide it with the move_cost function, that tells it the cost between each two nodes.

The third function passed to PathFinder is heuristic_to_goal. You should be familiar with it from the A* articles, and I'll have more to say about it later.

Implementing the open set

You'll recall that the A* algorithm uses the open set to keep track of the nodes it still has to visit. The open set is perhaps the most important data structure for A*, and implementing it correctly is non-trivial.

I was surprised to find out that most of the implementations of the open set online are very inefficient. I also began with an inefficient implementation, but then A* just took too long to run on even simple graphs! Optimizing the open set with the correct data structure speeded things up by about 100! To read about the various considerations of the implementation, Amit's Implementation notes is a terrific resource.

My implementation uses the PriorityQueueSet class defined in the file priorityqueueset.py. It is a marriage of a priority queue with a set, which is required, because the open set must be both sorted by priority and the nodes in it must be unique.

The data structure is very efficient except for one operation. This operation is updating a node in the queue to a lower priority. Luckily, it doesn't happen often in realistic pathfinding problems, so overall it doesn't hinder the performance too much.

The implementation of A*

Finally, you're ready to tackle compute_path, the method of PathFinder that implements A*. You'll quickly see how closely it follows the various pseudocodes for A* you find in articles. Python is very pseudocode-like, it's one of its greatest powers!

One important thing you should keep in mind while reading the code of PathFinder is its usage of the helper _Node class. This node holds the point in your graph and its associated costs that help A* do its work. Read its documentation string for more information.

GridMap

For pathfinding in our game we're interested in a very special type of graph - a rectangular grid. Such a grid graph is implemented in gridmap.py. The idea is as follows:

The grid is rectangular, and you can get from any square to any neighbor square (up, down, left, right and diagonally), unless that square is blocked [3].

Consider the 4 full squares (one of them blocked) on the following image:

GridMap will represent this map using the following graph:

Several things to note here:

The arrows are bi-directional, meaning that a path exists between two nodes both ways (which usually makes sense in game maps).
Node D is unreachable - it represents the blocked square in the map.
The costs for moving between nodes is the Euclidean distance between them.

Now, if you run the file pathfinder.py - you'll see a small ASCII demo of PathFinder in action on a map created using GridMap. You can play with the settings and see how PathFinder responds.

The distance-to-goal heurustic

As promised, I'll mention the distance-to-goal heuristic which is required for the correct usage of the A* algorithm. In rectangular grids, the heuristic is easy to compute - it is simply the distance between the point and the goal.

Here's an example:

Suppose the algorithm has currently reached the blue node and the goal is green. The two yellow nodes are being considered as candidates for the next step. Both are distance 1 from the blue node, but which one should be picked?

The distance-to-goal heuristic states that the node closer to the goal should be picked, because it has more chance of leading to the goal quickly. The distance can be estimated as the "line-of-sight Euclidean distance", so the node to the right of the blue node will be picked next (but see exercise 1).

The pathfinder visualizer demo

The file pathfinder_visualize.py (in the example_code directory) contains a simple visualization of the pathfinding algorithm using Pygame. Just run it and read the directions at the top. You can mark goals and starting points, set and unset obstacles, and then ask it to compute a path by pressing F5.

There's nothing new in terms of Pygame in this demo - if you've followed the tutorial so far, you should have no trouble understanding its code. Note especially how it uses PathFinder and MapGrid to compute and display paths.

Demos like this are very helpful for analyzing and playing around with code and algorithms. Luckily we know Pygame now, so they're quite simple to implement .

Conclusion

In this part we went on a short side-walk from our Creeps game, to implement a pathfinding algorithm that we can later incorporate into the game.

The algorithm itself is A*, and while you're encouraged to understand how it works using the articles I've pointed to and my code, it's not a must. You'll be able to continue learning how to build the game even by treating it as a black box. Keep in mind, though, that if you're serious about game programming, you will be eventually forced to understand A* and pathfinding, as it's a very vital component of almost any game's AI.

In the next part we'll get back to our Creeps, making them a bit more intelligent using the algorithm we've covered here.

Exercises

The distance-to-goal heuristic makes most sense for such maps. However, sometimes it misleads the algorithm to attempt a longer way. Can you think of such situations? Hint: what if there's a long obstacle on the line-of-sight path between the nodes? Simulate this using the visualizer demo.
Try to give the visualizer an impossible problem, by surrounding the goal with walls, for example. How does it behave?
Can you make up a map that takes the pathfinder a long time to find a path in? What's the longest time you've managed to make it run?
Try to change the implementation of PriorityQueueSet to use simpler data structures. For example, use a simple sorted array. Time the pathfinder algorithm now - how long does it take to solve problems on 20x20 grids?
Can you cause the PathFinder almost never find paths that include diagonal movement, but still find them when they're the only option to reach a goal? Hint: use the movement cost function to help it decide.

[1]	Also called vertices in graph terminology.

[2]	7 what, apples? It depends on what you use the graph for. For our pathfinding needs, the cost can represent the time it takes the character to move from one node to another.

[3]	This represents an obstacle.

Writing a game in Python with Pygame. Part II

2008-12-20T12:34:33-08:00

This is part II of the "Writing a game in Python with Pygame" tutorial.

Welcome back

In the first part of this tutorial we've created a simple simulation of "Creeps" - round creatures moving around the screen and bouncing off walls. Not much of a game there, but a good start nonetheless.

In this part, we are going to extend this simulation, making it much more game-like. It is not the final step, of course. The final product of this part is still going to be far from a real, interesting game, but many useful game programming concepts will be introduced, and the simulation will definitely have much more feeling of a game in it.

Here's a teaser screenshot of the final product of this part:

The code

The full code for this part can be downloaded from here. As before, it is highly recommended to download it, run it and have it open in the editor while reading this tutorial.

Goals for this part

In this part I'm going to cover:

A prettier background for the game
Responding to user events
A more complex internal state for the creeps
Simple animation
Rendering text

So let's get started.

Background

In the first part we've just splashed a bucket of greenish swamp-like color onto the screen and called that a background. Since we want the game to be a bit more appealing, this won't do any longer.

We'll now tile a pretty background image onto the screen, and create a bounded "game field" for the creeps to roam in.

What is tiling, you ask? Tiling, in simple terms, is taking a small surface and repeating it in a pattern until a larger surface is covered. In our case, we'll take this image:

And tile it in a simple repeating-row pattern. The code doing it is in the draw_background function:

def draw_background(screen, tile_img, field_rect):
    img_rect = tile_img.get_rect()

    nrows = int(screen.get_height() / img_rect.height) + 1
    ncols = int(screen.get_width() / img_rect.width) + 1

    for y in range(nrows):
        for x in range(ncols):
            img_rect.topleft = (x * img_rect.width,
                                y * img_rect.height)
            screen.blit(tile_img, img_rect)

    field_color = (109, 41, 1)
    draw_rimmed_box(screen, field_rect, field_color, 4, Color('black'))

The loop does the tiling. The last line of the function creates the playing field - a dark-brown filled rectangle to which the creeps will be restricted. The field is drawn using the utility function draw_rimmed_box - it's very simple, and you can study it on your own [1].

In the game screenshot above you can also see another box with some text on the right. This is drawn separately, and we'll get to it soon enough.

Hey, you've clicked me!

So far the only user event our game has responded to was closing closing the game window. Not much interaction there, so we'll pump it up. Here's the new event handler in our main loop:

for event in pygame.event.get():
    if event.type == pygame.QUIT:
        exit_game()
    elif event.type == pygame.KEYDOWN:
        if event.key == pygame.K_SPACE:
            paused = not paused
    elif (  event.type == pygame.MOUSEBUTTONDOWN and
            pygame.mouse.get_pressed()[0]):
        for creep in creeps:
            creep.mouse_click_event(pygame.mouse.get_pos())

A couple of things were added. First, there's a handler for the user's pressing the space key on the keyboard. This flips the "paused" state of the game - try it now.

The second handler is only slightly more complex. When a left mouse button is clicked inside the application, each creep gets its mouse_click_event method called with the mouse click coordinates.

The idea is simple: creeps have health, and we can decrease their health by successfully clicking on them. A health bar is drawn above each creep showing its health as a proportion of red to green (click on some creeps to see their health decrease).

The implementation is also quite simple. Here's the mouse click handler of a creep:

def mouse_click_event(self, pos):
    """ The mouse was clicked in pos.
    """
    if self._point_is_inside(vec2d(pos)):
        self._decrease_health(3)

You see that when the click was found to be inside the creep, its health is decreased. Let's see how the click inside the creep is detected:

def _point_is_inside(self, point):
    """ Is the point (given as a vec2d) inside our creep's
        body?
    """
    img_point = point - vec2d(
        int(self.pos.x - self.image_w / 2),
        int(self.pos.y - self.image_h / 2))

    try:
        pix = self.image.get_at(img_point)
        return pix[3] > 0
    except IndexError:
        return False

This method detects if the click is inside the creep. More specifically, inside the solid area of the creep's image. Clicking inside the creep's bounding box but outside its body won't result in True. Here's how it's done:

First, the click point is recomputed to be relatively to the creep's image. If the point isn't inside its image on the screen, there's nothing to talk about. If it is inside, we still don't know if it's in the solid region. For this purpose, the pixel at the point of the click is examined. If the alpha constituent of the point is positive, this is part of the creep's body. Otherwise, it's just part of its bounding box but outside the body (see [2]).

Drawing the health bars is very simple, and you should be able to understand the code of the draw method (which replaces blitme from the code of part I) that implements this.

Simple animation

What happens when the creep's health goes down to 0? I hope you've already experimented with the game and saw it, but if you didn't, here's a screenshot:

If you've played with the game, however, you've surely noticed that the explosion the creep undergoes is animated - it's changing with time.

What is an animation? In its simplest form, it is a sequence of images that are drawn one after another in the same location, creating the appearance of movement. It's not unlike our creeps moving on the screen (you can see the whole game as an animation, really), but for the sake of this part I'm specifically referring to a static animation that stays in the same place.

The animation is implemented in the module simpleanimation.py which you can find in the downloaded code package. You can experiment with it by running it standalone (the module uses Python's if __name__ == "__main__" feature to allow stand-alone running).

The code should be very simple to understand, because there's nothing much to it. The SimpleAnimation class receives a list of image objects and draws them to the screen with the given period and duration. Note how the explosion is simulated by taking the same image, rotating it by 90 degrees and using SimpleAnimation to change the two in rapid succession.

Back in creeps.py, our creep uses SimpleAnimation to show its own explosion after its health has reached 0:

def _explode(self):
    """ Starts the explosion animation that ends the Creep's
        life.
    """
    self.state = Creep.EXPLODING
    pos = ( self.pos.x - self.explosion_images[0].get_width() / 2,
            self.pos.y - self.explosion_images[0].get_height() / 2)
    self.explode_animation = SimpleAnimation(
        self.screen, pos, self.explosion_images,
        100, 300)

It's very straightforward, really.

Creep state

The creeps of this part are much more complex than of part I. They have health which can decrease, and they can explode and disappear. To manage this complexity, we're going to use a state machine [3].

What states can the creep be in? A normal state, when the creep is roaming around, an exploding state in which the creep is replaced by the explosion animation, and an inactive state, in which the creep no longer functions. These are coded as follows:

(ALIVE, EXPLODING, DEAD) = range(3)

See the code of update for state management - the creep is updated differently, depending on which state it's in. The same is true for the draw method. It's a good idea now to search for self.state throughout the code, taking note of where the state is modified, and where it is used.

Displaying textual information

When you run the game (or in the large screenshot at the top of this part), you'll see a simple scoreboard in the top right corner of the screen. It counts the amount of active creeps on the screen, and will also display an exciting message when you've killed all the creeps.

This display is implemented in the function draw_messageboard - study its code now, it should be quite simple to understand in conjunction with the docs.

Sprites and sprite Groups

I hope you've noticed that in both parts of the tutorial, the Creep class derives from pygame.sprite.Sprite. Sprite is a utility class of Pygame that implements some useful common methods for managing the animated images that represent the actors of the game (known in game programming jargon as sprites).

In the first part I didn't use any of its capabilities at all. Here, I'm using its capability of being collected into sprite Groups.

The list of creeps in the main function has now turned into a sprite group. The cool thing is that whenever a sprite is added to a group, it keeps track of which groups it's in, so calling self.kill() in a sprite causes it to be removed from all the groups and thus from the game. The update method of Creep calls kill() when the explosion has ended. This way, the main loop doesn't have to explicitly keep track of which sprites are active in the group - they do it themselves.

That said, I'm still not sure I'm going to use the full capabilities of Sprites. For me, they're just a guideline, not a must. Perhaps I'll find out later that my code can be structured better with them. Or perhaps I'll see I don't need them at all. We'll see [4].

Wrapping up

All the goals stated in the beginning of this part were achieved, so that's it, for now. We've turned the simplistic creeps simulation into something resembling a rudimentary game. True, it's more likely to pave your way to severe RSI than cause you any serious fun, but it's a simple game nonetheless. Not bad for just 450 lines of Python code!

In future parts of this tutorial, we'll continue developing the code on our way to a real game, so stay tuned. Oh, and give the exercises a go, I guarantee you they will make your understanding of the material much deeper.

Exercises

Try to pause the game (press SPACE), click a couple of times on a creep, and resume the game. Notice that the creep's health decreased? Try to fix this, i.e. block mouse events during the pause.
Can you see that when a creep is facing diagonally, his health bar is a bit farther from his body than when he's facing up or to the side? Can you figure out why? (Hint: re-read the section of part I dealing with the size of the rotated image). Propose ways to fix this.
Review the code of the _explode method. Note the complex computation of the explosion's position. Why is it needed? Try to modify it (for example, removing the consideration of the explosion image's size) and observe the difference.
Add a running clock to the scoreboard. It should begin at 00:00 and advance by 1 each second. When the game ends, the clock should stop.
Set the creeps' speed to higher than the default and attempt to catch them. It's quite challenging!

[1]	Note also the usage of the `Color` module to specify color. This is a useful PyGame module, and I've changed almost all the hard-coded color references in the code to named colors.

[2]

The images of creeps are stored in PNG files that support alpha transparency. If you examine the image with an image editor that supports transparency (Paint.NET or GIMP, for example), you'll see that the area outside the creep's round body is transparent. This is used to blend the creep in a pleasing way into its background, and can also be employed to detect what's inside and what's outside of the creeps's body.

[3]	I assume you know what a state machine is, and if you don't, Wikipedia and Google are your friends.

[4]	To learn more about Pygame sprites, read this tutorial.

Writing a game in Python with Pygame. Part I

2008-12-13T11:18:50-08:00

Introduction

Games are one of the most applicative areas of programming. To write even the simplest games, you have to get into graphics, math, physics and even AI. It's a great and fun way to practice programming.

If you're a fan of Python (and even if you aren't) and are interested in games, Pygame is a great library for game programming, and you should definitely check it out. It runs on all major platforms, and provides simple tools to manage complex graphical worlds with movement and sounds.

There are quite a lot of Pygame tutorials on the web, but most of them are basic. Even the Pygame book stays at an introductory level. In order to proceed to a higher level of mastery, I've decided to write a tutorial of my own, hoping that it will provide the next logical step for persons wanting to use Pygame.

This tutorial explicitly encourages you to tinker with the code. It is also highly recommended to do the exercises in the end. These will greatly aid your understanding of the learned material.

Preliminaries

For reasons I've mentioned above, this tutorial is not for complete beginners. If you're just beginning with Pygame, first go through some of the tutorials from this page. This tutorial is also recommended as a basic introduction to Pygame.

Here, I assume that you have the following knowledge:

Python (you don't have to be an advanced user, but not a complete beginner either)
Basics of math and physics (vectors, rectangles, laws of movement, probability, etc.). I will explain all the non-trivial tricks, but I won't teach how to add vectors, and so on.
An acquaintance with Pygame. I.e. you've already went through at least a couple of the tutorials mentioned above.

Oh, and another thing... This tutorial will focus on a 2D game. 3D is a whole new level of complexity, and I prefer a simpler but complete game to a half-baked 3D demo.

Let's get started

In this part, we'll end up writing a demo - a complete simulation of creeps, round creatures that move around the screen, bouncing off walls and changing their direction from time to time:

While this is not yet a game per se, it's a useful starting point, from which we can implement many various ideas. I'll leave myself the luxury of postponing the decision of which game it will eventually be, for now.

The code

The complete package for part 1, with all the required images, can be downloaded from here. I recommend you to download it and run the demo. Having the code in front of your eyes is very useful. I tested it with Python 2.5.2 and Pygame 1.8.1, although it will probably work with other versions as well.

Pygame's docs

Pygame's API is documented fairly well. There is a complete list of modules, classes, constants and functions provided by Pygame there, and I encourage you to consult this resource often - for each Pygame class/method you're not familiar with.

Creeps

Okay, so first let's set the goals for this part:

We want to have creeps moving around the screen
The number of creeps and their appearance should be easily configurable
The creeps will bounce off walls correctly
To make things more interesting, the creeps will exhibit semi-random behavior

So what is a creep ?

A creep is a small image that will be moved around the screen and rotated using Pygame's capabilities. Keeping rotated images pretty takes more artistic skill than I possess, so I'll limit the rotations to quantas of 45 degrees (meaning that creeps will move up, down, left, right or in 4 diagonals).

The creep images contained in the downloadable package are small .png files [1]

Note that all the creep images have the same orientation. This is significant, as we will learn later.

How do creeps move?

As you've undoubtedly read in one of the basic Pygame tutorials (haven't you ??), movement is an illusion. Nothing really moves on a computer screen. Rather, the program displays a sequence of images with small displacements fast enough for the human eye to perceive movement. The rule of thumb is that anything 30 updates per second [2] or faster is good enough and looks smooth to the average person.

To implement periodic update of the screen, games use the game loop.

The game loop

Just like a GUI, every game has the "main loop". In Pygame you implement it with a Python loop, which is simple enough. Here's our main loop:

# The main game loop
#
while True:
    # Limit frame speed to 50 FPS
    #
    time_passed = clock.tick(50)

    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            exit_game()

    # Redraw the background
    screen.fill(BG_COLOR)

    # Update and redraw all creeps
    for creep in creeps:
        creep.update(time_passed)
        creep.blitme()

    pygame.display.flip()

Jumping right into the code, eh ? Well, let's see what goes on here. As I've said, it's your basic Python loop - endless, until the user asks to quit. pygame.QUIT is the only event handled here, as you can see. It arrives when the user attempts to close the program's window.

How often does this loop run ? This is decided by the call to clock.tick. clock is a pygame.time.Clock object, created earlier. The call to tick basically says this: sleep until the next 1/50 second boundary, at most. In practice, this limits the game speed to 50 FPS, which is a good thing, because we want the game to be smooth on one hand, and not eat up most of the CPU on the other hand. You can experiment with this effect by playing with the value. Lower it to 10, for example. How does the demo look ? Also, see exercises 1 and 3.

Now is a good time to immerse yourself in the documentation of tick, by the way.

The really interesting stuff happens later. On each iteration, the screen is refilled with the background color and all the creeps are updated and drawn. Finally, the display is updated with flip (Yes, you should read its documentation now).

What comes before the loop

Now let's see what comes before the main loop:

# Game parameters
SCREEN_WIDTH, SCREEN_HEIGHT = 400, 400
BG_COLOR = 150, 150, 80
CREEP_FILENAMES = [
    'bluecreep.png',
    'pinkcreep.png',
    'graycreep.png']
N_CREEPS = 20

pygame.init()
screen = pygame.display.set_mode(
            (SCREEN_WIDTH, SCREEN_HEIGHT), 0, 32)
clock = pygame.time.Clock()

# Create N_CREEPS random creeps.
creeps = []
for i in range(N_CREEPS):
    creeps.append(Creep(screen,
                        choice(CREEP_FILENAMES),
                        (   randint(0, SCREEN_WIDTH),
                            randint(0, SCREEN_HEIGHT)),
                        (   choice([-1, 1]),
                            choice([-1, 1])),
                        0.1))

OK, not much magic here. The first few lines are self-explanatory. I also assume you already know how to initialize Pygame and create a display object. What about the creation of creeps, though?

creeps is a list of Creep objects - the heart and soul of this game. Here's the declaration of the Creep class with its constructor's signature:

class Creep(Sprite):
    """ A creep sprite that bounces off walls and changes its
        direction from time to time.
    """
    def __init__(
            self, screen, img_filename, init_position,
            init_direction, speed):
        """ Create a new Creep.

            screen:
                The screen on which the creep lives (must be a
                pygame Surface object, such as pygame.display)

            img_filaneme:
                Image file for the creep.

            init_position:
                A vec2d or a pair specifying the initial position
                of the creep on the screen.

            init_direction:
                A vec2d or a pair specifying the initial direction
                of the creep. Must have an angle that is a
                multiple of 45 degres.

            speed:
                Creep speed, in pixels/millisecond (px/ms)
        """

The arguments are well documented, and you can see how they are matched by the passed values when the creeps are created:

creeps.append(Creep(screen,
                    choice(CREEP_FILENAMES),
                    (   randint(0, SCREEN_WIDTH),
                        randint(0, SCREEN_HEIGHT)),
                    (   choice([-1, 1]),
                        choice([-1, 1])),
                    0.1))

First, we pass the screen surface to the Creep. It will use it to figure out how to bounce off walls, and where to draw itself.

Next, the Creep is provided with a random image from the list of images (choice is a function from Python's standard random module), and is set in a random position on the screen (randint is also from random), with a random direction (more about the direction later). The speed is set to 0.1 px/ms (0.1 pixels per millisecond), or 100 pixels per second.

Vectors and directions

This is perhaps the least simple part of the creeps demo. Grokking vectors in game programming is essential, since vectors are the chief mathematical tool for making computations related to movement on the screen.

We'll use vectors for two things. One is to describe the position and velocity (displacement) of creeps. As you surely know, a position (a point) on the XY plane can be represented by a 2D vector. The difference between two vectors is the velocity (displacement) vector. In other words, adding the velocity vector to the original position vector yields the new position:

This is all good and nice, except for a small twist. While in the mathematical world, we're accustomed to the XY plane to look as it does on the diagram above (positive X pointing right, positive Y pointing up), when we're drawing on the screen we must think a bit differently. In almost all graphical drawing interfaces, the top-left corner is (0, 0), X increases to the right, and Y increases to downwards. In other words, the screen drawing XY plane is:

This is a very important diagram! It represents the basic 8 normalized vectors we'll be using in the creep demo. These are the directions the creep can be pointing in (all multiples of 45 degrees over the unit circle). Make sure you understand it before moving on.

Recall the direction argument to the constructor of Creep ? This is the vector that specifies the initial direction of the creep. Actually, the constructor allows to pass in a pair, which is later turned into a vector and normalized (so, for instance, passing the pair (-1, -1) will result in the expected north-west direction).

This direction will be later changed by the creep itself when it either decides to go another way or bounces off a wall.

Implementing vectors

Surprisingly, Pygame doesn't have a "standard" vector implementation shipping with it. So game writers have to either roll their own or find vector modules online.

Included in the package is the vec2d.py file, a 2D vector implementation I've borrowed from the Pygame Wiki. It is a pretty good implementation of a 2D vector with a lot of useful utility functions. There's no need for you to read and understand its full code now, but see exercise 4.

Updating the creep

The most interesting function of this demo is the update method of Creep.

def update(self, time_passed):

This method is called periodically by the main loop and is passed the amount of time passed (in milliseconds) since the previous call. Using this knowledge, the creep can compute its next location.

Let's learn the code of update, step by step:

# Maybe it's time to change the direction ?
#
self._change_direction(time_passed)

# Make the creep point in the correct direction.
# Since our direction vector is in screen coordinates
# (i.e. right bottom is 1, 1), and rotate() rotates
# counter-clockwise, the angle must be inverted to
# work correctly.
#
self.image = pygame.transform.rotate(
    self.base_image, -self.direction.angle)

First, the internal _change_direction is called to see if the creep wants to randomly change its direction. The code of _change_direction will be simple to understand after we complete going through update, so I'm leaving it for exercise 5.

The next operation is to rotate the creep image in the correct direction. Recall how I noted that all the creep images point to the right? This is essential for correct and consistent rotation. transform.rotate (read its docs!) rotates a given surface counterclockwise by the provided angle.

Now, why do we give it a negation of the angle ? This is exactly because of the inverted "screen XY plane" I've mentioned before. Imagine the base creep image (which is, by the way, loaded in the constructor of Creep - see how):

And suppose our direction is 45 degrees (that is, south-east in our screen coordinates). If we give 45 degrees to rotate, it will make the creep point north-east (as its rotation is counterclockwise). So to perform the correct rotation, we have to negate the angle.

Next in update, we see:

# Compute and apply the displacement to the position
# vector. The displacement is a vector, having the angle
# of self.direction (which is normalized to not affect
# the magnitude of the displacement)
#
displacement = vec2d(
    self.direction.x * self.speed * time_passed,
    self.direction.y * self.speed * time_passed)

self.pos += displacement

As I said, self.direction is a normalized vector that tells us where the creep points to. It is important for it to be normalized for this computation to work correctly, because we don't want it to affect the magnitude of the displacement. The displacement is computed from the basic rule of motion that distance equals speed multiplied by time, just in 2 dimensions.

The next part of update deals with bouncing off walls. To make it more intelligible, I want to first show how the creep is drawn to the screen.

Blitme!

Blitting is the game programmers' jargon for transferring an image (or a pattern) onto a drawable surface. In Pygame this is implemented with the blit function.

def blitme(self):
    """ Blit the creep onto the screen that was provided in
        the constructor.
    """
    # The creep image is placed at self.pos.
    # To allow for smooth movement even when the creep rotates
    # and the image size changes, its placement is always
    # centered.
    #
    draw_pos = self.image.get_rect().move(
        self.pos.x - self.image_w / 2,
        self.pos.y - self.image_h / 2)
    self.screen.blit(self.image, draw_pos)

Blitting, like many other things in Pygame, use the versatile pygame.Rect class. The call to blit accepts an image (a surface, actually) and a rectangle that specifies where this image will be blitted to the surface on which blit is invoked.

And sure enough, we provide the drawing position as the creep's current position (self.pos) but with a small adjustment. What for ?

Thing is, when images are rotated in Pygame, their size increases. Here's why:

Since the image is square, Pygame has to include all of its information in the rotated image, so the rotated image has to grow in size. This only happens for rotations that are not multiples of 90 degrees, by the way (see exercise 6).

So, whenever a creep turns, its image size changes. Without a special adjustment, the creep will shift with each turn and the animation won't be smooth and pretty.

The adjustment is simple enough: we center the creep when we draw it. Look at this code again:

draw_pos = self.image.get_rect().move(
    self.pos.x - self.image_w / 2,
    self.pos.y - self.image_h / 2)
self.screen.blit(self.image, draw_pos)

The draw position is computed to be the center of the creep's image. Even when the image rotates and grows, its center stays in the same place, so there will be no noticeable shift in the creep this way.

Bouncing off walls

Make sure you understand the "centered drawing" trick described in the previous section (and see exercise 7) first. Once you do, understanding how the creep bounces off walls is easy. Here's the code:

# When the image is rotated, its size is changed.
# We must take the size into account for detecting
# collisions with the walls.
#
self.image_w, self.image_h = self.image.get_size()
bounds_rect = self.screen.get_rect().inflate(
                -self.image_w, -self.image_h)

if self.pos.x < bounds_rect.left:
    self.pos.x = bounds_rect.left
    self.direction.x *= -1
elif self.pos.x > bounds_rect.right:
    self.pos.x = bounds_rect.right
    self.direction.x *= -1
elif self.pos.y < bounds_rect.top:
    self.pos.y = bounds_rect.top
    self.direction.y *= -1
elif self.pos.y > bounds_rect.bottom:
    self.pos.y = bounds_rect.bottom
    self.direction.y *= -1

First, the screen boundary itself is computed, by taking the rectangle representing the screen and adjusting it to the image size (this is required for our centered drawing).

Then, for each of the 4 walls we compute whether the creep collides with it, and if it does, the creep's direction is inverted in the axis perpendicular to the wall, simulating a smooth bounce. Let's dissect one of such conditions:

if self.pos.x < bounds_rect.left:
    self.pos.x = bounds_rect.left
    self.direction.x *= -1

This is for the bounce off the left wall. The creeps always arrives to it from the right, so when we negate the X component of its direction vector while keeping the Y component intact, it will start moving to the right but with the same vertical direction.

Conclusion

We've seen most of the interesting code of creeps.py now. If something still remains unclear, go through the whole code with the diagrams from this tutorial in front of your eyes. If things remain unclear, let me know and I'll gladly help.

One can understand a tutorial or a lecture on several levels. The most basic is just reading it. To make understanding deeper, one must also practice the material. And to master something, you should apply your brain to new material, new challenges based on the tutorial but not directly explained in it. For this, I once again warmly encourage you to at least look at the exercises and try to think how to do them. The best would be implementing solutions and tinkering with the code itself.

What's next

The creeps demo can serve as a good basis for quite a few games. I haven't decided which I want to write, yet, and how far I want to take this tutorial at all. So its future direction depends a lot on your feedback. Feel free to comment or write me an email.

Exercises

Increase the amount of creeps by modifying the N_CREEPS constant. On my PC, the demo runs easily and smoothly with hundreds of creeps.
Modify the creep creation line to have 60% gray creeps, 20% blue and 20% pink.
Experiment with the call to clock.tick in the main loop. Try to print out the time passed between ticks, and then modify the argument to tick. If you provide no argument, it runs as fast as it can. See how much time passes between ticks when the amount of creeps increases.
Open vec2d.py, and read the code of all the methods and attributes used in our creeps demo.
Modify the _change_direction method to change the behavior of creeps. (1) Make them change direction more often and observe the behavior. (2) Can you make them stop for a second once in a while ? You'd have to modify the speed for that.
Can you use basic trigonometry to compute by how much the image increases when it's rotated by 45 degrees in Pygame ?
Rewrite the drawing code to cancel centered drawing (just provide the unadjusted image rectangle to blit). How does it look ?

Updates

13.12.2008 - Simplified the code for bouncing off walls. Thanks to Andrei for the tip.

[1]	PNG is a useful format - it is free, provides efficient lossless compression and supports alpha (transparency).

[2]	Or Frames Per Second (FPS) in game programming jargon. Counting FPS is the hobby of game programmers worldwide.