GUI Scripting: References & Resources

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

FYI - Earliest id Games – Before GUI Scripting

Initially, there was no GUI scripting language, just UI coding in C. See for example:

• For Quake 3 , a 3-part 2001 UI Tutorial by IoN_PuLse, starting with UI Coding Tutorial #1
• For Quake 3 Arena, tutorials about HUD scoreboard (by Heffx) or popup menus (by HypoThermia).

Doom 3/Quake 4 GUI Tutorials and Reference Lists

Much of this TDM wiki "GUI Scripting" series, particularly about Properties, draws from the first 3 references listed next, arguably the three best tutorials and language references of the Doom 3/Quake 4 era. While the original host sites are no more, these pages have been migrated with reformatting to dhewm3. Alternative sources (probably without reformatting) are shown in some cases.

Ref 1 - Making Doom 3 Mods: GUIS

Original Source - www.iddevnet.com

From the original 2004 id Studios documentation, part of an extensive tutorial series "Doom3 Software Development Kit, Making Doom 3 Mods". This particular page includes a walkthrough using the "testguis" command. See GUI Scripting: Tools, for additional commentary about doing that.

Current Source - iddevnet.dhewm3.org

• "Making Doom 3 Mods: GUIS"

There is also a link to a brief mention of editguis

Alternative Source - old.mrhide.fr

• editguis

Ref 2 – Doom 3 GUI Scripting

Original Source - www.modwiki.net

This Doom 3 "GUI scripting quick reference" is possibly due to Zeh. The site has these main child pages:

• Items (i.e., guiDef types)
• Item properties
• Variables types (i.e., User variables)
• Events
• Commands

and further breakouts from those.

Current Source - modwiki.dhewm3.org

• "GUI scripting"

Alternative Source - Wayback Machine

• "GUI scripting".

