GUI Scripting: TDM vs Doom 3, Quake 4

From The DarkMod Wiki
Revision as of 22:29, 21 July 2022 by Geep (talk | contribs) (Add Event Handlers section)
Jump to navigationJump to search

This page is part of a series. See GUI Scripting Language for overview.

TDM's GUI scripting usage has evolved from the original open-sourced idTech 4 engine and Doom 3. It is thus quite similar but not identical to Doom 3, as well as Quake 4 or other id-family games. This may need to be kept if mind if you are using a tutorial or GUI editing tool for these other games.

Nomenclature Differences Among Tutorial Sources

The rather odd naming of GUI elements by id Software was not a big hit with subsequent documentation authors, who chose other nomenclatures:

[table TO DO]

[Note 1] This nomenclature is what's generally used in the "Quake 4 editguis" editor, including the version included with Doom 3.

[Note 2] Window Registers can be changed with 'set' or 'transition'. Window Variables cannot, so constant.

"Window Types" are analogous to Microsoft Dialog Controls. The id nomenclature reflects the C++ code; thus .h and .cpp files with names like Windows and WinVar (and references to Registers) comprise part of the implementation. Also important are OverlaySys, UserInterface, and the system to post and dispatch events.

Usage Differences

This analysis is based on a "reasonable effort"; it should not be taken as definitive or complete.

In-Game Active Surfaces

Doom 3 has interactive GUIs to show a 2D mouse cursor on an in-game 2D surface, e.g., an in-game computer screen, with active buttons and text input areas. There were stock models designed for this (e.g., flatmonitor.lwo).

This purpose is far less important for TDM, due to its different historical period. And TDM has other ways to provide in-world buttons, either flat (e.g., simple frobbable surface) or 3D. Consequently, the SDK code to support this form of interactive GUI was removed in TDM, as unlikely to be useful and complicating frob highlighting. See post by ishvan (Ref 11).

Still, TDM uses GUIs applied to in-game surfaces for some purposes, e.g., readables or custom video effects. Anf for full-screen overlays, supports the mouse cursor.

guiDef Types

Fully Supported in TDM, Doom 3, Quake 4

bindDef, choiceDef, editDef, listDef, renderDef, sliderDef, windowDef

Types for which Support Varies

Key:

Y = Supported, used

N = Probably or definitely no code for this

n = Some leftover C++ code for this, but probably either skips over or breaks 

guiDef           TDM  Doom 3  Quake 4
animationDef      n      n      N
fieldDef          n      n      N
gameBearShootDef  N      Y      N
gameBustOutDef    N      Y      N
gameSSDDef        N      Y      N
graphDef          N      N      Y
htmlDef           N      N      Y
markerDef         n      n      N
popupDef          N      N      Y

Chief source for Doom 3: Ref 9 - C++ Class Reference for Doom 3 GPL

Chief source for Quake 4: Ref 3

Properties

Fonts in GUI Text

TDM fonts are entirely different from Doom 3 and other id fonts (presumably for legal and licensing reasons). See Fonts for TDM choices.

Shortcut to Components of Vectors such as Colors

