Menu commands
 
These are the commands which are used in menu files. For examples of menus used for interactive consoles, refer to the Consoles tutorial in the SinEd Tutorials section. For more details on menu commands and layout strings, please refer to the Console Black Magic page.

Menu commands are colored in lavender in my custom SinScript syntax coloring wordfile for UltraEdit32.


actionitem
 
Function
 
This sets the action to take when the menu item in which this command is included is selected and the user hits enter. Several actionitem commands can be used in the same line and must be separated by semi-colon's.

Syntax
 
actionitem "<actionitem_command1> <argument1>;<actionitem_command2> <argument2> ..."

Notes & examples
 
The possible actionitem commands are:

  • consolecmd
  • pushmenu
  • stuffcmd
  • centerprint
  • function
  • callback
  • popmenu
The most important of these actionitem commands is undoubtedly the consolecmd command since it's what makes consoles truly interactive. The text string argument after consolecmd is the data that will be sent to the console variable when the menu item that contains this action item is selected. Here's an example of the use of consolecmd:

actionitem "consolecmd 5"

In this example, when the menu item that contains this actionitem command is selected and the user hits the enter key, the value "5" is assigned the console variable (which is the "consolename" of the console entity). The value can then be read by a coninput Variable command.

The second most important of these actionitem commands is the pushmenu command. This is what makes hierarchical menus possible. The text string argument after pushmenu is the name of the menu to display on the console when the menu item that contains this action item is selected. Here's an example of the use of pushmenu:

actionitem "pushmenu level2"

In this example, when the menu item that contains this actionitem command is selected and the user hits the enter key, the menu commands contained between the "menulevel level2" command down to the next menulevel command in the menu file are loaded as the new menu to be displayed on the console. The player can then select an item from this new menu or go back to the previous menu by hitting the ESC key.

The role of the stuffcmd command is to pass any valid game console command or cvar to the game console for immediate execution. Do not confuse the game console (the one you drop in the game with the ~ tilde key) with in-game interactive consoles (console entities IOW). Here's an example of the use of stuffcmd:

actionitem "stuffcmd \"play dialog/general/phone/phone1.wav\""

