Making Games with Python & Pygame

1

Gates to Buddhist Practice Padma Pub Chagdud Tulku Year: 1993 Language: english File: PDF, 10.79 MB

2

Zizek: A Reader's Guide Wiley-Blackwell Kelsey Wood Year: 2012 Language: english File: PDF, 4.20 MB

Making Games with
Python & Pygame

By Al Sweigart

Copyright © 2012 by Albert Sweigart
Some Rights Reserved. ―Making Games with Python & Pygame‖) is licensed under a Creative
Commons Attribution-Noncommercial-Share Alike 3.0 United States License.
You are free:
To Share — to copy, distribute, display, and perform the work
To Remix — to make derivative works
Under the following conditions:
Attribution — You must attribute the work in the manner specified by the author or
licensor (but not in any way that suggests that they endorse you or your use of the work).
(Visibly include the title and author's name in any excerpts of this work.)
Noncommercial — You may not use this work for commercial purposes.
Share Alike — If you alter, transform, or build upon this work, you may distribute
the resulting work only under the same or similar license to this one.

This summary is located here: http://creativecommons.org/licenses/by-nc-sa/3.0/us/
Your fair use and other rights are in no way affected by the above. There is a human-readable
summary of the Legal Code (the full license), located here:
http://creativecommons.org/licenses/by-nc-sa/3.0/us/legalcode
Book Version 2

If you've downloaded this book from a torrent, it’s probably out of date. Go
to http://inventwithpython.com/pygame to download the latest version.
ISBN (978-1469901732)
1st Edition

Email questions to the author: al@inventwithpython.com

For Calvin Chaos

Email questions to the author: al@inventwithpython.com

Who is this book for?

i

WHO IS THIS BOOK FOR?
When you get down to it, programming video games is just about lighting up pixels to make
pretty pictures appear on the screen in response to keyboard and mouse input.
And there are very few things that are as fun.
This book will teach you how to make graphical computer games in the Python programming
language using the Pygame library. This book assumes you know a little bit about Python or
programming in general. If you don’t know how to program, you can learn by downloading the
free book ―Invent Your Own Computer Games with Python‖ from http://inventwithpython.com.
Or you can jump right into this book and mostly pick it up along the way.
This book is for the intermediate programmer who has learned what variables and loops are, but
now wants to know, ―What do actual game programs look like?‖ There was a long gap after I first
learned programming but didn’t really know how to use that skill to make something cool. It’s
my hope that the games in this book will give you enough ideas about how programs work to
provide a foundation to implement your own games.
The full text of this book is available in HTML or PDF format at
http://inventwithpython.com/pygame.
-Al Sweigart

ii

http://inventwithpython.com/pygame

ABOUT THIS BOOK
Hello! This book will teach you how to make graphical computer games with the Pygame
framework (also called the Pygame library) in the Python programming language. Pygame makes
it easy to create programs with 2D graphics. Both Python and the Pygame framework can be
downloaded for free from http://python.org and http://pygame.org. All you need is a computer
and this book to begin making your own games.
This book is an intermediate programming book. If you are completely new to programming,
you can still try to follow along with the source code examples and figure out how programming
works. However, it might be easier to learn how to program in Python first. ―Invent Your Own
Computer Games with Python‖ is a book that is available completely for free from
http://inventwithpython.com. That book teaches programming by making non-graphical, textbased games for complete beginners, and also has a few chapters about using the Pygame library.
However, if you already know how to program in Python (or even some other language, since
Python is so easy to pick up) and want to start making games beyond just text, then this is the
book for you. The book starts with a short introduction to how the Pygame library works and the
functions it provides. Then it provides the complete source code for some actual games and
explains how the code works, so you can understand how actual game programs make use of
Pygame.
This book features seven different games that are clones of popular games that you’ve probably
already played. The games are a lot more fun and interactive than the text-based games in ―Invent
with Python‖, but are still fairly short. All of the programs are less than 600 lines long. This is
pretty small when you consider that professional games you download or buy in a store can be
hundreds of thousands of lines long. These games require an entire team of programmers and
artists working with each other for months or years to make.
The website for this book is http://inventwithpython.com/pygame. All the programs and files
mentioned in this book can be downloaded for free from this website, including this book itself.
Programming is a great creative activity, so please share this book as widely as possible. The
Creative Commons license that this book is released under gives you the right to copy and
duplicate this book as much as you want (as long as you don’t charge money for it).
If you ever have questions about how these programs work, feel free to email me at
al@inventwithpython.com.

Email questions to the author: al@inventwithpython.com

About This Book

iii

TABLE OF CONTENTS
Who is this book for? ........................................................................................................................ i
About This Book .............................................................................................................................. ii
Chapter 1 – Installing Python and Pygame ...................................................................................... 1
What You Should Know Before You Begin ................................................................................ 1
Downloading and Installing Python ............................................................................................. 1
Windows Instructions .................................................................................................................. 1
Mac OS X Instructions................................................................................................................. 2
Ubuntu and Linux Instructions .................................................................................................... 2
Starting Python............................................................................................................................. 2
Installing Pygame......................................................................................................................... 3
How to Use This Book................................................................................................................. 4
The Featured Programs ................................................................................................................ 4
Downloading Graphics and Sound Files ...................................................................................... 4
Line Numbers and Spaces ............................................................................................................ 4
Text Wrapping in This Book ....................................................................................................... 5
Checking Your Code Online ........................................................................................................ 6
More Info Links on http://invpy.com ........................................................................................... 6
Chapter 2 – Pygame Basics.............................................................................................................. 7
GUI vs. CLI ................................................................................................................................. 7
Source Code for Hello World with Pygame ................................................................................ 7
Setting Up a Pygame Program ..................................................................................................... 8
Game Loops and Game States ................................................................................................... 10
pygame.event.Event Objects ........................................................................................... 11

The QUIT Event and pygame.quit() Function .................................................................. 12
Pixel Coordinates ....................................................................................................................... 13

iv http://inventwithpython.com/pygame
A Reminder About Functions, Methods, Constructor Functions, and Functions in Modules (and
the Difference Between Them) .................................................................................................. 14
Surface Objects and The Window ............................................................................................. 15
Colors ......................................................................................................................................... 16
Transparent Colors ..................................................................................................................... 17
pygame.Color Objects.......................................................................................................... 18

Rect Objects ............................................................................................................................... 18
Primitive Drawing Functions ..................................................................................................... 20
pygame.PixelArray Objects.............................................................................................. 23

The pygame.display.update() Function ...................................................................... 24
Animation .................................................................................................................................. 24
Frames Per Second and pygame.time.Clock Objects ....................................................... 27
Drawing Images with pygame.image.load() and blit() ............................................ 28
Fonts........................................................................................................................................... 28
Anti-Aliasing.............................................................................................................................. 30
Playing Sounds........................................................................................................................... 31
Summary .................................................................................................................................... 32
Chapter 3 – Memory Puzzle .......................................................................................................... 33
How to Play Memory Puzzle ..................................................................................................... 33
Nested for Loops ..................................................................................................................... 33
Source Code of Memory Puzzle ................................................................................................ 34
Credits and Imports .................................................................................................................... 42
Magic Numbers are Bad ............................................................................................................ 42
Sanity Checks with assert Statements................................................................................... 43
Telling If a Number is Even or Odd .......................................................................................... 44
Crash Early and Crash Often! .................................................................................................... 44
Making the Source Code Look Pretty ........................................................................................ 45
Using Constant Variables Instead of Strings ............................................................................. 46
Making Sure We Have Enough Icons ........................................................................................ 47
Tuples vs. Lists, Immutable vs. Mutable ................................................................................... 47
Email questions to the author: al@inventwithpython.com

About This Book

v

One Item Tuples Need a Trailing Comma ................................................................................. 48
Converting Between Lists and Tuples ....................................................................................... 49
The global statement, and Why Global Variables are Evil.................................................... 49
Data Structures and 2D Lists ..................................................................................................... 51
The ―Start Game‖ Animation..................................................................................................... 52
The Game Loop ......................................................................................................................... 52
The Event Handling Loop .......................................................................................................... 53
Checking Which Box The Mouse Cursor is Over ..................................................................... 54
Handling the First Clicked Box ................................................................................................. 55
Handling a Mismatched Pair of Icons ........................................................................................ 56
Handling If the Player Won ....................................................................................................... 56
Drawing the Game State to the Screen ...................................................................................... 57
Creating the ―Revealed Boxes‖ Data Structure ......................................................................... 58
Creating the Board Data Structure: Step 1 – Get All Possible Icons ......................................... 58
Step 2 – Shuffling and Truncating the List of All Icons ............................................................ 59
Step 3 – Placing the Icons on the Board .................................................................................... 59
Splitting a List into a List of Lists.............................................................................................. 60
Different Coordinate Systems .................................................................................................... 61
Converting from Pixel Coordinates to Box Coordinates ........................................................... 62
Drawing the Icon, and Syntactic Sugar ...................................................................................... 63
Syntactic Sugar with Getting a Board Space’s Icon’s Shape and Color .................................... 64
Drawing the Box Cover ............................................................................................................. 64
Handling the Revealing and Covering Animation ..................................................................... 65
Drawing the Entire Board .......................................................................................................... 66
Drawing the Highlight ............................................................................................................... 67
The ―Start Game‖ Animation..................................................................................................... 67
Revealing and Covering the Groups of Boxes ........................................................................... 68
The ―Game Won‖ Animation .................................................................................................... 68
Telling if the Player Has Won ................................................................................................... 69

vi

http://inventwithpython.com/pygame

Why Bother Having a main() Function? ................................................................................ 69
Why Bother With Readability? .................................................................................................. 70
Summary, and a Hacking Suggestion ........................................................................................ 74
Chapter 4 – Slide Puzzle ................................................................................................................ 77
How to Play Slide Puzzle ........................................................................................................... 77
Source Code to Slide Puzzle ...................................................................................................... 77
Second Verse, Same as the First ................................................................................................ 85
Setting Up the Buttons ............................................................................................................... 86
Being Smart By Using Stupid Code .......................................................................................... 87
The Main Game Loop ................................................................................................................ 88
Clicking on the Buttons ............................................................................................................. 89
Sliding Tiles with the Mouse ..................................................................................................... 90
Sliding Tiles with the Keyboard ................................................................................................ 90
―Equal To One Of‖ Trick with the in Operator ........................................................................ 91
WASD and Arrow Keys ............................................................................................................ 91
Actually Performing the Tile Slide ............................................................................................ 92
IDLE and Terminating Pygame Programs ................................................................................. 92
Checking for a Specific Event, and Posting Events to Pygame’s Event Queue ........................ 92
Creating the Board Data Structure ............................................................................................. 93
Not Tracking the Blank Position................................................................................................ 94
Making a Move by Updating the Board Data Structure ............................................................ 94
When NOT to Use an Assertion ................................................................................................ 95
Getting a Not-So-Random Move ............................................................................................... 96
Converting Tile Coordinates to Pixel Coordinates .................................................................... 97
Converting from Pixel Coordinates to Board Coordinates ........................................................ 97
Drawing a Tile ........................................................................................................................... 97
The Making Text Appear on the Screen .................................................................................... 98
Drawing the Board ..................................................................................................................... 99
Drawing the Border of the Board............................................................................................... 99

Email questions to the author: al@inventwithpython.com

About This Book

vii

Drawing the Buttons ................................................................................................................ 100
Animating the Tile Slides ........................................................................................................ 100
The copy() Surface Method ................................................................................................. 101
Creating a New Puzzle ............................................................................................................. 103
Animating the Board Reset ...................................................................................................... 104
Time vs. Memory Tradeoffs .................................................................................................... 105
Nobody Cares About a Few Bytes ........................................................................................... 106
Nobody Cares About a Few Million Nanoseconds .................................................................. 107
Summary .................................................................................................................................. 107
Chapter 5 – Simulate.................................................................................................................... 108
How to Play Simulate .............................................................................................................. 108
Source Code to Simulate .......................................................................................................... 108
The Usual Starting Stuff .......................................................................................................... 114
Setting Up the Buttons ............................................................................................................. 115
The main() Function ............................................................................................................. 115
Some Local Variables Used in This Program .......................................................................... 116
Drawing the Board and Handling Input ................................................................................... 117
Checking for Mouse Clicks ..................................................................................................... 118
Checking for Keyboard Presses ............................................................................................... 118
The Two States of the Game Loop .......................................................................................... 119
Figuring Out if the Player Pressed the Right Buttons .............................................................. 119
Epoch Time .............................................................................................................................. 121
Drawing the Board to the Screen ............................................................................................. 122
Same Old terminate() Function ....................................................................................... 122
Reusing The Constant Variables .............................................................................................. 123
Animating the Button Flash ..................................................................................................... 123
Drawing the Buttons ................................................................................................................ 126
Animating the Background Change ......................................................................................... 126
The Game Over Animation ...................................................................................................... 127

viii

http://inventwithpython.com/pygame

Converting from Pixel Coordinates to Buttons ........................................................................ 129
Explicit is Better Than Implicit................................................................................................ 129
Chapter 6 – Wormy ...................................................................................................................... 131
How to Play Wormy ................................................................................................................ 131
Source Code to Wormy ............................................................................................................ 131
The Grid ................................................................................................................................... 137
The Setup Code ........................................................................................................................ 137
The main() Function ............................................................................................................. 138
A Separate runGame() Function .......................................................................................... 139
The Event Handling Loop ........................................................................................................ 139
Collision Detection .................................................................................................................. 140
Detecting Collisions with the Apple ........................................................................................ 141
Moving the Worm .................................................................................................................... 142
The insert() List Method................................................................................................... 142
Drawing the Screen .................................................................................................................. 143
Drawing ―Press a key‖ Text to the Screen ............................................................................... 143
The checkForKeyPress() Function ................................................................................ 143
The Start Screen ....................................................................................................................... 144
Rotating the Start Screen Text ................................................................................................. 145
Rotations Are Not Perfect ........................................................................................................ 146
Deciding Where the Apple Appears ........................................................................................ 147
Game Over Screens.................................................................................................................. 147
Drawing Functions ................................................................................................................... 148
Don’t Reuse Variable Names ................................................................................................... 151
Chapter 7 - Tetromino .................................................................................................................. 153
How to Play Tetromino ............................................................................................................ 153
Some Tetromino Nomenclature ............................................................................................... 153
Source Code to Tetromino ....................................................................................................... 154
The Usual Setup Code ............................................................................................................. 166

Email questions to the author: al@inventwithpython.com

About This Book

ix

Setting up Timing Constants for Holding Down Keys ............................................................ 166
More Setup Code ..................................................................................................................... 166
Setting Up the Piece Templates ............................................................................................... 168
Splitting a ―Line of Code‖ Across Multiple Lines ................................................................... 171
The main() Function ............................................................................................................. 172
The Start of a New Game......................................................................................................... 173
The Game Loop ....................................................................................................................... 174
The Event Handling Loop ........................................................................................................ 174
Pausing the Game .................................................................................................................... 174
Using Movement Variables to Handle User Input ................................................................... 175
Checking if a Slide or Rotation is Valid .................................................................................. 175
Finding the Bottom .................................................................................................................. 178
Moving by Holding Down the Key.......................................................................................... 179
Letting the Piece ―Naturally‖ Fall ............................................................................................ 182
Drawing Everything on the Screen .......................................................................................... 182
makeTextObjs(), A Shortcut Function for Making Text .................................................. 183

The Same Old terminate() Function ................................................................................ 183
Waiting for a Key Press Event with the checkForKeyPress() Function........................ 183
showTextScreen(), A Generic Text Screen Function ..................................................... 184

The checkForQuit() Function.......................................................................................... 185
The calculateLevelAndFallFreq() Function .......................................................... 185
Generating Pieces with the getNewPiece() Function ....................................................... 188
Adding Pieces to the Board Data Structure ............................................................................. 189
Creating a New Board Data Structure...................................................................................... 189
The isOnBoard() and isValidPosition() Functions ............................................... 190
Checking for, and Removing, Complete Lines ........................................................................ 192
Convert from Board Coordinates to Pixel Coordinates ........................................................... 195
Drawing a Box on the Board or Elsewhere on the Screen ....................................................... 195
Drawing Everything to the Screen ........................................................................................... 196

x

http://inventwithpython.com/pygame

Drawing the Score and Level Text .......................................................................................... 196
Drawing a Piece on the Board or Elsewhere on the Screen ..................................................... 197
Drawing the ―Next‖ Piece ........................................................................................................ 197
Summary .................................................................................................................................. 198
Chapter 8 – Squirrel Eat Squirrel ................................................................................................. 200
How to Play Squirrel Eat Squirrel............................................................................................ 200
The Design of Squirrel Eat Squirrel ......................................................................................... 200
Source Code to Squirrel Eat Squirrel ....................................................................................... 201
The Usual Setup Code ............................................................................................................. 211
Describing the Data Structures ................................................................................................ 212
The main() Function ............................................................................................................. 213
The pygame.transform.flip() Function .................................................................... 214
A More Detailed Game State than Usual ................................................................................. 214
The Usual Text Creation Code................................................................................................. 215
Cameras ................................................................................................................................... 215
The ―Active Area‖ ................................................................................................................... 217
Keeping Track of the Location of Things in the Game World ................................................ 218
Starting Off with Some Grass .................................................................................................. 219
The Game Loop ....................................................................................................................... 219
Checking to Disable Invulnerability ........................................................................................ 219
Moving the Enemy Squirrels ................................................................................................... 219
Removing the Far Away Grass and Squirrel Objects .............................................................. 221
When Deleting Items in a List, Iterate Over the List in Reverse ............................................. 221
Adding New Grass and Squirrel Objects ................................................................................. 223
Camera Slack, and Moving the Camera View ......................................................................... 223
Drawing the Background, Grass, Squirrels, and Health Meter ................................................ 224
The Event Handling Loop ........................................................................................................ 226
Moving the Player, and Accounting for Bounce...................................................................... 228
Collision Detection: Eat or Be Eaten ....................................................................................... 229

Email questions to the author: al@inventwithpython.com

About This Book

xi

The Game Over Screen ............................................................................................................ 231
Winning ................................................................................................................................... 232
Drawing a Graphical Health Meter .......................................................................................... 232
The Same Old terminate() Function ................................................................................ 232
The Mathematics of the Sine Function .................................................................................... 233
Backwards Compatibility with Python Version 2.................................................................... 236
The getRandomVelocity() Function.............................................................................. 237
Finding a Place to Add New Squirrels and Grass .................................................................... 237
Creating Enemy Squirrel Data Structures ................................................................................ 238
Flipping the Squirrel Image ..................................................................................................... 239
Creating Grass Data Structures ................................................................................................ 239
Checking if Outside the Active Area ....................................................................................... 240
Summary .................................................................................................................................. 241
Chapter 9 – Star Pusher................................................................................................................ 242
How to Play Star Pusher .......................................................................................................... 242
Source Code to Star Pusher...................................................................................................... 242
The Initial Setup....................................................................................................................... 256
Data Structures in Star Pusher ................................................................................................. 271
The ―Game State‖ Data Structure ............................................................................................ 271
The ―Map‖ Data Structure ....................................................................................................... 271
The ―Levels‖ Data Structure .................................................................................................... 272
Reading and Writing Text Files ............................................................................................... 272
Text Files and Binary Files ...................................................................................................... 272
Writing to Files ........................................................................................................................ 273
Reading from Files................................................................................................................... 274
About the Star Pusher Map File Format .................................................................................. 274
Recursive Functions ................................................................................................................. 280
Stack Overflows ....................................................................................................................... 281
Preventing Stack Overflows with a Base Case ........................................................................ 283

xii http://inventwithpython.com/pygame
The Flood Fill Algorithm ......................................................................................................... 284
Drawing the Map ..................................................................................................................... 285
Checking if the Level is Finished ............................................................................................ 287
Summary .................................................................................................................................. 288
Chapter 10 – Four Extra Games ................................................................................................... 289
Flippy, an ―Othello‖ Clone ...................................................................................................... 290
Source Code for Flippy ............................................................................................................ 292
Ink Spill, a ―Flood It‖ Clone .................................................................................................... 305
Source Code for Ink Spill ........................................................................................................ 305
Four-In-A-Row, a ―Connect Four‖ Clone................................................................................ 317
Source Code for Four-In-A-Row ............................................................................................. 317
Gemgem, a ―Bejeweled‖ Clone ............................................................................................... 327
Source Code for Gemgem ........................................................................................................ 327
Summary .................................................................................................................................. 340
Glossary ....................................................................................................................................... 342
About the Author ......................................................................................................................... 347

Email questions to the author: al@inventwithpython.com

About This Book

xiii

This page intentionally left blank.

…except for the above text.
And the above text.
And the above text.
And the above text.
And the above text.
And the above text.
And the above text.
And the above text.
And the above text.
Traceback (most recent call last):
File "<pyshell#1>", line 1, in blankpage
def blankpage(): blankpage()
RuntimeError: maximum recursion depth exceeded

xiv http://inventwithpython.com/pygame

Email questions to the author: al@inventwithpython.com

Chapter 1 – Installing Python and Pygame

1

CHAPTER 1 – INSTALLING
PYTHON AND PYGAME
What You Should Know Before You Begin
It might help if you know a bit about Python programming (or how to program in another
language besides Python) before you read through this book; however even if you haven’t you
can still read this book anyway. Programming isn’t nearly as hard as people think it is. If you ever
run into some trouble, you can read the free book ―Invent Your Own Computer Games with
Python‖ online at http://inventwithpython.com or look up a topic that you find confusing on the
Invent with Python wiki at http://inventwithpython.com/wiki.
You don’t need to know how to use the Pygame library before reading this book. The next
chapter is a brief tutorial on all of Pygame’s major features and functions.
Just in case you haven’t read the first book and already installed Python and Pygame on your
computer, the installation instructions are in this chapter. If you already have installed both of
these then you can skip this chapter.

Downloading and Installing Python
Before we can begin programming you'll need to install software called the Python interpreter on
your computer. (You may need to ask an adult for help here.) The interpreter is a program that
understands the instructions that you’ll write (or rather, type out) in the Python language. Without
the interpreter, your computer won't be able to run your Python programs. We'll just refer to ―the
Python interpreter‖ as ―Python‖ from now on.
The Python interpreter software can be downloaded from the official website of the Python
programming language, http://www.python.org. You might want the help of someone else to
download and install the Python software. The installation is a little different depending on if
your computer’s operating system is Windows, Mac OS X, or a Linux OS such as Ubuntu. You
can also find videos online of people installing the Python software on their computers at
http://invpy.com/installing.

Windows Instructions
When you get to http://python.org, you should see a list of links on the left (such as ―About‖,
―News‖, ―Documentation‖, ―Download‖, and so on). Click on the Download link to go to the

