It’s been a long time since I worked on TextWidget at all, but since someone posted a question about it I decided to fix the issue and re-release the source. But since I didn’t want to simply update the blog post I decided to give the project a proper home on google code: http://code.google.com/p/textwidget/

The project is really simple and meant as an easy way for you to create “text buttons” for your PyGame projects. It’s not meant to be the definitive way to do this, just a simple solution for people that just want to drop a class in and have working “text buttons”. It’s LGPL so you can use it in whatever way you want. If you do decide to use it please drop me an email and let me know.

For more information on how to use the project please take a look at the initial blog post.

Hey everyone, I’ve been getting hit with a bunch of spam comments over the last few days so I’ve made it so that all comments must be moderated before they will appear.

Sorry about this, I don’t like this form of comment posting, but hopefully after a few days I will be able to switch it back to normal.

And sorry about the lack of posts here, yes I am still alive, it’s just that real life has been working me pretty hard these last few weeks.

I’ve been playing around with my PyGTK app and a new PyGame engine that I am working on from the ground up. Something that I can understand and that I can use. I’ll post more information about it when there is more information…right now it does next to nothing!

So I’ve been working on PyGame for PyWeek lately and I’ve been having a lot of fun. I also took a weekend off from my email so I did not notice that Lord Taran has been creating Spanish translations for a bunch of my PyGTK tutorials.

If you are interested in the Spanish tutorials check them out, or if you are interested in seeing what happened at pyweek and the car crash that was my entry check it out as well.

Introduction

All right, this is just a little tutorial about working with text in pygame. Now, this isn’t the only way to work with text, there are many other methods to do this, in fact much of the time you’ll probably end up using images for interactive text. So this is mainly meant to serve as a informative guide to using the text features in PyGame, and how you might want to implement them.

The TextWidget object discussed in this tutorial can be used to make something that looks like this (but you’d probably want to use better looking colours):

The full source and necessary files for this tutorial can be downloaded here.

So, in order to make this easy to use and very reusable we’re going to create a class called TextWidget in a file called TextWidget.py. The top of the file is full of the standard python initialization:

#! /usr/bin/env python

import pygame

TEXT_WIDGET_CLICK = pygame.locals.USEREVENT + 1

We import pygame and then we set a define TEXT_WIDGET_CLICK , which will be used later on as the event type when the TextWidget is clicked on.

The next thing to do is define the actual class:

class TextWidget(object):

Now the astute among you will recognize that this is a “new-style” python class (i.e. it’s base class is the object class) rather then a classic class. I did this for two reasons:

1. I wanted to be able to control what happens when people set values in the class. So, for example, if you set the size of the font to be something, I wanted the display to automatically adjust to reflect the new size.
2. I haven’t really used new-style classes before so I thought I’d try them out.

Note: If you are unfamiliar with properties or new-style classes you might want to give this a read:

• Unifying types and classes in Python 2.2
• Introduction To New-Style Classes In Python

As a result of number one above I’m going to use properties for those values that I want to perform some “automatic processing” when their values changes.

The properties that I am going to define are as follows:

