Events

Events#

Events are methods that Miniworlds calls automatically. Register them on a World or an Actor with the @...register decorator.

Main Loop#

@world.register
def on_setup(self):
    self.add_background((255, 255, 255))

@world.register
def act(self):
    print(self.frame)

on_setup runs once before the world starts. act runs once per frame while the world is running.

Keyboard#

Use a specific key handler when you only care about one key:

@player.register
def on_key_down_w(self):
    self.move_up()

@player.register
def on_key_pressed_space(self):
    self.y -= 2

Use a generic handler when you need to inspect the currently pressed keys:

@player.register
def on_key_pressed(self, keys):
    if "a" in keys:
        self.move_left()
    if "d" in keys:
        self.move_right()

Keyboard events:

  • on_key_down(self, keys): once when a key is pressed

  • on_key_pressed(self, keys): every frame while a key is held

  • on_key_up(self, keys): when a key is released

  • on_key_down_<key>(self), on_key_pressed_<key>(self), on_key_up_<key>(self): key-specific handlers without a keys parameter

Common key names include w, a, s, d, space, left, right, up, and down.

Mouse#

@circle.register
def on_mouse_left(self, position):
    if self.detect_point(position):
        self.center = position

@circle.register
def on_clicked_left(self, position):
    self.color = (255, 0, 0)

Mouse events:

  • on_mouse_left(self, position), on_mouse_right(self, position), on_mouse_middle(self, position): while a button is held

  • on_mouse_left_down(self, position), on_mouse_left_up(self, position): press and release events

  • on_mouse_motion(self, position): mouse movement

  • on_clicked(self, position), on_clicked_left(self, position), on_clicked_right(self, position): actor click events

  • on_mouse_over(self, position), on_mouse_enter(self, position), on_mouse_leave(self, position): actor hover events

  • on_wheel_up(self, position), on_wheel_down(self, position): mouse wheel

Sensors And Borders#

@player.register
def on_detecting_actor(self, other):
    print("touching", other)

@player.register
def on_not_detecting_world(self):
    self.remove()

Sensor and collision events:

  • on_detecting(self, other): any detected actor

  • on_detecting_actor(self, other): any actor on the same position

  • on_detecting_<ClassName>(self, other): actors of a specific class, for example on_detecting_wall

  • on_not_detecting(self): no actor detected

  • on_not_detecting_<ClassName>(self): no actor of that class detected

  • on_detecting_world(self): actor is inside the world

  • on_not_detecting_world(self): actor is outside the world

  • on_detecting_not_on_world(self): alias for on_not_detecting_world

  • on_detecting_borders(self, borders): receives a list like ["left"]

  • on_detecting_left_border(self), on_detecting_right_border(self), on_detecting_top_border(self), on_detecting_bottom_border(self)

Both on_not_detecting_world and on_detecting_not_on_world are accepted.

Messages#

Messages are useful when actors should communicate without holding direct references to each other.

@button.register
def on_clicked_left(self, position):
    self.send_message("open_door")

@door.register_message("open_door")
def open(self, sender):
    self.switch_costume("open")

Use send_message(message, data=None) to broadcast a message. Use @actor.register_message("message") or @world.register_message("message") to react to it.

Focus#

Actors can react when they receive or lose focus after a click:

  • on_focus(self)

  • on_focus_lost(self)

Contents