2

http://inventwithpython.com/pygame

download page, then look for the file called ―Python 3.2 Windows Installer (Windows binary -does not include source)‖ and click on its link to download Python for Windows.
Double-click on the python-3.2.msi file that you've just downloaded to start the Python installer.
(If it doesn’t start, try right-clicking the file and choosing Install.) Once the installer starts up,
just keep clicking the Next button and just accept the choices in the installer as you go (no need
to make any changes). When the install is finished, click Finish.

Mac OS X Instructions
Mac OS X 10.5 comes with Python 2.5.1 pre-installed by Apple. Currently, Pygame only
supports Python 2 and not Python 3. However, the programs in this book work with both Python
2 and 3.
The Python website also has some additional information about using Python on a Mac at
http://docs.python.org/dev/using/mac.html.

Ubuntu and Linux Instructions
Pygame for Linux also only supports Python 2, not Python 3. If your operating system is Ubuntu,
you can install Python by opening a terminal window (from the desktop click on Applications >
Accessories > Terminal) and entering ―sudo apt-get install python2.7‖ then
pressing Enter. You will need to enter the root password to install Python, so ask the person who
owns the computer to type in this password if you do not know it.
You also need to install the IDLE software. From the terminal, type in ―sudo apt-get
install idle‖. The root password is also needed to install IDLE (ask the owner of your
computer to type in this password for you).