For 4Vect properties (e.g., RGBA properties like backcolor, bordercolor, matcolor, forecolor), individual R, G, B, Alpha values can be referenced by notation like backcolor_x, backcolor_y, backcolor_z, backcolor_w. This is available in Quake 4, as described in Ref 3, but not in Doom 3 or TDM [[GUI Scripting: Resources & References | HMart 2020 (Ref 10)].

Event Handlers

onTime time

Then you have a sequence of onTime event handlers inside a guiDef, Quake 4, but not TDM or Doom 3, allows time in milliseconds to be specified relative to that of the preceding onTime, with a plus-sign prefix. Example syntax: 

onTime +100 {

Event Handler Commands

Commands for which Parsing Code Exists in TDM

As of 2.10 in GuiScript.cpp. But not necessarily functionality! Commands seemingly not pertinent to TDM are in parentheses. See discussion about individual commands further below.

  • resetCinematics;
  • resetTime [guiDef] time;
  • set parameters;
  • setFocus bool;
  • showCursor bool;
  • transition 4-6 parameters;
  • (endGame;)
  • (evalRegs;)
  • (localSound sound;)
  • (runScript function;)

Also, there are additional parenthetical commands discussed below, that have no parsing code in TDM.

resetCinematics; – additional parameters?

Note: TDM's code in GuiScript.cpp seems to show that this can take 2 optional parameters, but what are they? No use of additional parameters was seen in TDM, but maybe in Doom 3 or Quake 4? Speculatively: 

resetCinematics [guiDef_name] [time];

resetTime [guiDef_name] time;

In some idTech4 documentation, time itself is also optional and assumed zero, TDM can crash if the time parameter is omitted.

(set "cmd" runscript function;)

Runs the specified function in the game script. Like "runScript function", this form is believed to be quietly parsed but ignored in TDM.

The RunScript page of Ref 2 – Doom 3 GUI Scripting indicates that this command was widely used in id Software's code.

set "cmd" command_keyword command_parameter;

In a GUI event block, this special form of the "set" statement issues a GUI command to the engine code. On a multiplayer game, it's to the local client. This distinction is of no importance to single-player TDM. Similarly, some calls to the engine code were forwarded to game code when those were separate code bases. They are merged in modern TDM, but internal call patterns can reflect this history. Also, in TDM, only the core developers, not mappers, can take direct advantage of this form. The evolving collection of cmd command keywords for TDM is now quite different than for Doom 3. For example [[GUI Scripting: References & Resources | Ref 10 - HMart 2020], in Doom 3, the main menu starts up a map automatically with a set "cmd" "startgame..." inside an onTime handler. The mapper could do this more generally, for example: 

onTime 12000  // after 12 seconds
{
   set "cmd" "startgame test.map";
}

whereas TDM has no startgame keyword. For more about what TDM supports, see GUI Scripting: Parsing of Set 'Cmd'.

transition 4-6 parameters

Ref 10 HMart recommended TDM try to implement a way for GUIs to "use colors defined with #define on transitions as well [as float parameters], instead of having to use definevec4 in the Desktop window."

However, TDM can #define colors for transitions (and separatedly for color properties). See GUI Scripting: Preprocessor Directives. Perhaps HMart was referring to an earlier TDM version, or recommending some method (other than definevec4) used in another idTech4 family platform, that would allow a single color #define to work with both properties and transitions.

See also the discussion above about 4vect properties and _x, _y, _z, _w suffixes.

(endGame;)

Ends the game. In multiplayer Doom 3, causes disconnect. Unused in TDM.

(evalRegs;)

Re-evaluates window registers (variables). [[GUI Scripting: References & Resources | Ref 1] says: should not be needed anymore in Doom 3. Unused in TDM core.

(localSound <sound>;)

Plays a sound given by a sound shader or a file path. Used in Doom 3, but not functional in TDM. If working with the main menu, consider alternatives like: 

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

Mappers can control sounds by other means, e.g., with .script files.

(runScript function;)

Runs the specified function in the game script. Believed to be quietly parsed but ignored in TDM. According to [[GUI Scripting: References & Resources | HMart (Ref 10)], the function can be specified either of two ways:

  • As the name of a particular function in a map script:
runScript "map_name::functionName";
  • As the name of a placeholder spawnarg (like gui::gui_parm6) on the attached entity, that has the function name, e.g.:
runScript "gui::gui_parm6";

The RunScript page of Ref 2 – Doom 3 GUI Scripting indicates that runScript could be used by mappers in Doom 3. This would seem to be confirmed by a "RunScript "gui::gui_parm" line seen in a GUI of Ref 8 – Doom 3 Test Project.

However, Ref 1 – Making Doom 3 Mods reported "runScript" as unused; maybe just by id developers, who can use the "set 'cmd' runscript alternative?

In any case, as noted, TDM seems to quietly parse but otherwise ignore any effort to call a user .script function from a GUI. See also "set 'cmd' runscript function" above.

(namedEvent <eventName>;)

Available in Quake 4 but not Doom 3 or (to date) TDM (Ref 10 - HMart 2020). Within an event handler, a named event can be raised, which would then be handled elsewhere in the GUI, using an onNamedEvent handler of the same name.

HMart in 2019 (Ref 10) reported adding this functionality to a custom version of the idtech4 engine ("fhDoom") and suggested C++ code to add it to TDM.

(onInit;)

Quake 4 calls this when GUI is loaded. Doom3 and TDM would presumably use onActivate or onTime 0.

.Script Commands Related to GUIs

SetGuiParm Commands In Doom3, if an entity had multiple GUIs, the SetGui... commands in .script would broadcast values to all of them. If this was not wanted, the GUIs would have to be undesirably edited to make keynames unique. In TDM, the handle to a particular GUI (namely, 1, 2, or 3) is given, so the value propagation is individualized.

CVars

Suffice it to say, lots of differences here too, with plentiful new CVars added to TDM. For access to CVars by .gui and .script, see GUI Scripting: CVars.

The editGUIS Tool

The specialized "editGUIS" editor is [add ref to bugtracker] broken under TDM (probably since 2.0). Alternatives are discussed in GUI Scripting: Tools and GUI Scripting: EditGuis Editor.

Retrieved from "https://wiki.thedarkmod.com/index.php?title=GUI_Scripting:_TDM_vs_Doom_3,_Quake_4&oldid=29717"