How-To: Easily Create PyGame User Interface & Heads Up Display Elements

pygame.org logo

When one starts to dive into the amazing capabilities of the pygame library for python3, one finds a loaded tool storehouse of items to use. As you dive further into the ability of pygame to help quickly render sprites, create a game loop and move around a player, your inner child wakes up and has Mario or Zelda like dreams.

Zelda in Python — pygame.org game project

The great design behind pygame being so flexible — allowing you to craft every detail of your desired end result game, and elements of need start to repeat over and over. Such elements, typically end up being user interface and heads up display needs. When user interaction and game events, or game play, create a need for interaction between game and player.

There are a few options you can target in meeting this need for user interface elements. You could target the PyQt route, using the python wrapped Qt UI framework, which — to be honest, is a clunky way of offering interaction with a game. You can also have a look at the wiki page from pygame.org, for possible options of user interface elements options.

However if you look at games, they have their own style of user interface and heads up display elements as part of the natural flow and design of the game itself. From the intro scenes, to game scene, to game options, heads up displays (HUDs) and more.

Since most pygames are a typical game loop, like the one below:

import pygame

pygame.init()
window = pygame.display.set_mode((600,400))
clock = pygame.time.Clock()
run = True

while run:
    pygame.display.update()
    clock.tick(40)
    event_list = pygame.event.get()
        
    window.fill((125,125,125)) # Fill window

    for event in event_list:
        if event.type == pygame.QUIT:
            run = False

Typical user interface elements that are not pygame.sprite.Sprite or pygame.Surface based elements do not blend well, or have the desired design aspects of the game itself, or game flow.

With this design need in mind, I started creating a new open source GitHub project that is designed to offer user interface and heads up display (HUD) elements developed with only core python libs and pygame. I call this project, PYGame User Interface eXtreme — pyguix.

Example pyguix.ui.elements.MessageBox

With pyguix, which can be found here: Pygames-pyguix github project, you can easily employ this library with any pygame project, and with very little time, and very little code have user interface elements up and running like:

1. Message Boxes (pyguix.ui.elements.MessageBox)

pyguix.ui.elements.MessageBox with global theme ex_red.json applied

2. Contextual Popup Menus (ie: right mouse click menus) (pyguix.ui.elements.PopupMenu)

pyguix.ui.elements.PopupMenu with global theme ex_red.json applied

3. Open / Close Head Up Display Elements (pyguix.ui.elements.SnapHUD)

pyguix.ui.elements.SnapHUD and PopupMenu with them default.json applied

To quickly see this in action, make sure you have PyGame downloaded, and simply clone the repo, and open the file: ui_elements_demo_all1.py in the root of the pyguix root folder. You will see a similar display to the one found in the picture above.

Next the README file that is found in the root folder, and on the GitHub project site has details of each element that can be targeted and easily rendered in your games.

For example, once the import statement of ‘import pyguix.ui.elements as ui’ is qualified like the below.:

pyguix.ui.elements import screenshot from vscode

You will be able to easily show a ui.MessageBox user interface element, that is an inherited pygame.sprite.Sprite with similar code as follows.:

mb = ui.MessageBox(
  window=window,
  event_list=pygame.event.get()
 )

# NOTE: Act upoon if the MessageBox was canceled, if not can act upon the .clicked() value.:
if not mb.canceled():
  print(mb.clicked())
else:
  print("You canceled the MessageBox instance.")

That’s it! With the above the code, which you can find in the ‘messagebox_simple_call.py’ within the project, you will see a ui.MessageBox render like the one below, with an output based on if a button was clicked, or if the user canceled the MessageBox.

pyguix.ui.elements.MessageBox simple example

Another great built in feature for the ui.MessageBox, is the ability for the user to hit the Enter or ‘return’ key and have what button you want that key to represent from possible buttons you easily configure for each MessageBox. Finally similar built in action for the .canceled() in that the user can either click on the ‘X’ button or can hit the ‘Esc’ key to cancel the ui.MessageBox instance.

Mix in the other two elements like the ui.PopupMenu and ui.SnapHUD and you will have pure python3/pygame built user interface and HUD elements that allow for your to quickly get your games up and running faster, and easier than ever before.

There is so much more to cover in this new release that I have just dropped, like custom theme ability that applies across all elements within a game instance. Again you can read more details about each within the README of the GitHub project.

Each week, I will continue this series that started today with examples of how to make pygame user interface and HUD elements easier and faster. Doing so in a way that allows you to easily customize, and control every element, just like you can with any other aspect of a pygame.sprite.Sprite or pygame.Surface, etc.

This includes more example implementations of MessageBox, PopupMenu as well as SnapHUD instance and more.

I truly hope this helps you out in your quest for making interactive and meaningful games and simulations using python, pygame and now pyguix. Feedback is welcomed!

J. Brandon George

twitter: @PyFryDay

email: darth.data410@gmail.com

github: DarthData410