MENUDEF

From ZDoom Wiki
Jump to navigation Jump to search

ZDoom's new menu system uses a special MENUDEF lump to define the menus. Using the MENUDEF syntax, it is possible to update existing menus and define additional ones.

Note: Much of the menu structure defined here is accessed internally by CCMDs and menu generation code. If you want to design your own menus make sure that they are named identically and that links to all important submenus are present.


The basic syntax is similar to SBARINFO, however it does not use semicolons to end statements.

BlockType "BlockName"
{
    Key Value
    Key Value1, Value2
}

The main block types are the following:

DefaultListMenu
Any list menus after this block will inherit the ListMenu instructions defined in it.
ListMenu
A list of commands, such as the main menu in the various games.
AddListMenu
A ListMenu whose contents are added to an existing ListMenu.
OptionMenu
A list of options, pairing each one with its current value.
AddOptionMenu
An OptionMenu whose contents are added to an existing OptionMenu.
OptionValue
A way to pair meaningful names to values, they are referenced by OptionMenus.
OptionString
A way to pair a user displayed name to a string CVar.

A menu block can contain different kinds of instructions, settings and actions, as well as conditional subblocks.

AddListMenu and AddOptionMenu optionally support an extra parameter to insert the contents before or after a certain menu item in the existing menu. The syntax is as follows:

AddListMenu "MenuName" before "SubMenuName"
{
    ...
}

All contents will be inserted directly before the item called "SubMenuName" in the existing menu. Specify "after" instead of "before" to insert the contents directly after that item instead. Note that the name of a menu item (which corresponds internally to the value of its mAction field) usually refers to a submenu in list menus but can also refer to a console command. In option menus, it can refer to a submenu, a console command, or a CVAR. If GZDoom cannot find a suitable menu item to serve as insertion point, no error is thrown, and everything is inserted at the end of the existing menu as if before/after wasn't specified at all.

ListMenu Instructions

An instruction changes how the next elements will be treated.

Font "<font name>" [, "<font color>" ] [, "<highlight color>" ]
Chooses which font will be used from then on. Caution: this will not work in OptionMenus and will make ZDoom spit an error at loadup.
Linespacing <y>
Changes how much space to leave in between each line.
LabelOffset <x>
Changes how much labels are offset.
PlayerDisplay <x>, <y>, "RR GG BB", "RR GG BB"
Changes the position of the box where the player character is shown in the Player Class selection menu (when a new game is started). The color definitions (in hex) define the range of the background.
Position <x>, <y>
Forcibly changes the starting position for the next element. (The position of the each element is normally automatically calculated from the position of its predecessor.)
Selector "<graphic>", <x>, <y>
Changes the graphic used to indicate the currently selected menu item in a ListMenu. Graphic is the name of a graphic to use, "M_SKULL1" for example. using "-" as the graphic name will instead use the small cursor provided in the Console font, like in option menus, and will make it blink. The coordinates provided are offsets from the current menu item.

StaticText <x>, <y>, "<text>" [, "<fcolor>"] (ListMenu)

Optionally, a font color can be specified. Only font colors defined in TEXTCOLO are supported.
StaticTextCentered <x>, <y>, "<text>" [, "<fcolor>"]
Displays non-interactive text centered at the specified position. Optionally, a font color can be specified. Only font colors defined in TEXTCOLO are supported.
StaticTextSwitchable "<text_off>", "<text_on>", "<value>" [, "<fcolor>"]
Displays the given text depending on value. Optionally, a font color can be specified. Only font colors defined in TEXTCOLO are supported.
StaticPatch <x>, <y>, "<lump>"
Displays a non-interactive image lump.
StaticPatchCentered <x>, <y>, "<lump>"
Displays a non-interactive image lump centered at the specified position.
ValueText "<text>", "<CVAR>" [, "<OptionValue reference>" ]
(Verification needed)
Size <x>, <y>
Change how pixels are scaled. Defaults to "OptClean", which defers to the user's choice on how pixels are scaled. Set to "Clean" to force the old square-pixels method, or to an X-Y resolution to scale the menu to imitate full-screen based on a specific screen resolution.
AnimatedTransition
Enables animated transitions between list menus. Note that animated transitions between two menus will only work if both of them have this instruction in their definitions.

OptionMenu Instructions

An instruction changes how the next elements will be treated.
StaticText "<text>" [, "<fcolor>"]

Displays non-interactive text at the specified position.
StaticTextSwitchable "<text_off>", "<text_on>", "<value>" [, "<fcolor>"]
Displays the given text depending on value.
Title "<text>"
Displays a title for an OptionMenu.
Position <y>
Repositions the starting point for the entire optionmenu. Only useful once. Further instances will simply override the previously defined Positions.

Settings

A setting is a way to change something, generally a console variable. Types of settings include:

