Wiki

GUIs with pygame

sections
Which GUI type are you
The user perspective
GUI libraries

From time to time, questions about GUI elements for pygame come up. The following sections give some links to GUI modules and libraries written for pygame and try - where possible - to give advice to which library you should refer for your pygame project.

A quick note to those who developed their own GUI system for Pygame: You are encouraged to add it to this page. Simply add a description, preferably in the form that the already existing ones provide, at the bottom of this page.

[edit]

Which GUI type are you

Before you just use the first GUI library you find on the internet, you should ask yourself these questions:

How much GUI do I need?
How special are my requirements on GUI elements?
What type of project am I working on?

Although the last question might sound a bit like an insult, it is possibly the most important question for your GUI decision. People (especially newcomers to game programming) tend to forget about their goal and, which is quite more important, the impression the project will have on its users.

Arcade games such as a Space Invaders project mostly do not need many GUI elements. It may need a text entry for the highscores and maybe some button basics for the main game menu. In contrast, a full featured economy simulation game like the good old Oil Imperium would need text entry boxes, buttons, lists for statistical data, table-like elements, spinner buttons for money amounts and many, many more.

Summing up those both fictional cases, the first one would need around two GUI elements while the second would need more than five. Additionally, if the arcade game has ingame GUI elements, those need to have a low reaction latency, while the economy simulation is mostly in the same gaming state showing an only slowly changing game window.

[edit]

The user perspective

Another issue you have to deal with is the user perspective. The user perspective is a kind of usability from the user point of view and - in this case - simply means: "How much effort do I need to invest to run this game?". Far too often this question is silently ignored by newcomers, thus it is brought up here. If a user first has to install dependency X for the GUI you have integrated, then has to get and install the GUI and then can run the game, it is possibly too late (unless your game has outstanding concept/graphics/gameplay). He simply will remove it from his computer.

You therefore should check if the GUI library you are about to integrate in your game can be incorporated in your game distribution or if it has many third party dependencies, for which the integration/installation effort is higher than the benefit.

p>First of all, pygame relies on the SDL, which means that it can only have one window at a time. Thus, trying to implement multiple Gtk, Qt, ... application instances that use pygame, is an impossibility. The second problematic reason is that those toolkits use their own main loop, which possibly forces you to pipe their events to your pygame instance and vice versa. And to mention some other points in short: Drawing the toolkit elements on the pygame window is impossible and the SDL/pygame fullscreen mode will be problematic.

As you see, using those toolkits together with pygame will, in nearly any case, cause more problems than their usage solves. So let's quickly go to the next section.

[edit]

GUI libraries

Now that you clarified those questions, you should know enough about the requirements you have on the specific GUI library type you want. The following presents a (not always up to date and possibly always incomplete) list of GUI libraries and modules suitable for the use with pygame. The entries also mention the basic capabilities and constraints the particular library has.

There is also a GUI comparision available, which was made by David Keeney for his own pygame project.

pgu

Easy to incorporate all-purpose library with own GUI module. Includes the usual GUI element functionality with some nice additions. Due to its relatively low internal complexity, the library is suitable for a low to medium amount of GUI elements and is easy to integrate into existing game code. The GUI elements have a relatively low response time and low overhead, which makes it very suitable for arcade games or games with a real-time approach.

rich GUI element set
includes image based theme engine
very pygame oriented. The paint() methods take pygame.Surfaces, the event() methods take pygame.Events.pgu is easy to extend with your own pygame based widgets.
additional game functionalities besides GUI
easy to incorporate into a game
library is about to reach a mature, stable state
very suitable for arcade or rt games
very easy-to-use API, so it is quite nice for the rapid development of small applications (several custom level editors have been created using pgu)
depends on python and pygame only

pgu in a level editor application

pgu in a game level selection interface

OcempGUI

Specialized GUI library with a rich GUI element set and a high functionality. It serves nearly all needs expected from a GUI library, which includes a relatively high (internal) complexity. Very suitable for a medium to high and very high GUI amount, a low GUI amount should be realized with another library, because OcempGUI would be overkill here. The incorporation into own distributions is possible, but more complex than with pgu, yet easy to integrate into existing code. As of version 0.1.1, includes internal support for Twisted, making it suitable for network games as well. Due to its high internal complexity the GUI element response time is somewhat lower than with other libraries, so that it should not be used in arcade like games or games, that have a real-time approach, criar sites.

Because of its rich feature set, it serves most needs of round based game types, simulation games, network games, or non-game applications.

rich GUI element set based on pygame.
high abstraction layers, own GUI elements can be created with less effort
various accessibility (a11y) support layers reaching from full keyboard navigation support a system integration via the ATK/AT-SPI standards
library supports own drawing engines and themes for user-defined look-and-feel
includes internal support for Twisted via the TwistedRenderer
easy to incorporate
library is currently in a beta state, but very stable
very suitable for round based and simulation games or applications
full z-axis support using layers
minimum dependencies are python and pygame only

[edit]