class hgame.HGame(object)

In a Humerus-based game there is exactly one instance of HGame (or HEGame if the game has a level editor). This object acts as a central junction point between the internal state of the game and the user interface, implemented by an HShell.

HGame performs the following functions:

Keeping track of the level set being played.
Maintaining a list of levels from the current level set that have been completed.
When a level is completed, finding the next uncompleted level to play.
Saving the state of progress of the game in a file, and restoring it from a previously saved file.

Levels and Level Sets

Humerus allows levels to be grouped into level sets. A level set is simply a directory named with a distinctive suffix. Within the level set, levels are stored one per file.

The order in which levels are played is determined by the lexicographical ordering of their filenames. It is recommended that you adopt a convention such as prefixing the filename with a level number, including leading zeroes, to control the ordering of the levels.

HGame maintains a level attribute that holds a reference to the level currently being played. The level can be represented by any object that has the following attributes and methods:

is_completed: An attribute that becomes true when the player completes the level.
begin_frame(): Called at the beginning of each frame.
reset(): Should return the level to its initial state.

You will need to provide your HGame class with a read_level() method that loads a level from a specified file and returns a level object for it.

Saved Game Files

By default, HGame writes the following information to a saved game file:

Magic numbers identifying the file as belonging to the game application and as being a saved-game file.
A version number identifying the format of the saved-game data.
The version number of the application that saved the file.
The pathname of the level set being played.
The names of levels that have been completed.

If you have any additional game state that you want preserved in the saved-game file, you can store it in the state attribute of the HGame. This attribute can refer to an object of almost any type; the only restriction is that it must be pickleable. If you use the state attribute, you will also need to provide a new_state() method that creates and returns a new state object of the appropriate type.

The filename suffixes, magic numbers and version numbers can all be customized using class attributes. You can also provide information about which data formats are understood by earlier versions of the game, so that if a user tries to open a saved game file with the wrong version of the game, he can be given an error message indicating which version he needs to use.

Class Attributes

app_version = (1, 0, 0): Version number of the game application.

app_magic = "????": Magic "number" identifying the game application. Traditionally a 4-character string, but this is not a requirement.

save_file_version = 1: Version number of the saved-game data format written by this version of the application (an integer).

save_min_version = 1: Minimum data format version understood by this version of the application.

save_app_version = (1, 0, 0): Earliest application version that understands the saved-game data format written by this version of the application.

save_version_ranges = {}: Information about application versions that understand saved-game data versions earlier than save_min_version. A mapping from data versions to pairs of application versions (min_app_version, max_app_version).

save_file_magic = "SAVE": Magic "number" identifying the file as a saved-game file. You probably won't need to change this.

save_file_default_name = "SavedGame": Default filename for saved-game files.

save_file_suffix = ".gam": Filename suffix for saved-game files.

level_file_suffix = ".lev": Filename suffix for level files.

level_set_suffix = ".lvs": Filename suffix for level set directories.

std_level_dir_name = "levels" + level_set_suffix: Name of the directory containing the game's built-in levels, within the Albow Resources directory.

default_save_dir_name = "Saves": Default directory for saved-game files, within the directory two levels up from the Albow Resources directory.

default_custom_level_dir_name = "Mods": Default directory in which to look for custom level sets, within the directory two levels up from the Albow Resources directory.

Attributes

level: Object representing the level currently being played.

playing_level_dir: Pathname of the directory containing the level being played.

level_name: Filename (last pathname component) of the level being played.

save_dir: Directory of the saved-game file last loaded or saved.

save_name: Filename (last pathname component) of the saved-game file last loaded or saved.

unsaved_progress: True if there is game progress that has not been saved. This is set automatically when the player completes a level. If you have additional game state to be saved, you will need to set this flag yourself when it changes.

state: Object holding additional state to be saved in a saved-game file.

Abstract Methods

read_level(path): Should read a level from the specified pathname and return an object representing it. The object returned will be assigned to the level attribute.

new_state(): Should create and return a new object holding any additional state to be saved in a saved-game file, initialised as for a new game. If you do not need to save any additional state, you do not need to implement this method.

Methods

You will probably not need to call any of these methods yourself, as they are called at the appropriate time from the HShell. They are documented here in case you want to know about them for customization purposes.

game_in_progress(): Returns true if a level is being played that belongs to a level set (as opposed to a stand-alone level).

level_loaded(): Returns true if a level is currently loaded.

level_in_progress(): Returns true if a level is being played and it is not yet completed.

level_is_completed(): Returns true if a level is loaded and it has been completed.

playing_level_set(): Returns true if a level set is being played (whether a level is loaded or not).

new_game(): Starts a new game. Discards any currently loaded level, clears the list of completed levels and creates a fresh state object.

load_game(path): Restores a game from the specified saved-game file. If the level referenced by the file can't be found, the user will be asked to locate it.

save_game(path): Saves the state of the current game in the specified saved-game file.


load_level(path): Loads the level file specified by path.


load_next_uncompleted_level(): Finds the next uncompleted level in the current level set and loads it.

get_std_level_dir(): Returns the full pathname of the directory holding the game's built-in levels.

get_save_dir(): Returns the full pathname of the directory last used to load or save a game.

get_playing_level_dir(): Returns the full pathname of the directory from which a level was last loaded, or the standard level directory if no level has been loaded.

next_uncompleted_level_path(): Returns the full pathname of the next uncompleted level in the current level set. If all levels are complete or a level set is not being played, returns None.

begin_frame(): Calls the begin_frame() method of the current level object. If the level becomes completed, adds it to the list of completed levels.

is_final_level(): If this method returns true, then the currrent level will remain loaded when it is completed, instead of automatically loading the next level. The default implementation always returns false.