MENUDEF

From ZDoom Wiki
Jump to navigation Jump to search

ZDoom's 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.
DefaultOptionMenu
Any option menus after this block will inherit the OptionMenu instructions defined in it.
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.
ImageScroller
A list of images and text to display in a slideshow-like fashion.

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.

Note: While it's possible to type text strings for menu labels directly in the MENUDEF file, authors are highly recommended to utilize the LANGUAGE lump to pass string values instead. This will not only allow to easily localize those strings into other languages in the future, but will also save the author the trouble of copy-pasting the strings that are reused in multiple places.


ListMenu Instructions

An instruction changes how the next elements will be treated.

Class "type"

The type of base class to use for this menu.
  • type: The name of a ZScript menu class. The class must inherit from ListMenu.

NetgameMessage "text"

If set, prevents this menu from being used while playing online, displaying text when trying to do so.
  • text: A text string to display. Can be a LANGUAGE reference.

Font "fontname", "fontcolor", "highlightcolor"

Sets the font for the current menu. Requires a color and, optionally a highlight color.
  • fontname: The name of a font. The name can either be a name from the FONTDEFS lump, or the name of a folder containing a Unicode font.
  • fontcolor: The main color as a color name (e.g. "Red"), a color name defined in the TEXTCOLO lump, or "Untranslated" (uses font's own standard color).
  • highlightcolor (optional): Color used for when the menu element is focused and highlighted. If omitted, color will be used instead.

Linespacing y

Changes how much space to leave in between menu elements.
  • y: An integer number (e.g. 18) that determines how much space to leave between elements.

CenterMenu

If specified, all elements of the list menu are placed at the screen center. Note, this doesn't change the text alignment (all elements will still be left-aligned), only the base position of the elements.

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).
  • x: An integer number for the horizontal position of the box
  • y: An integer number for the vertical position of the box
  • RR GG BB: A hex color value (e.g. "FF 00 00") determinining the start of the color range.
  • RR GG BB: A hex color value (e.g. "00 00 FF") determinining the end of the color range.
  • noportrait (optional): Can be true/false or omitted. If true, 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.)
  • x: An integer number for the horizontal position of the next element
  • y: An integer number for the vertical position of the next element

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: The name of a graphic to use, such as "M_SKULL1". Using "-" will instead use the small cursor provided in the Console font, like in option menus, and will make it blink.
  • x: An integer number for the horizontal offset of the cursor from the menu element
  • y: An integer number for the vertical offset of the cursor from the menu element

TextItem "label", "hotkey", "submenu"

Defines a selectable label for a submenu.
  • label: A text string. Can be a LANGUAGE reference.
  • hotkey: A hotkey for the element, such as "g". "" can be used to not define a hotkey.
  • submenu: The name of an OptionMenu menu.

PatchItem "graphic", "hotkey", "submenu"

Defines a selectable graphic element for a menu.
  • graphic: The name of a graphic to use.
  • hotkey: A hotkey for the element, such as "g". "" can be used to not define a hotkey.
  • submenu: The name of an OptionMenu element.

StaticText x, y, "text", "fontcolor"

