BGEE, BG2EE, IWDEE (patch 2.0 and later)

This page lists the parts of the engine's Lua interface that deal with MENU menus and items: the global variables the engine creates or reads for them, and the Lua functions that operate on them. It does not cover the rest of the engine's Lua functions, nor the Lua code that the games ship in their own UI.MENU and Lua files. The other globals the engine defines (engine objects such as game and worldScreen, data tables such as characters and chargen, and the callbacks it expects) are listed on the Engine Lua globals page.

The information comes from patches 2.6.6.0 and 2.7.3.0 of BGEE, BG2EE and IWDEE. All six builds register the same menu functions with the same arguments. Descriptions marked † are inferred from the engine's own field and function names; the code that consumes them was not traced in detail.

Item handles. Several functions take or return an item: a Lua light userdata that points to the engine's record of a menu item. Handles come from nameToItem, Infinity_FindUIItemByName, Infinity_GetMenuItemByName, Infinity_FindItemWithBam or Infinity_FindItemWithText. Functions that take an item name look it up in nameToItem.

Name	Direction	Description
nameToItem	Set by engine	Table that maps item names to item handles. It is rebuilt after the MENU file has been parsed, and it covers top-level items with a name. The engine's lookup by item name reads this table, so Lua code can add entries to it or replace them.
nameToItemPointer	Set by engine	Temporary variable used while nameToItem is built. It is left holding the last item entered.
instanceId	Set by engine	Set to the instance number of the item being processed before its enabled expression is evaluated, and before the engine runs that item's Lua for drawing, events and tooltips. Items created with Infinity_InstanceAnimation receive the value of currentAnimationID as their instance number; all other items have 0.
rowNumber	Set by engine	While a list is drawn or measured: the key of the current row in the table returned by the list's table expression.
rowSelected	Set by engine	While a list is drawn or measured: the list's selected row.
list<address>	Set by engine	One empty table per list item, created when the item is parsed. No other engine code refers to it.
highlight group name	Set by engine	For each highlightgroup name that is not yet a global, a global of that name holding the first item of the group.
prefix<address>	Set by engine	The functions generated from Lua strings in the MENU file (for example action, enabled and variant followed by an address). See How a menu becomes Lua.
getUiString (2.7.3.0) t (2.6.6.0)	Read by engine	Function that the engine calls with one string to translate the text of text STRING and placeholder STRING while the MENU file is parsed. It must return a string. Other engine code calls getUiString as well.
styles	Read by engine	Table of text styles used by text style, read while the MENU file is parsed.
fontcolors	Read by engine	Table that maps colour names (and numbers as text) to hexadecimal colour strings. MENU color values read it while the file is parsed, and the font renderer reads it as well.
currentAnimationID	Read by engine	Read by Infinity_InstanceAnimation as the instance number of the new item. The engine never changes it, so the Lua code must set it.
edit, slider and toggle variables	Read and written	The globals named by an item's var, position and toggle strings. Infinity_EnterEdit assigns the var variable. †

Functions generated from MENU strings are called without arguments, with a traceback handler installed, so a run-time error does not stop the engine. Their context comes from the globals above.

A function is listed here if it, or a function it calls directly, uses the engine's menu records: the menu table, the menu stack, the overlay and background menus, the item under the mouse, the lookup by item name, item construction, or item text measurement. Two functions that receive an item handle and read its fields (Infinity_ClickItem and Infinity_IsItemEnabled) are included as well. Numeric arguments that are left out count as 0. Menus are looked up by name, panel and state as described on the MENU page.