• text – The string of text that the TextWidget will display.
• colour – The colour that the text will be rendered in.
• size – The size of the font.
• font_filename – The filename of the font to use for the text (probably something returned by pygame.font.get_fonts or pygame.font.match_font.
• highlight – A boolean, whether the font is highlighted or not. (i.e. whether the mouse is over the TextWidget.
• highlight_cursor – A boolean that controls whether or not to show a hand cursor when the TextWidget is in highlight mode. If the TextWidget is not supposed to be interactive you should set this to False.

There are also a few other important members of the class, but since they are not python properties I have listed them separately:

• __hand – A hand cursor, which can optionally by displayed when the cursor hovers over the text.
• dirty – A boolean, that lets the TextWidget know whether or not it needs to draw. If dirty = False it will not draw, if dirty = True it will draw.
• bold_rect – pygame.Rect – A rectangle that is equal to the size of the highlighted text. It is used so that when we move from highlighted to non-highlighted text all of the text is erased. Otherwise if we just drew updated the normal rectangle, all of the highlighted text that was outside of it would not be redrawn.
• rect – pygame.Rect – The Rectangle where the text will be drawn. Use this to position your text, but its height and width will always be controlled by the text and the font.
• highlight_increase – Boolean whether or not the text should increase in size when the cursor is over it. If the text is “non-interactive” then this should be False.
• tracking – Boolean whether or not the TextWidget is tracking a mouse click. Used so that we can tell whether or not a true “click” has occurred. A true click is one where both the mouse-down and mouse-up events occur on the TextWidget.

To hopefully make the functionality of the TextWidget a bit clearer here is some non-highlighted text and then some highlighted text:

The Code

Now we get to the heart of the actual python\PyGame code, where we actually create a working TextWidget object.

So we’ll start off at the top of the file and then work out way downwards in a linear manner.

class TextWidget(object):
    """This is a helper class for handling text in PyGame.  It performs 
    some basic highlighting and tells you when the text has been clicked.
    This is just one of the many ways to handle your text.
    This is a new-style class and I am somewhat new to them so hopefully it 
    all works.
    """
    #Hand Cursor
    __hand_cursor_string = (
    "     XX         ",
    "    X..X        ",
    "    X..X        ",
    "    X..X        ",
    "    X..XXXXX    ",
    "    X..X..X.XX  ",
    " XX X..X..X.X.X ",
    "X..XX.........X ",
    "X...X.........X ",
    " X.....X.X.X..X ",
    "  X....X.X.X..X ",
    "  X....X.X.X.X  ",
    "   X...X.X.X.X  ",
    "    X.......X   ",
    "     X....X.X   ",
    "     XXXXX XX   ")
    __hcurs, __hmask = pygame.cursors.compile(__hand_cursor_string, ".", "X")
    __hand = ((16, 16), (5, 1), __hcurs, __hmask)

The above code is where we create the hand cursor that we will use if the person turns on the highlight_cursor. We first define what the cursor will look like as explained in the PyGame cursor documentation.

The next step is to create all of our properties, now this code may seem a bit complicated, especially since it deals with functions that we have not created yet, but as I explain it, it could become clearer and clearer.

#Text
def __get_text(self):
    return self.__m_text
def __set_text(self, text):
    if (self.__m_text != text):
        self.__m_text = text
        self.update_surface()
text = property(__get_text, __set_text)

The above code creates the TextWidget.text property. The __get_text() function is used to get the text property which is represented by the __m_text variable, and the __set_text() function is the function that is called when you want to set the value of the text property.

What you will notice about the __set_text() function is that it first tests to see if the text that we are setting (text) is any different then the current text (__m_text) if it isn’t any different we don’t do anything.

However if it is different we set __m_text and we call update_surface(). update_surface() is a member function that I will explain in more detail later, but for now all you need to know is that it updates what the widget will display. So since we changed the text we want the widget to update and display the new text.

You can probably see why I wanted to use new-style classes and properties now.

#Colour
def __get_colour(self):
    return self.__m_colour
def __set_colour(self, colour):
    if (self.__m_colour != colour):
        self.__m_colour = colour
        self.update_surface()
colour = property(__get_colour, __set_colour)

Next is the colour property, as you can see it’s basically identical to the text property, so I won’t bother explaining it.

#Size
def __get_size(self):
    return self.__m_size
def __set_size(self, size):
    if (self.__m_size != size):
        self.__m_size = size
        self.create_font()
size = property(__get_size, __set_size)

The next property is the size property, which controls the size of the font. Now this is slightly different in that it calls the create_font() function rather then the update_surface() function that the text and the colour property did.

The reason for this is that the size property is used in the creation of the actual font object that is used to update the surface which is eventually drawn to the screen. As with the update_surface() function I will explain the create_font() function later. Properties that call create_font() do not have to call update_surface() because create_font() calls update_surface().

#Font Filename
def __get_font_filename(self):
    return self.__m_font_filename
def __set_font_filename(self, font_filename):
    if (self.__m_font_filename != font_filename):
        self.__m_font_filename = font_filename
        self.create_font()
font_filename = property(__get_font_filename, __set_font_filename)

Then we have the font_filename property that represents the full path to the font file. So if that changes we need to recreate the font in order to display the text using the correct font.

#Highlight
def __get_highlight(self):
    return self.__m_highlight
def __set_highlight(self, highlight):
    if (not(self.__m_highlight == highlight)):
        #Save the bold_rect
        if (self.__m_highlight):
            self.bold_rect = self.rect
        self.__m_highlight = highlight
        #update the cursor
        self.update_cursor()
        if (highlight):
            self.size += self.highlight_increase
        else:
            self.size -= self.highlight_increase
        if (self.highlight_increase == 0):
            self.create_font()
highlight = property(__get_highlight, __set_highlight)

Next we have the highlight property, the highlight property is a boolean property that controls whether or not the TextWidget should display “highlighted” or not. When a TextWidget is highlighted the font will be displayed in bold, have its size increased by a specific amount, and (if enabled) the hand cursor will be displayed.

So now since the __get_highlight() function is the same as all of the others, I’ll just explain the __set_highlight() function.

First we check to see that the new value is different then the old value. We do this so that we don’t waste time with useless font creations or extra draws.

Then we check to see if the current state of the TextWidget is highlighted, because if it is, we know that it is about to go back to normal (because of the first if.) If that is the case we save the current rect as bold_rect so that the next time we draw we will want bold_rect to be drawn so that all of the previous highlighted text is overwritten.

Then we set the internal highlight value and call the update_cursor() function which will decide whether or not the cursor should be a hand or the default arrow.

Then we set the size of the font depending on whether or not the highlight state has been turned on. If it is we increase the size, and if it is not we decrease the size back down to normal.

Since increasing or decreasing the size will call create_font() we only need to call create_font() if self.highlight_increase is equal to zero, since in that case the value of the size property will not change and the font will not be created.

#Show Highlight Cursor
def __get_highlight_cursor(self):
    return self.__m_highlight_cursor
def __set_highlight_cursor(self, highlight_cursor):
    if (self.__m_highlight_cursor != highlight_cursor):
        self.__m_highlight_cursor = highlight_cursor
        self.update_cursor()
highlight_cursor = property(__get_highlight_cursor, __set_highlight_cursor)

Lastly we have the highlight_cursor property, which is a boolean property that controls whether or not the highlight (hand) cursor should be displayed. If you have made it this far and have understood the rest of the properties then understanding this property shouldn’t be too difficult. Basically it simply checks to see if we should update the property, and if so it updates it and then calls update_cursor() just in case we need the cursor to update right now.

def __init__(self, text="", colour=(0,0,0), size=32
             , highlight_increase = 20, font_filename=None
             , show_highlight_cursor = True):
    """Initialize the TextWidget
    @param text = "" - string - The text for the text widget
    @param colour = (0,0,0) - The colour of the text
    @param size = 32 - number - The size of the text
    @param highlight_increate - number - How large do we want the
    text to grow when it is highlighted?
    @param font_filename = None - string the patht to the font file
    to use, None to use the default pygame font.
    @param show_highlight_cursor = True - boolean - Whether or not to change
    the cursor when the text is highlighted.  The cursor will turn into
    a hand if this is true.
    """
    
    #inits
    self.dirty = False
    self.bold_rect = None
    self.highlight_increase = highlight_increase
    self.tracking = False
    self.rect = None
    
    #property inits
    self.__m_text = None
    self.__m_colour = None
    self.__m_size = None
    self.__m_font_filename = None
    self.__m_highlight = False
    self.__m_font = None
    self.__m_highlight_cursor = False
    self.__m_rect = None
    
    self.text = text
    self.colour = colour
    self.size = size
    self.font_filename = font_filename
    self.highlight = False
    self.highlight_cursor = show_highlight_cursor
    
    self.create_font()

Now we actually start using the class the first thing we do is code the __init__() function in which we initialize all of our data members and properties, and then create the font at the end. This may result in the font being create twice sometimes but it will only happen once when the Widget is created, and it makes sure that the font is always created.

def update_cursor(self):
    if (self.highlight_cursor):
        if (self.highlight):
            pygame.mouse.set_cursor(*self.__hand)
        else:
            pygame.mouse.set_cursor(*pygame.cursors.arrow)

Here is the update_cursor() function, it’s pretty straight forward. First we check whether or not we are supposed to change the cursor at all. If we are then we check to see if we are highlighted or not. If we are highlighted then we use the hand cursor that we created above, and if we are not highlighted we use the built-in pygame arrow cursor.

Drawing and Fonts

Now we finally get to drawing and the font creation that we talked about earlier. The first thing to do is to create our font:

def create_font(self):
    """Create the internal font, using the current settings
    """
    if (self.size):
        self.__m_font = pygame.font.Font(self.font_filename
                                 , self.size)
        self.update_surface()

As you can see this function really is pretty simple, all we need to make sure that we have is a size for the font. Then we create the font using pygame.font.Font() We don’t care if self.font_filename is None since if it is None, then the default font will be loaded.

After the font has been created we call update_surface():

def update_surface(self):
    """Update the current surface, basically render the
    text using the current settings.
    """
    if (self.__m_font):
        self.__m_font.set_bold(self.highlight)
        self.image = self.__m_font.render(self.text
                                        , True
                                        , self.colour)
        self.dirty = True
        if (self.rect):
            # Used the current rects center point
            self.rect = self.image.get_rect(center=self.rect.center)
        else:
            self.rect = self.image.get_rect()

In update_surfacte() we first make sure that our font (__m_font) exists, since if it does not then there is no point in creating any surface. Then we set the font’s bold setting Font.set_bold() function and controlled by the highlight property.

Then we render the font onto a pygame.surface using the Font.render() function and our current text and colour. We also make sure that the font is anti-aliased by passing True as the second parameter.

Then we set self.Dirty to True to make sure that the next time through the draw loop the new surface gets displayed.

The last thing we do in the function is move our text into the correct location. If self.rect has been specified then we move the image into that position and set our rect, otherwise we initialize self.rect to be be surfaces rectangle.

self.rect must eventually be move into some position because Surface.get_rect() always returns a rectangle that starts at 0,0.

def draw(self, screen):
    """Draw yourself text widget
    @param screen - pygame.Surface - The surface that we will draw to
    @returns - pygame.rect - If drawing has occurred this is the 
    rect that we drew to.  None if no drawing has occurred."""
    
    rect_return = None
    if ((self.image)  and  (self.rect) and (self.dirty)):
        if (self.bold_rect):
            """We may need to overwrite the bold text size
            This gets rid of leftover text when moving from 
            bold text to non-bold text.
            """
            rect_return = pygame.Rect(self.bold_rect)
            """Set to None, since we only need to do this
            once."""
            self.bold_rect = None
        else:
            rect_return = self.rect
        #Draw the text
        screen.blit(self.image, self.rect)
        #Dirty no more
        self.dirty = False

    return rect_return

Finally we get to the draw code, and thankfully it’s pretty simple. The draw() function take a pygame.Surface as the only parameter, this is the surface that we will be drawing to, probably the main surface in your game or application. The draw function will also return a pygame.Rect object (or None) which represents the area of the surface that needs to be updated (or not).

The first thing we do in the function is make sure that we actually have something to draw. We check our rectangle (self.tect) and our surface (self.image) to make sure that everything has been initialized, and then we check self.dirty to see if we should draw anything.

Then we check to see if self.bold_rect is valid, if it is we return it as the rectangle to update and invalidate the bold_rect, since it only needed once, when moving from highlighted to non-highlighted). If self.bold_rect is not valid then we will return self.rect as the rectangle to update.

Then we blit our text to the screen (which is stored in self.image as a pygame.Surface object) and set self.dirty to False so that we do not needlessly draw in the future.

Events

If you remember way back at the beginning of this tutorial we create a define for a future event that would be fired when the TextWidget was clicked on:

TEXT_WIDGET_CLICK = pygame.locals.USEREVENT + 1

Now is where we use it and let the main class know when a TextWidget has been clicked.

def on_mouse_button_down(self, event):
    """Called by the main application when the
    MOUSEBUTTONDOWN event fires.
    @param event - Pygame Event object
    MOUSEBUTTONDOWN  pos, button
    """
    #Check for collision
    self.tracking = False
    if (self.rect.collidepoint(event.pos)):
        self.tracking = True

First we have the on_mouse_button_down() function, this should be called by your main application during the event loop. If you come across a MOUSEBUTTONDOWN event, then you should pass it to all of your TextWidget objects, or at least the TextWidgets that you want to be interactive.

All this function does is check to see if the mouse button down event occurred within the TextWidgets rect, if it did, self.Tracking is set to True to let the TextWidget know that it is “tracking” or listening for the MOUSEBUTTONUP event to complete the click.

def on_mouse_button_up(self, event):
    """Called by the main application when the
    MOUSEBUTTONDOWN event fires.
    @param event - Pygame Event object
    MOUSEBUTTONDOWN  pos, button
    """
    #Check for collision
    if ((self.tracking) and (self.rect.collidepoint(event.pos))):
        self.on_mouse_click(event)
    #Not Tracking anymore
    self.tracking = False

Next we have the on_mouse_button_up function which called by your main application for all of your interactive TextWidget objects when the MOUSEBUTTONDOWN event is found.

This function is very simple, it first checks to see if we are currently tracking, if we are then we check to see if the event has occurred within the TextWidget’s rect. If it has we call self.one_mouse_click() and pass it the event.

Then we set self.tracking to False, since whatever happened we are no longer tracking. Now if you don’t fully understand what the self.tracking boolean does, it simply makes sure that the TextWidget behaves like a standard button, which means that it only registers MOUSEBUTTONUP events as a “click” if the MOUSEBUTTONDOWN also occurred within the buttons rectangle.

def on_mouse_click(self, event):
    """Called by the main application when the
    MOUSEBUTTONDOWN event fires, and the text widget
    has been clicked on.  You can either let
    this post the event (default) or you can override this
    function call in your app.
    ie. myTextWidget.on_mouse_click = my_click_handler
    @param event - Pygame Event object
    MOUSEBUTTONDOWN  pos, button
    """
    #Create the TEXT_WIDGET_CLICK event
    event_attrib = {}
    event_attrib["button"] = event.button
    event_attrib["pos"] = event.pos
    event_attrib["text_widget"] = self
    e = pygame.event.Event(TEXT_WIDGET_CLICK, event_attrib)
    pygame.event.post(e)

Finally in our event handling we have the on_mouse_click() function. By default this function will post a TEXT_WIDGET_CLICK event to the PyGame event queue which you can handle in whichever manner you like.

The event has the following attributes:

• button – The button of the mouse that was used for the click. This is the same as the MOUSEBUTTONUP event’s button attribute.
• pos (x,y) – The position of the mouse cursor when the click occurred. The is the same as the MOUSEBUTTONUP event’s pos attribute.
• text_widget – The TextWidget object that was clicked on, so you know how to handle the event.

That is the default way that the on_mouse_click() function functions, in general it is probably easier to override the on_mouse_click() function in all of the TextWidget instances that you want to be interactive.

As an example, in your main application you might use the following for an Exit TextWidget:

self.exit_text.on_mouse_click = self.on_exit_clicked

Using the TextWidget

In order to make it easy to see how to use the TextWidget object (if it is not already) I whipped up a quick sample application, the short flash capture is to show you what it looks like without having to run it:

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

import TextWidget

class PyGameText:
    """An example class used to illustrate possible ways to work
    with the TextWidget text in a pygame game.
    """
    
    def __init__(self, width=640, height=480):
        """Initialize
        @param width=640 - The width of the pygame window
        @param height=480 - The height of the pygame window.
        """
        
        pygame.init()
        #create the screen
        self.screen = pygame.display.set_mode((width, height), 0) 
        self.background = pygame.Surface(self.screen.get_size(), SWSURFACE)
        self.background = self.background.convert()
        image, rect = self.load_image("background.png")
        if (image):
            self.background.blit(image, (0,0))
        else:
            #Just fill with a solid colour
            self.background.fill((124,124,124))
        self.screen.blit(self.background, (0,0))
        
    def main_loop(self):
        """The main Python loop"""
        
        pygame.display.update()
        self.timer = pygame.time.Clock()
        
        # Text Widget list
        self.text_widgets = []
        #Create our Text WIdgets
        self.new_game_text = TextWidget.TextWidget("New Game", (200,200,200))
        #make this the biggest text
        self.new_game_text.size = 96
        self.new_game_text.rect.center = self.screen.get_rect().center
        self.new_game_text.rect.top = 0;
        self.text_widgets.append(self.new_game_text)
        
        self.high_score_text = TextWidget.TextWidget("High Scores", (255,0,0), 64)
        self.high_score_text.rect.center = self.screen.get_rect().center
        self.high_score_text.rect.top = self.new_game_text.rect.bottom + 30
        self.text_widgets.append(self.high_score_text)
        
        self.website_text = TextWidget.TextWidget("Website", (255,0,255), 64)
        self.website_text.rect.center = self.screen.get_rect().center
        self.website_text.rect.top = self.high_score_text.rect.bottom + 30
        self.text_widgets.append(self.website_text)
        
        # Different font for the last one, and let's make it increase
        # more
        self.exit_text = TextWidget.TextWidget("Exit", (0, 255,255)
                                , 64, 40
                                , pygame.font.match_font("sans", False, True))
        self.exit_text.rect.center = self.screen.get_rect().center
        self.exit_text.rect.top = self.website_text.rect.bottom + 30
        self.exit_text.on_mouse_click = self.on_exit_clicked
        self.text_widgets.append(self.exit_text)
           
        while 1: 
            #Tick of the timer
            self.timer.tick()
            
            self.event_loop()
            
            self.draw()
                
    def event_loop(self):
        """Perform the event loop."""
        
        for event in pygame.event.get():
            if (event.type == pygame.QUIT):
                pygame.quit()
                sys.exit()
            elif (event.type == ACTIVEEVENT):
                if (event.gain == 1):
                    for text in self.text_widgets:
                        text.dirty = True
                    self.draw()
                elif (event.state ==2): 
                    #We are hidden so wait for the next event
                    pygame.event.post(pygame.event.wait())             
            elif (event.type == pygame.MOUSEMOTION):
                for text in self.text_widgets:
                    text.highlight = text.rect.collidepoint(event.pos)
            elif (event.type == pygame.MOUSEBUTTONDOWN):
                for text in self.text_widgets:
                    text.on_mouse_button_down(event)
            elif (event.type == pygame.MOUSEBUTTONUP):
                for text in self.text_widgets:
                    text.on_mouse_button_up(event)
            elif (event.type == TextWidget.TEXT_WIDGET_CLICK):
                print event.text_widget             
    
    def draw(self):
        """Draw everything"""        
        rects = []
        rects.append(self.timer_update())
        for text in self.text_widgets:
            rect = text.draw(self.screen)
            if (rect):
                rects.append(rect)
        pygame.display.update(rects)        
        
    def timer_update(self):
        """Update the Timer
        returns - pygame.rect - The rect that the timer
        needs to be redrawn, or None on error"""
        
        rect_return = None
        
        if (pygame.font):     
            timer_string = "%.2f" % self.timer.get_fps()
            #basic font
            font = pygame.font.Font(None, 36)
            message = font.render(timer_string, 1, (147, 1, 16))
            if (message):
                rect_return = message.get_rect(left=0)
                rect_return.width += 25
                self.screen.blit(self.background, rect_return)
                self.screen.blit(message, rect_return) 
        
        return rect_return
    
    def load_image(self, name, colorkey=None):
        full_path = os.path.realpath(os.path.dirname(sys.argv[0]))
        full_path = os.path.join(full_path, name)
        try:
            image = pygame.image.load(full_path)
        except pygame.error, message:
            print 'Cannot load image:', full_path
            return None, None
        image = image.convert()
        if colorkey is not None:
            if colorkey is -1:
                colorkey = image.get_at((0,0))
            image.set_colorkey(colorkey, RLEACCEL)
        return image, image.get_rect()
    
    def on_exit_clicked(self, event):
        pygame.quit()
        sys.exit()

if __name__ == "__main__":
    text = PyGameText()
    text.main_loop()

Now most of the code isn’t that exciting and is a pretty basic example of a short PyGame application so I won’t explain every line of this code. I will highlight three portions:

Text Widget Creation

Here is how I created the four TextWidgets in the example application, each is slightly different so you might want to look at each and try to understand what it is doing:

# Text Widget list
self.text_widgets = []
#Create our Text WIdgets
self.new_game_text = TextWidget.TextWidget("New Game", (200,200,200))
#make this the biggest text
self.new_game_text.size = 96
self.new_game_text.rect.center = self.screen.get_rect().center
self.new_game_text.rect.top = 0;
self.text_widgets.append(self.new_game_text)

self.high_score_text = TextWidget.TextWidget("High Scores", (255,0,0), 64)
self.high_score_text.rect.center = self.screen.get_rect().center
self.high_score_text.rect.top = self.new_game_text.rect.bottom + 30;
self.text_widgets.append(self.high_score_text)

self.website_text = TextWidget.TextWidget("Website", (255,0,255), 64)
self.website_text.rect.center = self.screen.get_rect().center
self.website_text.rect.top = self.high_score_text.rect.bottom + 30;
self.text_widgets.append(self.website_text)

# Different font for the last one, and let's make it increase
# more
self.exit_text = TextWidget.TextWidget("Exit", (0, 255,255)
                        , 64, 40
                        , pygame.font.match_font("sans", False, True))
self.exit_text.rect.center = self.screen.get_rect().center
self.exit_text.rect.top = self.website_text.rect.bottom + 30;
# Override the on_mouse_click function
self.exit_text.on_mouse_click = self.on_exit_clicked
self.text_widgets.append(self.exit_text)

In general this code is pretty simple, it mostly involves creating our TextWidget objects, settings some of their properties and then adding them to a list. It really should be pretty self explanatory how this code works, one thing that I will point out is how the in the exit_text TextWidget the pygame.font.match_font() function is used to get the path to the font, and the on_mouse_click() function is overridden.

The Event Loop

def event_loop(self):
    """Perform the event loop."""

for event in pygame.event.get():
    if (event.type == pygame.QUIT):
        pygame.quit()
        sys.exit()
    elif (event.type == ACTIVEEVENT):
        if (event.gain == 1):
            for text in self.text_widgets:
                text.dirty = True
            self.draw()
        elif (event.state ==2): 
            #We are hidden so wait for the next event
            pygame.event.post(pygame.event.wait())             
    elif (event.type == pygame.MOUSEMOTION):
        for text in self.text_widgets:
            text.highlight = text.rect.collidepoint(event.pos)
    elif (event.type == pygame.MOUSEBUTTONDOWN):
        for text in self.text_widgets:
            text.on_mouse_button_down(event)
    elif (event.type == pygame.MOUSEBUTTONUP):
        for text in self.text_widgets:
            text.on_mouse_button_up(event)
    elif (event.type == TextWidget.TEXT_WIDGET_CLICK):
        print event.text_widget

The first thing you should notice is that we respond to the ACTIVEEVENT, we do this so that when the PyGame window gets focus back (after loosing it) we redraw all of the text widgets. We force the TextWidgets to redraw by setting the dirty member to True.

Next we set the TextWidget.highlight property by checking for a collision with each TextWidget rect when we get the MOUSEMOTION event.

If you want your TextWidgets to be responsive to a click whenever you get a MOUSEBUTTONDOWN or MOUSEBUTTONUP event you can simply pass it forward to the on_mouse_button_down() and on_mouse_button_up() functions in each widget, the TextWidget will take care of the rest of the processing.

The example also shows how to handle the TEXT_WIDGIT_CLICK event:

elif (event.type == TextWidget.TEXT_WIDGET_CLICK):
        print event.text_widget

In the example I simply print out the TextWidget, but you could do whatever you wanted to.

The Draw Loop

def draw(self):
    """Draw everything"""        
    rects = []
    rects.append(self.timer_update())
    for text in self.text_widgets:
        rect = text.draw(self.screen)
        if (rect):
            rects.append(rect)
    pygame.display.update(rects)

The draw loop is actually pretty simple. I use a list to keep track of rectangles that I want to update at the end of the draw using pygame.display.update() function.

In order to draw the TextWidget’s I simply loop through the list of them and call their draw() function. If the draw() function returns a rectangle, then I know that the TextWdiget has drawn so I add it to the list of rectangles that need to be updated.

If None is returned then I know that the TextWidget has not drawn and that it does not need to be drawn.

Conclusion

The full source and necessary files for this tutorial can be downloaded here.

So that’s it for this tutorial, as I said early on I’m not saying that this is the best or only way to work with text, I’m simply presenting this as a possible way to work with text, or as an example that might help get you started with your own text processing.

If you have any suggestions, problems, or notice anything that is incorrect, as always, add a comment!

Feel free to use this in whatever manner you want (it’s licensed under the LGPL), but if you do end up using it, I would appreciate it if you sent me an email and let me know.

Hi everyone just a quick post to let you know that I probably won’t be posting much during this month as I have decided to participate in nanowrimo which leaves me almost no time to come up with tutorials.

I as mentioned in the past Satoshi Tanabe over at satolog has translated a few of my tutorials over into Japanese, which is very cool. It also turns out that someone over at blog.chinaunix.net has also translated one of my tutorials (Building an application with PyGTK and Glade) into Chinese, again very cool! Thanks a lot for the translations guys.

I’ve also been working on some pyGame in my spare time over the last few months, I’ve been working on a level editor and a widget set:

Of course that doesn’t show very much but it show show my scrollbars! The problem with building the level editor is that y you always have to keep working on the smallest details (like a scrollable area0 before you can get to the real heart of the problem. Oh well it’s till fun!

Talk to you all soon!

Recently I’ve been playing around in PyGame for the past PyWeek and having a blast! Sadly my PyWeek entry was mostly a bust as real life got the better of me, but it reminded my how much I enjoy python and doing simple game programming.

Hopefully I’ll continue on with both my PyGTK and PyGame work! If you like Python and are interested in creating games, I definately think that you should check out PyGame.

All right in this section of the tutorial we are going to start adding the bad guys. If you are familiar with the changes that we made in part two it should be pretty clear to you how are are going to create these bad guys. If you haven’t already you should check out part one and part two. If you would like the full source and all of the images you can get it here.

First we are going have to create a new class based on our basicSprite class. I created a new file called basicMonster.py and inside of that I created a class called Monster:

class Monster(basicSprite.Sprite):

For now we’re not going to go too crazy in our enemy AI, we’re just going to get them to choose a random direction to move and move in that direction until they hit a wall. We’ll also add in another option where after a certain amount of moves the monster will choose another random direction. This is just to add a little but more randomness into the Monster, it’s not really what we’d like to use at the end of the day but it works out all right.

Now we’ll take a look at the Monsters __init__ function:

def __init__(self, centerPoint, image, scared_image=None):
    
    basicSprite.Sprite.__init__(self, centerPoint, image)
    """Save the original rect"""
    self.original_rect = pygame.Rect(self.rect)
    self.normal_image = image
    if scared_image !=None:
        self.scared_image = scared_image
    else:
        self.scared_image = image
    
    self.scared = False
    """Initialize the direction"""
    self.direction = random.randint(1,4)
    self.dist = 3
    self.moves = random.randint(100,200)
    self.moveCount = 0;

You can see that there is a bit more happening here then there is in out basic sprites. The first thing you’ll notice is the fact that the Monster is going to have two images, a normal image and a scared image. The scared image is what we will be drawn as the monster when the snake is in it’s “super” state, which is caused when it eats a super pellet.

You’ll also notice that we save a copy of the original rect, the reason that we do this is because that is where the Monster will go if it has been eaten by the snake. This probably isn’t how we will want to handle it in the end, but it’s a pretty good start.

Then we start laying out the Monster AI, the first thing to do is choose an initial direction:

self.direction = random.randint(1,4)

The direction is simply a random integer between 1 and 4, each integer being a direction from the Monster to travel in (1=left, 2=up, 3=right, and 4=down) the monster will then travel self.dist pixels every-time it is updated until it hits a wall, at which point it will choose another random direction.

After that we initialize the idea of moves and moveCount, this is the second degree of randomness that we add into the Monster. The idea is that after 100-200 moves the Monster will choose another random direction.

If you’ve read part 2 of this PyGame series the structure of our Monsters update function should come as no surprise:

def update(self,block_group):
    """Called when the Monster sprit should update itself"""        
    xMove,yMove = 0,0
    
    if self.direction==1:
        xMove = -self.dist
    elif self.direction==2:
        yMove = -self.dist
    elif self.direction==3:
        xMove = self.dist
    elif self.direction==4:
        yMove = self.dist
    
    self.rect.move_ip(xMove,yMove) #Move the Rect
    self.moveCount += 1 #Update the Move count
    
    if pygame.sprite.spritecollideany(self, block_group):
        """IF we hit a block, don't move - reverse the movement"""
        self.rect.move_ip(-xMove,-yMove)
        self.direction = random.randint(1,4)
    elif self.moves == self.moveCount:
        """If we have moved enough, choose a new direction"""
        self.direction = random.randint(1,4)
        self.moves = random.randint(100,200)
        self.moveCount = 0;

The next thing that we are going to create is a function that will let us set the Monsters scared state:

def SetScared(self, scared):
    """Tell the monster to be scared or not"""
    """Should we update out scared image?"""
    if self.scared != scared:
        self.scared = scared
        if scared:
            self.image = self.scared_image
        else:
            self.image = self.normal_image

This function is pretty self-explanatory, we just set the current state and the current image for the monster based on that state.

The next function that we need is a “eaten” function, this is the function that will be called when the monster has been eaten by the snake. This function is, again, very simply and simply moves the monster back to it’s original position and resets its state:

def Eaten(self):
    """Well looks like we've been eaten!, reset to the original
    position and stop being scared"""
    self.rect = self.original_rect
    self.scared = False
    self.image = self.normal_image

The next thing that we need to do is make sure that the snakes update function takes into account these new monsters:

def update(self,block_group,pellet_group,super_pellet_group,monster_group):
    """Called when the Snake sprit should update itself"""
    
    if (self.xMove==0)and(self.yMove==0):
        """If we arn'te moving just get out of here"""
        return
    """All right we must be moving!"""
    self.rect.move_ip(self.xMove,self.yMove)
    
    if pygame.sprite.spritecollideany(self, block_group):
        """IF we hit a block, don't move - reverse the movement"""
        self.rect.move_ip(-self.xMove,-self.yMove)
    
    """Check to see if we hit a Monster!"""
    lst_monsters =pygame.sprite.spritecollide(self, monster_group, False)
    if (len(lst_monsters)>0):
        """Allright we have hit a Monster!"""
        self.MonsterCollide(lst_monsters)
    else:
        """Alright we did move, so check collisions"""
        """Check for a snake collision/pellet collision"""
        lstCols = pygame.sprite.spritecollide(self
                                             , pellet_group
                                             , True)
        if (len(lstCols)>0):
            """Update the amount of pellets eaten"""
            self.pellets += len(lstCols)
            """if we didn't hit a pellet, maybe we hit a SUper Pellet?"""
        elif (len(pygame.sprite.spritecollide(self, super_pellet_group, True))>0):
            """We have collided with a super pellet! Time to become Super!"""
            self.superState = True
            pygame.event.post(pygame.event.Event(SUPER_STATE_START,{}))
            """Start a timer to figure out when the super state ends"""
            pygame.time.set_timer(SUPER_STATE_OVER,0)
            pygame.time.set_timer(SUPER_STATE_OVER,3000)

You’ll notice that this function is relatively similar to what happened in part 2, except that some of the code has been moved here, and we now check to see if we have collided with any monsters.

The first thing we check is if we have collided with a wall, if so we reverse our movement, so that the snake doesn’t move. Instead of leaving the function, we continue to test to see if the snake has hit a monster. If the snake has hit a monster we call the MonsterCollide function to see what should happen. If no monster was hit we then check to see if any pellets or super pellets were hit.

If the snake eats a super pellet, we set its state to be super, then we post an event to our main loop telling it that the snake has become super, and then we start a three second time. The three second timer is basically how long the snake will stay in it’s super state and be able to eat monsters.

The MonsterCollide function is detailed below:

def MonsterCollide(self, lstMonsters):
    """This Function is called when the snake collides with the a Monster
    lstMonsters is a list of Monster sprites that it has hit."""
    
    if (len(lstMonsters)< =0):
        """If the list is empty, just get out of here"""
        return

    """Loop through the monsters and see what should happen"""
    for monster in lstMonsters:
        if (monster.scared):
            monster.Eaten()
        else:
            """Looks like we're dead"""
            pygame.event.post(pygame.event.Event(SNAKE_EATEN,{}))

The MonsterCollide function is relatively simple, It loops trough the list of monsters that the snake has collided with and decides what to do with each of them. If the monster is scared it gets eaten, and if the monster is not scared then we post the snake eaten even.

No we need to look at the changes that we need to make to the LoadSprites function in the PyMan.py file. The only think that we are going to change is add the code to load the monsters, it will be identical to the code that we use to load the other sprites, except that monsters have a normal and scared image, and we will also switch to using RenderUpdates for our pygame groups, RenderUpdates are just like normal PyGame sprite groups except that they keep track of the rects that they have drawn to. So when you call RenderUpdates.Draw it will draw all of the sprites in the groups and then return a list of “dirty” rects. You then take the list of rects and pass it into pygame.display.update.

This way you save time by only redrawing only those sections of the screen that have changed.

The next changes that we need to make are in the MainLoop function. The first thing we have to do is pay attention to the events and timers that we have created in out other code.

elif event.type == SUPER_STATE_OVER:
    self.snake.superState = False
    """Stop the timer"""
    pygame.time.set_timer(SUPER_STATE_OVER,0)
    for monster in self.monster_sprites.sprites():
        monster.SetScared(False)
elif event.type == SUPER_STATE_START:
    for monster in self.monster_sprites.sprites():
        monster.SetScared(True)
elif event.type == SNAKE_EATEN:
    """The snake is dead!"""
    """For now kist quit"""
    sys.exit()

Handling these events is pretty straight forward, the only one that will eventually change is the SNAKE_EATEN event. For now we just quite the game but in the future we will use up lives and things like that.

The next, and final change for this tutorial is the section of the code where we actually draw the sprites. As detailed above we are using RenderUpdate groups this time instead of the normal groups that we have used in the past. As a result our drawing code has to change slightly in order to pay attention to the rects that we have dirtied:

"""Do the Drawing"""     
textpos = 0          
self.screen.blit(self.background, (0, 0))     
if pygame.font:
    font = pygame.font.Font(None, 36)
    text = font.render("Pellets %s" % self.snake.pellets
                        , 1, (255, 0, 0))
    textpos = text.get_rect(centerx=self.background.get_width()/2)
    self.screen.blit(text, textpos)

reclist = [textpos]  
reclist += self.pellet_sprites.draw(self.screen)
reclist += self.super_pellet_sprites.draw(self.screen)
reclist += self.snake_sprites.draw(self.screen)
reclist +=  self.monster_sprites.draw(self.screen)
"""Now Update the Display"""
pygame.display.update(reclist)

As you can see not much has actually changed except for the fact that we are now paying attention to the rectangles that we have dirtied and are only updating those rather then redrawing the entire screen.

If you would like the full source of this tutorial, you can get it here.

Well that’s it for this tutorial, sorry it’s been such a long time coming, it seems that real life got in the way of my learning python. Hopefully I will get back on my schedule of updating this site once a week soon.

All right in Part one we actually created a semi-working almost-game, in part two we’re going to go a bit further, in part two we’re going to add the walls that will make help make PyMan (our python based PacMan clone) an actual game.

Note: Part one has been mistakenly half-deleted by me, so it is not fully available at this time. I am working to re-write it so it should be up soon.

Note: I also changed the images that I used in Part one so now we have a new smaller snake.

You can download the full source for Part Two here.

What we are going to do is base some of our level code on a great PyGame tutorial over at DevShed specifically the idea of the level layout. This is something that has always puzzled me about games, how they create their levels? I’ve read some articles and beginnings of books but I’ve never really be able to understand it, but the multidimensional array approach discussed in the DevShed article is nothing if not simple.

So the idea is that our game world, or game board, will basically be a grid of 24×24 pixel items, and we will have a multidimensional array or list that we will used to describe it.

So for example lets say we have a grid like this:


0 0 0 0 0
1 1 1 1 1
1 0 0 0 1
1 1 1 1 1
0 0 0 0 0


Now that grid may result in the following:

Where 0 is nothing and where 1 is a blue square. We could then add 2’s if we wanted to and make those red squares, or anything else that we wanted. So that is basically how our levels are going to be defined.

The first thing we are going to do is add a new file to our project called levelBase.Py, in that we will define a class called level which is as follows:

class Level:
    """The Base Class for Levels"""
    def getLayout(self):
        """Get the Layout of the level"""
        """Returns a [][] list"""
        pass
    def getImages(self):
        """Get a list of all the images used by the level"""
        """Returns a list of all the images used.  The indices 
        in the layout refer to sprites in the list returned by
        this function"""
        pass

Pretty simple not much going on there, getLayout returns a multidimensional list of numbers that represents the level, and getImages returns a list of the images used by the level.

It may seem complicated but once you see our first level it will start to make some sense. The next thing to do is add a file called level001.py to our project. I waffled on this a bit, I was unsure if it was better to have one file called levels.py that contained classes called level001, or make each level a separate file. In then end I went with each level being a separate file, just because it separates things, but I don’t really know if one method is superior over the other. Here is the code for level001.py:

#! /usr/bin/env python

import levelBase
from helpers import load_image

class level(levelBase.Level):
    """Level 1 of the PyMan Game"""
    
    def __init__(self):
        self.BLOCK = 1
        self.SNAKE = 2
        self.PELLET = 0
    
    def getLayout(self):
        return [[9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9 ,9, 9, 9, 9, 9, 9, 9, 9, 9, 9],\
                [9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9 ,9, 9, 9, 9, 9, 9, 9, 9, 9, 9],\
                [9, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ,1, 1, 1, 1, 1, 1, 1, 1, 1, 9],\
                [9, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1 ,0, 0, 0, 0, 0, 0, 0, 0, 1, 9],\
                [9, 1, 0, 1, 1, 0, 1, 1, 1, 0, 1 ,0, 1, 1, 1, 0, 1, 1, 0, 1, 9],\
                [9, 1, 0, 2, 0, 0, 0, 0, 0, 0, 0 ,0, 0, 0, 0, 0, 0, 0, 0, 1, 9],\
                [9, 1, 0, 1, 1, 0, 1, 0, 1, 1, 1 ,1, 1, 0, 1, 0, 1, 1, 0, 1, 9],\
                [9, 1, 0, 0, 0, 0, 1, 0, 0, 0, 1 ,0, 0, 0, 1, 0, 0, 0, 0, 1, 9],\
                [9, 1, 1, 1, 1, 0, 1, 1, 1, 0, 1, 0, 1, 1, 1, 0, 1, 1, 1, 1, 9],\
                [9, 1, 1, 1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1, 9],\
                [9, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 9],\
                [9, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 9],\
                [9, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 9],\
                [9, 1, 1, 1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1, 9],\
                [9, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 9],\
                [9, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 9],\
                [9, 1, 0, 1, 1, 0, 1, 1, 1, 0, 1, 0, 1, 1, 1, 0, 1, 1, 0, 1, 9],\
                [9, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 1, 9],\
                [9, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 9],\
                [9, 1, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 9],\
                [9, 1, 0, 1, 1, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 1, 0, 1, 9],\
                [9, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 9],\
                [9, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 9]]         
        
    def getSprites(self):
        block, rect = load_image('block.png')
        pellet, rect = load_image('pellet.png',-1)
        snake, rect = load_image('snake.png',-1)
        return [pellet,block,snake]

You can see that in the __init__ function the level defines three values: BLOCK, SNAKE, and PELLET. These values correspond to the numbers in the list returned by getLayout(). So wherever there is a 1 in the list, that will correspond to a BLOCK, a 0 is a PELLET, and a 2 is our snake. In this example I use 9 to represent a blank square.

You’ll also notice that the getImages() function returns a list of images that are indexed by those same values. So in the list returned by getImages(), position [BLOCK] is the block image.

So far so good, the next thing we are going to do is add a base class for all of our sprites. In Part one we didn’t need to do this since we only had two sprites, but in this lesson (as we can see above) we are going to have at least three and that number will continue to grow. So we will add another file to our project called basicSprite.py, this will be the base class that we use for all of our sprites. It doesn’t do much besides add a few initialization features to pygame.sprite.Sprite class. The code for basicSprite.py is as follows:

#! /usr/bin/env python

import pygame

class Sprite(pygame.sprite.Sprite):
        
    def __init__(self, centerPoint, image):
        pygame.sprite.Sprite.__init__(self) 
        """Set the image and the rect"""
        self.image = image
        self.rect = image.get_rect()
        """Move the rect into the correct position"""
        self.rect.center = centerPoint

As you can see all that basicSprite.Sprite does is really add a few initialization values: centerPoint and image. Image is the image that the sprite will use and centerPoint is the center point of the rect, it controls where the image will be placed. The nice thing about using the center point is that it is correct regardless of the images size. So if you have a 16×16 image and a 24×24 image the center point will be the same, but the topleft point (which we used in part one) will be different for both.

Because of the addition of the basicSprite.Sprite we are going to have to change our snake sprite from part one, we are also going to move the sprite into it’s own file since it will start getting a bit complicated as time goes on. So we will add the file snakeSprite.py to our project. snakeSprite.py will contain a class called Snake, which will be based off of our basicSprite.Sprite class:

class Snake(basicSprite.Sprite):

Snake will initialize itself as follows:

def __init__(self, centerPoint, image):
    """initialize base class"""
    basicSprite.Sprite.__init__(self, centerPoint, image)
    """Initialize the number of pellets eaten"""
    self.pellets = 0
    """Set the number of Pixels to move each time"""
    self.x_dist = 3
    self.y_dist = 3 
    """Initialize how much we are moving"""
    self.xMove = 0
    self.yMove = 0

You’ll notice that the initialization is similar to the initialization in part one except this time we are using the basicSprite.Sprite class to set up our image and rect. Then we initialize the same values, except we have introduce two new ones, self.xMove and self.yMove. The reason for this is we are going to change the way that we move our snake.

If you tried out the last tutorial you’ll see that just moving the character on the key down events didn’t work all that well. It worked well enough but if you start pressing more then one key are the same time pyGame seemed to get a bit confused.

In order to combat this we will use another tip taken from the DevShed tutorial and pay attention to both the DOWN and UP events associated with keystrokes. We will also switch to using the update() function to update the snake.

So what we are going to is add two functions to the Snake class MoveKeyUp() and MoveKeyDown(). What these functions will do is adjust the xMove and yMove variables depending on what key has been pressed. Then when the update function is called the Snake will update it’s positions according the values of xMove and yMove. It may seem a bit complicated but it’s actually pretty simple:

def MoveKeyDown(self, key):
    """This function sets the xMove or yMove variables that will
    then move the snake when update() function is called.  The
    xMove and yMove values will be returned to normal when this 
    keys MoveKeyUp function is called."""
    
    if (key == K_RIGHT):
        self.xMove += self.x_dist
    elif (key == K_LEFT):
        self.xMove += -self.x_dist
    elif (key == K_UP):
        self.yMove += -self.y_dist
    elif (key == K_DOWN):
        self.yMove += self.y_dist
    
def MoveKeyUp(self, key):
    """This function resets the xMove or yMove variables that will
    then move the snake when update() function is called.  The
    xMove and yMove values will be returned to normal when this 
    keys MoveKeyUp function is called."""
    
    if (key == K_RIGHT):
        self.xMove += -self.x_dist
    elif (key == K_LEFT):
        self.xMove += self.x_dist
    elif (key == K_UP):
        self.yMove += self.y_dist
    elif (key == K_DOWN):
        self.yMove += -self.y_dist

As you can see when we press the K_LEFT key down we add -x_dist pixels to the xMove variable. This will then be used to move the snake in the update() function. Then when we let up the K_LEFT key we remove the -x_dist values that we added to xMove. For example if you hold down K_LEFT for a moment xMove will before -3 (move three pixels to the left every time the update() function is called), then when you let the K_LEFT key up xMove will become 0 (don’t move).

Then all we have to do is add the update function:

def update(self,block_group):
    """Called when the Snake sprit should update itself"""
    self.rect.move_ip(self.xMove,self.yMove)
    """IF we hit a block, don't move - reverse the movement"""
    if pygame.sprite.spritecollide(self, block_group, False):
        self.rect.move_ip(-self.xMove,-self.yMove)

Now the update() function is function in pyGames Sprite class. It really doesn’t do anything besides providing a convenient way to update a group of sprites. It will also pass the same parameters to all of your sprites in the group. So if you have a bunch of sprites that need to know the current time when you update them it’s a good idea to add them to the same group and then update them all at once by calling the group.update() function and pass the time.

You’ll also notice that there is a second parameter passed to this function called block_group, this is the group of all of our block sprites. We use that group to do a hit test. If the snake has collided with a block after we have adjusted it’s rect, we reverse the movement.

No we are going to go back to our PyManMain class and edit the LoadSprites() function. We are going to use this function to load the level that we created in level001.py and all of the sprites that we need:

def LoadSprites(self):
    """Load all of the sprites that we need"""
    """calculate the center point offset"""
    x_offset = (BLOCK_SIZE/2)
    y_offset = (BLOCK_SIZE/2)
    """Load the level"""        
    level1 = level001.level()
    layout = level1.getLayout()
    img_list = level1.getSprites()
    
    """Create the Pellet group"""
    self.pellet_sprites = pygame.sprite.Group()
    """Create the block group"""
    self.block_sprites = pygame.sprite.Group()
    
    for y in xrange(len(layout)):
        for x in xrange(len(layout[y])):
            """Get the center point for the rects"""
            centerPoint = [(x*BLOCK_SIZE)+x_offset,(y*BLOCK_SIZE+y_offset)]
            if layout[y][x]==level1.BLOCK:
                block = basicSprite.Sprite(centerPoint, img_list[level1.BLOCK])
                self.block_sprites.add(block)
            elif layout[y][x]==level1.SNAKE:
                self.snake = Snake(centerPoint,img_list[level1.SNAKE])
            elif layout[y][x]==level1.PELLET:
                pellet = basicSprite.Sprite(centerPoint, img_list[level1.PELLET])
                self.pellet_sprites.add(pellet)  
    """Create the Snake group"""            
    self.snake_sprites = pygame.sprite.RenderPlain((self.snake))

Since this function is a bit more complicated I will try to explain it in more detail. The first thing that we do is calculate the x_offset and the y_offset, using the value BLOCK_SIZE. BLOCK_SIZE is simple a global created in pyMan.py that refers to the size that each block will be. So in this case, BLOCK_SIZE = 24. The x_offset and y_offsets are the center points of a block. We use these offsets to position the sprites that we will create.

After that we load the level: we create an instance of the level001 class, and then get it’s layout and it’s image list. Then we create our pellet and block groups, these will be sprite groups that contain all the pellet or block sprites.

The next step is to loop through the layout of the level and create the necessary sprites at each position. We first calculate the current blocks center point, just to make the code a bit cleaner, and then we check to see what the current position in the layout is. It it’s a BLOCK position we create new block sprite and add it to the block_sprites group. If it’s a PELLET position, we create a new pellet sprite and add it to the pellet_sprites group.

The only sprite that we treat a bit differently is the snake sprite, since we will only have one snake per level, we only create one. And if the level designer mistakenly added two snakes, we will use the second snake as the snakes position.

You’ll also notice that both the pellet and the block sprites are simply basicSprites.Sprite’s since they don’t really do anything else besides get drawn to the screen.

Now we simply have to adjust our MainLoop() function to take into account all of the changes that we have made to our game:

def MainLoop(self):
        """This is the Main Loop of the Game"""
        
        """Load All of our Sprites"""
        self.LoadSprites();
        
        """Create the background"""
        self.background = pygame.Surface(self.screen.get_size())
        self.background = self.background.convert()
        self.background.fill((0,0,0))
        """Draw the blocks onto the background, since they only need to be 
        drawn once"""
        self.block_sprites.draw(self.background)
        
        while 1:
            for event in pygame.event.get():
                if event.type == pygame.QUIT: 
                    sys.exit()
                elif event.type == KEYDOWN:
                    if ((event.key == K_RIGHT)
                    or (event.key == K_LEFT)
                    or (event.key == K_UP)
                    or (event.key == K_DOWN)):
                        self.snake.MoveKeyDown(event.key)
                elif event.type == KEYUP:
                    if ((event.key == K_RIGHT)
                    or (event.key == K_LEFT)
                    or (event.key == K_UP)
                    or (event.key == K_DOWN)):
                        self.snake.MoveKeyUp(event.key)
            """Update the snake sprite"""        
            self.snake_sprites.update(self.block_sprites)
                        
            """Check for a snake collision/pellet collision"""
            lstCols = pygame.sprite.spritecollide(self.snake
                                                 , self.pellet_sprites
                                                 , True)
            """Update the amount of pellets eaten"""
            self.snake.pellets = self.snake.pellets + len(lstCols)
                        
            """Do the Drawing"""               
            self.screen.blit(self.background, (0, 0))     
            if pygame.font:
                font = pygame.font.Font(None, 36)
                text = font.render("Pellets %s" % self.snake.pellets
                                    , 1, (255, 0, 0))
                textpos = text.get_rect(centerx=self.background.get_width()/2)
                self.screen.blit(text, textpos)
               
            self.pellet_sprites.draw(self.screen)
            self.snake_sprites.draw(self.screen)
            
            pygame.display.flip()

It’s a lot of code, but it’s not really that different then the code was in part one. An obvious difference is the way in which we adjust the snakes position, using the MoveKeyUp, MoveKeyDown, and update function. Everything else is basically identical to the way that it was in part one.

The only other difference is the fact that we have to draw the block sprites. Since the blocks are static and will never be updated, we are going to draw then to the background surface. This will save us a bit of drawing time when we draw.

When we run the code now we are greeted with the simple PyMan level that we saw at the beginning of this post. Now this isn’t close to being a finished game as there is no level two, and there are no bad guys, but our simple game it starting to take shape.

In the next part of this pyGame series I hope to add the bad guys to the level and the idea of the super pellets. If you want to download the code for this post you can do so here.

If you like this post remember to digg it

Prerequisites

In order to follow along with this tutorial you will need Python 2.4 and PyGame 1.7.0+ installed. Since I’m doing this all on a Mac and Python 2.4.2 is not available from MacPython or any other site as a disk image I decided to install from source.

If you are try to build Python on a Mac as well you should probably install into the /Library/Frameworks path as explained by this site.

Basically once you have downloaded the source from python.org unpack the tar ball as follows:

tar -zxvf Python-2.4.2.tgz

Once that has finished change to the Python-2.4.2 directory that was just created and install it by issuing the following commands:

./configure --enable-framework
make
sudo make frameworkinstall


For Windows or Linux you should be able to install easily given the instructions on the Python site.

This will install Python in the /Library/Frameworks path, and create a symlink to the python executable in /use/local/bin, which is not part of the PATH environment variable on new OS X builds, so you will probably want to add it:

export PATH=/usr/local/bin:$PATH

Part One

The full source of this tutorial can be downloaded here.

So let’s actually start creating this game using PyGame. For our snake image in the game I’m going to use the snake to the left for now. As you can see I’m not artist, but I was able to install the gimp on my Mac and get that image to a point that I think is relatively acceptable. If anyone out there has any graphics skills and can whip me up a better looking python in a 64×64 png I’d gladly use it!

So the first thing we are going to do is create a new PyDev project in Eclipse. I’m going to use Python 2.4 for this project because it is the version that is compatible with my PyGame Installation.

Then I’m going to create a new file called PyMan.py, this will be the main file of our game for now. The architecture may change as I go through this and discover better ways to use the files in my projects but for now this will work as a main file. In the directory that I create my project I will also create a subfolder entitled “data” and in that subfolder I will have another folder entitled “images” where I will store the above snake.png image.

Note: A lot of the information in this post was taken from the Pete Shinner’s great Line by Line Chimp and Python Pygame Introduction tutorials.

Now the first thing that we are going to have to do is import the libraries that we are going to need, we’ll also warn the user if the font or sound mixers are not available:

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

if not pygame.font: print 'Warning, fonts disabled'
if not pygame.mixer: print 'Warning, sound disabled'

Then we’re going to create a class called PyManMain, this is going to be the main class of our game, it will handle all of the main functions in our game, things like the game loop, the screen creation, and keeping track of all of our sprites:

class PyManMain:
    """The Main PyMan Class - This class handles the main 
    initialization and creating of the Game."""
    
    def __init__(self, width=640,height=480):
        """Initialize"""
        """Initialize PyGame"""
        pygame.init()
        """Set the window Size"""
        self.width = width
        self.height = height
        """Create the Screen"""
        self.screen = pygame.display.set_mode((self.width
                                               , self.height))

As you can see our __init__ function takes two optional parameters height and width, this will be the height and the width of the screen that we create. The __init__ function basically initializes pygame (pygame.init()) and then creates our main screen using the pygame.display.set_mode function.

So far so good! The next thing that we are going to need is a game loop, this is the loop that will process all of the events that PyGame sends our way. To do that, we’re going to add a function to our PyManMain class called MainLoop:

def MainLoop(self):
    """This is the Main Loop of the Game"""
    while 1:
        for event in pygame.event.get():
            if event.type == pygame.QUIT: 
                sys.exit()

We’ll also add the code to our class that will start out game:

if __name__ == "__main__":
    MainWindow = PyManMain()
    MainWindow.MainLoop()

If you run this now you will be with a very uninspiring black screen. It may not be much but for the amount of code that we’ve written it’s pretty good.

The next thing that we need to create is out snake sprite. We are going to wrap our snake sprite in it’s own class called snake (of course) and it will be based off of the pygame.sprite.Sprite class. If you want to read more about PyGames sprite and group classes you should read piman’s great sprite tutorial:

class Snake(pygame.sprite.Sprite):
    """This is our snake that will move around the screen"""
    
    def __init__(self):
        pygame.sprite.Sprite.__init__(self) 
        self.image, self.rect = load_image('snake.png',-1)
        self.pellets = 0

As you can see the Snake class really isn’t doing much besides initializing the Sprite base class and loading the snake image. It also sets pellets to zero, this variable isn’t used yet but it is the number of pellets that our snake has eaten.

You’ll notice that we use load_image to load our snake image. This function is taken from the Line by Line Chimp tutorial. I created a new file for my project called helpers.py which will contain all helper functions. I put load_image in this file and added the following to the top of PyMan.py:

from helpers import *

Now we have to create an instance of our snake sprite and display it. To do this I created another function in the PyManMain class called LoadSprites, this function will take care of loading all of our sprites:

def LoadSprites(self):
    """Load the sprites that we need"""
    self.snake = Snake()
    self.snake_sprites = pygame.sprite.RenderPlain((self.snake))

This function creates the sprite (self.snake = Snake) and then creates a group that contains our snake sprite (self.snake_sprites = pygame.sprite.RenderPlain((self.snake))).

We are also going to have to make some changes to the MainLoop function, we are going to have to load all of our sprites before we enter the while loop:

"""Load All of our Sprites"""
self.LoadSprites();

Then after our event for loop but within the while loop we need to tell PyGame to draw our sprit:

self.snake_sprites.draw(self.screen)
pygame.display.flip()

Now we’re getting somewhere! We’ve got our little PyMan snake displaying himself in the top left corner of our screen. Not too bad.

The next thing that we’re going to want to do is create and display all of our pellets, this isn’t very difficult if you understood the snake sprite above you’ll understand this:

class Pellet(pygame.sprite.Sprite):
        
    def __init__(self, rect=None):
        pygame.sprite.Sprite.__init__(self) 
        self.image, self.rect = load_image('pellet.png',-1)
        if rect != None:
            self.rect = rect

The only difference you’ll see in the pellet class is the fact that we have an optional rect parameter, which lets us place the pellet where ever we want. The pellets I’ve created aren’t the best pellets that I’ve ever seen but just like the snake.png they’ll do for this example.

We then need to load the pellet sprites in our LoadSprites function:

"""figure out how many pellets we can display"""
nNumHorizontal = int(self.width/64)
nNumVertical = int(self.height/64)       
"""Create the Pellet group"""
self.pellet_sprites = pygame.sprite.Group()
"""Create all of the pellets and add them to the 
pellet_sprites group"""
for x in range(nNumHorizontal):
    for y in range(nNumVertical):
        self.pellet_sprites.add(Pellet(pygame.Rect(x*64, y*64, 64, 64)))

Then we have to draw the pellets in out MainLoop:

self.pellet_sprites.draw(self.screen)
self.snake_sprites.draw(self.screen)
pygame.display.flip()

Now it’s time to make that snake move, to do so we’re going to have to look at the event loop in our MainLoop. ( for event in pygame.event.get():) What we are going to do is move the snake around when the arrow keys are pressed. To do that we are going to check to see if the event is a KEYDOWN event, and if it is a key down event whether the key being pressed is one of the arrow keys:

if event.type == pygame.QUIT: 
    sys.exit()
elif event.type == KEYDOWN:
    if ((event.key == K_RIGHT)
    or (event.key == K_LEFT)
    or (event.key == K_UP)
    or (event.key == K_DOWN)):
        self.snake.move(event.key)

Then we have to add a move function to our snake class that will actually move our snake:

def move(self, key):
    """Move your self in one of the 4 directions according to key"""
    """Key is the pyGame define for either up,down,left, or right key
    we will adjust ourselves in that direction"""
    xMove = 0;
    yMove = 0;
    
    if (key == K_RIGHT):
        xMove = self.x_dist
    elif (key == K_LEFT):
        xMove = -self.x_dist
    elif (key == K_UP):
        yMove = -self.y_dist
    elif (key == K_DOWN):
        yMove = self.y_dist
    self.rect.move_ip(xMove,yMove);

You’ll notice that the move function references self.x_dist and self.y_dist, these are basically two integers that I set in the snake’s __init__ function, they are the number of pixels that we want the snake to move in the x or y direction. I set mine to 5.

To move the snake we adjust it’s rect so that the next time it is displayed it will be drawn in a different direction. To do that we call the rect.move_ip function with the amount of pixels in the x and y directions to move.

Now we are going to have to add some collision detection to make our snake eat our pellets. Thankfully the spirt and group classes have built in collision detection that we are able to use:

"""Check for collision"""
lstCols = pygame.sprite.spritecollide(self.snake
                                     , self.pellet_sprites
                                     , True)
"""Update the amount of pellets eaten"""
self.snake.pellets = self.snake.pellets + len(lstCols)

We use the pygame.sprite.spritecollide function to see if our snake sprite collided with any of the pellet sprites. If they did we kill which ever pellet that was hit by passing True as the third parameter. pygame.sprite.spritecollide basically goes through all of the sprites in the group passes and sees if the sprites rect intersects with the sprit passed in as parameter one.

pygame.sprite.spritecollide also returns a list of all the sprites that were collided by our snake, so we use that to update the number of pellets that we have eaten.

The last thing that we our going to do in this tutorial is display the number of pellets that we have eaten to the user:

if pygame.font:
    font = pygame.font.Font(None, 36)
    text = font.render("Pellets %s" % self.snake.pellets
                        , 1, (255, 0, 0))
    textpos = text.get_rect(centerx=self.width/2)
    self.screen.blit(text, textpos)

This code is taken from the line by line chimp example with very few changes. Instead of telling the user to hit the chimp for cash, we’re telling them how many pellets that the snake has eaten so far. We need to put the code right right before we draw our sprites in the game loop.

That’s about it for this example, there is a bit of code in the finished “product” that I didn’t discuss but if you download the full source it the new code should be pretty self explanatory. Now this isn’t a full example by any means and probably isn’t something that you’d really want to base any game off of, but it does give you a pretty basic idea about what is required to create a game in using Python and PyGame.

If you are really interested in creating a game I’d suggest you download the full source and play around with it a bit. I’m also suggest (insist?) that you read the documentation and tutorials provided for you on the main PyGame site, if it wasn’t for them I would have been unable to write this simple tutorial.

Whew, that was a lot a typing, it’s time for me to go make some dinner and have a glass of wine.

Useful links:

If you like this post remember to digg it.

Note: Whew! Many thanks to James for finding the google cahce for me! I looked for it when I first deleted it but couldn’t fine it. Much appreciated!

Here are some alternate images that were sent to me by a kind reader named Jordan:

Well as someone who programs a lot and likes using computers creating a viedo game is always something that I’ve wanted to do. In the past I spent a lot of time learning OpenGL and actually went quite far in the creation of a simple/not-so-simple game. The game was put on hold indefinitely once real life responsibilities started to encroach on my evenings. Since then I’ve longed to try again.

Every since I heard about PyGame from import this, I thought it looked promising. It’s cross platform, which is something that is very important to me as a developer, and it lets me stratch my Python skills which is the whole reason I have this website. Here is some of the about information from the PyGame website:

Pygame is a set of Python modules designed for writing games. It is written on top of the excellent SDL library. This allows you to create fully featured games and multimedia programs in the python language. Pygame is highly portable and runs on nearly every platform and operating system.

So I decided to test my skills and create a simple game using PyGame. My first instinct was to create a cool game, but I soom realized that creating cool game right away probably wasn’t going to be the easiest thing to do so I decided to try something really simple and went with the idea of a PacMan clone, which I decided to call PyMan.

Now I assume that there have been many PacMan clones written using PyGame, but I’m honestly not trying to copy them or steal their thunder, I’m simply trying to learn how PyGame works.

The first thing that you should do is visit the PyGame site and read some of their documentation and tutorials. So I’m going to assume that you have a limited understanding of what PyGame is and how to program in Python, not too much becuase I don’t, but still a little bit.

Since this project is probably going to be a bit more complicated I’m going to use Eclipse with the PyDev plugin. I’m also going to use the gimp for all of my graphics, since it’s the only graphics program that I know how to use, now I just need to figure out how to install it on OS X.