MENUDEF

An instruction changes how the next elements will be treated.

Class "<type>"

The type of base class to use for this menu. Must inherit from ListMenu.

NetgameMessage "<text>"

If set, prevents this menu from being used while playing online, displaying <text> when trying to do so.

Font "<name>" [, "<color>" ] [, "<highlightcolor>" ]

Chooses which font will be used for the list menu.

Linespacing <y>

Changes how much space to leave in between each line.

CenterMenu

If set, centers all items in the list menu.

PlayerDisplay <x>, <y>, "RR GG BB", "RR GG BB" [, <noportrait>]

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. If <noportrait> is set to 1 then the player's portrait won't be displayed.

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.)

SelectedItem

If set, the last item that was created is set to automatically be selected on menu load.

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.

TextItem "<label>", "<hotkey>", "<submenu>"

Defines a selectable label that has the keyboard shortcut <hotkey> and goes to <submenu>.

PatchItem "<lump>", "<hotkey>", "<submenu>"

Defines a selectable picture that has the keyboard shortcut <hotkey> and goes to <submenu>.

StaticText <x>, <y>, "<text>" [, "<fontcolor>"]

Optionally, a font color can be specified. Only font colors defined in TEXTCOLO are supported.

StaticTextCentered <x>, <y>, "<text>" [, "<fontcolor>"]

Displays non-interactive text centered at the specified position. Optionally, a font color can be specified. Only font colors defined in TEXTCOLO are supported.

StaticPatch <x>, <y>, "<lump>" [, <centered>] [, "<substitute>"]

Displays a non-interactive image lump. When <substitute> is set to a LANGUAGE key it will use that to display text instead if localization of the patch is required.

StaticPatchCentered <x>, <y>, "<lump>"

Displays a non-interactive image lump centered at the specified position.

CaptionItem "<text>" [, "<fontname>"]

Adds a title to the menu. A font type can also be optionally provided.

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 menus. Note that animated transitions between two menus will only work if both of them have this instruction in their definitions.

Animated

Allows the list menu to update at the same rate as the renderer instead of every game tic. This can be used if high framerate animations in your list menu are desired.

MouseWindow <x1>, <x2>

Defines a horizontal range for the mouse to be considered for hovering over items. <x1> is the leftmost part of the window while <x2> is the rightmost part.

ForceList

If overriding a skill, episode, or player menu, they can turn into option menus if the menu grows too large. This will disable that behavior. Mostly useful for creating simple list menu overrides.

protected

This is not a standard instruction but is instead something applied after your option menu name. This tells any option menu that tries to replace this one that is should inherit all of its elements instead of outright overriding it. Once an option menu is marked as protected, a redefinition cannot get rid of it.

OptionMenu "GuaranteedItemsMenu" protected
{
    // Any following option menus that attempt to redefine GuaranteedItemsMenu will inherit all of these items
}

An instruction changes how the next elements will be treated.

Class "<type>"

The type of base class to use for this menu. Must inherit from OptionMenu.

Title "<text>"

The display title for the menu. Also uses Caption as an alias.

Position <y>

Repositions the starting point for the entire menu. Only useful once. Further instances will simply override the previously defined Positions. Setting this to a positive value will hide the menu title.

DefaultSelection <index>

The index of the item that should be selected by default. Items are added in-order by how they're defined in the file and start at index 0.

ScrollTop <amt>

Defines the number of items starting from the top that should be excluded from scrolling. This can be used to keep certain elements always on screen.

StaticText "<text>" [, "<fontcolor>"]

Displays non-interactive text at the specified position. Color can be either a TEXTCOLO entry name in double quotes, or the number 1 for the menu header font color defined in GameInfo.

StaticTextSwitchable "<text_off>", "<text_on>", "<value>" [, "<fontcolor>"]

Displays the given text depending on value.

AnimatedTransition

Enables animated transitions between menus. Note that animated transitions between two menus will only work if both of them have this instruction in their definitions.

Animated

Allows the option menu to update at the same rate as the renderer instead of every game tic. This can be used if high framerate animations in your option menu are desired.

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>" [, <centered>]]

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>" [, <centered>]]

Can be used with CVars that act like flags. <bitshift> specifies the amount to shift all option values by.

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>, "<zerotext>" [, "<negativeonetext>"]

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 zerotext. If it is set to -1, it is replaced by what is passed as negativeonetext. The default value of negativeonetext 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.

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

Submenu "<label>", "<menu block reference>" [, <param>] [, <centered>]

Opens the listed submenu.

LabeledSubmenu "<label>", "<CVAR>", "<menu block reference>"

Similar to Submenu but displays the text of the given CVar next to it.

Command "<label>", "<command>" [, <centered>] [, <closeonselect>]

Calls a console command. If <closeonselect> is set, the submenu is closed once used.

SafeCommand "<label>", "<command>" [, "<prompt>"]

Calls a console command with an additional confirmation. Optionally, a custom prompt can be specified.

Class "<type>"

The type of base class to use for this menu. Must inherit from ImageScrollerMenu.

AnimatedTransition

Enables animated transitions between menus. Note that animated transitions between two menus will only work if both of them have this instruction in their definitions.

Animated

Allows the scroller to update at the same rate as the renderer instead of every game tic. This can be used if high framerate animations in your image scroller are desired.

TextBackground "<lump>"

The image to display behind any drawn text on a page.

TextBackgroundBrightness <brightness>

The brightness of the image in the background. Can be between 0 and 1.

TextScale <scale>

The scalar to apply to all text.

TextFont "<fontname>"

The name of the font to use for drawing text.

TextItem "<text>" [, <y>]

Adds a text slide that displays the given text. Optionally, a y offset can be set for the text. By default the text is centered vertically.

ImageItem "<lump>"

Adds a picture slide.

Note that slides are presented in the order that they're defined in the file.

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.

IfNotGame(<game> [, <game>...] ) {}

Works on the opposite logic of IfGame

IfOption(<option> [, <option>...]) {}

Executes the subblock if each given option evaluates to true.

Options include:

Else {}

Executes the subblock if the prior if statement did not succeed.

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 inherit from ListMenuItem, option menu items must inherit from OptionMenuItem, and image scroller items must inherit from ImageScrollerPage.
• The name of your item class must be prefixed with the core class it inherits from (e.g. a custom list item called MyItem would need to be called ListMenuItemMyItem internally).
• Your menu item class must have a public method called Init()

Your Init() method will determine how many parameters the item has, what type they must be, and what order. If the first parameter is the menu descriptor class for your menu, it will pass the current state of the menu to your Init() method. This can be used for gathering special information such as fonts, spacing, etc. The type must match the type the menu uses e.g. a list menu will need a ListMenuDescriptor . Parameters with default values can be left out when using them in your MENUDEF. Below is a list of acceptable parameter types:

• [ListMenu/OptionMenu/ImageScroller]Descriptor (must be first parameter)
• string
• Name
• Color
• bool
• int
• double
• CVar
• Font
• TextureID

To add an instance of your custom item to the menu, specify its name without the core class prefix. Then add a comma-separated list of values that will be passed as arguments to your Init() method when it gets called.

Example ZScript code and MENUDEF usage:

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

    ...
}

MENUDEF:

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

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"
}