Creates a static text element (not selectable). The element will use the font specified by the Font instruction for this menu.
  • x: An integer number for the horizontal position of the element
  • y: An integer number for the vertical position f the element
  • text: A text string. Can be a LANGUAGE reference.
  • fontcolor (optional): The font color as a color name (e.g. "Red"), a color name defined in the TEXTCOLO lump, or "Untranslated" (uses font's own standard color). If omitted, will use the color as specified by the Font instruction for this menu.

StaticTextCentered x, y, "text", "fontcolor"

Same as StaticText but centered: creates a static text element (not selectable) whose text is center-aligned. The element will use the font specified by the Font instruction for this menu.
  • x: An integer number for the horizontal position of the element
  • y: An integer number for the vertical position f the element
  • text: A text string. Can be a LANGUAGE reference.
  • fontcolor (optional): The font color as a color name (e.g. "Red"), a color name defined in the TEXTCOLO lump, or "Untranslated" (uses font's own standard color). If omitted, will use the color as specified by the Font instruction for this menu.

StaticPatch x, y, "graphic", centered, "substituteString"

Creates a non-interactive image.
  • x: An integer number for the horizontal position of the element
  • y: An integer number for the vertical position f the element
  • graphic: The name of a graphic to use.
  • centered (optional): Can be true/false. If true, the image will be centered at the specified coordinates instead of being left-aligned.
  • substituteString (optional): An optional LANGUAGE reference. If provided, this string will be displayed instead of the image if the user's language is set to something other than default.

StaticPatchCenteredx, y, "graphic"

Creates a non-interactive image. Same as StaticPatch with the centered argument set to true and without localization options.
  • x: An integer number for the horizontal position of the element
  • y: An integer number for the vertical position f the element
  • graphic: The name of a graphic to use.

CaptionItem "text", "fontname"

Adds a title to the menu. A font type can also be optionally provided.
  • text: A text string. Can be a LANGUAGE reference.
  • fontname (optional): The name of a font. The name can either be a name from the FONTDEFS lump, or the name of a folder containing a Unicode font.

Size x, y
Size Clean

Change how pixels are scaled. If not used, scaling 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.
  • x: Horizontal resolution
  • y: Vertical resolution
Note: Even if the menu's resolution is set to high values, like 1920, 1080, if its elements are placed anywhere outside of the 320x200 box, by default the menu will fall back to a simple text version. Use ForceList to circumvent that.

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 (i.e. every frame) 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: the leftmost part of the window
  • x2: the rightmost part of the window

ForceList

If overriding a skill, episode, or player menu, they can turn into option menus if the menu size exceeds 320x200. This is mostly useful for high resolution menus,

OptionMenu Instructions

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
}

Class "type"

The type of base class to use for this menu.

Title "text"
Caption "text"

Adds a title for the menu. Both Title and Caption can be used.
  • text: A text string. Can be a LANGUAGE reference.

Position y

Repositions the starting point for the entire menu. Can only be used once; further instances will simply override the previously defined Positions. Setting this to a positive value will hide the menu title.
y: Vertical position

DefaultSelection index

The index of the item that should be selected by default.
  • index: An integer number determining which menu element should be selected by default. Elements are added in the order they're defined in the file, and start at index 0.

ScrollTop number

Defines the element at which the scrolling area must begin (if the menu doesn't fit in the screen). All elements above the specified index will be excluded from scrolling and thus will be always visible.
  • number: An integer number determining the index of the element at which the scrolling is allowed. Elements are added in the order they're defined in the file, and start at index 0.

StaticText "text", "fontcolor"

Creates a static text element (not selectable). The element will use the font specified by the Font instruction for this menu.
  • text: A text string. Can be a LANGUAGE reference. Using "" will create an empty string, which can be used to visually separate sections of the menu.
  • fontcolor (optional): The font color as a color name (e.g. "Red"), a color name defined in the TEXTCOLO lump, "Untranslated" (uses standard font color), or 1 for the menu header font color defined in GameInfo.

StaticTextSwitchable "text_off", "text_on", "CVAR", "fontcolor"

Displays the given text depending on the value of the provided CVAR.
  • text_off: A text string to display when the specified CVAR evaluates to 0. Can be a LANGUAGE reference.
  • text_on: A text string to display when the specified CVAR evaluates to any value that is not 0. Can be a LANGUAGE reference.
  • CVAR: The name of a console variable. Can be both one of the GZDoom CVARs or a custom CVAR defined in CVARINFO.
  • fontcolor (optional): The font color as a color name (e.g. "Red"), a color name defined in the TEXTCOLO lump, "Untranslated" (uses standard font color), or 1 for the menu header font color defined in GameInfo.

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 menu to update at the same rate as the renderer (i.e. every frame) instead of every game tic. This can be used if high framerate animations in your list menu are desired.

OptionMenu Settings

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

Control "label", "command"

An option to change a key bind.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • command: A command that the bind must execute. This must be a console command, such as "+attack" (primary attack) or a custom command defined in KEYCONF.

MapControl "label", "command"

An option to change an automap key bind. Automap commands can be bound in the console with the mapbind command (as opposed to bind used for regular binds), and they're only functional when the automap is open.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • command: A command that the bind must execute.

Option "label", "CVAR", "OptionValue reference", "graycheck CVAR", centered

Creates an option that can set the specified CVAR to one of the possible values. The list of possible values must be defined separately, with a custom OptionValue block.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • CVAR: The name of the console variable that this option will be able to modify. Can be used on all types of CVARs.
  • "OptionValue reference": The name of an OptionValue block that contains the names and values used by this option.
  • graycheck CVAR (optional): The name of a console variable that determines if this element should be selectable. If specified, and the CVAR value evalutes to 0, this element will be grayed-out and unselectable.
  • centered (optional): Can be true/false. If true, the element will be centered at the specified coordinates instead of being left-aligned.

FlagOption "label", "CVAR", "OptionValue reference", bit, "graycheck CVAR", centered

Can be used with integer CVARs that act like flags.
Creates an option that can set the specified CVAR to one of the possible values. The list of possible values must be defined separately, with a custom OptionValue block.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • CVAR: The name of the console variable that this option will be able to modify. Can be used on integer CVARs.
  • bit: An integer value within the 0-31 range. Refers to which bit the flag toggles.
  • "OptionValue reference": The name of an OptionValue block that conatins the names and values used by this option.
  • graycheck CVAR (optional): The name of a console variable that determines if this element should be selectable. If specified, and the CVAR value evalutes to 0, this element will be grayed-out and unselectable.
  • centered (optional): Can be true/false. If true, the element will be centered at the specified coordinates instead of being left-aligned.

ColorPicker "label", "CVAR"

Creates an element that can modify a color CVAR. Upon selection, opens a small predefined submenu with a color palette and RGB sliders.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • CVAR: The name of the console variable that this option will be able to modify. Can be used on color CVARs.

Slider "label", "CVAR", minimum, maximum, increment, decimal places, "graycheck CVAR"

Creates an option that modifies the specified CVAR within a range of values, and draws a visible slider the user can move. The value of the CVAR is displayed next to the slider.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • CVAR: The name of the console variable that this option will be able to modify. Can be used on integer or float CVARs.
  • minimum: An integer or float-point number that determines the minimum valid value.
  • maximum: An integer or float-point number that determines the maximum valid value.
  • increment: An integer or float-point number that determines by how much the CVAR value must change if the user presses right/left on their keyboard when having this item selected. Note, it has no effect if the user uses the mouse cursor to drag the slider.
  • decimal places (optional): An optional integer number that determines how many decimal numbers after the point must be visible. Default is 0 (do not show any numbers after the point).
  • graycheck CVAR (optional): The name of a console variable that determines if this element should be selectable. If specified, and the CVAR value evalutes to 0, this element will be grayed-out and unselectable.

ScaleSlider "label", "CVAR", minimum, maximum, increment, "zerotext", "negativeonetext"

Same as Slider, but can also replace the slider with a text string if the value of the specified CVAR is 0 or -1. In contrast to Slider, this element cannot display float-point numbers and currently doesn't support a graycheck CVAR.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • CVAR: The name of the console variable that this option will be able to modify. Can be used on integer or float CVARs.
  • minimum: An integer or float-point number that determines the minimum valid value.
  • maximum: An integer or float-point number that determines the maximum valid value.
  • increment: An integer or float-point number that determines by how much the CVAR value must change if the user presses right/left on their keyboard when having this item selected. Note, it has no effect if the user uses the mouse cursor to drag the slider.
  • zerotext: A text string to display instead of the slider if the value of the CVAR is 0. Can be a LANGUAGE reference. Note, for this to take effect, minimum must be 0. Note, because this element only displays integer values, trying to map it to a float CVAR will cause the decimal part to be truncated, and as result zerotext will be displayed for values above 0.0 but below 1.0 (e.g. 0.5).
  • negativeonetext (optional): A text string to display instead of the slider if the value of the CVAR is -1. Can be a LANGUAGE reference. Note, for this to take effect, minimum must be -1.

TextField "label", "CVAR", "graycheck CVAR"

Creates an element that opens a text field where the user can directly enter a value for the specified CVAR.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • CVAR: The name of the console variable that this option will be able to modify. Can be used on integer, double or string CVARs.
  • graycheck CVAR (optional): The name of a console variable that determines if this element should be selectable. If specified, and the CVAR value evalutes to 0, this element will be grayed-out and unselectable.

NumberField "label", "CVAR", minimum, maximum, increment, "graycheck CVAR"

Similar to Slider, but without the actual slider: the numeric value of the CVAR is displayed directly. The displayed value will always be formatted to display 3 decimal values (e.g. 3 will be displayed as 3.000).
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • CVAR: The name of the console variable that this option will be able to modify. Can be used on integer or float CVARs.
  • minimum (optional): An integer or float-point number that determines the minimum valid value. If unspecified, the default value is 0.
  • maximum (optional): An integer or float-point number that determines the maximum valid value. If unspecified, the default value is 100.
  • increment (optional): An integer or float-point number that determines by how much the CVAR value must change if the user presses right/left on their keyboard when having this item selected. Note, it has no effect if the user uses the mouse cursor to drag the slider. If unspecified, the default value is 1. Cannot be lower than 1.
  • graycheck CVAR (optional): The name of a console variable that determines if this element should be selectable. If specified, and the CVAR value evalutes to 0, this element will be grayed-out and unselectable.

OptionMenu Commands

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

Submenu "label", "OptionMenu reference", param, centered

Creates an element that opens the listed submenu.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • OptionMenu reference: The name of another OptionMenu block tha this option will open.
  • param (optional): A value to pass to the Menu.SetMenu() call used to open the submenu. Does nothing and for all intents and purposes can be left at 0.
  • centered (optional): Can be true/false. If true, the element will be centered instead of being left-aligned.

LabeledSubmenu "label", "CVAR", "OptionMenu reference"

Similar to Submenu, but also displays the value of the given CVAR next to it.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • CVAR: The name of a CVAR to display next to the element. Can be used on any type of CVAR. If the CVAR has no value, prints "$NOTSET" ("Not set") instead.
  • OptionMenu reference: The name of another OptionMenu block tha this option will open.

Command "label", "command", centered, closeonselect

Creates an element that calls a console command when selected.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • command: The console command to execute.
  • centered (optional): Can be true/false. If true, the element will be centered instead of being left-aligned.
  • closeonselect (optional): Can be true/false. If true, the current menu will close after calling the command.

SafeCommand "label", "command", "prompt"

Same as Command, but displays a confirmation text with a Yes/No selection.
  • label: A text string to display for the label. Can be a LANGUAGE reference.
  • command: The console command to execute.
  • prompt (optional): A text string to display for the prompt. Can be a LANGUAGE reference.

ImageScroller Instructions

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 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.
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:
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 OpenAL is present.
MMX True if MMX is present.
SWRender True if the software renderer is completely disabled
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 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
}

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