Starting Python
We will be using the IDLE software to type in our programs and run them. IDLE stands for
Interactive DeveLopment Environment. The development environment is software that makes it
easy to write Python programs, just like word processor software makes it easy to write books.
If your operating system is Windows XP, you should be able to run Python by clicking the Start
button, then selecting Programs, Python 3.1, IDLE (Python GUI). For Windows Vista or
Windows 7, just click the Windows button in the lower left corner, type ―IDLE‖ and select
―IDLE (Python GUI)‖.
If your operating system is Max OS X, start IDLE by opening the Finder window and click on
Applications, then click Python 3.2, then click the IDLE icon.

Email questions to the author: al@inventwithpython.com

Chapter 1 – Installing Python and Pygame

3

If your operating system is Ubuntu or Linux, start IDLE by opening a terminal window and then
type ―idle3‖ and press Enter. You may also be able to click on Applications at the top of the
screen, and then select Programming, then IDLE 3.

The window that appears when you first run IDLE is called the interactive shell. A shell is a
program that lets you type instructions into the computer. The Python shell lets you type Python
instructions, and the shell sends these instructions to the Python interpreter to perform.

Installing Pygame
Pygame does not come with Python. Like Python, Pygame is available for free. You will have to
download and install Pygame, which is as easy as downloading and installing the Python
interpreter. In a web browser, go to the URL http://pygame.org and click on the ―Downloads‖
link on the left side of the web site. This book assumes you have the Windows operating system,
but Pygame works the same for every operating system. You need to download the Pygame
installer for your operating system and the version of Python you have installed.
You do not want to download the ―source‖ for Pygame, but rather the Pygame ―binary‖ for your
operating system. For Windows, download the pygame-1.9.1.win32-py3.2.msi file. (This is
Pygame for Python 3.2 on Windows. If you installed a different version of Python (such as 2.7 or
2.6) download the .msi file for your version of Python.) The current version of Pygame at the
time this book was written is 1.9.1. If you see a newer version on the website, download and
install the newer Pygame.
For Mac OS X, download the .zip or .dmg file for the version of Python you have and run it.
For Linux, open a terminal and run ―sudo apt-get install python-pygame‖.
On Windows, double click on the downloaded file to install Pygame. To check that Pygame is
install correctly, type the following into the interactive shell:
>>> import pygame