Control "<label>", "<command>"
For changing key bindings
MapControl "<label>", "<command>"
For changing automap key bindings
Option "<label>", "<CVAR>", "<OptionValue reference>" [, "check" [, Center]]
Allows you to set a console variable to different values, using an OptionValue block as a reference to give names to these values. "OnOff" will work for a default two switch toggle without having to make a new definition. check is an optional console variable. If its value evaluates to false, then the setting is drawn darkened and unselectable.
FlagOption "<label>", "<CVAR>", "<OptionValue reference>", bitshift [, "check" [, Center]]
(Need more info)
Slider "<label>", "<CVAR>", <minimum>, <maximum>, <inc> [, decimal places [, "check"]]
Allows you to set a console variable to a range of values between <min> and <max>, using steps of <inc> units. You can optionally set how many decimals places are shown (defaults to 1). check is an optional console variable. If its value evaluates to false, then the setting is drawn darkened and unselectable.
ScaleSlider "<label>", "<CVAR>", <minimum>, <maximum>, <inc>, "<zero_text>" [, "negone_text"]
A special version of Slider which is replaced by a descriptive text for special value settings, which are 0 and -1. If the slider is set to 0, the slider is replaced by what is passed as zero_text. If it is set to -1, it is replaced by what is passed as negone_text. The default value of negone_text is an empty string.
ColorPicker "<label>", "<CVAR>"
Allows you to set a console variable to a chosen color.
TextField "<label>", "<CVAR>" [, "<check>" ]
Allows to set a console variable's value by typing it directly. <check> is an optional console variable. If its value evaluates to false, then the setting is drawn darkened.
NumberField "<label>", "<CVAR>" [, <minimum>, <maximum> [, <inc> [, "<check>" ]]]]
Similar to Slider, but without the actual slider; this allows to set a console variable to a range of values between <min> and <max>, using steps of <inc> units. <check> is an optional console variable. If its value evaluates to false, then the setting is drawn darkened. The default values for <minimum>, <maximum> and <inc> are 0.0, 100.0 and 1.0, respectively.

Commands

A command performs an action when activated. Types of commands include:

PatchItem "<lump>", "<key>", "<menu block reference>"
"lump" assigns a graphic selector to open "menu block reference" menu; "key" assigns a keyboard shortcut.
TextItem "<label>", "<key>, "<menu block reference>"
"label" assigns a textual selector to open "menu block reference" menu; "key" assigns a keyboard shortcut.
Submenu "<label>", "<menu block reference>"
Opens the listed submenu.
Command "<label>", "<command>"
Calls a console command.
SafeCommand "<label>", "<command>" [, "<prompt>"]
Calls a console command with an additional confirmation. Optionally, a custom prompt can be specified.

If statements

If/else statements allow certain menu items to appear for different scenarios. Please note these statements are checked at compile-time only, and valid option checks appear to be semi-hardcoded. It is not possible to use them to create dynamic menus.

IfGame(<game> [, <game>...] ) {}
Uses the code if the current game is one of those listed.
IfOption(<option> [, <option>...]) {}
Executes the subblock if each given option evaluates to true.
Options include:
ReadThis True if the "Read This" menu should be shown in the main menu.
SwapMenu True if the Save/Load and Option menus should be swapped in the main menu.
Windows True if running on a Windows OS.
Unix True if running on a UNIX®-based OS.
Mac True if running on a Macintosh OS.
OpenAL True if the OpenAL is present.
Else {}
Executes the subblock if the prior if statement did not succeed.

Custom menu items

Note: This feature is for ZScript only.

See also: ZScript menus

You can also implement custom menu items in ZScript and add them to your menus via MENUDEF. To do that, your item class must comply with the following specifications:

  • List menu items must be subclassed from ListMenuItem and option menu items must be subclassed from OptionMenuItem.
  • The name of your menu item class must start with OptionMenuItem for option menu items or ListMenuItem for list menu items (for example: OptionMenuItemMyCustomItem).
  • Your menu item class must have a method named Init. MENUDEF parser will call this method when it adds your item to the menu.

To add an instance of your custom item to the menu, specify its name without the OptionMenuItem/ListMenuItem prefix. Then add a comma-separated list of values that will be passed as arguments to your Init method when it gets called. It is not necessary to specify values for optional arguments.

Example ZScript code and MENUDEF usage:

class OptionMenuItemMyCustomItem : OptionMenuItem
{
    protected void Init(int a, string b, bool c = false)
    {
        ...
    }

    ...
}

MENUDEF:

OptionMenu "MyCoolOptionMenu"
{
    MyCustomItem 5, "String value" // c is optional, will be set to false
}

Examples

This example extends the HUD options menu to add a custom options submenu.

OptionValue "CHUD_HUDColors"
{
    0, "Red"
    1, "Blue"
    2, "Green"
}

OptionMenu "CoolHUDOptions"
{
    Title "My Cool HUD Options"
    Option "HUD color", "chud_hudcolor", "CHUD_HUDColors"
}

AddOptionMenu "HUDOptions"
{
    StaticText ""
    Submenu "My Cool HUD Options", "CoolHUDOptions"
}