Revision 1.0, March 28th, 2004
Handling Input Events in Pygame is not difficult, but there are several
techniques that can be used. You will want to use the correct method
for the correct job. The two main techniques are Event Handling and State Checking. This tutorial will
look at each of these, as well as show how to handle the keyboard,
mouse, and joysticks.
State Checking simply means
calling a function to check the current position or value of an input
device. This is usually the simplest way a program can figure out what
is going on. Your program calls one of the state functions and knows
immediately what the user is doing. The state is connected directly to
the input device, so you know exactly what is going on.
Each Input device has an object that provides several methods to check
the current state.
But there are several problems writing a game with State Checking
as the only input control. First, you have no way to know the order
actions. When calling button press checking function, there could be 2
or 3 buttons all pressed at once, you have no way to determine the
order of pressing. The second problem is you can completely "miss"
button pushes. If the user clicks very fast, between your calls to
check the button state, you will never know anything changed. These
problems are solved with event handling.
- pygame.mouse: This is a
module that contains functions for accessing the mouse. This
module can also change the system cursor graphics, control visibility,
and actually reposition the mouse.
- get_pos(): Returns the
X,Y pair of the mouse position. Relative to the top left corner of the
- get_rel(): Returns the
X,Y pair of mouse movement since the last time get_rel()
was called. This is the only function of its kind, that is based on
- get_pressed(): Returns
three values representing the pressed state of three mouse buttons. 0
values mean not pressed, 1 values mean pressed.
- pygame.key: This is a
module that contains functions for accessing the keyboard.
This module can control keyboard repeat rates and translate key id values into
- get_pressed(): Returns
a tuple representing the pressed state for every key on the keyboard.
Use key id values
to index the state of an individual button.
- get_mods(): Returns an
integer representing the pressed state of all the modifier
keys (Alt, Control, Shift, Locks, etc). The integer is a bitwise array
of each key, using the modifier
key id values. To test if a key or combination of keys is pressed,
use python bit masking operators.
- pygame.key.get_mods() & KMOD_SHIFT
- true if either shift key is pressed
- pygame.key.get_mods() & KMOD_RCTRL
- true if right control key is pressed
- Joystick: An object
created from the function
pygame.joy.Joystick(id). Each joystick ojbect has an init() method that
must be called before any of these state methods will work.
Returns the position of a specific axis on the joystick. Axis 0 is
usually left/right and Axis 1 is up/down. Other axis can represent
throttle or twists on the joystick device. The position is a value
between -1 and 1, with 0 being the center.
Report the X,Y position of a trackball located on the joystick device.
The balls work similar to a regular mouse position.
Report the pressed state of a button on the joystick device. 0
represents not pressed, and 1 represents pressed.
- get_hat(hatnum): Get
the current position of a hat control. Hats are like miniature
joysticks on top of joystick devices that can report simple directions.
Returns an X,Y pair of the position of the hat. Values from -1 to 1,
with 0 being the center.
problem to avoid, if your game calls these checking functions multiple
times computing the current frame, the value can switch partway through
computing your frame. You may want to save the state into a variable
and always check with that variable.
The preferred way of dealing with input is Event Handling. Event handling is
commonly used in graphical interface programs. The system keeps a list
of things that have happened, and your program can process this,
usually once per frame. This list of events is known as the Event Queue, and it allows you to
know the order of everything that happened since your last time
checking the queue.
The pygame examples
includes an excellent event inspector program named, "eventlist.py"
Pygame has several methods for managing the queue, all in the pygame.event module. Be aware that
Pygame's queue is lower level than what you might be used to in bigger
GUI frameworks. It is up to your game to manage everything about the
queue. The main function you will use is pygame.event.get(), which removes
the events in the queue and returns them inside a list.
The events are a single Event object type. Each event has a specific type ID attribute named
"id". It also has several other named attributes specific to that type.
This outline shows the input event ID's and the attributes they carry.
When you want to move objects while certain buttons are held down, you
should check the event queue, and set the state of interesting buttons
to global variables. Then your code can check the state of those
- Mouse Events
- MOUSEMOTION: occur
frequently as the mouse is moving
- pos: current X,Y
position of the mouse, relative to the topleft window corner
- rel: amount of X,Y
relative motion in this mouse event
- buttons: three values
representing the state of each mouse button during this move
- MOUSEBUTTONUP: occur
when any mouse button is pressed
- MOUSEBUTTONDOWN: occur
when any mouse button is released
- button: number value
representing the mouse button pressed or released
- pos: X,Y mouse
position when the button was pressed or released
- Keyboard Events
- KEYDOWN: occur when any keyboard button is
- KEYUP: occur when any keyboard button is
- key: key id of the
button that was pressed or released
- mod: state of
keyboard modifiers when the button was pressed or released
- unicode: represents
the system translated keypress into a unicode character string, only on
- Joystick Events
- JOYAXISMOTION: occur
when joystick axis changes
- joy: joystick id of
- axis: axis id of the
- pos: new position of
the axis, -1 to 1 with 0 the center
- JOYBALLMOTION: occur
when joystick ball rotates
- joy: joystick id of
- ball: ball id of the
- rel: X,Y movement of
- JOYHATMOTION: occur
when joystick hat changes
- joy: joystick id of
- hat: hat id of the
- value: X,Y position
of the hat, -1 to 1 with 0 the center
- JOYBUTTONUP: occur when
joystick button pressed
- JOYBUTTONDOWN: occur
when joystick button released
- joy: joystick id of
- button: joystick
button pressed or released
The keyboard is probably the simplest input device. Keys are
represented by their key id value. The only real control you have over
the keyboard is setting repeat rates. By default, pygame sends a single
KEYDOWN and KEYUP event for every keypress. You can enable key
repeating with pygame.key.set_repeat().
The defaults are usually fine, but you can fine tune the repeat
behavior. When keys are repeating, you will receive multiple KEYDOWN
events for as long as the key is held, and a final KEYUP when it is
One other common need is getting text entry from the keyboard. This
involved proper capitalization with the shift keys, as well as special
input handling on international keyboards. This is a complex task to do
by yourself. Fortunately, Pygame already provides these translations
with every KEYDOWN event. The unicode attribute is the "system
translated" representation of the key. For special control keys it can
often be an empty string.
One last keyboard helpful tip. Remember that the keycode for the main
ENTER key is K_RETURN. The keycode for the keypad enter key is K_ENTER.
See the full list of keyboard keycode's here, in the reference
Mouse input is fairly straightforward. There are a couple extra
features you may want to be aware of. The mouse wheel is emulated in
pygame through buttons 4 and 5. The only way to receive these events is
from the MOUSEBUTTONDOWN events. This also means Pygame doesn't handle
extended mouse buttons beyend the regular 3.
Pygame can enable a special "virtual infinite area", best used for
fullscreen games. Typical behavior is the mouse is trapped to the
screen edges in fullscreen mode. If you only care about relative mouse
movement, this can present a problem. Even if the mouse cursor is
hidden, you will stop receiving relative motion past the edges of the
screen. To enable the "virtual infinite area" you must set the mouse
cursor to invisible, then also grab the input focus with pygame.event.set_grab(1).
Managing the Event Queue
Your program must deal with the input event queue as it runs. Even if
your program doesn't use events, there are a few things you'll need to
watch for. The first thing to be aware of is that the queue does not
have infinite size. Once the queue fills up, new events can no longer
be created. The queue is plenty large to hold events for a single
frame, but you if you ignore it for too long it will fill up.
Especially with MOUSEMOTION events that get created frequently.
Another thing to be aware of is that your application needs to do some
coordination with the graphic environment it lives in. This is
especially important for windowed games, but still necessary for
fullscreen games as well. When you call the Pygame event queue
functions, Pygame will take a moment to cooperate with the graphics
environment, and potentially even create new events on the queue
itself. These are events like QUIT, VIDEORESIZE, and others that
let your program know what is going on. This makes it important that
your application calls at least one pygame.event function, usually once
per frame. If you do not care at all about the Pygame queue, you can
which will allow Pygame to do its necessary processing. You may also
to do the same thing, but keep the queue empty.
Some programs and games reach a point where they are waiting on user
input. This is common in image viewers, simple paint programs, or even
turn based games. If you are creating this type of program and would
like to be extremely cooperative with other running applications, you
can use pygame.event.wait().
If no events are available, your program will be put to sleep by the
operating system, until some events becomes available. This means your
program will take 0% cpu time while it is waiting for the users actions.
Pygame's event queue also has several ways to deal with events of a
specific type. First you can call pygame.event.set_blocked(events),
which prevents certain types of events from even entering the queue.
You can also pass a list of interesting event types to pygame.event.get(), and you will
only receive events of the type you asked for. Be careful passing this
mask into pygame.event.get. All other event types will remain on the
queue, and will eventually fill it up if you never ask for them.
Pygame reserves a set of event ID values for custom use in your
program. These are values between USEREVENT and NUMEVENTS. It is up to
your program to coordinate how these events are used. Certain pygame
functions will require an event ID for creating their own events. For
example, you can have Sound objects create an event of any type when
they are finished playing.
To create your own events you first create an Event object, and pass it
to pygame.event.post(). The
Event objects are easy to create, you simply pass an event type ID and
a list of keyword named arguments. Examples may make this easier.
PLAYERDEAD = USEREVENT+2
It is also simple to set up custom timer events, that are added to the
queue for every time interval. You need to call pygame.time.set_timer(USEREVENT, delay).
The delay is in milliseconds, and the given event type will appear on
the event queue after each amount of time in the delay argument.
deadevent = pygame.event.Event(PLAYERDEAD, player=1, score=game.player1.score)