4

http://inventwithpython.com/pygame

If nothing appears after you hit the Enter key, then you know Pygame has successfully been
installed. If the error ImportError: No module named pygame appears, then try to
install Pygame again (and make sure you typed import pygame correctly).
This chapter has five small programs that demonstrate how to use the different features that
Pygame provides. In the last chapter, you will use these features for a complete game written in
Python with Pygame.
A video tutorial of how to install Pygame is available from this book's website at
http://invpy.com/videos.

How to Use This Book
―Making Games with Python & Pygame‖ is different from other programming books because it
focuses on the complete source code for several game programs. Instead of teaching you
programming concepts and leaving it up to you to figure out how to make programs with those
concepts, this book shows you some programs and then explains how they are put together.
In general, you should read these chapters in order. There are many concepts that are used over
and over in these games, and they are only explained in detail in the first game they appear in.
But if there is a game you think is interesting, go ahead and jump to that chapter. You can always
read the previous chapters later if you got ahead of yourself.

The Featured Programs
Each chapter focuses on a single game program and explain how different parts of the code work.
It is very helpful to copy these programs by typing in the code line by line from this book.
However, you can also download the source code file from this book's website. In a web browser,
go to the URL http://invpy.com/source and follow the instructions to download the source code
file. But typing in the code yourself really helps you learn the code better.

Downloading Graphics and Sound Files
While you can just type in the code you read out of this book, you will need to download the
graphics and sound files used by the games in this book from http://invpy.com/downloads. Make
sure that these image and sound files are located in the same folder as the .py Python file
otherwise your Python program will not be able to find these files.

Line Numbers and Spaces
When entering the source code yourself, do not type the line numbers that appear at the beginning
of each line. For example, if you see this in the book:

Email questions to the author: al@inventwithpython.com

Chapter 1 – Installing Python and Pygame

5

1. number = random.randint(1, 20)
2. spam = 42
3. print('Hello world!')

You do not need to type the ―1.‖ on the left side, or the space that immediately follows it. Just
type it like this:
number = random.randint(1, 20)
spam = 42
print('Hello world!')

