In-depth game example

This tutorial will walk you through the steps of writing a simple Asteroids clone. It is assumed that the reader is familiar with writing and running Python programs. This is not a programming tutorial, but it should hopefully be clear enough to follow even if you’re a beginner. If you get stuck, first have a look at the relevant sections of the programming guide. The full source code can also be found in the examples/game/ folder of the pyglet source directory, which you can follow along with. If anything is still not clear, let us know!

Basic graphics

Lets begin! The first version of our game will simply show a score of zero, a label showing the name of the program, three randomly placed asteroids, and the player’s ship. Nothing will move.

Setting up

First things first, make sure you have pyglet installed. Then, we will set up the folder structure for our project. Since this example game is written in stages, we will have several version folders at various stages of development. We will also have a shared resource folder with the images, called ‘resources,’ outside of the example folders. Each version folder contains a Python file called which runs the game, as well as a sub-folder named game where we will place additional modules; this is where most of the logic will be. Your folder structure should look like this:

        (images go here)

Getting a window

To set up a window, simply import pyglet, create a new instance of pyglet.window.Window, and call

import pyglet
game_window = pyglet.window.Window(800, 600)

if __name__ == '__main__':

If you run the code above, you should see a window full of junk that goes away when you press Esc. (What you are seeing is raw uninitialized graphics memory).

Loading and displaying an image

Since our images will reside in a directory other than the example’s root directory, we need to tell pyglet where to find them:

import pyglet
pyglet.resource.path = ['../resources']

pyglet’s pyglet.resource module takes all of the hard work out of finding and loading game resources such as images, sounds, etc.. All that you need to do is tell it where to look, and reindex it. In this example game, the resource path starts with ../ because the resources folder is on the same level as the version1 folder. If we left it off, pyglet would look inside version1/ for the resources/ folder.

Now that pyglet’s resource module is initialized, we can easily load the images with the image() function of the resource module:

player_image = pyglet.resource.image("player.png")
bullet_image = pyglet.resource.image("bullet.png")
asteroid_image = pyglet.resource.image("asteroid.png")

Centering the images

Pyglet will draw and position all images from their lower left corner by default. We don’t want this behavior for our images, which need to rotate around their centers. All we have to do to achieve this is to set their anchor points. Lets create a function to simplify this:

def center_image(image):
    """Sets an image's anchor point to its center"""
    image.anchor_x = image.width // 2
    image.anchor_y = image.height // 2

Now we can just call center_image() on all of our loaded images:


Remember that the center_image() function must be defined before it can be called at the module level. Also, note that zero degrees points directly to the right in pyglet, so the images are all drawn with their front pointing to the right.

To access the images from, we need to use something like from game import resources, which we’ll get into in the next section.

Initializing objects

We want to put some labels at the top of the window to give the player some information about the score and the current difficulty level. Eventually, we will have a score display, the name of the level, and a row of icons representing the number of remaining lives.

Making the labels

To make a text label in pyglet, just initialize a pyglet.text.Label object:

