Humerus

A Game Skeleton for Albow
Version 2.1

Contents

Introduction

Humerus is a set of classes for use with the Albow widget library. It provides an infrastructure and basic user interface for a game, with optional support for progression through a sequence of levels and a built-in level editor.

Basic facilities provided by Humerus include:
Level support includes: Level editor support facilities include:

Class Overview

The basic functionality of Humerus is provided by the following classes.
Options
This class defines certain standard command-line options used by Humerus and provides code to parse and handle them. By subclassing it, you can provide default values for the options, choose which of them are to be changeable by the player, and add options of your own.
HGame
A Humerus game contains one HGame instance. This object serves as a central junction between the user interface and the internal state of the game. You will typically subclass this class or one of its variations and add your own game-specific state and functionality.
HShell
This is a subclass of the Albow Shell class that implements the default user interface functionality. You will typically subclass this class or one of its variations and add game-specific user interface code.
MainCommandScreen
This class implements the default main menu. You can use it as-is, or subclass it to customize and extend the menu. You can also use it as a base class for other screens, such as your playing screen, that don't have a menu but need to respond to the keyboard equivalents of the menu commands.
Level functionality is provided by the following classes.
HLGame
Games that have levels should use this instead of HGame.

HLShell
Games that have levels should use this instead of HShell.

Level editor functionality is provided by the following classes.
HEGame
Games having a level editor should use this instead of HGame.
HEShell
Games having a level editor should use this instead of HShell.
EditCommandScreen
This class implements the default level editor menu. You can use it as-is, or subclass it to customize and extend the menu. You can also use it as a base class for other screens, such as your level editor screen, that don't have a menu but need to respond to the keyboard equivalents of the menu commands.

Structure

The following diagrams illustrate how the various classes of a Humerus game fit together.

Without levels


With levels but without level editor

With level editor

Usage

Creating a basic game

Using Humerus typically involves the following steps.
  1. Define a subclass of Options that specifies the command-line options you want to use. Before importing any other modules or instantiating any other classes, it is recommended to instantiate your Options class. This will process the command-line options and initialize the PyGame display. Ensuring that the display is initialized will enable you to use Albow's resource-loading facilities in the course of importing and defining your other classes. For example,
    from humerus.options import Options

    class MyOptions(Options):
    ...

    my_options = MyOptions()
    If you are making any changes to the default Albow or Humerus themes, you should do this next, before instantiating any user interface classes.

  2. Define a subclass of HGame and instantiate it.
    from humerus.hgame import HGame

    class MyGame(HGame):
    ...

    my_game = MyGame()
  3. Define a subclass of HShell (or HEShell if your game will have a level editor) and instantiate it, passing it your game and options objects.
    from humerus.hshell import HShell

    class MyShell(HShell):
    ...

    my_shell = MyShell(my_game, my_options)
    During initialization of your Shell object, you will probably want to create and attach whatever Screens you use.

  4. Call the run() method of your Shell object.
    my_shell.run()

Creating a game with levels

The above examples assume that your game doesn't have levels. If you want support for levels, use HLShell and HLGame in place of HShell and HGame. For example,
from humerus.options import Options

class MyOptions(Options):
...

my_options = MyOptions()
from humerus.hlgame import HLGame
from humerus.hlshell import HLShell

class MyGame(HLGame):
...

class MyShell(HLShell):
...

my_game = MyGame()
my_shell = MyShell(my_game, my_options)

Creating a game with a level editor

If you want support for a level editor, use HEShell and HEGame in place of HShell and HGame. There also one other thing to change: when creating your Options object, pass with_editor = True to enable the editor-related command line options. For example,

from humerus.options import Options

class MyOptions(Options):
...

my_options = MyOptions(with_editor = True)
from humerus.hegame import HEGame
from humerus.heshell import HEShell

class MyGame(HEGame):
...

class MyShell(HEShell):
...

my_game = MyGame()
my_shell = MyShell(my_game, my_options)

Themes

Humerus defines Albow themes for the following classes. You can redefine them to customize the appearance of the standard menu screens.

Class NameBase ClassUsage
MainMenuTitleLabelTitle of the main menu screen
MainMenuButtonButtonButtons of the main menu screen
EditMenuTitleLabelTitle of the editor menu screen
EditMenuButtonButtonButtons of the editor menu screen
ChangeDotWidgetChange indicator for level editor

Example Code

There are three example programs in the examples/Pong directory:

pong.py - A very simple game exercising the basic functions of Humerus.

ponglev.py - An extended version with levels.

ponged.py - An extended version incorporating a level editor.
---