GUI Scripting: Parsing of Set 'Cmd'

See GUI Scripting Language for a broader background article.

Overview of GUI Commands Invoked by Set "Cmd"

by Geep

GUI scripts typically contain event handlers (like onTime, onAction, etc.). Within the body of an event handler, there can be "set" commands, one form of which sets the value of a property or variable.

Another form, discussed here, has "cmd" as its first parameter. It invokes a "GUI command", parsed and acted upon in the core C++ code. This is one way developers working on the source code and main menu system (and related systems like objectives) can tie a GUI to core functionality.

Unavailable to Mappers

from greebo:

The set "cmd" trickery applies only to the main menu system, and will not work in regular player or entity GUIs. The main menu GUI has special support in the C++ code, e.g., in idGameLocal::HandleMainMenuCommand.

In particular, the logging available through the set "cmd" command, crucial in the past for debugging main menus, is not available to the mapper.

Syntax

set "cmd" "value";

where value contains a GUI command and any parameters it takes.

Examples

The most frequently used GUI commands are "play" and "log", each of which takes one parameter:

set "cmd" "log 'BriefingStateEnd called.'";
set "cmd" "play sound/meta/menu/mnu_select;";

See the Note by Tels below about usage of "log" for main menu system testing.

Extending the above syntax, it is possible to list a sequence of commands, separated by semicolons:

set "cmd" "play sound/meta/menu/mnu_select; saveGame 1";

Other commands tend to be used in the context of a particular GUI. A survey follows.

TDM’s Specialized GUI Commands

by Geep

This listing is "specialized" in the sense that it excludes 'log' and 'play'. Some commands shown are from Doom 3 days, but most have been added since. Be aware that there are additional GUI commands defined in the C++ code, but those shown here are in actual use (as of TDM 2.10) by each .gui file mentioned. A few take parameters (not always indicated here), but more typical is to set a state variable (e.g., in the GUI event handler) and have the function body retrieve it by name.

Within GUIs of the Main Menu System

• mainmenu_briefing.gui: briefing_show, briefing_scroll_down_request, briefing_scroll_up_request
• mainmenu_briefing_video.gui: briefingVideoHeartBeat, loadVideoDefinitions, prepareBriefingVideo, startBriefingVideo
• mainmenu_debriefing_video.gui: debriefingVideoHeartBeat, prepareDebriefingVideo, startDebriefngVideo
• mainmenu_download.gui: refreshAvailableMissionList, onDownloadableMissionSelected, onSelectMissionForDownload, onSelectallmissionsfordownload, onDeselectMissionForDownload, onStartDownload, onDownloadableMissionShowDetails, onGetNextScreenshotForAvailableMission, onGetPrevScreenshotForAvailbleMission
• mainmenu_failure.gui: restart, exec tdm_restart_gui_update_objectives
• mainmenu_loadsave.gui: loadsavemenu_init, updateSaveGameInfo, loadGame, close
• mainmenu_main.gui: onStartMissionClicked, check_tdm_version, uninstallMod, mainmenu_init, refreshMissionList
• mainmenu_main_ingame.gui: restart, mainmenuingame_init
• mainmenu_message.gui: $gui::MsgBoxMiddleButtonCmd, $gui::MsgBoxLeftButtonCmd, $gui::MsgBoxRightButtonCmd
• mainmenu_music.gui: $gui::BriefingVideoSoundCmd, $gui::DebriefingVideoSoundCmd, music nosound. Also, a number of #defines for various "MM_..._SOUND_CMD" music commands [Note 1].
• mainmenu_newgame.gui: installSelectedMission, onClickInstallSelectedMission, onMissionSelected, loadModNotes, darkModRestart, eraseSelectedModFromDisk
• mainmenu_objectives.gui: objective_open_request, diffSelect, close, objective_scroll_down_request, objective_scroll_up_request
• mainmenu_quit.gui: quit
• mainmenu_settings.gui: loadSettings
• mainmenu_settings_audio.gui: sound, sound eax
• mainmenu_settings_gameplay.gui: updateAIVision, updateAIHearing, setLPDifficulty, updateMeleeDifficulty
• mainmenu_settings_gamma.gui: resetBrightness, resetGamma
• mainmenu_settings_guisize.gui: resethud
• mainmenu_settings_language.gui: setLang '<language>'
• mainmenu_settings_video.gui: aspectRatioChanged, setVideoResWideScreen, updateCookedMathData, shadowimplchanged
• mainmenu_shop.gui: shopLoad, shopDone, shopBuy, shopSold, shopMore, shopDropUndrop
• mainmenu_success.gui: loadStatistics, onSuccessScreenContinueClicked
• mainmenu_utils.gui: mainMenuStartup, loadCustomVideoResolution, loadVideoDefinitions, close, mainmenu_heartbeat

