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 built 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. +menu_prompt calls +menu_clear_options for you before calling the supplied builder function, so the builder does not need to start with a manual clear.
With MENU_MODAL set to false the menu can be exited at any time by pressing enter or selecting 0. With MENU_MODAL set to true only a valid menu option can be selected; provide a way out by adding an option that sets MENU_IN_LOOP to false when chosen.
|
The looping behaviour only applies on the Glk console interpreter, where asknumber is synchronous. Under the web interpreters +menu_prompt renders the menu once and returns immediately — the player's response comes back as the next HTTP request and dispatches through the +menu_number grammar handler. The same JACL code drives both flows; you don't need to branch on interpreter. |
+menu_prompt accepts an optional second argument that seeds MENU_IN_LOOP. Pass true (or omit it) for the usual looping behaviour, or false to fire the menu exactly once. This is useful for one-shot confirmations where you want the menu wrapper for the option-building affordances but don't want the loop.
In MENU_PROXY mode each selected command is echoed back to the player in the input style before being parsed, so the transcript reads as though the player typed the command themselves. To suppress the echo (for menus where the underlying command is an implementation detail you would rather hide), set MENU_DISPLAY_COMMAND to false before +menu_prompt runs.
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: