There are many situations where it is desirable to present the player with a menu of options from which they can select. The menu.library contains a set of functions that assist in the display of menus and this chapter details their use.
There are two fundamental types of menu that can be created using menu.library. The first displays the menu options then returns the player to the normal game prompt. From there, if they type a command that contains only a single integer it is treated as the selection of one of the menu options. The second type of menu directly prompts the player to select an option using the asknumber command and then re-displays the menu options for a further selection. This type of menu can be further customised by setting the variable MENU_MODAL to either true or false. If MENU_MODAL is set to true the menu can only be exited by selecting an explicit option that breaks out of the menu loop. If MENU_MODAL is set to false the menu will exit if the player simply presses enter or types 0.
Both types of menus can be configured to work in one of two modes: proxy or execute. In proxy mode, the string attached to a menu option is treated as a command and is issued as if typed by the player when that option is selected. In execute mode, the string attached to a menu option is treated as the name of a function to execute when that option is selected. The mode of the menu is determined by setting the variable MENU_MODE to either MENU_PROXY or MENU_EXECUTE before displaying the menu.
We will start by demonstrating the creation of a menu that uses the normal game prompt for selecting options. Below is an example function that creates a simple three-option menu:
{+display_menu
set MENU_MODE = MENU_PROXY
execute "+menu_clear_options"
execute "+menu_add_option<Quietly open the door<open door"
execute "+menu_add_option<Sneak out the front door<out"
execute "+menu_add_option<Pick up the book<take book"
}
The first thing this function does is set the variable MENU_MODE to MENU_PROXY. This indicates that the final argument passed to the function +menu_add_option is a command to be proxied on the player's behalf.
The second line calls the function +menu_clear_options. This function simply erases any previous menu options so a new menu can be build from scratch.
The final three lines add options to the menu by calling the function +menu_add_option. This function takes two arguments: the text to be displayed for the menu option and either the in-game command to issue or the function to execute if this option is selected.
When this function is executed it will display:
1. Quietly open the door 2. Sneak out the front door 3. Pick up the book >
Typing 1, 2 or 3 from the command prompt will cause the appropriate command to be issued. This menu is considered active until it is erased by calling the function +menu_clear_options.
A looping menu is created by calling the function +menu_prompt and passing the name of the function that displays the menu options as an argument. For example, the following command will display the same menu as above, only using the asknumber command to prompt for a selection until the menu is exited:
set MENU_MODAL = false execute "+menu_prompt<+display_menu"
Using this approach, the player will not be able to perform any action other than select an option from the menu. The function +menu_prompt calls the function +menu_clear_options before calling the supplied function to build the menu. For this reason the function +menu_clear_options does not need to be called manually before adding options.
With the variable MENU_MODAL set to false, the menu can be exited at any time by simply pressing enter or selecting 0. If the variable MENU_MODAL was to be set to true, only a valid menu option can be selected. If you need to provide a mechanism for the player to exit the menu when MENU_MODAL is set to true, this is done by adding a menu option that sets the variable MENU_IN_LOOP to false when it is selected.
Below is an example of a menu displayed by calling +menu_prompt:
> menu MAIN MENU: 1. About 2. Instructions 3. Restore saved game 4. Save game in progress 5. Exit menu Type a number between 1 and 5: