GUI scripting

What’s this?

GUI scripting quick reference

- GUI items - GUI item properties - GUI variable types - GUI item events - GUI commands

GUI scripting is the system used on the GUI files when creating GUIs . The GUI scripting syntax is very different from the one featured on other scripting systems available on the engine. More than a programming language, it’s a layout system, where you can create buttons and images that will be displayed; its scripting features are also quite limited, and oftenly, a developer has to resort to using external script (for example, some level scripting ) to add advanced features to a given GUI.

Still, it’s a very powerful system to use, as it allows a multitude of new interactions inside the game and is quite easy to work with (you can change GUI files externally and reload them inside the game without having to recompile or restart anything).

Also, notice that this system is a natural evolution of what’s called the Team Arena menu system , a similar GUI system that has been available on id Software’s Team Arena version of the Quake 3 engine.

General schematics

A GUI script is composed of several different elements “windowDefs”, “renderDefs” or other types of elements, refered on this wiki as “items”. Each item is an screen element, whether visible or not, and it is used to build interface elements such as buttons, text fields, windows, menus and so on. Think of it as floating HTML elements, or Visual Basic elements, or Flash symbols/movieclips, or XUL box tags. It’s an standard approach to markup-based user interfaces , although the Doom 3 GUI system syntax itself looks more like an script than a markup system.

This is a sample GUI script:

windowDef Desktop {
    rect        0, 0, 640, 480
    windowDef title {
        rect        10, 10, 620, 460
        visible     1
        backcolor   0.7, 0.7, 0.7, 1
        forecolor   1, 1, 1, 1
        text        "Hello world."
        textscale   1
        font        "fonts/english"
    }
    windowDef button {
        rect        110,110,420,260
        visible     1
        background  "assets/close"
        matcolor    1, 1, 1, 1
        float       "alreadyClicked" 0
        onAction {
           // Makes the title invisible
            set "title::visible" "0";
            set "button::alreadyClicked" "1";
        }
    }
}

This example is a blank screen, with a “Hello world.” text on top of it, and a button that hides the text. You can see there’s one main windowDef (the Desktop GUI item ) which always has a fixed name and size - it’s the main document windowDef, let’s say - and it contains several children windowDefs inside of it, which make up the elements on screen.

Reference

The reference is meant to be a list of everything that can be done inside a GUI.

  • Items - Each GUI is made of several different items of different types.
  • Item properties - Each item can have a lot of properties define how they look like and how they act.
  • Variables types - Each item can also have additional variables.
  • Events - Items can have events that get called under certain conditions.
  • Commands - And of course, items can have some commands for simple scripting.

Additional syntax

There are two special syntax cases: comments and includes .

Comments

Comments are the classical unusable part of a GUI script. Lines marked as comments are completelly ignored by the game, so you can use comments to create special annotations on the script – something you need to remember, something you need people that’s messing with the code to know, something you want to turn off, etc. The GUI script accepts the two classical comment notations: “//” and “/* */”.

The comment marker “//” is used on the beginning of lines you want to mark as comments. Everything from the “//” on is ignored, so you can use comments on lines with code to mention important information. Example:

// Makes the title invisible
set "title::visible" "0";
set "button::alreadyClicked" "1"; // So it'll remember not to execute anymore

And the comment markers “/* */” are used to start and end comment blocks. They’re more fit to large pieces of text, or just multiline ones. Example:

/*
War Is Peace
Freedom Is Slavery
Ignorance Is Strength
*/

Remember that adding comments delimiters are the easiest way to “turn off” certain parts of the code - to “comment out” them - so it’s pretty normal to see comment blocks which actually contain scripts.

Includes

Includes exist to save on space and help reusing code. To do includes, use the #include keyword. With this keyword, you can include separate scripts (from other files) directly into your code – when the script gets interpreted by the GUI system, it behaves as if the script it’s referencing was included on that same line. For example,

#include "guis/gui_flicker.pd"

It’s the same as copying & pasting the content of guis/gui_flicker.pd file on this line.

Using #include is great for organization and portability, and you can use it anywhere on your GUI script. It also works exactly like the #include statement in Flash’s ActionScript.

  • GUIs at iddevnet - A lengthy explanation of the GUI system and its syntax. Very good resource.