score_label = pyglet.text.Label(text="Score: 0", x=10, y=460)
level_label = pyglet.text.Label(text="My Amazing Game",
                            x=game_window.width//2, y=game_window.height//2, anchor_x='center')

Notice that the second label is centered using the anchor_x attribute.

Drawing the labels

We want pyglet to run some specific code whenever the window is drawn. An on_draw() event is dispatched to the window to give it a chance to redraw its contents. pyglet provides several ways to attach event handlers to objects; a simple way is to use a decorator:

def on_draw():
    # draw things here

The @game_window.event decorator lets the Window instance know that our on_draw() function is an event handler. The on_draw() event is fired whenever - you guessed it - the window needs to be redrawn. Other events include on_mouse_press() and on_key_press().

Now we can fill the method with the functions necessary to draw our labels. Before we draw anything, we should clear the screen. After that, we can simply call each object’s draw() function:

def on_draw():


Now when you run, you should get a window with a score of zero in the upper left corner and a centered label reading “My Amazing Game” at the top of the screen.

Making the player and asteroid sprites

The player should be an instance or subclass of pyglet.sprite.Sprite, like so:

from game import resources
player_ship = pyglet.sprite.Sprite(img=resources.player_image, x=400, y=300)

To get the player to draw on the screen, add a line to on_draw():

def on_draw():

Loading the asteroids is a little more complicated, since we’ll need to place more than one at random locations that don’t immediately collide with the player. Let’s put the loading code in a new game submodule called

import pyglet
import random
from . import resources

def asteroids(num_asteroids):
    asteroids = []
    for i in range(num_asteroids):
        asteroid_x = random.randint(0, 800)
        asteroid_y = random.randint(0, 600)
        new_asteroid = pyglet.sprite.Sprite(img=resources.asteroid_image,
                                            x=asteroid_x, y=asteroid_y)
        new_asteroid.rotation = random.randint(0, 360)
    return asteroids

All we are doing here is making a few new sprites with random positions. There’s still a problem, though - an asteroid might randomly be placed exactly where the player is, causing immediate death. To fix this issue, we’ll need to be able to tell how far away new asteroids are from the player. Here is a simple function to calculate that distance:

import math
def distance(point_1=(0, 0), point_2=(0, 0)):
    """Returns the distance between two points"""
    return math.sqrt((point_1[0] - point_2[0]) ** 2 + (point_1[1] - point_2[1]) ** 2)

To check new asteroids against the player’s position, we need to pass the player’s position into the asteroids() function and keep regenerating new coordinates until the asteroid is far enough away. pyglet sprites keep track of their position both as a tuple (Sprite.position) and as x, y, and z attributes (Sprite.x, Sprite.y, Sprite.z). To keep our code short, we’ll just pass the position tuple into the function. We’re not using the z value, so we just use a throwaway variable for that:

def asteroids(num_asteroids, player_position):
    asteroids = []
    for i in range(num_asteroids):
        asteroid_x, asteroid_y, _ = player_position
        while distance((asteroid_x, asteroid_y), player_position) < 100:
            asteroid_x = random.randint(0, 800)
            asteroid_y = random.randint(0, 600)
        new_asteroid = pyglet.sprite.Sprite(
            img=resources.asteroid_image, x=asteroid_x, y=asteroid_y)
        new_asteroid.rotation = random.randint(0, 360)
    return asteroids

For each asteroid, it chooses random positions until it finds one away from the player, creates the sprite, and gives it a random rotation. Each asteroid is appended to a list, which is returned.

Now you can load three asteroids like this:

from game import resources, load
asteroids = load.asteroids(3, player_ship.position)

The asteroids variable now contains a list of sprites. Drawing them on the screen is as simple as it was for the player’s ship - just call their draw() methods:

def on_draw():
    for asteroid in asteroids:

This wraps up the first section. Your “game” doesn’t do much of anything yet, but we’ll get to that in the following sections. You may want to look over the examples/game/version1 folder in the pyglet source to review what we’ve done, and to find a functional copy.

Basic motion

In the second version of the example, we’ll introduce a simpler, faster way to draw all of the game objects, as well as add row of icons indicating the number of lives left. We’ll also write some code to make the player and the asteroids obey the laws of physics.

Drawing with batches

Calling each object’s draw() method manually can become cumbersome and tedious if there are many different kinds of objects. It’s also very inefficient if you need to draw a large number of objects. The pyglet class simplifies drawing by letting you draw all your objects with a single function call. All you need to do is create a batch, pass it into each object you want to draw, and call the batch’s draw() method.

To create a new batch, simply create an instance of

main_batch =

To make an object a member of a batch, just pass the batch into its constructor as the batch keyword argument:

score_label = pyglet.text.Label(text="Score: 0", x=10, y=575, batch=main_batch)

Add the batch keyword argument to each graphical object created in

To use the batch with the asteroid sprites, we’ll need to pass the batch into the game.load.asteroid() function, then just add it as a keyword argument to each new sprite. Update the function:

def asteroids(num_asteroids, player_position, batch=None):
    new_asteroid = pyglet.sprite.Sprite(img=resources.asteroid_image,
                                        x=asteroid_x, y=asteroid_y,

And update the place where it’s called:

asteroids = load.asteroids(3, player_ship.position, main_batch)

Now you can replace those five lines of draw() calls with just one:


Now when you run, it should look exactly the same.

Displaying little ship icons

To show how many lives the player has left, we’ll need to draw a little row of icons in the upper right corner of the screen. Since we’ll be making more than one using the same template, let’s create a function called player_lives() in the load module to generate them. The icons should look the same as the player’s ship. We could create a scaled version using an image editor, or we could just let pyglet do the scaling. I don’t know about you, but I prefer the option that requires less work.

The function for creating the icons is almost exactly the same as the one for creating asteroids. For each icon we just create a sprite, give it a position and scale, and append it to the return list:

def player_lives(num_icons, batch=None):
    player_lives = []
    for i in range(num_icons):
        new_sprite = pyglet.sprite.Sprite(img=resources.player_image,
                                          x=785-i*30, y=585, batch=batch)
        new_sprite.scale = 0.5
    return player_lives

The player icon is 50x50 pixels, so half that size will be 25x25. We want to put a little bit of space between each icon, so we create them at 30-pixel intervals starting from the right side of the screen and moving to the left. Note that like the asteroids() function, player_lives() takes a batch argument.

Making things move

The game would be pretty boring if nothing on the screen ever moved. To achieve motion, we’ll need to write our own set of classes to handle frame-by-frame movement calculations. We’ll also need to write a Player class to respond to keyboard input.

Creating the basic motion class

Since every visible object is represented by at least one Sprite, we may as well make our basic motion class a subclass of pyglet.sprite.Sprite. Another approach would be to have our class have a sprite attribute.

Create a new game submodule called and declare a PhysicalObject class. The only new attributes we’ll be adding will store the object’s velocity, so the constructor will be simple:

class PhysicalObject(pyglet.sprite.Sprite):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.velocity_x, self.velocity_y = 0.0, 0.0

Each object will need to be updated every frame, so let’s write an update() method:

def update(self, dt):
    self.x += self.velocity_x * dt
    self.y += self.velocity_y * dt

What’s dt? It’s the “delta time”, or “time step”. Game frames are not instantaneous, and they don’t always take equal amounts of time to draw. If you’ve ever tried to play a modern game on an old machine, you know that frame rates can jump all over the place. There are a number of ways to deal with this problem, the simplest one being to just multiply all time-sensitive operations by dt. I’ll show you how this value is calculated later.

If we give objects a velocity and just let them go, they will fly off the screen before long. Since we’re making an Asteroids clone, we would rather they just wrapped around the screen. Here is a simple function that accomplishes the goal:

def check_bounds(self):
    min_x = -self.image.width / 2
    min_y = -self.image.height / 2
    max_x = 800 + self.image.width / 2
    max_y = 600 + self.image.height / 2
    if self.x < min_x:
        self.x = max_x
    elif self.x > max_x:
        self.x = min_x
    if self.y < min_y:
        self.y = max_y
    elif self.y > max_y:
        self.y = min_y

As you can see, it simply checks to see if objects are no longer visible on the screen, and if so, it moves them to the other side of the screen. To make every PhysicalObject use this behavior, add a call to self.check_bounds() at the end of update().

To make the asteroids use our new motion code, just import the physicalobject module and change the new_asteroid = … line to create a new PhysicalObject instead of a Sprite. You’ll also want to give them a random initial velocity. Here is the new, improved load.asteroids() function:

def asteroids(num_asteroids, player_position, batch=None):
    new_asteroid = physicalobject.PhysicalObject(...)
    new_asteroid.rotation = random.randint(0, 360)
    new_asteroid.velocity_x = random.random()*40
    new_asteroid.velocity_y = random.random()*40

Writing the game update function

To call each object’s update() method every frame, we first need to have a list of those objects. For now, we can just declare it after setting up all the other objects:

game_objects = [player_ship] + asteroids

Now we can write a simple function to iterate over the list:

def update(dt):
    for obj in game_objects:

The update() function takes a dt parameter because it is still not the source of the actual time step.

Calling the update() function

We need to update the objects at least once per frame. What’s a frame? Well, most screens have a maximum refresh rate of 60 hertz. If we set our loop to run at exactly 60 hertz, though, the motion will look a little jerky because it won’t match the screen exactly. Instead, we can have it update twice as fast, 120 times per second, to get smooth animation.

The best way to call a function 120 times per second is to ask pyglet to do it. The pyglet.clock module contains a number of ways to call functions periodically or at some specified time in the future. The one we want is pyglet.clock.schedule_interval():

pyglet.clock.schedule_interval(update, 1/120.0)

Putting this line above in the if __name__ == ‘__main__’ block tells pyglet to call update() 120 times per second. Pyglet will pass in the elapsed time, i.e. dt, as the only parameter.

Now when you run, you should see your formerly static asteroids drifting serenely across the screen, reappearing on the other side when they slide off the edge.

Writing the Player class

In addition to obeying the basic laws of physics, the player object needs to respond to keyboard input. Start by creating a game.player module, importing the appropriate modules, and subclassing PhysicalObject:

from . import physicalobject, resources

class Player(physicalobject.PhysicalObject):

    def __init__(self, *args, **kwargs):
        super().__init__(img=resources.player_image, *args, **kwargs)

So far, the only difference between a Player and a PhysicalObject is that a Player will always have the same image. But Player objects need a couple more attributes. Since the ship will always thrust with the same force in whatever direction it points, we’ll need to define a constant for the magnitude of that force. We should also define a constant for the ship’s rotation speed:

self.thrust = 300.0
self.rotate_speed = 200.0

Now we need to get the class to respond to user input. Pyglet uses an event-based approach to input, sending key press and key release events to registered event handlers. But we want to use a polling approach in this example, checking periodically if a key is down. One way to accomplish that is to maintain a dictionary of keys. First, we need to initialize the dictionary in the constructor:

self.keys = dict(left=False, right=False, up=False)

Then we need to write two methods, on_key_press() and on_key_release(). When pyglet checks a new event handler, it looks for these two methods, among others:

import math
from pyglet.window import key
from . import physicalobject, resources

class Player(physicalobject.PhysicalObject)

    def on_key_press(self, symbol, modifiers):
        if symbol == key.UP:
            self.keys['up'] = True
        elif symbol == key.LEFT:
            self.keys['left'] = True
        elif symbol == key.RIGHT:
            self.keys['right'] = True

    def on_key_release(self, symbol, modifiers):
        if symbol == key.UP:
            self.keys['up'] = False
        elif symbol == key.LEFT:
            self.keys['left'] = False
        elif symbol == key.RIGHT:
            self.keys['right'] = False

That looks pretty cumbersome. There’s a better way to do it which we’ll see later, but for now, this version serves as a good demonstration of pyglet’s event system.

The last thing we need to do is write the update() method. It follows the same behavior as a PhysicalObject plus a little extra, so we’ll need to call PhysicalObject’s update() method and then respond to input:

def update(self, dt):
    super(Player, self).update(dt)

    if self.keys['left']:
        self.rotation -= self.rotate_speed * dt
    if self.keys['right']:
        self.rotation += self.rotate_speed * dt

Pretty simple so far. To rotate the player, we just add the rotation speed to the angle, multiplied by dt to account for time. Note that Sprite objects’ rotation attributes are in degrees, with clockwise as the positive direction. This means that you need to call math.degrees() or math.radians() and make the result negative whenever you use Python’s built-in math functions with the Sprite class, since those functions use radians instead of degrees, and their positive direction is counter-clockwise. The code to make the ship thrust forward uses an example of such a conversion:

if self.keys['up']:
    angle_radians = -math.radians(self.rotation)
    force_x = math.cos(angle_radians) * self.thrust * dt
    force_y = math.sin(angle_radians) * self.thrust * dt
    self.velocity_x += force_x
    self.velocity_y += force_y

First, we convert the angle to radians so that math.cos() and math.sin() will get the correct values. Then we apply some simple physics to modify the ship’s X and Y velocity components and push the ship in the right direction.

We now have a complete Player class. If we add it to the game and tell pyglet that it’s an event handler, we should be good to go.

Integrating the player class

The first thing we need to do is make player_ship an instance of Player:

from game import player
player_ship = player.Player(x=400, y=300, batch=main_batch)

Now we need to tell pyglet that player_ship is an event handler. To do that, we need to push it onto the event stack with game_window.push_handlers():


That’s it! Now you should be able to run the game and move the player with the arrow keys.

Giving the player something to do

In any good game, there needs to be something working against the player. In the case of Asteroids, it’s the threat of collision with, well, an asteroid. Collision detection requires a lot of infrastructure in the code, so this section will focus on making it work. We’ll also clean up the player class and show some visual feedback for thrusting.

Simplifying player input

Right now, the Player class handles all of its own keyboard events. It spends 13 lines of code doing nothing but setting boolean values in a dictionary. One would think that there would be a better way, and there is: pyglet.window.key.KeyStateHandler. This handy class automatically does what we have been doing manually: it tracks the state of every key on the keyboard.

To start using it, we need to initialize it and push it onto the event stack instead of the Player class. First, let’s add it to Player‘s constructor:

self.key_handler = key.KeyStateHandler()

We also need to push the key_handler object onto the event stack. Keep pushing the player_ship object in addition to its key handler, because we’ll need it to keep handling key press and release events later:


Since Player now relies on key_handler to read the keyboard, we need to change the update() method to use it. The only changes are in the if conditions:

if self.key_handler[key.LEFT]:
if self.key_handler[key.RIGHT]:
if self.key_handler[key.UP]:

Now we can remove the on_key_press() and on_key_release() methods from the class. It’s just that simple. If you need to see a list of key constants, you can check the API documentation under pyglet.window.key.

Adding an engine flame

Without visual feedback, it can be difficult to tell if the ship is actually thrusting forward or not, especially for an observer just watching someone else play the game. One way to provide visual feedback is to show an engine flame behind the player while the player is thrusting.

Loading the flame image

The player will now be made of two sprites. There’s nothing preventing us from letting a Sprite own another Sprite, so we’ll just give Player an engine_sprite attribute and update it every frame. For our purposes, this approach will be the simplest and most scalable.

To make the flame draw in the correct position, we could either do some complicated math every frame, or we could just move the image’s anchor point. First, load the image in

engine_image = pyglet.resource.image("engine_flame.png")

To get the flame to draw behind the player, we need to move the flame image’s center of rotation to the right, past the end of the image. To do that, we just set its anchor_x and anchor_y attributes:

engine_image.anchor_x = engine_image.width * 1.5
engine_image.anchor_y = engine_image.height / 2

Now the image is ready to be used by the player class. If you’re still confused about anchor points, experiment with the values for engine_image’s anchor point when you finish this section.

Creating and drawing the flame

The engine sprite needs to be initialized with all the same arguments as Player, except that it needs a different image and must be initially invisible. The code for creating it belongs in Player.__init__() and is very straightforward:

self.engine_sprite = pyglet.sprite.Sprite(img=resources.engine_image, *args, **kwargs)
self.engine_sprite.visible = False

To make the engine sprite appear only while the player is thrusting, we need to add some logic to the if self.key_handler[key.UP] block in the update() method:

if self.key_handler[key.UP]:
    self.engine_sprite.visible = True
    self.engine_sprite.visible = False

To make the sprite appear at the player’s position, we also need to update its position and rotation attributes:

if self.key_handler[key.UP]:
    self.engine_sprite.rotation = self.rotation
    self.engine_sprite.x = self.x
    self.engine_sprite.y = self.y
    self.engine_sprite.visible = True
    self.engine_sprite.visible = False

Cleaning up after death

When the player is inevitably smashed to bits by an asteroid, he will disappear from the screen. However, simply removing the Player instance from the game_objects list is not enough for it to be removed from the graphics batch. To do that, we need to call its delete() method. Normally a Sprite‘s own delete() method will work fine without modifications, but our subclass has its own child Sprite (the engine flame) which must also be deleted when the Player instance is deleted. To get both to die gracefully, we must write a simple but slightly enhanced delete() method:

def delete(self):
    super(Player, self).delete()

The Player class is now cleaned up and ready to go.

Checking For collisions

To make objects disappear from the screen, we’ll need to manipulate the game objects list. Every object will need to check every other object’s position against its own, and each object will have to decide whether or not it should be removed from the list. The game loop will then check for dead objects and remove them from the list.

Checking all object pairs

We need to check every object against every other object. The simplest method is to use nested loops. This method will be inefficient for a large number of objects, but it will work for our purposes. We can use one easy optimization and avoid checking the same pair of objects twice. Here’s the setup for the loops, which belongs in update(). It simply iterates over all object pairs without doing anything:

for i in range(len(game_objects)):
    for j in range(i+1, len(game_objects)):
        obj_1 = game_objects[i]
        obj_2 = game_objects[j]

We’ll need a way to check if an object has already been killed. We could go over to PhysicalObject right now and put it in, but let’s keep working on the game loop and implement the method later. For now, we’ll just assume that everything in game_objects has a dead attribute which will be False until the class sets it to True, at which point it will be ignored and eventually removed from the list.

To perform the actual check, we’ll also need to call two more methods that don’t exist yet. One method will determine if the two objects actually collide, and the other method will give each object an opportunity to respond to the collision. The checking code itself is easy to understand, so I won’t bother you with further explanations:

if not obj_1.dead and not obj_2.dead:
    if obj_1.collides_with(obj_2):

Now all that remains is for us to go through the list and remove dead objects:

for to_remove in [obj for obj in game_objects if obj.dead]:

As you can see, it simply calls the object’s delete() method to remove it from any batches, then it removes it from the list. If you haven’t used list comprehensions much, the above code might look like it’s removing objects from the list while traversing it. Fortunately, the list comprehension is evaluated before the loop actually runs, so there should be no problems.

Implementing the collision functions

We need to add three things to the PhysicalObject class: the dead attribute, the collides_with() method, and the handle_collision_with() method. The collides_with() method will need to use the distance() function, so let’s start by moving that function into its own submodule of game, called

import pyglet, math

def distance(point_1=(0, 0), point_2=(0, 0)):
    return math.sqrt(
        (point_1[0] - point_2[0]) ** 2 +
        (point_1[1] - point_2[1]) ** 2)

Remember to call from util import distance in Now we can write PhysicalObject.collides_with() without duplicating code:

def collides_with(self, other_object):
    collision_distance = self.image.width/2 + other_object.image.width/2
    actual_distance = util.distance(self.position, other_object.position)

    return (actual_distance <= collision_distance)

The collision handler function is even simpler, since for now we just want every object to die as soon as it touches another object:

def handle_collision_with(self, other_object):
    self.dead = True

One last thing: set self.dead = False in PhysicalObject.__init__().

And that’s it! You should be able to zip around the screen, engine blazing away. If you hit something, both you and the thing you collided with should disappear from the screen. There’s still no game, but we are clearly making progress.

Collision response

In this section, we’ll add bullets. This new feature will require us to start adding things to the game_objects list during the game, as well as have objects check each others’ types to make a decision about whether or not they should die.

Adding objects during play


We handled object removal with a boolean flag. Adding objects will be a little bit more complicated. For one thing, an object can’t just say “Add me to the list!” It has to come from somewhere. For another thing, an object might want to add more than one other object at a time.

There are a few ways to solve this problem. To avoid circular references, keep our constructors nice and short, and avoid adding extra modules, we’ll have each object keep a list of new child objects to be added to game_objects. This approach will make it easy for any object in the game to spawn more objects.

Tweaking the game loop

The simplest way to check objects for children and add those children to the list is to add two lines of code to the game_objects loop. We haven’t implemented the new_objects attribute yet, but when we do, it will be a list of objects to add:

for obj in game_objects:
    obj.new_objects = []

Unfortunately, this simple solution is problematic. It’s generally a bad idea to modify a list while iterating over it. The fix is to simply add new objects to a separate list, then add the objects in the separate list to game_objects after we have finished iterating over it.

Declare a to_add list just above the loop and add new objects to it instead. At the very bottom of update(), after the object removal code, add the objects in to_add to game_objects:


to_add = []

for obj in game_objects:
    obj.new_objects = []



Putting the attribute in PhysicalObject

As mentioned before, all we have to do is declare a new_objects attribute in the PhysicalObject class:

def __init__(self, *args, **kwargs):
    self.new_objects = []

To add a new object, all we have to do is put something in new_objects, and the main loop will see it, add it to the game_objects list, and clear new_objects.

Adding bullets

Writing the bullet class

For the most part, bullets act like any other PhysicalObject, but they have two differences, at least in this game: they only collide with some objects, and they disappear from the screen after a couple of seconds to prevent the player from flooding the screen with bullets.

First, make a new submodule of game called and start a simple subclass of PhysicalObject:

import pyglet
from . import physicalobject, resources

class Bullet(physicalobject.PhysicalObject):
    """Bullets fired by the player"""

    def __init__(self, *args, **kwargs):
        super(Bullet, self).__init__(
            resources.bullet_image, *args, **kwargs)

To get bullets to disappear after a time, we could keep track of our own age and lifespan attributes, or we could let pyglet do all the work for us. I don’t know about you, but I prefer the second option. First, we need to write a function to call at the end of a bullet’s life:

def die(self, dt):
    self.dead = True

Now we need to tell pyglet to call it after half a second or so. We can do this as soon as the object is initialized by adding a call to pyglet.clock.schedule_once() to the constructor:

def __init__(self, *args, **kwargs):
    super(Bullet, self).__init__(resources.bullet_image, *args, **kwargs)
    pyglet.clock.schedule_once(self.die, 0.5)

There’s still more work to be done on the Bullet class, but before we do any more work on the class itself, let’s get them on the screen.

Firing bullets

The Player class will be the only class that fires bullets, so let’s open it up, import the bullet module, and add a bullet_speed attribute to its constructor:

from . import bullet

class Player(physicalobject.PhysicalObject):
    def __init__(self, *args, **kwargs):
        super(Player, self).__init__(img=resources.player_image, *args, **kwargs)
        self.bullet_speed = 700.0

Now we can write the code to create a new bullet and send it hurling off into space. First, we need to resurrect the on_key_press() event handler:

def on_key_press(self, symbol, modifiers):
    if symbol == key.SPACE:

The fire() method itself will be a bit more complicated. Most of the calculations will be very similar to the ones for thrusting, but there will be some differences. We’ll need to spawn the bullet out at the nose of the ship, not at its center. We’ll also need to add the ship’s existing velocity to the bullet’s new velocity, or the bullets will end up going slower than the ship if the player gets going fast enough.

As usual, convert to radians and reverse the direction:

def fire(self):
    angle_radians = -math.radians(self.rotation)

Next, calculate the bullet’s position and instantiate it:

ship_radius = self.image.width/2
bullet_x = self.x + math.cos(angle_radians) * ship_radius
bullet_y = self.y + math.sin(angle_radians) * ship_radius
new_bullet = bullet.Bullet(bullet_x, bullet_y, batch=self.batch)

Set its velocity using almost the same equations:

bullet_vx = (
    self.velocity_x +
    math.cos(angle_radians) * self.bullet_speed
bullet_vy = (
    self.velocity_y +
    math.sin(angle_radians) * self.bullet_speed
new_bullet.velocity_x = bullet_vx
new_bullet.velocity_y = bullet_vy

Finally, add it to the new_objects list so that the main loop will pick it up and add it to game_objects:


At this point, you should be able to fire bullets out of the front of your ship. There’s just one problem: as soon as you fire, your ship disappears. You may have noticed earlier that asteroids also disappear when they touch each other. To fix this problem, we’ll need to start customizing each class’s handle_collision_with() method.

Customizing collision behavior

There are five kinds of collisions in the current version of the game: bullet-asteroid, bullet-player, asteroid-player, bullet-bullet, and asteroid-asteroid. There would be many more in a more complex game.

In general, objects of the same type should not be destroyed when they collide, so we can generalize that behavior in PhysicalObject. Other interactions will require a little more work.

Letting twins ignore each other

To let two asteroids or two bullets pass each other by without a word of acknowledgement (or a dramatic explosion), we just need to check if their classes are equal in the PhysicalObject.handle_collision_with() method:

def handle_collision_with(self, other_object):
    if other_object.__class__ == self.__class__:
        self.dead = False
        self.dead = True

There are a few other, more elegant ways to check for object equality in Python, but the above code gets the job done.

Customizing bullet collisions

Since bullet collision behavior can vary so wildly across objects, let’s add a reacts_to_bullets attribute to PhysicalObjects which the Bullet class can check to determine if it should register a collision or not. We should also add an is_bullet attribute so we can check the collision properly from both objects.

(These are not “good” design decisions, but they will work.)

First, initialize the reacts_to_bullets attribute to True in the PhysicalObject constructor:

class PhysicalObject(pyglet.sprite.Sprite):
    def __init__(self, *args, **kwargs):
        self.reacts_to_bullets = True
        self.is_bullet = False

class Bullet(physicalobject.PhysicalObject):
    def __init__(self, *args, **kwargs):
        self.is_bullet = True

Then, insert a bit of code in PhysicalObject.collides_with() to ignore bullets under the right circumstances:

def collides_with(self, other_object):
    if not self.reacts_to_bullets and other_object.is_bullet:
        return False
    if self.is_bullet and not other_object.reacts_to_bullets:
        return False

Finally, set self.reacts_to_bullets = False in Player.__init__(). The Bullet class is completely finished! Now let’s make something happen when a bullet hits an asteroid.

Making asteroids explode

Asteroids is challenging to players because every time you shoot an asteroid, it turns into more asteroids. We need to mimic that behavior if we want our game to be any fun. We’ve already done most of the hard parts. All that remains is to make another subclass of PhysicalObject and write a custom handle_collision_with() method, along with a couple of maintenance tweaks.

Writing the asteroid class

Create a new submodule of game called Write the usual constructor to pass a specific image to the superclass, passing along any other parameters:

import pyglet
from . import resources, physicalobject

class Asteroid(physicalobject.PhysicalObject):
    def __init__(self, *args, **kwargs):
        super(Asteroid, self).__init__(resources.asteroid_image, *args, **kwargs)

Now we need to write a new handle_collision_with() method. It should create a random number of new, smaller asteroids with random velocities. However, it should only do that if it’s big enough. An asteroid should divide at most twice, and if we scale it down by half each time, then an asteroid should stop dividing when it’s 1/4 the size of a new asteroid.

We want to keep the old behavior of ignoring other asteroids, so start the method with a call to the superclass’s method:

def handle_collision_with(self, other_object):
    super(Asteroid, self).handle_collision_with(other_object)

Now we can say that if it’s supposed to die, and it’s big enough, then we should create two or three new asteroids with random rotations and velocities. We should add the old asteroid’s velocity to the new ones to make it look like they come from the same object:

import random

class Asteroid:
    def handle_collision_with(self, other_object):
        super(Asteroid, self).handle_collision_with(other_object)
        if self.dead and self.scale > 0.25:
            num_asteroids = random.randint(2, 3)
            for i in range(num_asteroids):
                new_asteroid = Asteroid(x=self.x, y=self.y, batch=self.batch)
                new_asteroid.rotation = random.randint(0, 360)
                new_asteroid.velocity_x = (random.random() * 70 + self.velocity_x)
                new_asteroid.velocity_y = (random.random() * 70 + self.velocity_y)
                new_asteroid.scale = self.scale * 0.5

While we’re here, let’s add a small graphical touch to the asteroids by making them rotate a little. To do that, we’ll add a rotate_speed attribute and give it a random value. Then we’ll write an update() method to apply that rotation every frame.

Add the attribute in the constructor:

def __init__(self, *args, **kwargs):
    super(Asteroid, self).__init__(resources.asteroid_image, *args, **kwargs)
    self.rotate_speed = random.random() * 100.0 - 50.0

Then write the update() method:

def update(self, dt):
    super(Asteroid, self).update(dt)
    self.rotation += self.rotate_speed * dt

The last thing we need to do is go over to and have the asteroid() method create a new Asteroid instead of a PhysicalObject:

from . import asteroid

def asteroids(num_asteroids, player_position, batch=None):
    for i in range(num_asteroids):
        new_asteroid = asteroid.Asteroid(x=asteroid_x, y=asteroid_y, batch=batch)
    return asteroids

Now we’re looking at something resembling a game. It’s simple, but all of the basics are there.

Next steps

So instead of walking you through a standard refactoring session, I’m going to leave it as an exercise for you to do the following:

* Make the Score counter mean something
* Let the player restart the level if they die
* Implement lives and a “Game Over” screen
* Add particle effects

Good luck! With a little effort, you should be able to figure out most of these things on your own. If you have trouble, join us on the pyglet mailing list.

Also, in addition to this example game, there is yet another Asteroids clone available in the /examples/astraea/ folder in the pyglet source directory. In comparison to this example game excercise we’ve just completed, Astraea is a complete game with a proper menu, score system, and additional graphical effects. No step-by-step documentation is available for Astraea, but the code itself should be easy to understand and illustrates some nice techniques.