Event Hooks

Pygame Zero 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 Zero allows you to easily define the update() and draw() functions within your game module.

draw()

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

draw() must take no arguments.

Pygame Zero 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 Zero 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 Zero 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 Zero program can respond to input events by defining functions with specific names.

Somewhat like in the case of update(), Pygame Zero 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 Zero 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.
on_music_end()

Called when a music track finishes.

Note that this will not be called if the track is configured to loop.

Buttons and Keys

Built-in objects mouse and keys can be used to determine which buttons or keys were pressed in the above events.

Note that mouse scrollwheel events appear as button presses with the below WHEEL_UP/WHEEL_DOWN button constants.

class mouse

A built-in enumeration of buttons that can be received by the on_mouse_* handlers.

LEFT
MIDDLE
RIGHT
WHEEL_UP
WHEEL_DOWN
class keys

A built-in enumeration of keys that can be received by the on_key_* handlers.

BACKSPACE
TAB
CLEAR
RETURN
PAUSE
ESCAPE
SPACE
EXCLAIM
QUOTEDBL
HASH
DOLLAR
AMPERSAND
QUOTE
LEFTPAREN
RIGHTPAREN
ASTERISK
PLUS
COMMA
MINUS
PERIOD
SLASH
K_0
K_1
K_2
K_3
K_4
K_5
K_6
K_7
K_8
K_9
COLON
SEMICOLON
LESS
EQUALS
GREATER
QUESTION
AT
LEFTBRACKET
BACKSLASH
RIGHTBRACKET
CARET
UNDERSCORE
BACKQUOTE
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
DELETE
KP0
KP1
KP2
KP3
KP4
KP5
KP6
KP7
KP8
KP9
KP_PERIOD
KP_DIVIDE
KP_MULTIPLY
KP_MINUS
KP_PLUS
KP_ENTER
KP_EQUALS
UP
DOWN
RIGHT
LEFT
INSERT
HOME
END
PAGEUP
PAGEDOWN
F1
F2
F3
F4
F5
F6
F7
F8
F9
F10
F11
F12
F13
F14
F15
NUMLOCK
CAPSLOCK
SCROLLOCK
RSHIFT
LSHIFT
RCTRL
LCTRL
RALT
LALT
RMETA
LMETA
LSUPER
RSUPER
MODE
HELP
PRINT
SYSREQ
BREAK
MENU
POWER
EURO
LAST

Additionally you can access a set of constants that represent modifier keys:

class keymods

Constants representing modifier keys that may have been depressed during an on_key_up/on_key_down event.

LSHIFT
RSHIFT
SHIFT
LCTRL
RCTRL
CTRL
LALT
RALT
ALT
LMETA
RMETA
META
NUM
CAPS
MODE