Handling Events¶

The @wasabi2d.event decorator registers event handlers. The name of the function determines which event should be handled. For example, the function

@event
def on_mouse_down(pos):
    print(pos)

will be called when the mouse is clicked.

Wasabi2d automatically detects which parameters the handler takes, to make it quicker to define handlers that don’t need all of the event properties.

For example, wasabi2d will be happy to call any of these variations of an on_mouse_down function:

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

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

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

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

Parameters are matched by name, so they must be spelled exactly as in the documentation below. Each event hook has a different set of parameters that you can use, as described below.

Event Types¶

update([t][, dt][, keyboard])¶

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

Parameters

t (float) – The current game time, in seconds
dt (float) – The time since the last frame, in seconds. (dt is short for “delta t”, or “change in t”).
keyboard – The current state of the keyboard.

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, wasabi2d will pass it the elapsed time in seconds. You can use this to scale your movement calculations.

For example:

@event
def update(dt, keyboard):
    v = 20 * dt

    if keyboard.right:
        alien.pos[0] += v
    elif keyboard.left:
        alien.pos[0] -= v
    if keyboard.up:
        alien.pos[1] -= v
    elif keyboard.down:
        alien.pos[1] += v

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:

@event
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.

Keyboard State¶

If you’d like to know what keys are pressed on the keyboard, you can query the attributes of the wasabi2d.keyboard object. If, say, the left arrow is held down, then keyboard.left will be True, otherwise it will be False.

There are attributes for every key; some examples:

keyboard.a  # The 'A' key
keyboard.left  # The left arrow key
keyboard.rshift  # The right shift key
keyboard.kp0  # The '0' key on the keypad
keyboard.k_0  # The main '0' key

The full set of key constants is given in the Buttons and Keys documentation, but the attributes are lowercase, because these are variables not constants.