Skip to content

MENUDEF Changes

Jump to bottom
Evghenii Olenciuc edited this page Jul 28, 2024 · 43 revisions

**NOTE: This page covers all changes related to menus, not just MENUDEF specifically..

Misc

  • Bound action button names in bind menu are now uppercase.
  • VideoModeMenu no longer shows options for letterbox resolutions.
  • VideoModeMenu no longer prints multiple options for same resoltion.
  • Added a menubackbutton_selection entry for the GAMEINFO block in MAPINFO. It is similar to menubackbutton entry and lets you set a back button graphic to draw when it is being hovered by a mouse.
  • Added menuuparrow and menudownarrow entries for the GAMEINFO block in MAPINFO. When used, these two replace the up and down arrows that are displayed when you can scroll OptionMenu or FreeformMenu up and down respectively.

Maps related

  • The skirmish and call vote menus have an Option item that lets you select a map. That item uses the ZA_Levels OptionValue list, which is populated automatically by the engine. That levels list prints both map name and title (for example "MAP01 - Entryway"), which is not always desired. There are now new ZA_LevelNames and ZA_LevelTitles OptionValue lists that only contain map names (MAP01) and map titles (Entryway) respectively.
  • Added a ZA_LevelPreviews OptionValue list, which can be used to display level preview images in FreeformMenu. The level preview is set using the new MAPINFO PreviewPic map properly. If the preview image is not set, it defaults to NOMAPPIC image. That image is not present in engine by default and has to be set by the mod.
  • Added map category flags for MAPINFO (Category1, Category2, ..., Category9), which adds them to respected category OptionValue (ZA_Levels#, ZA_LevelNames#, ZA_LevelTitles#, ZA_LevelPreviews#)
  • Added menu_skirmishlevel1, menu_skirmishlevel2, ..., menu_skirmishlevel9 cvars to represent currently selected map for respected category, same as menu_skirmishlevel does for default maps list.
  • You can remove a map from default ZA_Levels list (and ZA_LevelNames, ZA_LevelTitles and ZA_LevelPreviews) using NotInCategory0 flag. That is useful if you don't want to see TITLEMAP in the list, or the MAP## maps from IWADs.
  • Added ZA_LevelsLoaded, ZA_LevelNamesLoaded, ZA_LevelTitlesLoaded, ZA_LevelsPreviewsLoaded lists that contain maps that were loaded using -addmap parameter when starting the game. In multiplayer they contain maps that the server is running.

New CCMD

  • upmenu - goes one menu back
  • setskirmishlevel <level name> [category] - accepts level names for parameters, like MAP01. When called, sets the menu_skirmishlevel cvar to that level. Also accepts random for level name. This is useful when creating custom skirmish menus. If the second category parameter is specified, the skirmish level will be set for respective menu_skirmishlevel# cvar.
  • setcallvotemap <level name> - same as above, but sets level for menu_callvotemap cvar, which is used in Call Vote menu.
  • When pressing the "Start Game!" button in skirmish menu, it calls the menu_startskirmish cmd. That cmd configures the game based on values from other skimish menu items, but it also force sets some flags based on gamemode. There is now an optional customgamemode parameter for menu_startskirmish, which prevents it from setting any flags. You can use it in conjunction with the GAMEMODE lump to set flags the way your mod needs.

ListMenu and OptionMenu additions

  • Backported AddListMenu and AddOptionMenu from gzdoom, you can now make mods that add elements to existing menus.
  • Added SubMenuCentered and CommandCentered items for OptionMenu, which work exactly same as SubMenu and Command, but the text is perfectly centered.
  • The ScreenResolution item now centers resolution texts.
  • The ScreenResolution item now has an optional Int parameter that sets maximum width for the item. That way you can bring the three resolution columns closer, which is especially fancy on wide screen monitors.

FreeformMenu

FreeformMenu is an entirely new menu type that lets you create more complex and modern menus. Take a look at an example of what you can create.

FreeformMenu lets you freely position elements on both X and Y axes, with any custom width and height.

If you position an element below vertical screen boundaries, the menu will automatically become scrollable. However, you can only scroll the menu vertically. Menu items placed outside horizontal boundaries can still be selected and activated by keyboard, but users cannot scroll the menu to them and thus cannot activate them with a mouse.

Coordinates used for item position and size are scaled based on player's resolution. For example, on FullHD 1920x1080 resolution 1 coordinate unit equals to 4 screen pixels. That way your menu elements will cover the same menu area no matter the player resolution.

The FreeformMenu menu and items are defined like below. That menu will draw the STFB3 texture at coordinates 0,20 and scaled to 420x35 units. It will then print the "This is a label" text on top of it.

FreeformMenu ExampleMenu {
    Label {
        Pos 0, 20
        Size 420, 35
        Text "This is a label"
        Background STFB3
    }
}

You can also define multiple parameters on same line like below

Label {
    Pos 0, 20       Text "This is a label"
    Size 420, 35    Background STFB3
}

FreeformMenu block parameters

  • DontDim - the menu won't dim background at all.
  • ResetScroll - resets scroll position to 0 every time the menu opens.
  • TopPadding <units> - offsets all menu elements down by specified units amount. Does not affect Static items. Default is 0.
  • CenterMenu - if the menu height is lower than the screen height, the menu will be centered vertically. Does not affect Static items.
  • OverrideHeight <units> - force sets the menu height to specified amount, no matter how much space menu items take.
  • DefaultSelection <index> - when opening the menu, the specified item will be automatically selected. Please note that moving the mouse resets the selected item. Default is -1, which makes the most top left item selected by default. You can also pass -2, which resets selected item to none every time the menu is opened.
  • NoBackButton - removes the back button that is drawn by default on all menus. When using this, it is recommended to add some other back button so that users could go back using a mouse. Users can also still go back using the Escape key.
  • IfGame(<game> [, <game>...] ) {} - same as IfGame from OptionMenu, uses the code if the current game is one of those listed.
  • IfOption(<option> [, <option>...]) {} - same as IfOption from OptionMenu, executes the subblock if each given option evaluates to true.

FreeformMenu items

Label

A simple item that can print a text and draw an image. It cannot be interacted with.

Parameter Default Description
Static The item position is always the same on screen. It is not affected by TopPadding, CenterMenu or scroll position at all
NotOnTitlemap The item will not be displayed when current map is TITLEMAP.
NotInSingleplayer The item will not be displayed when playing a cooperative gamemode (cooperative, survival, invasion) in singleplayer.
NotInBotplay The item will not be displayed when playing a deathmatch gamemode (deathmatch, tdm, ctf) in singleplayer.
NotInMultiplayer The item will not be displayed when playing a multiplayer match, no matter what gamemode it is.
Pos <horizontal>, <vertical> 0, 0 The item position. Please note that by default horizontal position is relative to center of the screen, so positive value will be right of center, and negative left of center.
Size <horizontal>, <vertical> 0, 0 Defines the size of background image and cuts any text that exceeds specified boundaries. If you pass -2 for both horizontal and vertical values, the label size will be equal to background image size.
Padding <horizontal>, <vertical> 0, 0 Offsets the text to the right and bottom by given amount.
Gravity <horizontal>, <vertical> center, top Defines the relative side of the screen to which the item position is calculated. Possible values for horizontal gravity are left, center and right, and for vertical gravity are top, center, bottom.
Anchor <horizontal>, <vertical> center, top Defines the anchor point within the item to which it's position, size and mouse area are calculated. This is the point that you move around using Pos parameter. Possible values for horizontal anchor are left, center and right, and for vertical anchor are top, center, bottom.
Alpha <value> 1.0 Defines the item transparency. Range is from 0.0 to 1.0.
VisibilityCVar <cvar>, <min>, <max> null If the specified cvar value is within the min/max range inclusively, the item will be visible, otherwise it will be hidden.
Text "<text>" "" The text to print
Font <font> SmallFont The font to use when printing text
FontColor <color name> Depends on game The font color when printing text
MaxTextWidth <horizontal> 0 If above 0 and if the text visual width exceeds the specified number, the text will be split and drawn on multiple lines.
Background <image> null An image to draw behind the text.

ActionableItem

You cannot use this item directly, but most other items inherit it's properties. It is listed here to avoid repeating the same parameters over and over for other items. It inherits all parameters from Label, and adds new ones listed below.

Parameter Default Description
NotSelectable This item can't be selected and activated.
SelectedFontColor <color name> Depends on game The font color to draw text with when the item is selected by keyboard or is hovered by a mouse.
SelectedBackground <image> Same as Background The background image to draw when the item is selected by keyboard or is hovered by a mouse.
SelectedForeground <image>, <width>, <height> null The image to draw ON TOP of background and text when the item is selected by keyboard or is hovered by a mouse. Please note that SelectedForeground has it's own width and height parameters.
EnableCVar <cvar>, <min>, <max> null If the cvar is set and it's value is below or above range, the item becomes darkened and cannot be selected.
MouseArea <horizontal, vertical> Same as Size Defines the area size where the item will react to mouse events. Useful when you want the mouse area to be different from actual item size.

SubMenu

Opens another menu when clicked. Supports same parameters as ActionableItem, plus the ones below.

Parameter Default Description
Menu <menu name> null The menu to open when clicked.
Param <int param> 0 Only useful when opening few built-in engine menus. Cannot be used at all in custom menus. When opening EpisodeMenu, the value sets the chosen player class index for singleplayer campaign. When opening EpisodeMenu with param -2, the player class will be set to what the playerclass cvar is set to. When opening the StartGame or StartGameConfirm menu, the param is the chosen difficulty index for singleplayer campaign.

Command

Executes a console command or an alias when clicked. Supports same parameters as ActionableItem, plus the ones below.

Parameter Default Description
SafeCommand The user will be asked to confirm the action before executing the command.
Command null The console command or alias to execute.

Option

Designed to display a cvar and set it to different values, defined by a OptionValue or OptionString block. Unlike it's OptionMenu counterpart, the FreeformMenu Option cannot be changed by keyboard arrow keys. The user has to use Enter and Backspace, or Left and Right mouse buttons to change the value forward and backward respectively. Supports same parameters as ActionableItem, except for Text and Background, plus the ones below.

Parameter Default Description
CVar <cvar> null The cvar to modify. This parameter is REQUIRED for the item to work correctly.
Values <block name> null The OptionValue or OptionString block that defines a list of possible values for the cvar. This parameter is REQUIRED for the item to work correctly.
UnknownValueText "<text>" "Unknown" The text to print if the cvar is set to a value that is not present in Values parameter.
BackgroundValues <block name> null The OptionValue or OptionString block that defines the background image to draw when the cvar is set to a specific value.
UnknownBackground null The background image to draw when the cvar is set to a value that is not present in Values parameter.

NumberField

Similar to Option, but only works with number cvars. Instead of using a predefined values list, it allows to set any value within the min/max borders inclusively. Supports same parameters as ActionableItem, except for Text and Padding, plus the ones below.

Parameter Default Description
CVar <cvar> null The cvar to modify. This parameter is REQUIRED for the item to work correctly.
Range <min>, <max>, <step> 0, 100, 1 The min/max range inclusively that the cvar can be set to, and the step by which the value changes on each click.

Slider

Similar to NumberField, but draws a slider instead of number directly. The user can move the slider with the mouse. Supports same parameters as Label, except for Text, Font, FontColor, MaxTextWidth and Background, plus the ones below.

Parameter Default Description
CVar <cvar> null The cvar to modify. This parameter is REQUIRED for the item to work correctly.
Range <min>, <max>, <step> 0, 100, 1 The min/max range inclusively that the cvar can be set to, and the step by which the value changes when moving the slider.
Textures <background image>, <slider image>, <selected slider image>, <slider image width>, <slider image height> Vanilla CONFONT slider Sets textures for background and the moving slider as well as slider size. The slider size can be configured by the Size parameter. If not set, the slider will use the default CONFONT graphics and the slider size will reset accordingly.

PlayerField

Similar to Option, but only works with number cvars. Lets the user choose a player and sets it's index to a number cvar. Supports same parameters as ActionableItem, except for Text and Padding, plus the ones below.

Parameter Default Description
AllowBots Allows the user to choose a bot player in the list.
AllowSelf Allows the user to choose himself in the list.
CVar <cvar> null The cvar to modify. This parameter is REQUIRED for the item to work correctly.

Control

Allows the user to configure a key bind for an action. Supports same parameters as ActionableItem, except for Text, plus the ones below.

Parameter Default Description
MapControl When set, the bound key will be saved to the automap binds section.
Action <action> null The action to bind the key to. This parameter is REQUIED for the item to work correctly.

ColorPicker

Draws a flat color based on cvar value. When clicked, opens a menu for the user to change the color. Supports same parameters as ActionableItem, except for Text, Padding, Background and SelectedBackground, plus the ones below.

Parameter Default Description
CVar <cvar> null The cvar to modify. This parameter is REQUIRED for the item to work correctly.

TextField

Allows the user to edit a string cvar value directly. Supports same parameters as ActionableItem, except for Text, plus the ones below.

Parameter Default Description
CVar <cvar> null The cvar to modify. This parameter is REQUIRED for the item to work correctly.

JoinMenuTeamOption

Similar to Option, but only works with the menu_jointeamidx cvar. Allows the user to choose a team, which is later used when joining a game. Supports same parameters as ActionableItem, except for Text and Padding.

JoinPlayerClassOption

Similar to Option, but only works with the menu_joinclassidx cvar. Allows the user to choose a class, which is later used when joining a game. Supports same parameters as ActionableItem, except for Text and Padding.

InsertFreeformMenu

Copies items from another FreeformMenu and inserts them at the position of InsertFreeformMenu. This is useful when creating menu blocks that should be displayed in multiple menus. Please note that the menu to insert has to be defined before the menu to insert to.

AddFreeformMenu <menu name to add to> [below <item action>]

You can add items to existing menus by using a AddFreeformMenu block. The added item coordinates stay global just like in original menu. The below example adds a second label to an existing menu named "ExampleMenu":

AddFreeformMenu "ExampleMenu" {
    Label {
        Pos 0, 40       Text "This is an added label"
        Size 420, 35    Background STFB3
    }
}

You can also add new items below existing item in parent menu. In that case the Y coordinate will be relative to the existing item. However, you can only add items below items that have action assigned to them, like Menu for SubMenu item, or Command for Command item.

AddFreeformMenu "ExampleMenu" below "ExampleCommand" {
    Label {
        Pos 0, 40       Text "This is an added label"
        Size 420, 35    Background STFB3
    }
}

AddOptionValue/AddOptionString <list to add to>

You can add items to existing OptionValue or OptionString lists by using the AddOptionValue and AddOptionString block respectively. The new entry is always added to the end of the list.:

AddOptionValue "ExampleList" {
    100: "New Value 100"
    200: "New Value 200"
    300: "New Value 300"
}
Clone this wiki locally