Main Menu Module

This page is a discussion of the Main Menu module.

The Main Menu module is designed to handle loading and saving of games, activation of new games, and changes to hotkey assignments, audio volume control settings, and display settings throughout the game. The basic architecture of the module is similar to other modules within the game that handle basic data types (such as integers and strings) and dictionaries. This module is required only by the Core Module; the game's design should be set to where the Main Menu is available to the player at almost any time, but it is not necessarily essential to the operation of any other module in the game. The Main Menu module is important to the game because it allows the player to set sound, display and controls to their own preferences as well as to manage their games in progress. All code for the Main Menu module is located in the sf3_mainmenu.py file.

Summary Description
The Main Menu interface is loaded during the initialization of the game routine by the Core Module as a default interface for the InterfaceHandler. After the Core Module has loaded up the Toybox Object into memory, it will display an animation which includes the name of the game and the introductory music, which can be interrupted by the player pressing any key (part of the function of the Preloader object). This will call up the Main Menu Interface. The player will be allowed to select menu options using the mouse. Activating most menu options will bring up an appropriate sub-menu. The module may be recalled at almost any point during the game by the player by pressing the &lt;Escape> key, which will be reserved specifically for this purpose throughout the entire game. Selecting "Quit" will bring up a sanity check; if the player chooses to quit, the module will check to see if the player has saved their game or not. If not, a second sanity check will occur asking whether the player wants to save their game or not. Regardless of if the player chooses to save their game at this point, the module will send the game shutdown command to the Core Module afterwards.

Data Structure of the Main_menu Object
The following list is an indication of the various variables and methods that will be included in the Main_menu object. This list contains suggested methods and variables included in the module. The Main_menu object is meant to be used as direct children of the Core Module, and have no child objects. Only one Main_menu object is meant to be used in the game, and is meant to be loaded by the Core Module after all other data crucial to the game's operation has been loaded. Its data structure is as follows:


 * Class: Main_menu
 * Class: Interface (for more information, see the discussion under the Core Module).
 * Flag: bSavedGame=False
 * Flag: bGameInProgress=False
 * Method: _init_
 * Method: NewGame
 * Method: ResumeGame
 * Method: LoadGame
 * Method: SaveGame
 * Method: SetOptions
 * Method: RollCredits
 * Method: QuitIt

Interface
The main menu interface (as intended at the time of this writing) consists of three main areas, as demonstrated in the graphic:
 * Background Graphic
 * Options Overlay
 * Interface Buttons

The largest area is the Background Graphic. This area consists of a decorative background image, with a three-dimensional model of an Interstel starship immediately above it. The starship will be set to rotate clockwise along the ship's yaw axis, at a pitch of fifteen degrees downward. This should allow the player to view all three axes of the ship as it rotates. The ship presented should match the class of the player's flagship (if there is a game in progress), and default to the Intrepid-II-class if there is no game in progress. This area is meant as eye candy; the player will have no interaction with this zone directly.

Above the Background Graphic is the Options Overlay. This will be a possibly translucent square area centered over the Background Graphic. It will be large enough to accommodate all of the required Interface Buttons, but again, the player will have no direct interaction with this zone.

The Interface Buttons sit on top of the Options Overlay. The number of buttons to be used will be defined by the module's XML file, as discussed below. At the time of this writing, the following six buttons are planned:
 * New Game
 * Load Game
 * Save Game
 * Game Options
 * Game Credits
 * Quit Game

Interface buttons may be activated in one of three ways: by clicking on them with the mouse, by using an appropriate hotkey for the desired menu (default hotkeys are F1 to F6 inclusive on the keyboard, with F1 corresponding to New Game and each successive key to the right corresponding to the next button downward; the hotkeys will be defined in the XML file, so this may change), or by using the arrow keys followed by the &lt;Enter&gt; key (by default, the "New Game" option will be highlighted upon the game's onset; the up and down arrow keys will move a cursor, which will highlight the next option up or down, respectively. The cursor will scroll, so pushing the up arrow key when the cursor is on the "New Game" button will move the cursor to "Quit Game", and vice versa). The buttons are displayed at all times when an option has not been selected while the interface is still active. When selected by the cursor, a specific button will turn red. The selection of a menu option will sound the ACKNOWLEDGED tone and activate a pre-programmed method (as defined in the XML file). While active, no calls will be made to the gameClock object to advance the time; thus, calling up the Main Menu should pause the game (as intended, this should be the primary way for the player to pause the game.)

_init_
The method's initializer will be called by the Preloader object when the player presses a key while the opening animation is playing. At that time, the animation will freeze and pass out of phase, creating the game's Main_menu object. The initializer begins by seeding the InterfaceHandler's Game_Settings tuple with the keys described in the Main_menu Interface's XML file (or the corresponding portion of the Toybox object as necessary. The corresponding Interface object's hMenuOptions dictionary is then also seeded with the appropriate information from the same data set. The initializer will then create the two game status flags, bSavedGame and bGameInProgress, and set both to False. The initializer then sets the call to the InterfaceHandler to pull up the visual portion of the Main Menu interface as well as the call to the Jukebox to begin playing the file sf3theme.mp3 before going out of scope.

NewGame
The purpose of this method is to gather the information needed to begin a new game and to execute the required function calls to start a new game; it's called when the player selects the appropriate menu option from the Main Menu interface. When selected by the player, the method will create a custom input dialogue, and display the dialogue when ready. The method will check the Toybox Object for the list of races that can be assigned at Starport (need to create this somewhere) and create a set of radio buttons, allowing the player to select their Captain character's species. A name dialogue box will also be included; this box will be seeded after a call to the Onomastikon module with a random name from the indicated species. The player will be allowed to overwrite this "default name" if they so choose. Another box will allow them to enter the name of their flagship; again, this will be auto-seeded (though this box should be limited to the list of ship names from the human_names.xml file). If the player overwrites the text in this box, the letters "I.S.S." will be added to the front of the entry.

At the bottom of the box will be two buttons, marked "OK" and "Cancel". Selecting "Cancel" causes the routine to exit; nothing further happens at that point and control of the game passes back to the Main Menu interface. If the player selects "OK", a call will be made to create a Character object with the information the player has provided and overwrite the blank Character object in the Toybox object with that new character. A default starship will be added to the Player object's Fleet object at that time, with the ship given the name provided by the player. A call will then be made to the gameClock object to check its hCalendar dictionary for routines with the "init" timestamp. Finally, the Main_menu object's bGameInProgress flag is set to True, and a command is sent to the Core Module's InterfaceHandler to set the ACTIVE_INTERFACE enum to OPERATIONS; this will bring up the Operations Interface at Starport, and should immediately default to activating the Notices option of that interface, where game control passes.

ResumeGame
The purpose of this method is to allow the player to continue a game in progress, enabling them to use a call to the Main Menu as a means of pausing their game; it's called when the player selects the appropriate menu option from the Main Menu interface. This option will only be displayed if the value of the bGameInProgress flag is True. When called, the method merely grabs the value of the LAST_ACTIVE_INTERFACE enum and sets the value of the ACTIVE_INTERFACE enum equal to it; this should return the game to the point where the player left off. Game control will pass back to the indicated Active interface.

LoadGame
The purpose of this method is to allow the player to continue a game from wherever they left off; it's called when the player selects the appropriate menu option from the Main Menu interface. When selected by the player, the method will open up a dialogue box that will enable the player to specify the filename under which they had previously saved their game. If the player cancels out of this dialogue, nothing further happens; control of the game passes back to the Main Menu module.

Otherwise, the method will check to see if the indicated file is of the proper type (we can probably set a customized extension for savegames...a quick Google search shows that .s3g isn't already taken. We also should be able to set up the dialog so that the routine ONLY searches for files of this type, and only saves games under this extension, reducing the probabilities of error). If the file is not of the proper type, the method will throw an error dialogue message; game control will pass back to the Main Menu module once the player closes the error box. Next, the method will open the indicated file. The routine will de-pickle the file and begin overwriting objects currently contained in the game's Toybox object; specifically, the method will overwrite the Player object, the gameClock object, and the Starport object's and Encounter_handler object's messageKeeper sub-object (basically, anything required to tell the game that the player will not be starting from the beginning must be replaced in the loading process.) Should any of the data prove to be unusable, the method will throw an error dialogue message; game control will pass back to the Main Menu module once the player closes the error box. Otherwise, the last step of the load will be to check the value of the LAST_ACTIVE_INTERFACE enum from the save file, and set the value of the Main_menu object's ACTIVE_INTERFACE enum to match; this should call up the appropriate interface and allow the game to proceed where it left off. Game control passes to the interface indicated as Active at that point.

SaveGame
The purpose of this method is to enable to the player to set a point for the player from which they may pick up their game at a later time; it's called when the player selects the appropriate menu option from the Main Menu interface. When selected by the player, the method will open up a dialogue box that will enable the player to enter a filename for their game in progress. If the player cancels out of this dialogue, nothing further happens; control of the game passes back to the Main Menu module. Otherwise, the method will check to see if the indicated filename already exists. If so, a second dialogue will open asking if the player would like to overwrite the file. If the player indicates yes, the method will proceed with the saving procedure (as outlined below). Otherwise, the second dialogue closes; the first dialogue box remains open, giving the player a chance to select another name. In all cases, if the player enters a filename that does not already exist, the routine will proceed with the saving procedure without further prompting the player.

If the routine gets the go ahead to proceed with the save, it will open a file to write to, and then save the current Player object, the gameClock object, and the messageKeeper sub-object of both the Starport and Encounter_handler object. The value of the LAST_ACTIVE_INTERFACE enum will also be saved. The routine will send the command to write these objects to the file, "pickling" the data as it is being saved (saving it in a secure binary format, to prevent the player from opening it up and tampering with the data). The routine will then close the file and report success in saving before going out of phase. Game control passes back to the Main Menu interface at that point, with the "Save Game" menu option highlighted.

SetOptions
The purpose of this method is to gather and execute information from the player to customize display, audio and control settings; it's called when the player selects the appropriate menu option from the Main Menu interface. When selected by the player, the method will create a custom input dialogue and display it once it's ready. This dialogue will have three selection buttons on the left-hand side, which say "Display", "Sound" and "Controls". The Display button will be highlighted when this dialogue is generated. Activating another dialogue button will require a mouse click; no other means of selection will be provided. Each set of controls will generate a series of options on the right hand side. An "OK" and "CANCEL" button will be provided at the bottom of the dialogue window; this will not change regardless of which of the selection buttons are active. Clicking "OK" will send a call to the InterfaceHandler to enable the player's selections. Clicking "CANCEL" will do nothing; this will keep things as they currently are. Either selection will close out the dialogue box and return game control to the Main Menu Module (after any changes are enacted, of course), with the "Game Options" button selected.

For "Display", a set of possible screen resolutions will be provided in a ListBox (these aren't a native function of Panda3d; we'll need to figure out a way to emulate them using the engine). The player will select their desired game resolution by selecting one of these options. Buttons for "Windowed" and "FullScreen" will also be provided; selecting "FullScreen" disables the ListBox and automatically selects whatever the current screen resolution is set on the computer on which the player is playing the game.

The "Sound" option will have two sliders provided, one for Music Volume and one for Sound Effects Volume, with buttons that allow either or both to be muted. Another button will also be provided that reverses the sound channels.

The "Controls" option will have a checkbox for disabling menu hotkeys, as well as another one for disabling the mouse. A scrollable list of labels will be provided which will be used to list out current selections for hotkeys; the player may use this to select their own hotkeys. Should the player select a hotkey for an option that has already been reserved for another function, the method will let them know about it rather than executing its instructions upon the player hitting the "OK" button. This should keep the game routine from becoming confused about what action to take when a hotkey is pressed.

RollCredits
This method's purpose is simply to display the game's credits; it's called when the player selects the appropriate menu option from the Main Menu interface. When selected by the player, the method will send a call to the InterfaceHandler to play a pre-defined animation containing the game's credits (similarly to when such an action is triggered by the Event and Plot Handler Module; see that module for further details). The animation's display, of course, overrides the display of the Main Menu interface and kills the menu music while playing. The animation can be overriden by the player by pressing any key on the keyboard, at which point control of the game will return to the Main Menu module. Control also returns to the Main Menu module when the animation completes one full playback cycle. When control passes back to the Main Module, the "Game Credits" option will be highlighted. This should not involve any changes to the ACTIVE_INTERFACE or LAST_ACTIVE_INTERFACE enums, as it needs to be possible for the player to be playing the game, call up the menu, run the credits and then go back to where they were in the game.

QuitIt
This method's purpose is to close out the game routine. It's called when the player selects "Quit Game" from the Main Menu. When selected by the player, the method will check the status of the bGameInProgress flag. If it is True, the method will then check the status of the bSavedGame flag. If both flags are true, the game will bring up a simple sanity check window asking the player if they are sure they wish to exit the game. If the player selects "Yes", the command is sent to the Core Module to kill the game routine. If the player selects "No", then the method exits without taking further action; control passes back to the Main Menu interface.

Should bGameInProgress be True but bSavedGame be False, the routine will call up a different sanity check, with the options to "Save Game", "Don't Save", and "Cancel". Selecting "Save Game" brings up a dialogue that allows the player the chance to save their game; if the dialogue returns a value that indicates the player did indeed save their game, the command to kill the game routine is sent at that point. Otherwise, game control passes back to the Main Menu with the method taking no further action. Selecting "Don't Save" sends the command to kill the game routine, while selecting "Cancel" causes the method to exit out without taking further action; control passes back to the Main Menu interface.

Finally, if the bGameInProgress flag is False, the method will bring up the simple sanity check window, with the same options/results as if both flags were True (although note in this case that the method will not check the status of the bSavedGame flag; logically, this flag should be set to False if there is not a game in progress).

In all cases, canceling out returns control of the game to the Main Menu interface, with the "Quit Game" option highlighted.

XML
The Main_menu object, like most of the other objects in the game, is largely XML driven; this will help keep it flexible up until SF3's design is finalized (i.e. menu options can be added and removed from the game freely, based upon what data is available in the XML files). The Main_menu object requires only one XML file, containing basic information on which menu options will be available and the areas of the screen at which they may be selected (the file "mainmenu_interface.xml"). This file is one of the (interface_name).xml files described in detail under the Core Module.

Module Status
This is current as of August 11, 2011.

This module is currently in the completed design phase; specific descriptions of the intended functions of modules have been written at this point, but no actual code has been written related to the module as yet (with the possible exception of XML files).

NEXT: Development Phases PREVIOUS: Onomastikon Module and Database TOP