class hlgame.HLGame(HGame)

HLGame is a subclass of HGame for games that consist of a sequence of levels. It is designed to be used in conjunction with an HLShell.

HLGame 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.
Recording which level the player is up to in the saved game file, and resuming from that level when the game is restored.

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 a level template for the current level. When play is about to begin, the level template is cloned (by default using the standard library's copy.deepcopy function), and the resulting object is bound to the playing_level attribute of the HLGame. Whenever the player restarts the level, a new clone of the level template is made.

A level or level template can be represented by any object that has the following methods:

level_is_completed(): Should return a nonzero value when the player completes the level, with a positive value indicating successful completion, and a negative value indicating failure.
begin_frame(): Called at the beginning of each frame.

Strictly speaking, it is only necessary for these methods to be present on the level objects cloned from the level template, because the level template itself is never played. However, it is usually convenient to implement levels and level templates using the same class.

If you are using HLGame directly, you will need to provide a read_level() method that loads a level template from a specified file. If you are using HEGame, additional support is provided for reading and writing level files.

Saved Game Files

By default, HLGame writes the following information to a saved game file in addition to that written by HGame:

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 as with HGame. Otherwise, no state object is needed, and you do not need to provide any new_state() method.

Class Attributes

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.
disable_gc_during_play: If true, cyclic garbage collection is disabled while a level is being played. This can result in more predictable timing for animated games, but you need to be careful not to generate cyclic garbage during play. The default is false.

Attributes

level: Level template for the current level.
playing_level: The level currently being played. Created by deep-copying the current level template when play begins.

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.

Abstract Methods

read_level(path): Should read a level template from the specified file 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.

is_final_level(): If this method returns true, then the game will be considered completed when the current level is completed successfully. The default implementation always returns false.

Note that the game will be considered complete anyway if the level is the last one in the level set, so you will only need to override this if you have some kind of branching level structure such that the game can end on some level other than the lexicographically last one.

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 template is currently loaded (although not necessarily being played).
level_started(): Returns true if a level is being played.

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

level_is_completed(): Returns a numeric value indicating whether the level being played has been completed. Positive indicates successful completion, negative indicates unsuccessful completion, and zero indicates that the level is not yet completed.

playing_level_set(): Returns true if a level set is being played (whether a level template 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): Stops and unloads any currently loaded level, then loads the level template specified by path.

load_next_uncompleted_level(): Finds the next uncompleted level in the current level set and loads it.
start_level(): Starts or restarts the currently loaded level.
stop_level(): Shuts down any level currently being played.
unload_level(): Stops and removes any level currently loaded.

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

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.