Within Other Core GUIs

• msg.gui: left, mid, right
• tdm_invgrid.gui , tdm_invgrid_brown.gui , tdm_invgrid_parchment.gui: updateInventoryGrid
• tdm_objectives.gui: updateObjectives
• tdm_objectives_core.gui: exec tdm_restart_gui_objectives_scrollup, exec tdm_restart_gui_objectives_scrolldown [Note 2]
• tdm_waituntilready.gui: playerIsReady
• readables\test\book<n>page.gui: close

[Note 1] Uses #defines for MM_..._SOUND_CMD commands (for MENU, INGAME, CREDITS, MISSION_SUCCESS, BRIEFING, and BRIEFING_VIDEO) which are of form "music <sound>;". Default sounds are #defined in mainmenu_custom_defaults.gui These can be redefined by the mapper in mainmenu_custom_defs.gui. For 2.08, defaults were defined in mainmenu_defs.gui.

[Note 2] Via #defines OBJECTIVE_SCROLL_DOWN_CMD, OBJECTIVE_SCROLL_UP_CMD. In 2.10, these were defined in mainmenu_failure.gui. In 2.08, in restart.gui. (Maybe still earlier in tdm_objectives_defs.gui).

Changes in this List Between 2.08 and 2.10

Probably most changes happened during the major menu revision of TDM 2.09. See also [Note 1][Note 2] above.

In 2.10, not 2.08:

• mainmenu_failure.gui - which was not in previous list; see above for calls.
• mainmenu_utils.gui: mainmenumodeselect

Calls moved from mainmenu_newgame.gui in 2.08 to mainmenu_main.gui in 2.10:

onStartMissionClicked, uninstallMod, refreshMissionList

In 2.08, not 2.10:

• mainmenu_main_ingame.gui: exec disconnect
• mainmenu_objectives.gui: gui::mapStartCmd
• mainmenu_objectives_core.gui: exec tdm_restart_gui_update_objectives
• mainmenu_restart.gui: exec tdm_restart_gui_update_objectives
• mainmenu_settings.gui: darkmodRestart
• mainmenu_settings_audio.gui: settings_controls.gui
• mainmenu_shop.gui: gui::mapStartCmd
• restart.gui: restart, exec disconnect, exec tdm_restart_gui_update_objectives

Early Implementation Note - When Parsing GUI Commands

By Tels

Commands in the main menu GUI with "cmd" as first parameter

set "cmd" "mycommand argument1 argument2;"

are handled in idGameLocal::HandleMainMenuCommands() in game/game_local.cpp.

Geep adds: See that function for details of buffering, parsing, and dispatching or executing the GUI commands listed above. Code was further improved in TDM 2.09; see source code comments by stgatilov.

Original Problem

For each of the parts "mycommand", "argument1", "argument2" and sometimes the final ";", the routine is called again.

One special case is just using "set" "cmd" "mycommand", this will call HandleMainMenuCommands() twice, once with "mycommand" and once with ";" as the menuCommand parameter.

Commands like "play" or "music" are special cases, too, only the first part ("play" or "music") is relayed to the routine, but the argument is not. Thus it seems impossible to recover what sound shader is to be played.

Implemented Solution

The routine therefore predicts how many arguments the current command takes, accumulating them on a stack. And when it has seen enough arguments, handles the command and clears the stack before returning.

Any stray ";" as command is silently skipped.

The routine will also complain if you don't give enough arguments to a command.

Examples

set "cmd" "play sound/meta/menu/mnu_hover";  // will result in "play", and potentially ";"
set "cmd" "log 'Some text here';";           // will result in "log", "Some text here" and ";" - written to the console
set "cmd" "mainmenu_heartbeat";              // will result in "mainmenu_heartbeat" and ";"
set "cmd" "mainmenu_heartbeat;";             // will result in "mainmenu_heartbeat", ";" and ";"

Note: The "log" command only works on MainMenu guis, and only if the executable has been built with the cvar "tdm_debug_mainmenu" set to "1".

See also

• Introduction to Doom3 GUIs
• GUI Scripting on modwiki
• For a look at available GUI Commands in the Doom 3 era, see The "set" command on modiwiki.