Note here that since the actionitem command string must be enclosed between double quotes, the argument of the stuffcmd command (the game console command itself) must itself be enclosed between escaped double quotes (\" characters). This is true for any actionitem command which requires its argument to be enclosed between double quotes.

The role of the centerprint command is simply to print the text string specified in the command argument in a box in the center of the screen. Here's an example of the use of centerprint:

actionitem "centerprint \"You're toast!\""

Here again, note that the argument of the centerprint command (the text string to print) must itself be enclosed between escaped double quotes (\" characters).

The role of the function command appears to be "to pass a function to the game" for immediate execution. I was never able to get accurate information on this one so the details are sketchy and I can't really define what a "function" involves here. I included it here so the information I already gathered would not be lost. Here are the functions which I know about because I have seen examples of them in Ritual's global/menus/main.mnu file:

  • refreshservers
  • startserver
  • joinserver
  • apply_vid_changes
  • vid_reset
  • savegame
  • loadgame
  • relogon
  • loadplayer
There are surely more functions apart from the ones in this short list. I have absolutely no information on the callback and popmenu actionitem commands.


appgloblayout
 
Function
 
This appends the layout string specified in the command argument to the global layout of the menu. The global layout is the layout text and graphics that is common to the main menu and all its sub-menus.

Syntax
 
appgloblayout "<layout_string>"

Notes & examples
 
The global layout of a menu is created by the use of the globlayout command.


autoheight
 
Function
 
Sets a default height for menu item placement. Used with the yspace and padding commands. Useful for evenly spaced menu items.

Syntax
 
autoheight oy<b|t|v> <spacing>

Notes & examples
 
Can also use the striaght y<b|t|v> <distance_from> type placement string.

yb: distance from bottom of screen or console face
yt: distance from top of screen or console face
yv: distance from center of screen or console face
oy<b|t|v>: same as above but weighted distance - adjusted to screen resolultion.

<distance_from> is in pixels when menu is displayed on the main screen and in virtual console units (see convirtualwidth and convirtualheight Console commands) when displayed on a console entity.


autotrigger
 
Function
 
Menu level command. This make a menu level change automatically to the next one listed in the actionitem command. Used mainly for screen image "slide shows". Not really useful for interactive menus.

Syntax
 
menulevel <menu_level_name> "autotrigger <time_delay>"

Notes & examples
 
In order for this command to work properly, the following command structure should be used in the menu level (in a typical example of the "slide show" role):

menulevel <menu_level_name> "autotrigger <time_delay>"

headeritem "cb <background_image> jcx jcy picn <foreground_image>"
enditem

menuitem "null"
selmenuitem "null"
actionitem "pushmenu <next_menu_level>"
enditem

menulevel <next_menu_level>

headeritem "cb <next_background_image> jcx jcy picn <next_foreground_image>"
enditem

In the above example, the background and foreground images stated in the headeritem command will display on the screen for a duration of <time_delay> before the screen changes the next background and foreground images in the next menu level called by the actionitem "pushmenu" command.

The reason that the menuitem "null" and selmenuitem "null" are used is that there are no actual menu items in this type of menu. And since the actionitem command is normally triggered when a menu item is selected and the user presses enter, the only way to make this menu level switch to the next is to have this automatic time delayed switching mechanism.


binditem
 
Function
 
This creates a key binding menu item. This command is used at the beginning of an item sub-section and must be terminated with an enditem command (same as the menuitem command). The associated selitem command must use the drawbind option as well and must be inside the same item sub-section.

Syntax
 
binditem <game_action_command> "<action_description>" "fc <R G B A> x<l|r|v> <distance_from> y<b|t|v> <distance_from> drawbind"

Notes & examples
 
<game_action_command>: this is the actual game action to bind the key to (+attack, +moveleft, +strafe, invuse, etc.).

<action_description>: this is a user defined description text string that will be placed next to the individual key binding menu item.

fc <R G B A>: this sets the foreground color and alpha (translucency) of the action and description text strings.

x<l|r|v> <distance_from> y<b|t|v> <distance_from>: this sets the position of the action and description text strings in the menu.

drawbind: this option is always used at the end of the layout string and is mandatory.


enditem
 
Function
 
Mandatory menu item sub-section terminating command. This is used at the end of every item sub-section.

Syntax
 
enditem

Notes & examples
 
There is an example of the use of this command in the notes of the autotrigger command.


fielditem
 
Function
 
Creates an empty field to be filled later by external data. This command is used at the beginning of an item sub-section and must be terminated with an enditem command. The mandatory selitem command must use the drawfield option and must be inside the same item sub-section. The localdata command must also be used to pass data to the field.

Syntax
 
fielditem <field_name> <length> <visible_length> "<initial_content>" "fc <R G B A> ox<l|r|v> <distance_from> oy<b|t|v> <distance_from> string \"<text_string>\" fc <R G B A> x<l|r|v> <distance_from> y<b|t|v> <distance_from> ox<l|r|v> <distance_from> oy<b|t|v> <distance_from> drawfield"

Notes & examples
 
<field_name>: this identifies the field. Used by the localdata command in the same item sub-section to pass data the the field.

<length>: total length of the field in characters.

<visible_length>: length of the visible portion of the field in characters.

<initial_content>: the initial text string in the field. Optional.

fc <R G B A>: foreground color and alpha (translucency) of the main heading text of the field plus the same foreground color and alpha (translucency) parameters preceding the drawfield parameter relate to the text that will fill the field.

ox<l|r|v> <distance_from> oy<b|t|v> <distance_from>: positioning parameters of the main heading text of the field and the same positioning parameters preceding the drawfield parameter relate to the field text itself.

string \"<text_string>\": main heading text of the field.

x<l|r|v> <distance_from> y<b|t|v> <distance_from>: positioning parameters for the field itself.

drawbind: this option is always used at the end of the layout string and is mandatory.


globlayout
 
Function
 
Sets the global layout text and graphics for a multiple level hierarchical menu. The global layout is displayed on all the menu levels of the menu file. This is used to set the text and graphics which must be common to the main menu and all of its sub-menus.

Syntax
 
globlayout "<layout_string>"

Notes & examples
 
You can append additional layout strings to an existing global layout with the appgloblayout command.


headeritem
 
Function
 
This is used to place a descriptive text or graphic header just before a menu item in a menu level section. Its role is mainly for console cosmetics. Each headeritem sub-section must be terminated by an enditem command.

Syntax
 
headeritem "<layout_string>"

Notes & examples
 
There is an example of the use of this command in the notes of the autotrigger command.


helpdata  
 
Function
 
This sets the layout string to display when a menu item is selected and the F1 key is pressed. This command can be paired with a binditem, fielditem, listitem, localdata, menuitem or slideritem inside a menu item sub-section.

Syntax
 
helpdata "<layout_string>" <fadetime>

Notes & examples
 
The <fadetime> argument determines how long the layout string will be displayed on the screen before fading out.

Note:
This command does not work when used in menus for interactive consoles. It works only when used in full-screen game menus.



listitem
 
Function
 
Creates a list of several selections inside a single item sub-section. This command is used at the beginning of an item sub-section and must be terminated with an enditem command. The numitems command must follow this command to specify the number of items in the list (and what they are) and the mandatory selitem command that follows must use the drawlist option. All three commands must be inside the same item sub-section. Once the player selects this item with the up/down arrows, using the left/right arrows will scroll through the individual items of the list.

Syntax
 
listitem <list_name> <selected_item> "x<l|r|v> <distance_from> y<b|t|v> <distance_from> fc <R G B A> ox<l|r|v> <distance_from> oy<b|t|v> <distance_from> string \"<text_string>\" x<l|r|v> <distance_from> y<b|t|v> <distance_from> ox<l|r|v> <distance_from> oy<b|t|v> <distance_from> drawlist \"numchars <value> red <value> green <value> blue <value>\""

Notes & examples
 
<list_name>: name of the list.

<selected_item>: number of the item selected in the list by default.

x<l|r|v> <distance_from> y<b|t|v> <distance_from>: these positioning parameters, when preceding the string parameter, relate to the title of the list and the same positioning parameters preceding the drawlist parameter relate to the list itself.

fc <R G B A>: foreground color and alpha (translucency) of the title text of the list.

ox<l|r|v> <distance_from> oy<b|t|v> <distance_from>: positioning parameter, when preceding the string parameter, relate to the title of the list and the same positioning parameters preceding the drawlist parameter relate to the list itself. Details of its exact inner workings unknown.

string \"<text_string>\": title text of the list.

drawlist \"numchars <value> red <value> green <value> blue <value>\": The numchars sub-parameter sets the character width and text color used for the list items which are not selected. The color sub-parameters are optional.


localdata
 
Function
 
This command is used to pass data between the server and certain item sub-sections which use the fielditem or slideritem commands. When used in a sub-section following a fielditem command, it is responsible for acquiring data from the server and pass it to the field created by the previous fielditem command. When used in a sub-section following a slideritem command, it will read the slider's position and use it as data to pass to the server command.

Syntax
 
localdata "<data_passing_command> <field_name>|<slider_name>"

Notes & examples
 
<data_passing_command>: this can be any standard game console command or cvar. The output from this command will be displayed in the field created by the previous fielditem command when used with fielditem. Inversely, when used with the slideritem command, it will take the slider's position as input data and pass it to the command.

<field_name>: this must be the same as the <field_name> parameter in the preceding fielditem command.

<slider_name>: this must be the same as the <slider_name> parameter in the preceding slideritem command.


menuitem
 
Function
 
This is the basic command of all menu item sections. The text or graphics displayed by the layout string in the command argument will be the selectable menu item itself. Each menu item sub-section must also include: a selitem or selmenuitem command, an actionitem command and must be terminated by an enditem command. It is possible to have as many menu item sub-sections as display space will allow in a menu level.

Syntax
 
menuitem "<layout_string>"

Notes & examples
 
When the menu item is scrolled through and selected by the player in the menu, the layout string argument of the selitem command in the same menu item section as the menuitem command is then displayed.

Note:
If no selected menuitem is needed in the menu level, the command menuitem "null" is then used. The main difference is that instead of using a selitem with the usual parameters after the menuitem command, the selmenuitem "null" command is then used. There is an example of this technique in the notes of the autotrigger command.



menulevel
 
Function
 
Marks the beginning of a menu level. A menu file must have at least one but you can have several menu levels in the same menu file to create hierarchical menus.

Syntax
 
menulevel main|<menu_level_name>

Notes & examples
 
Hierarchy levels:

main: this is the main or top level menu which appears on the console when first used by the player. The 'menulevel main' command is normally at the beginning of the menu file and "main" is the default top level menu.

<menu_level_name>: all the sub-menu names are user defined and the way each is called is controlled by using a actionitem "pushmenu <submenu_name>" command inside a menu item sub-section. A menu level "x" is defined as all the menu commands which are enclosed between the menulevel "x" command (to which they belong to) down to the next menulevel command.

There is an example of the use of this command in the notes of the autotrigger command.


numitems
 
Function
 
Used right after the listitem command to specify the number of items in the list. Right below the numitems command should be the actual list of items and optionally, the menu command related to each.

Syntax
 
numitems <number_of_list_items>
"<list_item1>" "<game_console_command1>"
"<list_item2>" "<game_console_command2>"
                    |
                    |

Notes & examples
 
"<game_console_command>": optional. When used, the standard game console command or cvar is executed when the item is selected in the list and the user presses enter.

When there is no optional command after the list item, the script is responsible for fetching and processing the information from the list item (which will be the text string of the list item itself) made available when that item is selected and the user presses enter.

When this hapens, thew value of the listitem text string is passed to the console variable. For more information on the details of this process, refer to the notes of the waitForConsole Master command and the coninput Variable command.


padding
 
Function
 
Sets a default padding value between menu items. Used with the autoheight and yspace commands. Useful for evenly spaced menu items.

Syntax
 
padding <padding_value>

Notes & examples
 
<padding_value> is in pixels when menu is displayed on the main screen and in virtual console units (see convirtualwidth and convirtualheight Console commands) when displayed on a console entity.


selitem
 
Function
 
This determines what will appear on the console when an item is selected on a console. For this reason, the selitem command is paired with an item type command in each menu item sub-section (binditem, fielditem, listitem, localdata, menuitem or slideritem).

Syntax
 
selitem "<layout_string>"

Notes & examples
 
Depending on what type of item the selitem command is paired with, the text or graphics displayed by the layout string in the command argument should be set to be similar to the paired item's layout string. The main role of this command is to give the player visual feedback when an item is selected in the menu.


selmenuitem
 
Function
 
Used in place of the selitem command whenever the menuitem "null" (no menu item) command is used. The selmenuitem command is always a "null" command.

Syntax
 
selmenuitem "null"

Notes & examples
 
Since I have not seen the selmenuitem command followed by anything else than "null", I assume this description to be correct. This seems to be used strictly for menu "slide shows" and there is an example of the use of this command in the notes of the autotrigger command.


slideritem
 
Function
 
This creates an adjustable slider as a menu item. This command is used at the beginning of an item sub-section and must be terminated with an enditem command. The mandatory selitem command must use the drawslider option and must be inside the same item sub-section. The localdata command can also be used to acquire data from the slider's position.

Syntax
 
slideritem <slider_name> <min_value> <max_value> <current_value> <length> "fc <R G B A> ox<l|r|v> <distance_from> oy<b|t|v> <distance_from> string \"<text_string>\" "fc <R G B A> ox<l|r|v> <distance_from> oy<b|t|v> <distance_from> drawslider"

Notes & examples
 
<slider_name>: this identifies the slideritem. The name can then be refered by a localdata command in the same item sub-section. It then uses the slider's position as data to pass to cvar commands.

<min_value>: minimum value of slider (when the cursor is all the way to the left).

<max_value>: maximum value of slider (when the cursor is all the way to the right).

<current_value>: value the slider is at initially.

<length>: the length of the cursor in pixels or virtual console units.

fc <R G B A>: foreground color and alpha (translucency) of the title text next to the slider (string parameter) and the second occurence sets the color and alpha (translucency) of the slider itself.

ox<l|r|v> <distance_from> oy<b|t|v> <distance_from>: positioning parameter. The one that precedes the string argument sets the position of the text title next to the slider and the next one sets the position of the slider itself.

string \"<text_string>\": descriptive text title next to the slider.


yspace
 
Function
 
Sets a default vertical spacing between menu items. Used with the autoheight and padding commands. Useful for evenly spaced menu items.

Syntax
 
yspace <spacing_value>

Notes & examples
 
<spacing_value> is in pixels when menu is displayed on the main screen and in virtual console units (see convirtualwidth and convirtualheight Console commands) when displayed on a console entity.