This tutorial explains the use and handling of UserEvents in Pygame.
Pygame comes with it’s own set of events which have predefined names, such as K_LEFT and K_RIGHT. These events are detected by us in the game loop and are used to inform us that a certain “event” has occurred. Pygame allows us to create our custom events to increase the level of control and flexibility we have over our game.
In order to actually begin “broadcasting” events, we’ll also be needing another pygame feature called “timers”, which we’ll also be discussing in this tutorial.
Pygame UserEvents
Pygame Events created by the user are called “Userevents”. In this section we’ll be explaining how to create such events in Pygame.
print_message = pygame.USEREVENT + 0
In the above code, we create a UserEvent called print_message by assigning it an event ID. Pygame has a total of 32 event slots (ID’s), of which the first 23 are used by Pygame (pre-defined events). Event ID’s from 24 to 32 are available for our use.
The pygame.USEREVENT has a value of 24, which we can assign to our user-defined event. For creating a second event, you would do pygame.USEREVENT + 1 (for an ID of 25), and so on. (The +0 in the above code is just for conceptual purposes).
Due to limitations imposed by pygame, only 9 UserEvents can exist at a given time, from values 24 – 32.
Pygame Timers
Creating a Pygame UserEvent is just the first step. The next step is to actually begin broadcasting the event periodically using pygame timers.
We’re going to be using the set_timer() function which will take two parameters, a UserEvent and a time interval. The UserEvent will be sent out as an event signal, repeated periodically after the specified time interval. In simpler words, if the 2000 milliseconds is the time interval, the event signal will generate every 2000 milliseconds.
pygame.time.set_timer(print_message, 3000)
The above code will generate an event signal for the event print_message every 3 seconds.
Detecting Events in Pygame
In this section we’ll demonstrate through the use of an example, how to detect the event we just created.
As we would with a normal event, within the game loop we are going to iterate through the list of events returned by pygame.event.get() and search for the event we just created. If this event is found, we will proceed to code that we wish to execute.
import pygame
pygame.init()
print_message = pygame.USEREVENT + 0
pygame.time.set_timer(print_message, 3000)
while True:
for event in pygame.event.get():
if event.type == print_message:
print("Hello World")
The above is a very “barebones” pygame program that prints out “Hello World” every 3 seconds. Try running this code yourself and see the result.
To disable this event, you need to call the set_timer() function again, with an interval of 0 seconds.
pygame.time.set_timer(print_message, 0)
Now this event will stop occurring every three seconds, until we start it again.
This marks the end of the Pygame UserEvents (Creating custom events) tutorial. Any suggestions or contributions for CodersLegacy are more than welcome. Questions regarding the tutorial content can be asked in the comments section below.