Menu Reference
Menu files define how the menus ingame look like and how they behave. They are written inside a custom definition language that allows the creation of menus as an asset without modifying the game's source code.
The origins of this menu system come from "Quake III: Arena". You can find a writeup about its structure and features here.
The system used in CoD game is based on this original system but was continually modified and extended with any title. Therefore depending on the CoD title the features of menus file vary.
File types
Menu Lists
The games bundle menus in what is called Menu Lists. It's nothing other than just a collection of menus.
Menu lists usually have the extension .txt
and are meant for being able to load a certain collection of menus at the same time. Quake III also did this by for example bundling ingame menus. Similarly IW4, for example also uses ui/ingame.txt
but also menu lists like ui/hud.txt
for bundling menus.
Other than that, menu lists are do the same thing as .menu
files. In fact you sometimes see the CoD games load .menu
files as menu lists as well. Convention however is that menu lists only load .menu
files with loadMenu
however.
Since ingame menus can only be used when loaded, and the game only loads menu lists, any menu has to be part of a menu list that is somewhen loaded to be able to be used.
Example of a menu list:
{
loadMenu { "ui/error_popmenu.menu" }
loadMenu { "ui/error_popmenu_submenu.menu" }
loadMenu { "ui/save_corrupted.menu" }
loadMenu { "ui/popup_connecting.menu" }
loadMenu { "ui/popup_acceptinginvite.menu" }
loadMenu { "ui/popup_gettingdata.menu" }
loadMenu { "ui/error_popmenu_party.menu" }
loadMenu { "ui/error_popmenu_lobby.menu" }
loadMenu { "ui/popup_reconnectingtoparty.menu" }
loadMenu { "ui/acceptinvite_warning.menu" }
loadMenu { "ui/pregame_loaderror.menu" }
loadMenu { "ui/pregame_loaderror_mp.menu" }
loadMenu { "ui/menu_resetstats_warning.menu" }
loadMenu { "ui/briefing.menu" }
loadMenu { "ui/victoryscreen.menu" }
loadMenu { "ui/victory_notice_popmenu.menu" }
loadMenu { "ui/connect.menu" }
loadMenu { "ui/expression_test.menu" }
}
Menu files
Menu files have the extension .menu
and hold data for one or multiple menus. They can be loaded from any other menu list or menu file with loadMenu
.
Example of a menu file:
{
menuDef
{
name "connect"
rect 0 0 640 480 0 0
style 1
focuscolor 1 1 1 1
onOpen
{
exec "selectStringTableEntryInDvar mp/didyouknow.csv 0 didyouknow";
}
itemDef
{
rect -426.667 -240 853.333 480 2 2
style 3
decoration
visible 1
textscale 0.55
background "$levelbriefing"
}
itemDef
{
rect 0 0 0 26 3 1
decoration
visible 1
textalign 6
textalignx -8
textscale 0.5833
textstyle 3
textfont 9
forecolor 1 0.8 0.4 1
exp text gametypename();
}
}
}
Menu file elements
The root element
Every menu file has a root element consisting of opening and closing curly parenthesis {}
. Any other element must be nested within this root element.
OAT supports having multiple root elements within the same file. This is meant to improve comfort when using features of the preprocessor.
Example:
{
// Any other element is nested within this root element
}
loadMenu
- Loading menu files
Can only be used within the root element.
Using the loadMenu
element it is possible to load other menu files. When used within the context of a menu list, all menus loaded from within the referenced file is added as part of the menu list.
Unlike when using the preprocessor feature #include
, the referenced menu file is loaded after parsing the current file.
Example:
{
loadMenu { "ui_mp/connect.menu" }
}
menuDef
- Menu Definitions
Can only be used within the root element.
Defining a menu is done with menuDef
. Everything enclosed in the following curly braces block is part of the menu.
Every menu must define a name
that is unique. If it shares its name with another menu, one menu does overwrite the other.
A menu is always a rectangle but does not necessarly have to be fullscreen. Menus are stacked on top of each other based on the order of opening.
Example:
{
menuDef
{
name TestMenu
// ...
}
}
itemDef
- Item Definitions
Can only be used within a menuDef element.
Items can be defined with an itemDef
and make up all the different elements of a menu. They are always rectangular but they can imitate other shapes when used with a background with transparency. A menu can have multiple items.
There are different types of items that do different things. It can for example be a text, an image, a listbox. See also the item type
property.
Example:
{
menuDef
{
name TestMenu
// ...
itemDef
{
rect 0 0 128 64 3 3
style 3
decoration
visible 1
textscale 0.55
background "logo_iw"
}
}
}
functionDef
- Function Definitions
WARNING
This is an OAT extension. Most other menu parsers will probably not support this feature.
Can only be used within the root element.
With functionDef
it is possible to define a function that can be reused within expressions within the same menu list.
Functions cannot take any arguments and are executed at most once per menu tick. This saves time evaluating expressions that are reused within many expressions in different places.
It is possible to use a different function within a functionDef
as long as it was already specified before it.
A functionDef
has two properties that are both mandatory to specify:
Name | Type |
---|---|
name | String |
value | Expression |
The value of a function can be used in any expression after its definition like this by calling it: nameOfTheFunction()
.
Example:
{
// Defining a custom function
functionDef
{
name isTeamAxis
value team("name") == "TEAM_AXIS";
}
menuDef
{
name TestMenu
visible when(isTeamAxis()); // Using the defined function
}
}
Calling a function does not need to be the entirety of an expression:
{
// ...
menuDef
{
// ...
visible when(dvarbool(ui_isTesting) && isTeamAxis() && actionslotusable(4));
}
}
Properties
Menus and items have properties. These are key-value pairs giving a certain property identified by its name a respective value. Different properties take different types of values. The most common types of values are:
- Literal values: For example a string or a number.
- Expressions: Can make use of functions and is evaluated to a literal value at runtime when displaying the menu.
- Event Handlers: A small script that specifies some code to execute upon triggering an event.
In rarer cases a property can also have a more complicated syntax. The available properties for menus and items are documented in their respective pages.
Example:
{
menuDef
{
// name property taking a literal value
name "TestMenu"
// visible property taking an expression
visible when(dvarbool(ui_isTesting));
// onOpen property taking an event handler
onOpen
{
open test_popup;
setDvar ui_testMenuOpen 1;
}
}
}