(An archived copy of this same content from from wiki.doom3reference.com doesn't appear to retrieve correctly.)

Ref 3 – Quake 4 GUIEditor [and Language]

Original Source - www.iddevnet.com

Both Doom 3 and Quake 4 have their own versions of an embedded "Quake 4 GUI Editor" invoked by "editguis". See GUI Scripting: Tools. Between Doom 3 and Quake 4, these tools - and their underlying languages and usage - are similar but not identical. So use this 2005 Quake 4 information with caution. Why list it here? Because for many aspects it’s the most informative.

This source has the following top-level contents:

• Using the GUIEditor
• Guidelines for GUI Editing and Creation
• Scripting Actions and Animations
• Floats, Definevec4, and NamedEvents
• Def Types
• Def Flags
• GUI Variables
• GUI Parms
• Font Information
• Adding Fonts to use in Quake 4 GUIs
• Placing a GUI In a Map

Current Source - iddevnet.dhewm3.org

• "GUIEditor" (Quake 4 version)

Ref 4 - Zeh's "(not yet) Complete GUI reference"

Original Source - wiki.doom3reference.com

This Oct 2007 post is probably a predecessor to Ref 2 here. Includes credits to rich_is_bored, goliathvt, patd, kazahana, Eutectic.

Ref 5 - Zeh’s Doom 3 "Complete GUI Scripting" Tutorials

Original Source - www.doom3world.org

In 2004, zeh (aka Zeh Fernando), developed an informal "Complete GUI Scripting" tutorial in a doom3world forum. This was subsequently migrated to modwiki, and then more recently to dhewm3. A work-in-progress introduction to the series can be seen in zeh’s personal page, but the links there no longer work.

Current Source - modwiki.dhewm3.org

From https://modwiki.dhewm3.org/doom3world/ or https://modwiki.dhewm3.org/Tutorial_list#zehs-tutorials

• Tutorial 0: A GUI script primer
• Tutorial 1: Your first GUI script
• Tutorial 2: Using the built-in GUI editor.
• Tutorial 3: Preparing and importing assets (cake status reporter #1). IMPORTANT: In this link, two versions of the content are appended: the first is missing its images, the second is complete.
• Tutorial 4: Making simple interactions (cake status reporter #2)
• Tutorial 5: Applying a GUi script to a map (cake status reporter #3)
• Tutorial 6: Creating a new HUD GUI (classic DOOM HUD #1)
• Tutorial 7: Creating basic HUD items (classic DOOM HUD #2)
• Tutorial 8: Using named events (classic DOOM HUD #3)
• Tutorial 9: Animating the marine face HUD (classic DOOM HUD #4)

See also 2 additional tutorials available from Wayback Machine

Alternative Source - Wayback Machine

• Tutorial 0: A GUI Script Primer
• Tutorial 1: Your First GUI Script
• Tutorial 2: Using the GUI Editor
• Tutorial 3: Preparing and Importing Assets
• Tutorial 4: Making Simple Interactions
• Tutorial 5: Applying a GUI script to a map
• Tutorial 6: Creating a new HUD GUI
• Tutorial 7: Creating basic HUD items
• Tutorial 8: Using named events
• Tutorial 9: Animating the marine face HUD
• Tutorial 10: Using custom fonts (classic DOOM HUD #5)
• Tutorial 11: Editing fonts (classic DOOM HUD #6)

Ref 6 – Doom 3 Tutorials by Rich_is_bored

Original Source - www.doom3world.org

Links to Wayback Machine archived versions of this tutorial and Zeh’s above, originally at (now defunct) doom3world.org, were found at this page

Current Source - Wayback Machine

• Quick & Dirty GUI Tutorial
• GUI Command Reference (work in progress)
• Security Camera Tutorial
• Making Video GUIs

Ref 7 - Demo Video by CruiseLinerMod

A 2014 YouTube video showing examples of custom interactive GUIs, as video screens, in Doom 3 style maps. Note the mouse cursors characteristic of Doom 3 interactive GUIs.

• Demo Video by CruiseLinerMod

Ref 8 - Doom 3 Test Project by Jared E. Mitchell

The link shows project work on several platforms. For the section related to Doom 3, parts of a project is shown, evidently involving an in-game monitor with a cursor-driven 2D puzzle, where "walls" are represented by colored bars. A screenshot shows development using editguis, and a portion of a GUI script with "runscript" commands in the event handlers. (There is a video, but inaccessible.)

• Scripting Examples

Ref 9 - C++ Class Reference for Doom 3 GPL

A visualization of Doom 3’s hierarchy structure, specifically related to classes implementing guiDefs.

• Classid Window diagram.
• Window.cpp source code.

Ref 10 - TDM Forum Posts by HMart et al

• July 2020, about differences between TDM & Quake 4.
• 2019, about raising an event from inside a GUI event handler.

Ref 11 - TDM Forum Posts by ishtvan et al

• interactive gui surface

TDM Resources Used in Analysis

TDM’s Core GUIs

GUI code full-examples, snippets, and analysis of usage frequency are largely based on TDM 2.10 core menus .gui files, found in tdm_gui01.pk4. This includes (within /guis/) the hierarchy of main menu .gui files, that starts with "mainmenu.gui" and #includes the others (tagged as mainmenu_*.gui). The main menu hierarchy includes not only the starting menu but also briefing, videos, objectives, load/save, missions success, and credits. The GUIs in these files call into the C++ code, as detailed in See GUI Scripting: Parsing of Set 'Cmd'. Those calls appear in event handlers (usually onAction or onTime, less commonly onMouseEnter or onNamedEvent).

TDM’s Core .Scripts and Engine Code

Understanding of GUI syntax and coverage, and development of code snippets and examples, sometimes required delving into associated TDM 2.10 script objects and the underlying engine C++/H source code (2.10 or 2.11 pre).

TDM FM Inspection

A sampling of TDM games (locally acquired during TDM 2.07-2.10 but including games created earlier) was available to text-search. This could provide supplementary insight into patterns of usage, e.g. of .gui and .script features.