Those numbers are only used so that this book can refer to specific lines in the code. They are not
a part of the actual program.
Aside from the line numbers, be sure to enter the code exactly as it appears. Notice that some of
the lines don’t begin at the leftmost edge of the page, but are indented by four or eight or more
spaces. Be sure to put in the correct number of spaces at the start of each line. (Since each
character in IDLE is the same width, you can count the number of spaces by counting the number
of characters above or below the line you're looking at.)
For example in the code below, you can see that the second line is indented by four spaces
because the four characters (―whil‖) on the line above are over the indented space. The third line
is indented by another four spaces (the four characters, ―if n‖ are above the third line's indented
space):
while spam < 10:
if number == 42:
print('Hello')

Text Wrapping in This Book
Some lines of code are too long to fit on one line on the pages in this book, and the text of the
code will wrap around to the next line. When you type these lines into the file editor, enter the
code all on one line without pressing Enter.
You can tell when a new line starts by looking at the line numbers on the left side of the code. For
example, the code below has only two lines of code, even though the first line wraps around:
1. print('This is the first line! xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxx’)
2. print('This is the second line, not the third line.')

6

http://inventwithpython.com/pygame

Checking Your Code Online
Some of the programs in this book are a little long. Although it is very helpful to learn Python by
typing out the source code for these programs, you may accidentally make typos that cause your
programs to crash. It may not be obvious where the typo is.
You can copy and paste the text of your source code to the online diff tool on the book’s website.
The diff tool will show any differences between the source code in the book and the source code
you’ve typed. This is an easy way of finding any typos in your program.
Copying and pasting text is a very useful computer skill, especially for computer programming.
There is a video tutorial on copying and pasting at this book’s website at
http://invpy.com/copypaste.
The online diff tool is at this web page: http://invpy.com/diff/pygame. There is also a video
tutorial on how to use this tool on the book’s website.

More Info Links on http://invpy.com
There is a lot that you can learn about programming. But you don’t need to learn all of it now.
There are several times in this book where you might like to learn these additional details and
explanations, but if I included them in this book then it would add many more pages. If this
larger, heavier book accidentally fell on you the weight of these many additional pages would
crush you, resulting in death. Instead, I have included ―more info‖ links in this book that you can
follow on this book’s website. You do not have to read this additional information to understand
anything in this book, but it is there if you are curious. These (and other) links have been
shortened and begin with http://invpy.com.
All of the information from these ―more info‖ links can also be downloaded from
http://invpy.com/pygamemoreinfo.
Even though this book is not dangerously heavy, please do not let it fall on you anyway.

Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics

7

CHAPTER 2 – PYGAME BASICS
Just like how Python comes with several modules like random, math, or time that provide
additional functions for your programs, the Pygame framework includes several modules with
functions for drawing graphics, playing sounds, handling mouse input, and other things.
This chapter will cover the basic modules and functions that Pygame provides and assumes you
already know basic Python programming. If you have trouble with some of the programming
concepts, you can read through the ―Invent Your Own Computer Games with Python‖ book
online at http://invpy.com/book. This book is aimed at complete beginners to programming.
The ―Invent with Python‖ book also has a few chapters covering Pygame. You can read them
online at http://invpy.com/chap17.
Once you learn more about Pygame, you can view the other modules that Pygame provides from
the online documentation at http://pygame.org/docs.

GUI vs. CLI
The Python programs that you can write with Python’s built-in functions only deal with text
through the print() and input() functions. Your program can display text on the screen and
let the user type in text from the keyboard. This type of program has a command line interface,
or CLI (which is pronounced like the first part of ―climb‖ and rhymes with ―sky‖). These
programs are somewhat limited because they can’t display graphics, have colors, or use the
mouse. These CLI programs only get input from the keyboard with the input() function and
even then user must press Enter before the program can respond to the input. This means realtime (that is, continuing to run code without waiting for the user) action games are impossible to
make.
Pygame provides functions for creating programs with a graphical user interface, or GUI
(pronounced, ―gooey‖). Instead of a text-based CLI, programs with a graphics-based GUI can
show a window with images and colors.

Source Code for Hello World with Pygame
Our first program made with Pygame is a small program that makes a window that says ―Hello
World!‖ appear on the screen. Open a new file editor window by clicking on IDLE’s File menu,
then New Window. Type in the following code into IDLE’s file editor and save it as
blankpygame.py. Then run the program by pressing F5 or selecting Run > Run Module from the
menu at the top of the file editor.

8

http://inventwithpython.com/pygame

Remember, do not type the numbers or the periods at the beginning of each line (that’s just for
reference in this book).
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

import pygame, sys
from pygame.locals import *
pygame.init()
DISPLAYSURF = pygame.display.set_mode((400, 300))
pygame.display.set_caption('Hello World!')
while True: # main game loop
for event in pygame.event.get():
if event.type == QUIT:
pygame.quit()
sys.exit()
pygame.display.update()

When you run this program, a black window like this will appear:

Yay! You’ve just made the world’s most boring video game! It’s just a blank window with ―Hello
World!‖ at the top of the window (in what is called the window’s title bar, which holds the
caption text). But creating a window is the first step to making graphical games. When you click
on the X button in the corner of the window, the program will end and the window will disappear.
Calling the print() function to make text appear in the window won’t work because
print() is a function for CLI programs. The same goes for input() to get keyboard input
from the user. Pygame uses other functions for input and output which are explained later in this
chapter. For now, let’s look at each line in our ―Hello World‖ program in more detail.

Setting Up a Pygame Program
The first few lines of code in the Hello World program are lines that will begin almost every
program you write that uses Pygame.
1. import pygame, sys

Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics

9

Line 1 is a simple import statement that imports the pygame and sys modules so that our
program can use the functions in them. All of the Pygame functions dealing with graphics, sound,
and other features that Pygame provides are in the pygame module.
Note that when you import the pygame module you automatically import all the modules that
are in the pygame module as well, such as pygame.images and pygame.mixer.music.
There’s no need to import these modules-inside-modules with additional import statements.
2. from pygame.locals import *

Line 2 is also an import statement. However, instead of the import modulename format, it
uses the from modulename import * format. Normally if you want to call a function that
is in a module, you must use the modulename.functionname() format after importing the
module. However, with from modulename import * , you can skip the modulename.
portion and simply use functionname() (just like Python’s built-in functions).
The reason we use this form of import statement for pygame.locals is because
pygame.locals contains several constant variables that are easy to identify as being in the
pygame.locals module without pygame.locals. in front of them. For all other modules,
you generally want to use the regular import modulename format. (There is more
information about why you want to do this at http://invpy.com/namespaces.)
4. pygame.init()

Line 4 is the pygame.init() function call, which always needs to be called after importing
the pygame module and before calling any other Pygame function. You don’t need to know what
this function does, you just need to know that it needs to be called first in order for many Pygame
functions to work. If you ever see an error message like pygame.error: font not
initialized, check to see if you forgot to call pygame.init() at the start of your
program.
5. DISPLAYSURF = pygame.display.set_mode((400, 300))

Line 5 is a call to the pygame.display.set_mode() function, which returns the
pygame.Surface object for the window. (Surface objects are described later in this chapter.)
Notice that we pass a tuple value of two integers to the function: (400, 300). This tuple tells
the set_mode() function how wide and how high to make the window in pixels. (400,
300) will make a window with a width of 400 pixels and height of 300 pixels.

10

http://inventwithpython.com/pygame

Remember to pass a tuple of two integers to set_mode(), not just two integers themselves. The
correct way to call the function is like this: pygame.display.set_mode((400, 300)).
A function call like pygame.display.set_mode(400, 300) will cause an error that
looks like this: TypeError: argument 1 must be 2-item sequence, not int.
The pygame.Surface object (we will just call them Surface objects for short) returned is
stored in a variable named DISPLAYSURF.
6. pygame.display.set_caption('Hello World!')

Line 6 sets the caption text that will appear at the top of the window by calling the
pygame.display.set_caption() function. The string value 'Hello World!' is
passed in this function call to make that text appear as the caption:

Game Loops and Game States
7. while True: # main game loop
8.
for event in pygame.event.get():

Line 7 is a while loop that has a condition of simply the value True. This means that it never
exits due to its condition evaluating to False. The only way the program execution will ever
exit the loop is if a break statement is executed (which moves execution to the first line after the
loop) or sys.exit() (which terminates the program). If a loop like this was inside a function,
a return statement will also move execution out of the loop (as well as the function too).
The games in this book all have these while True loops in them along with a comment calling
it the ―main game loop‖. A game loop (also called a main loop) is a loop where the code does
three things:
1. Handles events.
2. Updates the game state.
3. Draws the game state to the screen.
The game state is simply a way of referring to a set of values for all the variables in a game
program. In many games, the game state includes the values in the variables that tracks the
player’s health and position, the health and position of any enemies, which marks have been
made on a board, the score, or whose turn it is. Whenever something happens like the player

Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics

11

taking damage (which lowers their health value), or an enemy moves somewhere, or something
happens in the game world we say that the game state has changed.
If you’ve ever played a game that let you saved, the ―save state‖ is the game state at the point that
you’ve saved it. In most games, pausing the game will prevent the game state from changing.
Since the game state is usually updated in response to events (such as mouse clicks or keyboard
presses) or the passage of time, the game loop is constantly checking and re-checking many times
a second for any new events that have happened. Inside the main loop is code that looks at which
events have been created (with Pygame, this is done by calling the pygame.event.get()
function). The main loop also has code that updates the game state based on which events have
been created. This is usually called event handling.

pygame.event.Event Objects
Any time the user does one of several actions (they are listed later in this chapter) such as
pressing a keyboard key or moving the mouse on the program’s window, a
pygame.event.Event object is created by the Pygame library to record this ―event‖. (This is
a type of object called Event that exists in the event module, which itself is in the pygame
module.) We can find out which events have happened by calling the pygame.event.get()
function, which returns a list of pygame.event.Event objects (which we will just call Event
objects for short).
The list of Event objects will be for each event that has happened since the last time the
pygame.event.get() function was called. (Or, if pygame.event.get() has never been
called, the events that have happened since the start of the program.)

12

http://inventwithpython.com/pygame

7. while True: # main game loop
8.
for event in pygame.event.get():

Line 8 is a for loop that will iterate over the list of Event objects that was returned by
pygame.event.get(). On each iteration through the for loop, a variable named event
will be assigned the value of the next event object in this list. The list of Event objects returned
from pygame.event.get() will be in the order that the events happened. If the user clicked
the mouse and then pressed a keyboard key, the Event object for the mouse click would be the
first item in the list and the Event object for the keyboard press would be second. If no events
have happened, then pygame.event.get() will return a blank list.

The QUIT Event and pygame.quit() Function
9.
10.
11.

if event.type == QUIT:
pygame.quit()
sys.exit()

Event objects have a member variable (also called attributes or properties) named type
which tells us what kind of event the object represents. Pygame has a constant variable for each
of possible types in the pygame.locals modules. Line 9 checks if the Event object’s type is
equal to the constant QUIT. Remember that since we used the from pygame.locals
import * form of the import statement, we only have to type QUIT instead of
pygame.locals.QUIT.

If the Event object is a quit event, then the pygame.quit() and sys.exit() functions are
called. The pygame.quit() function is sort of the opposite of the pygame.init()
function: it runs code that deactivates the Pygame library. Your programs should always call
pygame.quit() before they call sys.exit() to terminate the program. Normally it doesn’t
really matter since Python closes it when the program exits anyway. But there is a bug in IDLE
that causes IDLE to hang if a Pygame program terminates before pygame.quit() is called.
Since we have no if statements that run code for other types of Event object, there is no eventhandling code for when the user clicks the mouse, presses keyboard keys, or causes any other
type of Event objects to be created. The user can do things to create these Event objects but it
doesn’t change anything in the program because the program does not have any event-handling
code for these types of Event objects. After the for loop on line 8 is done handling all the Event
objects that have been returned by pygame.event.get(), the program execution continues
to line 12.
12.

pygame.display.update()

Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics

13

Line 12 calls the pygame.display.update() function, which draws the Surface object
returned by pygame.display.set_mode() to the screen (remember we stored this object
in the DISPLAYSURF variable). Since the Surface object hasn’t changed (for example, by some
of the drawing functions that are explained later in this chapter), the same black image is redrawn
to the screen each time pygame.display.update() is called.
That is the entire program. After line 12 is done, the infinite while loop starts again from the
beginning. This program does nothing besides make a black window appear on the screen,
constantly check for a QUIT event, and then redraws the unchanged black window to the screen
over and over again. Let’s learn how to make interesting things appear on this window instead of
just blackness by learning about pixels, Surface objects, Color objects, Rect objects, and the
Pygame drawing functions.

Pixel Coordinates
The window that the ―Hello World‖ program creates is just composed of little square dots on your
screen called pixels. Each pixel starts off as black but can be set to a different color. Imagine that
instead of a Surface object that is 400 pixels wide and 300 pixels tall, we just had a Surface object
that was 8 pixels by 8 pixels. If that tiny 8x8 Surface was enlarged so that each pixel looks like a
square in a grid, and we added numbers for the X and Y axis, then a good representation of it
could look something like this:

We can refer to a specific pixel by using a Cartesian Coordinate system. Each column of the Xaxis and each row of the Y-axis will have an ―address‖ that is an integer from 0 to 7 so that we
can locate any pixel by specifying the X and Y axis integers.
For example, in the above 8x8 image, we can see that the pixels at the XY coordinates (4, 0), (2,
2), (0, 5), and (5, 6) have been painted black, the pixel at (2, 4) has been painted gray, while all
the other pixels are painted white. XY coordinates are also called points. If you’ve taken a math
class and learned about Cartesian Coordinates, you might notice that the Y-axis starts at 0 at the
top and then increases going down, rather than increasing as it goes up. This is just how Cartesian
Coordinates work in Pygame (and almost every programming language).

14

http://inventwithpython.com/pygame

The Pygame framework often represents Cartesian Coordinates as a tuple of two integers, such as
(4, 0) or (2, 2). The first integer is the X coordinate and the second is the Y coordinate. (Cartesian
Coordinates are covered in more detail in chapter 12 of ―Invent Your Own Computer Games with
Python‖ at http://invpy.com/chap12)

A Reminder About Functions, Methods, Constructor Functions, and
Functions in Modules (and the Difference Between Them)
Functions and methods are almost the same thing. They can both be called to execute the code in
them. The difference between a function and a method is that a method will always be attached to
an object. Usually methods change something about that particular object (you can think of the
attached object as a sort of permanent argument passed to the method).
This is a function call of a function named foo():
foo()

This is a method call of a method also named foo(), which is attached to an object stored in a
variable named duckie:
duckie.foo()

A call to a function inside of a module may look like a method call. To tell the difference, you
need to look at the first name and see if it is the name of a module or the name of a variable that
contains an object. You can tell that sys.exit() is a call to function inside of a module,
because at the top of the program will be an import statement like import sys.
A constructor function is the same thing as a normal function call, except that its return value is
a new object. Just by looking at source code, a function and constructor function look the same.
Constructor functions (also called simply a ―constructor‖ or sometimes ―ctor‖ (―see-tor‖) for
short) are just a name given to functions that return a new object. But usually ctors start with a
capital letter. This is why when you write your own programs, your function names should only
begin with a lowercase letter.
For example, pygame.Rect() and pygame.Surface() are both constructor functions
inside the pygame module that return new Rect and Surface objects. (These objects are
described later.)
Here’s an example of a function call, a method call, and a call to a function inside a module:
import whammy
fizzy()
Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics

15

egg = Wombat()
egg.bluhbluh()
whammy.spam()

Even though these names are all made up, you can tell which is a function call, a method call, and
a call to a function inside a method. The name whammy refers to a module, since you can see it is
being imported on the first line. The fizzy name has nothing before it and parentheses after it,
so you know it is a function call.
Wombat() is also a function call, in this case it is a constructor function that returns an object.
(The capital letter that it starts with isn’t a guarantee that it’s a constructor function rather than a
regular function, but it is a safe bet.) The object is stored in a variable named egg. The
egg.bluhbluh() call is a method call, which you can tell because bluhbluh is attached to a
variable with an object in it.

Meanwhile, whammy.spam() is a function call, not a method call. You can tell it is not a
method because the name whammy was imported as a module earlier.

Surface Objects and The Window
Surface objects are objects that represent a rectangular 2D image. The pixels of the Surface object
can be changed by calling the Pygame drawing functions (described later in this chapter) and then
displayed on the screen. The window border, title bar, and buttons are not part of the display
Surface object.
In particular, the Surface object returned by pygame.display.set_mode() is called the
display Surface. Anything that is drawn on the display Surface object will be displayed on the
window when the pygame.display.update() function is called. It is a lot faster to draw
on a Surface object (which only exists in the computer’s memory) than it is to draw a Surface
object to the computer screen. Computer memory is much faster to change than pixels on a
monitor.
Often your program will draw several different things to a Surface object. Once you are done
drawing everything on the display Surface object for this iteration of the game loop (called a
frame, just like a still image on a paused DVD is called) on a Surface object, it can be drawn to
the screen. The computer can draw frames very quickly, and our programs will often run around
30 frames per second (that is, 30 FPS). This is called the ―frame rate‖ and is explained later in
this chapter.
Drawing on Surface objects will be covered in the ―Primitive Drawing Functions‖ and ―Drawing
Images‖ sections later this chapter.

16

http://inventwithpython.com/pygame

Colors
There are three primary colors of light: red, green and blue. (Red, blue, and yellow are the
primary colors for paints and pigments, but the computer monitor uses light, not paint.) By
combining different amounts of these three colors you can form any other color. In Pygame, we
represent colors with tuples of three integers. The first value in the tuple is how much red is in the
color. An integer value of 0 means there is no red in this color, and a value of 255 means there is
the maximum amount of red in the color. The second value is for green and the third value is for
blue. These tuples of three integers used to represent a color are often called RGB values.
Because you can use any combination of 0 to 255 for each of the three primary colors, this
means Pygame can draw 16,777,216 different colors (that is, 256 x 256 x 256 colors). However,
if try to use a number larger than 255 or a negative number, you will get an error that looks like
―ValueError: invalid color argument‖.
For example, we will create the tuple (0, 0, 0) and store it in a variable named BLACK. With
no amount of red, green, or blue, the resulting color is completely black. The color black is the
absence of any color. The tuple (255, 255, 255) for a maximum amount of red, green, and
blue to result in white. The color white is the full combination of red, green, and blue. The tuple
(255, 0, 0) represents the maximum amount of red but no amount of green and blue, so the
resulting color is red. Similarly, (0, 255, 0) is green and (0, 0, 255) is blue.
You can mix the amount of red, green, and blue to form other colors. Here are the RGB values for
a few common colors:
Color
Aqua
Black
Blue
Fuchsia
Gray
Green
Lime
Maroon
Navy Blue
Olive
Purple
Red
Silver
Teal
White
Yellow

RGB Values
( 0, 255, 255)
( 0,
0,
0)
( 0,
0, 255)
(255,
0, 255)
(128, 128, 128)
( 0, 128,
0)
( 0, 255,
0)
(128,
0,
0)
( 0,
0, 128)
(128, 128,
0)
(128,
0, 128)
(255,
0,
0)
(192, 192, 192)
( 0, 128, 128)
(255, 255, 255)
(255, 255,
0)

Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics

17

Transparent Colors
When you look through a glass window that has a deep red tint, all of the colors behind it have a
red shade added to them. You can mimic this effect by adding a fourth 0 to 255 integer value to
your color values.
This value is known as the alpha value. It is a measure of how opaque (that is, not transparent) a
color is. Normally when you draw a pixel onto a surface object, the new color completely
replaces whatever color was already there. But with colors that have an alpha value, you can
instead just add a colored tint to the color that is already there.
For example, this tuple of three integers is for the color green: (0, 255, 0). But if we add a
fourth integer for the alpha value, we can make this a half transparent green color: (0, 255,
0, 128). An alpha value of 255 is completely opaque (that is, not transparency at all). The
colors (0, 255, 0) and (0, 255, 0, 255) look exactly the same. An alpha value of 0
means the color is completely transparent. If you draw any color that has an alpha value of 0 to a
surface object, it will have no effect, because this color is completely transparent and invisible.
In order to draw using transparent colors, you must create a Surface object with the
convert_alpha() method. For example, the following code creates a Surface object that
transparent colors can be drawn on:
anotherSurface = DISPLAYSURF.convert_alpha()

Once things have been drawn on the Surface object stored in anotherSurface, then
anotherSurface can be ―blitted‖ (that is, copied) to DISPLAYSURF so it will appear on the
screen. (See the ―Drawing Images with pygame.image.load() and blit()‖ section later
in this chapter.)
It’s important to note that you cannot use transparent colors on Surface objects not returned from
a convert_alpha() call, including the display Surface that was returned from
pygame.display.set_mode().
If we were to create a color tuple to draw the legendary Invisible Pink Unicorn, we would use
(255, 192, 192, 0), which ends up looking completely invisible just like any other color
that has a 0 for its alpha value. It is, after all, invisible.

18

http://inventwithpython.com/pygame

(Above is a screenshot of a drawing of the Invisible Pink Unicorn.)

pygame.Color Objects
You need to know how to represent a color because Pygame’s drawing functions need a way to
know what color you want to draw with. A tuple of three or four integers is one way. Another
way is as a pygame.Color object. You can create Color objects by calling the
pygame.Color() constructor function and passing either three or four integers. You can store
this Color object in variables just like you can store tuples in variables. Try typing the following
into the interactive shell:
>>> import pygame
>>> pygame.Color(255, 0, 0)
(255, 0, 0, 255)
>>> myColor = pygame.Color(255, 0, 0, 128)
>>> myColor == (255, 0, 0, 128)
True
>>>

Any drawing function in Pygame (which we will learn about in a bit) that has a parameter for
color can have either the tuple form or Color object form of a color passed for it. Even though
they are different data types, a Color object is equal to a tuple of four integers if they both
represent the same color (just like how 42 == 42.0 will evaluate to True).
Now that you know how to represent colors (as a pygame.Color object or a tuple of three or
four integers for red, green, blue, and optionally alpha) and coordinates (as a tuple of two integers
for X and Y), let’s learn about pygame.Rect objects so we can start using Pygame’s drawing
functions.

Rect Objects
Pygame has two ways to represent rectangular areas (just like there are two ways to represent
colors). The first is a tuple of four integers:
1. The X coordinate of the top left corner.
Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics

19

2. The Y coordinate of the top left corner.
3. The width (in pixels) of the rectangle.
4. Then height (in pixels) of the rectangle.
The second way is as a pygame.Rect object, which we will call Rect objects for short. For
example, the code below creates a Rect object with a top left corner at (10, 20) that is 200 pixels
wide and 300 pixels tall:
>>> import pygame
>>> spamRect = pygame.Rect(10, 20, 200, 300)
>>> spamRect == (10, 20, 200, 300)
True

The handy thing about this is that the Rect object automatically calculates the coordinates for
other features of the rectangle. For example, if you need to know the X coordinate of the right
edge of the pygame.Rect object we stored in the spamRect variable, you can just access the
Rect object’s right attribute:
>>> spamRect.right
210

The Pygame code for the Rect object automatically calculated that if the left edge is at the X
coordinate 10 and the rectangle is 200 pixels wide, then the right edge must be at the X
coordinate 210. If you reassign the right attribute, all the other attributes are automatically
recalculated:
>>> spam.right = 350
>>> spam.left
150

Here’s a list of all the attributes that pygame.Rect objects provide (in our example, the
variable where the Rect object is stored in a variable named myRect):

20

http://inventwithpython.com/pygame

Attribute Name

Description

myRect.left

The int value of the X-coordinate of the left side of the rectangle.

myRect.right

The int value of the X-coordinate of the right side of the rectangle.

myRect.top

The int value of the Y-coordinate of the top side of the rectangle.

myRect.bottom

The int value of the Y-coordinate of the bottom side.

myRect.centerx

The int value of the X-coordinate of the center of the rectangle.

myRect.centery

The int value of the Y-coordinate of the center of the rectangle.

myRect.width

The int value of the width of the rectangle.

myRect.height

The int value of the height of the rectangle.

myRect.size

A tuple of two ints: (width, height)

myRect.topleft

A tuple of two ints: (left, top)

myRect.topright

A tuple of two ints: (right, top)

myRect.bottomleft

A tuple of two ints: (left, bottom)

myRect.bottomright

A tuple of two ints: (right, bottom)

myRect.midleft

A tuple of two ints: (left, centery)

myRect.midright

A tuple of two ints: (right, centery)

myRect.midtop

A tuple of two ints: (centerx, top)

myRect.midbottom

A tuple of two ints: (centerx, bottom)

Primitive Drawing Functions
Pygame provides several different functions for drawing different shapes onto a surface object.
These shapes such as rectangles, circles, ellipses, lines, or individual pixels are often called
drawing primitives. Open IDLE’s file editor and type in the following program, and save it as
drawing.py.
1. import pygame, sys
2. from pygame.locals import *
Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics

21

3.
4. pygame.init()
5.
6. # set up the window
7. DISPLAYSURF = pygame.display.set_mode((500, 400), 0, 32)
8. pygame.display.set_caption('Drawing')
9.
10. # set up the colors
11. BLACK = ( 0,
0,
0)
12. WHITE = (255, 255, 255)
13. RED
= (255,
0,
0)
14. GREEN = ( 0, 255,
0)
15. BLUE = ( 0,
0, 255)
16.
17. # draw on the surface object
18. DISPLAYSURF.fill(WHITE)
19. pygame.draw.polygon(DISPLAYSURF, GREEN, ((146, 0), (291, 106), (236, 277),
(56, 277), (0, 106)))
20. pygame.draw.line(DISPLAYSURF, BLUE, (60, 60), (120, 60), 4)
21. pygame.draw.line(DISPLAYSURF, BLUE, (120, 60), (60, 120))
22. pygame.draw.line(DISPLAYSURF, BLUE, (60, 120), (120, 120), 4)
23. pygame.draw.circle(DISPLAYSURF, BLUE, (300, 50), 20, 0)
24. pygame.draw.ellipse(DISPLAYSURF, RED, (300, 250, 40, 80), 1)
25. pygame.draw.rect(DISPLAYSURF, RED, (200, 150, 100, 50))
26.
27. pixObj = pygame.PixelArray(DISPLAYSURF)
28. pixObj[480][380] = BLACK
29. pixObj[482][382] = BLACK
30. pixObj[484][384] = BLACK
31. pixObj[486][386] = BLACK
32. pixObj[488][388] = BLACK
33. del pixObj
34.
35. # run the game loop
36. while True:
37.
for event in pygame.event.get():
38.
if event.type == QUIT:
39.
pygame.quit()
40.
sys.exit()
41.
pygame.display.update()

When this program is run, the following window is displayed until the user closes the window:

22

http://inventwithpython.com/pygame

Notice how we make constant variables for each of the colors. Doing this makes our code more
readable, because seeing GREEN in the source code is much easier to understand as representing
the color green than (0, 255, 0) is.
The drawing functions are named after the shapes they draw. The parameters you pass these
functions tell them which Surface object to draw on, where to draw the shape (and what size), in
what color, and how wide to make the lines. You can see how these functions are called in the
drawing.py program, but here is a short description of each function:





fill(color) – The fill() method is not a function but a method of pygame.Surface
objects. It will completely fill in the entire Surface object with whatever color value you pass
as for the color parameter.
pygame.draw.polygon(surface, color, pointlist, width) – A polygon is shape made up of
only flat sides. The surface and color parameters tell the function on what surface to
draw the polygon, and what color to make it.
The pointlist parameter is a tuple or list of points (that is, tuple or list of two-integer
tuples for XY coordinates). The polygon is drawn by drawing lines between each point and
the point that comes after it in the tuple. Then a line is drawn from the last point to the first
point. You can also pass a list of points instead of a tuple of points.
The width parameter is optional. If you leave it out, the polygon that is drawn will be filled
in, just like our green polygon on the screen is filled in with color. If you do pass an integer
value for the width parameter, only the outline of the polygon will be drawn. The integer
represents how many pixels width the polygon’s outline will be. Passing 1 for the width
parameter will make a skinny polygon, while passing 4 or 10 or 20 will make thicker
polygons. If you pass the integer 0 for the width parameter, the polygon will be filled in
(just like if you left the width parameter out entirely).
All of the pygame.draw drawing functions have optional width parameters at the end,
and they work the same way as pygame.draw.polygon()’s width parameter.
Probably a better name for the width parameter would have been thickness, since that
parameter controls how thick the lines you draw are.

Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics










23

pygame.draw.line(surface, color, start_point, end_point, width) – This function draws a
line between the start_point and end_point parameters.
pygame.draw.lines(surface, color, closed, pointlist, width) – This function draws a series
of lines from one point to the next, much like pygame.draw.polygon(). The only
difference is that if you pass False for the closed parameter, there will not be a line from
the last point in the pointlist parameter to the first point. If you pass True, then it will
draw a line from the last point to the first.
pygame.draw.circle(surface, color, center_point, radius, width) – This function draws a
circle. The center of the circle is at the center_point parameter. The integer passed for
the radius parameter sets the size of the circle.
The radius of a circle is the distance from the center to the edge. (The radius of a circle is
always half of the diameter.) Passing 20 for the radius parameter will draw a circle that
has a radius of 20 pixels.
pygame.draw.ellipse(surface, color, bounding_rectangle, width) – This function draws an
ellipse (which is like a squashed or stretched circle). This function has all the usual
parameters, but in order to tell the function how large and where to draw the ellipse, you must
specify the bounding rectangle of the ellipse. A bounding rectangle is the smallest rectangle
that can be drawn around a shape. Here’s an example of an ellipse and its bounding rectangle:

The bounding_rectangle parameter can be a pygame.Rect object or a tuple of four
integers. Note that you do not specify the center point for the ellipse like you do for the
pygame.draw.circle() function.
pygame.draw.rect(surface, color, rectangle_tuple, width) – This function draws a
rectangle. The rectangle_tuple is either a tuple of four integers (for the XY coordinates
of the top left corner, and the width and height) or a pygame.Rect object can be passed
instead. If the rectangle_tuple has the same size for the width and height, a square will
be drawn.

pygame.PixelArray Objects
Unfortunately, there isn’t a single function you can call that will set a single pixel to a color
(unless you call pygame.draw.line() with the same start and end point). The Pygame
framework needs to run some code behind the scenes before and after drawing to a Surface
object. If it had to do this for every single pixel you wanted to set, your program would run much
slower. (By my quick testing, drawing pixels this way is two or three times slower.)
Instead, you should create a pygame.PixelArray object (we’ll call them PixelArray objects
for short) of a Surface object and then set individual pixels. Creating a PixelArray object of a
Surface object will ―lock‖ the Surface object. While a Surface object is locked, the drawing

24

http://inventwithpython.com/pygame

functions can still be called on it, but it cannot have images like PNG or JPG images drawn on it
with the blit() method. (The blit() method is explained later in this chapter.)
If you want to see if a Surface object is locked, the get_locked() Surface method will return
True if it is locked and False if it is not.
The PixelArray object that is returned from pygame.PixelArray() can have individual
pixels set by accessing them with two indexes. For example, line 28’s pixObj[480][380] =
BLACK will set the pixel at X coordinate 480 and Y coordinate 380 to be black (remember that
the BLACK variable stores the color tuple (0, 0, 0)).
To tell Pygame that you are finished drawing individual pixels, delete the PixelArray object with
a del statement. This is what line 33 does. Deleting the PixelArray object will ―unlock‖ the
Surface object so that you can once again draw images on it. If you forget to delete the
PixelArray object, the next time you try to blit (that is, draw) an image to the Surface the program
will raise an error that says, ―pygame.error: Surfaces must not be locked
during blit‖.

The pygame.display.update() Function
After you are done calling the drawing functions to make the display Surface object look the way
you want, you must call pygame.display.update() to make the display Surface actually
appear on the user’s monitor.
The one thing that you must remember is that pygame.display.update() will only make
the display Surface (that is, the Surface object that was returned from the call to
pygame.display.set_mode()) appear on the screen. If you want the images on other
Surface objects to appear on the screen, you must ―blit‖ them (that is, copy them) to the display
Surface object with the blit() method (which is explained next in the ―Drawing Images‖
section).

Animation
Now that we know how to get the Pygame framework to draw to the screen, let’s learn how to
make animated pictures. A game with only still, unmoving images would be fairly dull. (Sales of
my game ―Look At This Rock‖ have been disappointing.) Animated images are the result of
drawing an image on the screen, then a split second later drawing a slightly different image on the
screen. Imagine the program’s window was 6 pixels wide and 1 pixel tall, with all the pixels
white except for a black pixel at 4, 0. It would look like this:

Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics

25

If you changed the window so that 3, 0 was black and 4,0 was white, it would look like this:

To the user, it looks like the black pixel has ―moved‖ over to the left. If you redrew the window
to have the black pixel at 2, 0, it would continue to look like the black pixel is moving left:

It may look like the black pixel is moving, but this is just an illusion. To the computer, it is just
showing three different images that each just happen to have one black pixel. Consider if the
three following images were rapidly shown on the screen:

To the user, it would look like the cat is moving towards the squirrel. But to the computer, they’re
just a bunch of pixels. The trick to making believable looking animation is to have your program
draw a picture to the window, wait a fraction of a second, and then draw a slightly different
picture.
Here is an example program demonstrating a simple animation. Type this code into IDLE’s file
editor and save it as catanimation.py. It will also require the image file cat.png to be in the same
folder as the catanimation.py file. You can download this image from http://invpy.com/cat.png.
This code is available at http://invpy.com/catanimation.py.

26

http://inventwithpython.com/pygame

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.

import pygame, sys
from pygame.locals import *
pygame.init()
FPS = 30 # frames per second setting
fpsClock = pygame.time.Clock()
# set up the window
DISPLAYSURF = pygame.display.set_mode((400, 300), 0, 32)
pygame.display.set_caption('Animation')
WHITE = (255, 255, 255)
catImg = pygame.image.load('cat.png')
catx = 10
caty = 10
direction = 'right'
while True: # the main game loop
DISPLAYSURF.fill(WHITE)
if direction == 'right':
catx += 5
if catx == 280:
direction = 'down'
elif direction == 'down':
caty += 5
if caty == 220:
direction = 'left'
elif direction == 'left':
catx -= 5
if catx == 10:
direction = 'up'
elif direction == 'up':
caty -= 5
if caty == 10:
direction = 'right'
DISPLAYSURF.blit(catImg, (catx, caty))
for event in pygame.event.get():
if event.type == QUIT:
pygame.quit()
sys.exit()
pygame.display.update()

Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics

47.

27

fpsClock.tick(FPS)

Look at that animated cat go! This program will be much more of a commercial success than my
game, ―Look At This Rock 2: A Different Rock‖.

Frames Per Second and pygame.time.Clock Objects
The frame rate or refresh rate is the number of pictures that the program draws per second, and
is measured in FPS or frames per second. (On computer monitors, the common name for FPS is
hertz. Many monitors have a frame rate of 60 hertz, or 60 frames per second.) A low frame rate in
video games can make the game look choppy or jumpy. If the program has too much code to run
to draw to the screen frequently enough, then the FPS goes down. But the games in this book are
simple enough that this won’t be issue even on old computers.
A pygame.time.Clock object can help us make sure our program runs at a certain maximum
FPS. This Clock object will ensure that our game programs don’t run too fast by putting in
small pauses on each iteration of the game loop. If we didn’t have these pauses, our game
program would run as fast as the computer could run it. This is often too fast for the player, and
as computers get faster they would run the game faster too. A call to the tick() method of a
Clock object in the game loop can make sure the game runs at the same speed no matter how
fast of a computer it runs on. The Clock object is created on line 7 of the catanimation.py
program.
7. fpsClock = pygame.time.Clock()

The Clock object’s tick() method should be called at the very end of the game loop, after the
call to pygame.display.update(). The length of the pause is calculated based on how
long it has been since the previous call to tick(), which would have taken place at the end of
the previous iteration of the game loop. (The first time the tick() method is called, it doesn’t
pause at all.) In the animation program, is it run on line 47 as the last instruction in the game loop.
All you need to know is that you should call the tick() method once per iteration through the
game loop at the end of the loop. Usually this is right after the call to
pygame.display.update().
47.

fpsClock.tick(FPS)

Try modifying the FPS constant variable to run the same program at different frame rates. Setting
it to a lower value would make the program run slower. Setting it to a higher value would make
the program run faster.

28

http://inventwithpython.com/pygame

Drawing Images with pygame.image.load() and blit()
The drawing functions are fine if you want to draw simple shapes on the screen, but many games
have images (also called sprites). Pygame is able to load images onto Surface objects from PNG,
JPG, GIF, and BMP image files. The differences between these image file formats is described at
http://invpy.com/formats.
The image of the cat was stored in a file named cat.png. To load this file’s image, the string
'cat.png' is passed to the pygame.image.load() function. The
pygame.image.load() function call will return a Surface object that has the image drawn
on it. This Surface object will be a separate Surface object from the display Surface object, so we
must blit (that is, copy) the image’s Surface object to the display Surface object. Blitting is
drawing the contents of one Surface onto another. It is done with the blit() Surface object
method.
If you get an error message like ―pygame.error: Couldn't open cat.png‖ when
calling pygame.image.load(), then make sure the cat.png file is in the same folder as the
catanimation.py file before you run the program.
39.

DISPLAYSURF.blit(catImg, (catx, caty))

Line 39 of the animation program uses the blit() method to copy catImg to DISPLAYSURF.
There are two parameters for blit(). The first is the source Surface object, which is what will
be copied onto the DISPLAYSURF Surface object. The second parameter is a two-integer tuple
for the X and Y values of the topleft corner where the image should be blitted to.
If catx and caty were set to 100 and 200 and the width of catImg was 125 and the height
was 79, this blit() call would copy this image onto DISPLAYSURF so that the top left corner
of the catImg was at the XY coordinate (100, 200) and the bottom right corner’s XY coordinate
was at (225, 279).
Note that you cannot blit to a Surface that is currently ―locked‖ (such as when a PixelArray object
has been made from it and not yet been deleted.)
The rest of the game loop is just changing the catx, caty, and direction variables so that
the cat moves around the window. There is also a call to pygame.event.get() to handle the
QUIT event.

Fonts
If you want to draw text to the screen, you could write several calls to pygame.draw.line()
to draw out the lines of each letter. This would be a headache to type out all those

Email questions to the author: al@inventwithpython.com

Chapter 2 – Pygame Basics

29

pygame.draw.line() calls and figure out all the XY coordinates, and probably wouldn’t
look very good.

The above message would take forty one calls to the pygame.draw.line() function to
make. Instead, Pygame provides some much simpler functions for fonts and creating text. Here is
a small Hello World program using Pygame’s font functions. Type it into IDLE’s file editor and
save it as fonttext.py:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.

import pygame, sys
from pygame.locals import *
pygame.init()
DISPLAYSURF = pygame.display.set_mode((400, 300))
pygame.display.set_caption('Hello World!')
WHITE = (255, 255, 255)
GREEN = (0, 255, 0)
BLUE = (0, 0, 128)
fontObj = pygame.font.Font('freesansbold.ttf', 32)
textSurfaceObj = fontObj.render('Hello world!', True, GREEN, BLUE)
textRectObj = textSurfaceObj.get_rect()
textRectObj.center = (200, 150)
while True: # main game loop
DISPLAYSURF.fill(WHITE)
DISPLAYSURF.blit(textSurfaceObj, textRectObj)
for event in pygame.event.get():
if event.type == QUIT:
pygame.quit()
sys.exit()
pygame.display.update()

There are six steps to making text appear on the screen:
1. Create a pygame.font.Font object. (Like on line 12)
2. Create a Surface object with the text drawn on it by calling the Font object’s render()
method. (Line 13)
3. Create a Rect object from the Surface object by calling the Surface object’s
get_rect() method. (Line 14) This Rect object will have the width and height
correctly set for the text that was rendered, but the top and left attributes will be 0.

30

http://inventwithpython.com/pygame

4. Set the position of the Rect object by changing one of its attributes. On line 15, we set the
center of the Rect object to be at 200, 150.
5. Blit the Surface object with the text onto the Surface object returned by
pygame.display.set_mode(). (Line 19)
6. Call pygame.display.update() to make the display Surface appear on the screen.
(Line 24)
The parameters to the pygame.font.Font() constructor function is a string of the font file to
use, and an integer of the size of the font (in points, like how word processors measure font size).
On line 12, we pass 'freesansbold.ttf' (this is a font that comes with Pygame) and the
integer 32 (for a 32-point sized font).
See http://invpy.com/usingotherfonts for more info on using other fonts.
The parameters to the render() method call are a string of the text to render, a Boolean value
to specify if we want anti-aliasing (explained later in this chapter), the color of the text, and the
color of the background. If you want a transparent background, then simply leave off the
background color parameter in the method call.

Anti-Aliasing
Anti-aliasing is a graphics technique for making text and shapes look less blocky by adding a
little bit of blur to their edges. It takes a little more computation time to draw with anti-aliasing,
so although the graphics may look better, your program may run slower (but only just a little).
If you zoom in on an aliased line and an anti-aliased line, they look like this:

To make Pygame’s text use anti-aliasing, just pass