GUI Scripting: Parsing of Set 'Cmd'

See GUI Scripting Language for a broader background article.

Overview of GUI Commands

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 can tie a GUI to core functionality. Generally, mappers benefit from this indirectly.

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

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.11 pre) 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, onDownloadableMissionShowDetails, onGetNextScreenshotForAvailableMission, onGetPrevScreenshotForAvailbleMission
• mainmenu_loadsave.gui: loadsavemenu_init, updateSaveGameInfo, loadGame, close
• mainmenu_main.gui: check_tdm_version, * mainmenu_init
• mainmenu_main_ingame.gui: restart, mainmenuingame_init, exec disconnect
• mainmenu_message.gui: $gui::MsgBoxMiddleButtonCmd, $gui::MsgBoxLeftButtonCmd, $gui::MsgBoxRightButtonCmd
• mainmenu_music.gui: $gui::BriefingVideoSoundCmd, $gui::DebriefingVideoSoundCmd, music nosound
• mainmenu_newgame.gui: onStartMissionClicked, uninstallMod, installSelectedMission, onClickInstallSelectedMission, onMissionSelected, eraseSelectedModFromDisk
• mainmenu_objectives.gui: objective_open_request, close, gui::mapStartCmd, objective_scroll_down_request, objective_scroll_up_request
• mainmenu_objectives_core.gui: exec tdm_restart_gui_update_objectives
• mainmenu_quit.gui: quit
• mainmenu_restart.gui: exec tdm_restart_gui_update_objectives
• mainmenu_settings.gui: loadSettings, darkmodRestart
• mainmenu_settings_audio.gui: sound, sound eax, settings_controls.gui:
• mainmenu_settings_gameplay.gui: updateAIVision, updateAIHearing, setPDifficulty, 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, gui::mapStartCmd, shopBuy, shopSold, shopDropUndrop, shopMore
• mainmenu_success.gui: loadStatistics, onSuccessScreenContinueClicked
• mainmenu_utils.gui: mainMenuStartup, loadCustomVideoResolution, loadVideoDefinitions, close, * mainmenu_heartbeat

Within Other Core GUIs

• msg.gui: left, mid, right
• restart.gui: restart, exec disconnect, exec tdm_restart_gui_update_objectives
• 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
• tdm_waituntilready.gui: playerIsReady
• readables\test\book<n>page.gui: close

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.

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 modiwki