Event Hooks¶

Pygame Turbo will automatically pick up and call event hooks that you define. This approach saves you from having to implement the event loop machinery yourself.

Game Loop Hooks¶

A typical game loop looks a bit like this:

while game_has_not_ended():
    process_input()
    update()
    draw()

Input processing is a bit more complicated, but Pygame Turbo allows you to easily define the update() and draw() functions within your game module.

draw()¶

Called by Pygame Turbo when it needs to redraw your game window.

draw() must take no arguments.

Pygame Turbo attempts to work out when the game screen needs to be redrawn to avoid redrawing if nothing has changed. On each step of the game loop it will draw the screen in the following situations:

If you have defined an update() function (see below).
If a clock event fires.
If an input event has been triggered.

One way this can catch you out is if you attempt to modify or animate something within the draw function. For example, this code is wrong: the alien is not guaranteed to continue moving across the screen:

def draw():
    alien.left += 1
    alien.draw()

The correct code uses update() to modify or animate things and draw simply to paint the screen:

def draw():
    alien.draw()

def update():
    alien.left += 1

update() or update(dt)¶

Called by Pygame Turbo to step your game logic. This will be called repeatedly, 60 times a second.

There are two different approaches to writing an update function.

In simple games you can assume a small time step (a fraction of a second) has elapsed between each call to update(). Perhaps you don’t even care how big that time step is: you can just move objects by a fixed number of pixels per frame (or accelerate them by a fixed constant, etc.)

A more advanced approach is to base your movement and physics calculations on the actual amount of time that has elapsed between calls. This can give smoother animation, but the calculations involved can be harder and you must take more care to avoid unpredictable behaviour when the time steps grow larger.

To use a time-based approach, you can change the update function to take a single parameter. If your update function takes an argument, Pygame Turbo will pass it the elapsed time in seconds. You can use this to scale your movement calculations.

Event Handling Hooks¶

Similar to the game loop hooks, your Pygame Turbo program can respond to input events by defining functions with specific names.

Somewhat like in the case of update(), Pygame Turbo will inspect your event handler functions to determine how to call them. So you don’t need to make your handler functions take arguments. For example, Pygame Turbo will be happy to call any of these variations of an on_mouse_down function:

def on_mouse_down():
    print("Mouse button clicked")

def on_mouse_down(pos):
    print("Mouse button clicked at", pos)

def on_mouse_down(button):
    print("Mouse button", button, "clicked")

def on_mouse_down(pos, button):
    print("Mouse button", button, "clicked at", pos)

It does this by looking at the names of the parameters, so they must be spelled exactly as above. Each event hook has a different set of parameters that you can use, as described below.

on_mouse_down([pos][, button])¶

Called when a mouse button is depressed.

Parameters:

pos – A tuple (x, y) that gives the location of the mouse pointer when the button was pressed.
button – A mouse enum value indicating the button that was pressed.

on_mouse_up([pos][, button])¶

Called when a mouse button is released.

Parameters:

pos – A tuple (x, y) that gives the location of the mouse pointer when the button was released.
button – A mouse enum value indicating the button that was released.

on_mouse_move([pos][, rel][, buttons])¶

Called when the mouse is moved.

Parameters:

pos – A tuple (x, y) that gives the location that the mouse pointer moved to.
rel – A tuple (delta_x, delta_y) that represent the change in the mouse pointer’s position.
buttons – A set of mouse enum values indicating the buttons that were depressed during the move.

To handle mouse drags, use code such as the following:

def on_mouse_move(rel, buttons):
    if mouse.LEFT in buttons:
        # the mouse was dragged, do something with `rel`
        ...

on_key_down([key][, mod][, unicode])¶

Called when a key is depressed.

Parameters:

key – An integer indicating the key that was pressed (see below).
unicode – Where relevant, the character that was typed. Not all keys will result in printable characters - many may be control characters. In the event that a key doesn’t correspond to a Unicode character, this will be the empty string.
mod – A bitmask of modifier keys that were depressed.

on_key_up([key][, mod])¶

Called when a key is released.

Parameters:

key – An integer indicating the key that was released (see below).
mod – A bitmask of modifier keys that were depressed.

Game controllers also have their own events:

on_joy_down([joybtn][, instance_id])¶

Called when a controller button is depressed.

Parameters:

joybtn – An integer indicating the button that was pressed (see below).
instance_id – An integer identifying the device on which the button was pressed. This can be used to distinguish controls for multiple controllers for example in co-op games.

on_joy_up([joybtn][, instance_id])¶

Called when a controller button is released.

Parameters:

joybtn – An integer indicating the button that was let go off (see below).
instance_id – An integer identifying the device on which the button was released.

on_joy_move([axis][, value][, instance_id])¶

Called when a controller axis is moved, for example the thumbsticks on a typical console controller.

Parameters:

axis – An integer indicating the axis that had its value change (see below).
value – The new value of the changed axis. Values for thumbsticks range from -1 to 1 with 0 being centered while shoulder triggers range from 0 to 1 with 1 being fully pressed in.
instance_id – An integer identifying the device on which the axis value was changed.

on_joy_added([instance_id])¶

Called when a new controller is connected.