Event Hooks — Pygame Zero 1.2.1 documentation (original) (raw)

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:

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 (seebelow). 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 (seebelow). 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 belowWHEEL_UP/WHEEL_DOWN button constants.

class mouse

A built-in enumeration of buttons that can be received by theon_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

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