Call	Returns	Description
Menu stack
Infinity_PushMenu(name, panel, state)	–	Pushes the menu onto the menu stack. It also reads the menu's modal value to adjust the mouse cursor, and saves the world view position. †
Infinity_PopMenu() Infinity_PopMenu(name, panel, state)	–	With no arguments, closes the top menu. With a name, closes that menu if it is on the stack. Before closing, it runs the actionexit code of the item under the mouse if that item belongs to the menu.
Infinity_TransitionMenu(name, panel, state)	–	When a menu is open, records a transition from the top menu to the named menu. When the stack is empty, pushes the named menu. †
Infinity_IsMenuOnStack(name)	1 or nil	Whether the named menu is currently on the stack.
Infinity_GetCurrentScreenName()	string	Name of the top menu, or "" if the stack is empty.
Infinity_SetBackground(name) Infinity_SetBackground(nil)	–	Makes the menu (with panel 0 and state 0) the background menu. The old background menu receives a close event and the new one an open event. With an explicit nil, clears the background menu without any events.
Infinity_SetOverlay(name) Infinity_SetOverlay(nil)	–	Does the same as Infinity_SetBackground, for the overlay menu.
Infinity_SetLanguage(language, subtitles)	–	Writes the language and subtitle options to the INI. It then switches the game language, reloads the dialog files, runs the Lua resource L_language and translates all menus again from their original strings. 2.7.3.0 also writes the font-zoom option.
Menu geometry
Infinity_GetMenuArea(name)	x, y, w, h	The menu's offset (x, y) and size (w, h), for the menu with panel 0 and state 0.
Infinity_GetOffset(name)	x, y	The menu's offset (panel 0, state 0).
Infinity_SetOffset(name, x, y)	–	Sets the menu's offset. A nil argument leaves that coordinate unchanged.
Infinity_GetMousePosition()	x, y	Mouse position converted to user-interface coordinates for the top menu. †
Items by name
Infinity_FindUIItemByName(name)	item	The item named in nameToItem. If there is none, it returns a null light userdata, not nil.
Infinity_GetArea(name)	x, y, w, h	The item's area.
Infinity_SetArea(name, x, y, w, h)	–	Sets the item's area. A nil argument leaves that value unchanged.
Infinity_ScaleToText(name)	–	Sets the item's height to the height of its text at its current width.
Infinity_SetScrollTop(name, top)	–	Scrolls the item's content to top, clamped to the content height.
Infinity_GetListHeight(name)	number	Total height of the list's rows. To compute it, the function evaluates the list's table and sets rowNumber/rowSelected for each row.
Infinity_FocusTextEdit(name)	–	Starts text input in the named edit item, which must have a var. If no such item exists, it ends the current text input. †
Infinity_PlayMovie(movie, name)	–	Loads the WBM resource movie into the named movie item, replacing the previous movie. The item's loop flag decides whether the movie loops.
Infinity_StopMovie(name)	–	Releases the movie of the named item.
Infinity_StartItemCapture(name)	–	Starts mouse capture for the named item, as if it had been clicked. †
Infinity_StopItemCapture()	–	Ends any mouse capture.
Template instances
Infinity_InstanceAnimation(template, unused, x, y, w, h, list, row)	–	Creates a copy of the item nested in the named template and appends it to the template's menu. The copy gets these values: the instance number from the global currentAnimationID; position x, y; size w, h (unless both are 0); and the template's name as its template name. If list names a list item, the position is made relative to that list, and for lists with a row height or row width it is moved to row row (rows count from 1, and −1 selects the list's selected row). The arguments are read from the top of the Lua stack downwards, so all eight must be passed. The second one is read but not used.
Infinity_DestroyAnimation(template, id)	–	Removes and frees every item of the template's menu whose template name is template (compared case-sensitively) and whose instance number is id.
Items by handle and search
Infinity_GetMenuItemByName(name)	item or nil	Searches the items of the menus on the stack for one with this name (case-insensitive).
Infinity_FindItemWithBam(bam, sequence)	item or nil	Searches the menus on the stack for an item whose bam (or slot icon) is bam, compared case-insensitively. If sequence is given, the item's BAM sequence must match it as well.
Infinity_FindItemWithText(text)	item or nil	Searches the menus on the stack for an item whose text, either a string or a dialog.tlk string reference, equals text.
Infinity_IsItemEnabled(item)	boolean	Returns the item's clickable value. Despite the function's name, it does not evaluate the item's enabled expression.
Infinity_ClickItem(item)	–	Simulates a mouse click on the item by posting input events at a point inside its area.
Infinity_EnterEdit(name, text)	–	Finds the named item in the top menu and assigns text to the global variable named by its var.
Infinity_ScrollLists(amount)	–	Scrolls the lists of the top menu. †
Infinity_SelectListItem(name, text, n)	–	Simulates a click on a row of a list in the top menu, chosen by text or by number. †
Infinity_SelectDialogueOption(n)	–	Simulates a click on dialogue option n in the WORLD_DIALOG menu. †