GUI Scripting Language

Overview of the "GUI Scripting" series by Geep, 2022

IMPORTANT: THIS PAGE & SERIES IS A WORK IN PROGRESS

Introduction

Inherited from Doom 3, TDM has a specialized GUI layout language within .gui text files to define:

• Full-screen dialogs, such as menus
• Screen overlays, such as popup messages, HUD items and underwater murk.
• Active game-world surfaces like readables or custom video effects.

This language differs from that of .script files. It describes the visual appearance and (to some extent) behavior – including text display - of nested rectangular areas. For mappers, these areas can be manipulated through .script files. Beyond that, for menu developers interfacing to C++ code, it allows defining what MS Windows traditionally called "dialog controls", for selection from lists or multiple choices, setting values from sliders, and entry of text.

The Basics for Mappers

Need I Learn GUI Scripting?

Often not! For the mapper, much can be accomplished without much GUI wrangling.

Customizing Aspects of Your FM Using Only #defines in a Standard GUI

The TDM main menu hierarchy is set up to allow you to customize it without really knowing GUI scripting, just by commenting/uncommenting particular #defines. Such customizations include:

• Main menu background art or music
• Aspects of pre-mission briefing (text or video)
• Aspects of post-mission debriefing (text or video)

You do this by overriding the core "guis/mainmenu_custom_defs.gui" file with your own altered copy. See the comments in that file for details.

Deploying Stock GUIs or the Entities that Use Them

For many things you want to do, there’s already a provided gui-using entity and/or stock or sample .gui files. For particular guidance, see:

• Briefing and Video Briefing
• Full-Screen Video Cutscenes
• A Full-Screen Slide in Mid-Game
• Subtitles
• Popup messages
• Readables
• Text_Decals_for_Signs_etc.
• Swimmable Water#Coloured, Murky Water

Tools & Tricks for GUI Scripting

Occasionally, you may need to craft a .gui from scratch, or as a novel customization. You can do this in a text editor, but be aware that the .gui language is quirky, and the existing parsing system unhelpful in detecting errors.

• GUI Scripting: Syntax & Usage. Tips for coping with the "syntax from hell".
• GUI Scripting: Tools. How to edit and test GUIs.

A Basic "windowDef" Template

With nomenclature used in this series.

Every .gui file (unless designed just to be #included) must have a top-level "windowDef" structure, typically named "Desktop". Nested within, there may be more windowDefs (and other members of the "guiDef" family described further below), each with a locally-unique <name>. The basic template outline, with the terminology used in this series, is:

windowDef <Name> {
<Property List>
<User Variable List>

<Nested Child windowDefs or other guiDefs>

<Event Handlers>
}

Property List

This is zero or more "Properies", each on its own line. A Property has a predefined name, type (Boolean, float, vec2, vec4, string) and default value. If a property is not listed, it still exists, with its default value.

• GUI Scripting: Properties in Common to all guiDefs, and the only properties of windowDefs.

User Variable List

This is zero or more "User Variables", each on its own line. Unlike Properties, a User Variable is not predefined. This is a float typically used as a bool. It always has a default value of 0.

• GUI Scripting: User Variables, likewise applicable to all guiDefs.

Event Handlers

An "Event Handler" catches user actions, .script requests, or elapsed time occurrences. There are various particular types (e.g., onTime 0 {…}). Its body contains "GUI script commands", that can read properties and user variables. User variables, and some properties (known as "Registers"), can also be altered within the Event Handler, using the "set" or "transition" commands.

• GUI Scripting: Event Handlers, including their GUI Script Commands.

Names and Scope [REVISE THIS FURTHER]

Unlike some other languages, properties and user variables in a parent windowDef are not immediately visible to a child. Instead, the parent's name must be included as a prefix followed by "::":

windowDef Desktop {
  visible 1
  windowDef Child1 {
      visible "Desktop::visible"
  }
} REVISE THIS FURTHER

Also, there are GUI:: Parameters, that can be shared among guiDefs and .scripts. See:

• GUI Scripting: GUI:: Parameters

Good to Know

• GUI Scripting: Handles
• GUI Scripting: Interactions
• GUi Scripting: Preprocessor Directives

Examples [REVISE DESCRIPTIONS]

• GUI Scripting: Mission Start Example. This TDM code approaches "Hello, World" in simplicity.
• GUI Scripting: Popup Message Example Slightly more complex, sketching how an Entity, GUI, and script object collaborate to get results.
• GUI Scripting: Sign Text Example Another example of custom tweaking an entity and GUI, in this case to center text on a sign.
• GUI Scripting: Flashbomb Example
• GUI Scripting: On Entity's Surface. Apply video or special effects.

More Advanced Topics

Developers working on improvements to TDM core systems - the main menus, briefings, HUD, or entities with active surfaces - must be conversant with additional aspects of GUI scripting. Mappers too will want to understand such aspects if they are developing analogous but novel visual items.

Other "GuiDef" Types

The term "guiDef" has been coined here to describe the main layout structure shown in the template above, but generalized beyond just windowDef. (Other tutorial authors use "Window", "Item", or "Def" for this.) Details about each type can be found in their Properties descriptions.

Used throughout the core main menu hierarchy:

• editDef - text input, e.g., the name of a game save file, and for specifying certain video options.
• choiceDef – widely used for making choices among settings.
• sliderDef – widely used as a horizontal slider to control a setting value.
• listDef – provides a scrollable multi-column list control. Examples include mission downloads, mission select, and saved game select.

Rarely used:

• bindDef – used just In the Controls submenu, to bind particular keys to particular functions.
• renderDef – used to show a 3D model in an guiDef, typically an overlay. This is not a static snapshot or sprite, but an object that could be oriented, e.g., by code. In the game HUD, used for the compass playertool.

Details

• GUI Scripting: Properties Def-Specific to choiceDef, editDef, etc.

Additional Event Handler Commands

• GUI Scripting: Parsing of Set 'Cmd'. A way for a GUI to call C++ engine functions.
• GUI Scripting: Getting System CVars

Arcana

• GUI Scripting: TDM vs Doom 3, Quake 4. Usage and nomenclature differences.
• GUI Scripting: References & Resources used in this series. Includes other early GUI scripting tutorials.
• GUI Scripting: EditGuis Editor