GUI Scripting Language: Difference between revisions
Add section Names & Case Sensitivity |
|||
Line 36: | Line 36: | ||
===Tools & Tricks for GUI Scripting=== | ===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. | 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. | ||
====Names & Case Sensitivity==== | |||
* [[GUI Scripting: Names & Case Sensitivity]]. A gloss on when keywords and other names of things in the GUI are case-sensitive or insensitive, and related naming conventions and styles. Case issues can cause parser fails! | |||
====Syntax, Semantics, & Usage==== | ====Syntax, Semantics, & Usage==== | ||
* [[GUI Scripting: Syntax, Semantics, & Usage]]. A comprehensive list of "rules of thumb", with some highlighted, to help cope with the "syntax from hell". | * [[GUI Scripting: Syntax, Semantics, & Usage]]. A comprehensive list of "rules of thumb", with some highlighted, to help cope with the "syntax from hell". |
Revision as of 19:43, 4 October 2022
Overview and hub 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 ("Graphical User Interface") 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.
FM Customizing 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
- Creating Automaps
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.
Names & Case Sensitivity
- GUI Scripting: Names & Case Sensitivity. A gloss on when keywords and other names of things in the GUI are case-sensitive or insensitive, and related naming conventions and styles. Case issues can cause parser fails!
Syntax, Semantics, & Usage
- GUI Scripting: Syntax, Semantics, & Usage. A comprehensive list of "rules of thumb", with some highlighted, to help cope with the "syntax from hell".
Tools
- GUI Scripting: Tools. How to edit and test GUIs. Because GUI scripts are in separate files (with the .gui extension), they can be developed independently from the rest of the game code. A change in a GUI does not require a DMAP (unless an associated entity changes). Furthermore, GUI scripts can be reloaded on real time, which makes for easy debugging and testing.
Debugging
- GUI Scripting: Debugging. Ways to display or log info during GUI activity.
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> }
Nesting of child guiDefs can be as deep as you need.
Property List
This is zero or more "Properies", by convention 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", by convention 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, and has general syntax:
<onHandler> [handler_param] { <If-Clauses> and <GUI Script Commands> }
The two most widely used event handlers are:
- onTime time - fires when time in milliseconds is reached, for the specific guiDef’s timer.
- onNamedEvent event - Catches a custom event, generated by your entity’s script function (e.g., in a script object). Or catches an engine-generated event. See GUI Scripting: Named Events.
For a full list, with syntax and usage examples, see GUI Scripting: Event Handlers.
If Statements
Within the body of an Event Handler, if-clauses read or compare properties and user variables, then alter program flow accordingly. Basic syntax is:
- if (condition) {...} else if (another_condition) {...} else {...}
For details, see GUI Scripting: If Statements
GUI Script Commands
In the body of an Event Handler, including within arms of if-clauses, GUI script commands read and change properties, user variables, GUI: parameters, and timer functions. Most widely used are:
- set variable value_or_source;
- transition property start_value end_value time_duration [accel decel];
- resetTime time;
For a full list, with syntax and usage examples, see GUI Scripting: Commands.
Names and Scope [REVISE THIS FURTHER]
Unlike some other languages, properties and user variables in a parent guiDef are not immediately visible to a child. Instead, the parent's name must be included as a prefix followed by "::" (two colons):
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:
Good to Know
GUI:: Parameters
- GUI Scripting: GUI:: Parameters. How values are passed between a .gui and .script.
Handles
- GUI Scripting: Handles. Referencing a GUI from a script function.
Interactions[maybe]
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: Number Wheel Example
- GUI Scripting: In-World Menu Examples. Working with a "Entity GUI" on an in-game surface, to both emulate and deploy a choiceDef.
- GUI Scripting: Inventory Icon Example. Extend the skull-on-pedestal example from Inventory, to color-pulse that skull's inventory icon with a custom GUI and a generally-useful template for an inventory script object. More about GUI::Parameters too.
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.
Main Menu Tool Tips
Near the bottom of a guiDef for the main menu system, you may see something like:
toolTip("#str_menu_fov_tooltip")
See GUI Scripting:Tooltip Macro for more.
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; see GUI Scripting: TDM vs Doom 3, Quake 4.)
Follow the links below for details about each type, including their additional Properties.
Used throughout the core main menu hierarchy:
EditDef
See GUI Scripting: EditDef - text input, e.g., the name of a game save file, and for specifying certain video options.
ChoiceDef
See GUI Scripting: ChoiceDef – widely used for making choices among settings.
SliderDef
See GUI Scripting: SliderDef – widely used as a horizontal slider to control a setting value.
ListDef
See GUI Scripting: ListDef – provides a scrollable multi-column list control. Examples include mission downloads, mission select, and saved game select.
Rarely used:
BindDef
See GUI Scripting: BindDef – used just In the Controls submenu, to bind particular keys to particular functions.
RenderDef
See GUI Scripting: 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.
Additional Event Handler Commands
Set 'Cmd'
For a way for a main-menu GUi to invoke C++ engine functions, see GUI Scripting: Parsing of Set 'Cmd'.
Fetching CVars
See GUI Scripting: Getting System CVars.
Arcana
Formal Syntax Definition
See GUI Scripting: BNF.
TDM vs Doom 3 or Quake 4
For usage and nomenclature differences, see GUI Scripting: TDM vs Doom 3, Quake 4.
References and Resources
For sources used in this series, including other early GUI scripting tutorials, see GUI Scripting: References & Resources.