After working with the Doom 3 GUIs a while you will both love and hate them. GUI of course stands for Graphical User Interface. The GUI system is used for every single menu in the game, as well as the HUD, and random control panels you see placed around the levels. The system in Doom 3 is pretty simple in that there aren't very many commands, but the ones that are there are very powerful.

The whole system is based around nested windows and events (like javascript). There is one top level window called 'Desktop', then one or more windows that are 'children' of the desktop, then zero or more windows that are children of the children, etc...

Here's an example of a very simple GUI that could be used as a display on a computer screen or something (since it's not really interactive):

windowDef Desktop {
    rect      0, 0, 640, 480
    backcolor 0, 0, 0, 1

    windowDef Text1 {
        rect        35, 50, 285, 200 
        backcolor   0.5, 0.6, 0.6, 0.3
        bordercolor 0.5, 0.6, 0.6, 1
        bordersize  1
        text        "This is some Text!"
        font        "fonts/bank"
        textscale   0.5
        textalign   1
        shadow      1
        forecolor   0.7, 0.7, 0.4, 1
        visible     1

        windowDef Text2 {
            rect        5, 80, 275, 20 
            backcolor   0.0, 0.0, 0.0, 0.3
            bordercolor 1, 1, 1, 1
            bordersize  1
            text        "This is more Text!"
            font        "fonts/bank"
            textscale   0.5
            textalign   1
            textaligny  -13
            forecolor   0.4, 0.7, 0.7, 1
            visible     1
        }
    }

    windowDef Text3 {
        rect        350, 400, 285, 200 
        text        "Amazing"
        textalign   1
    }
}

To see what this looks like, paste the above code in to a file called "mygui.gui" in the "guis" subdirectory of your mod, then type, "testGUI guis/mygui.gui" in the console. If you want to change something and see the results, you don't have to exit the game. You can just type, "reloadGuis" in the console, and the change should show up immediately. For more advanced guis, you may have to hit escape and use "testGui" again after using "reloadGuis".

Now let's go ahead and make it a bit more interesting. Change the definition for Text3 to this:

windowDef Text3 {
    rect        350, 400, 285, 200
    text        "Amazing"
    textalign   1

    onTime 0 {
        transition rect "350, 400, 285, 200" "350, 300, 285, 200" "2000" ;
        transition forecolor "1 1 1 1" "1 0 0 1" "1000" ;
    }
    onTime 1000 {
        transition forecolor "1 0 0 1" "0 0 1 1" "1000" ;
    }
    onTime 2000 {
        transition rect "350, 300, 285, 200" "350, 400, 285, 200" "2000" ;
        transition forecolor "0 0 1 1" "1 1 0 1" "1000" ;
    }
    onTime 3000 {
        transition forecolor "1 1 0 1" "1 1 1 1" "1000" ;
    }
    onTime 4000 {
        resetTime 0 ;
    }
}

Amazing indeed. This simple change makes the amazing text bounce up and down while changing colors.

This code basically says:

• At time 0: Start a transition of the rectangle from "350, 400, 285, 200" to "350, 300, 285, 200" over 2 seconds, and start transitioning the foreground color from white to red over 1 second.
• At time 1000 (1 second): Transition from red to blue over 1 second.
• At time 2000 (2 seconds): Transition the rectangle back down over 2 seconds, and transition the color from blue to yellow.
• At 3 seconds: Trasition from yellow back to white over 1 second.
• At 4 seconds, start all over again.

The built in timer and the transition commands are very powerful tools. It should be noted that each window keeps it's own timer, so 'resetTime 0' only resets the time for the current window. If we wanted to reset the time for another window, we could say "resetTime Text1 0" and if we wanted to transition properties of a different window, we would say "transition Text1::foreground ..."

The other thing to note is a semicolon is required at the end of every line inside a script block. We will learn about script blocks in a second, but anything that starts with "on" is probably a script block.

Our gui is currently very fascinating to look at, but we can't do anything with it... yet.

There is a small issue witth the 'testGUI' command. You'll notice you don't have a cursor when you testGUI, but if you apply this gui to a surface in game, the cursor will appear. This is because world guis are handled a bit differently than menu guis. For testing purposes, we're going to turn our world gui into a menu gui so we can use the cursor with the 'testGUI' command. Set 'menugui 1' in the desktop window, and you will see your cursor when you testGUI (side note: to turn off the cursor for world guis, set 'nocursor 1').

Even though you can move your cursor around, you still can't click stuff. Why don't we go ahead fix that now. Add "notime 1" to Text3, and replace "onTime 4000" with this:

onTime 4000 {
    set notime 1 ;
}
onAction {
    set notime 0 ;
    resetTime 0 ;
}

Assuming all went well, the amazing text should do it's little dance every time you click it. Amazing.

If typing text really isn't your thing, there is a gui editor. Type 'editGuis' at the console to launch it. A word of warning: It tends to crash. a lot. And it doesn't handle very complex guis with a lot of transitions too well (it only shows the windows in their initial states). I use it to lay out a basic idea of what I want, then go in to the .gui file to fix it up and add scripts.

Window Types

Event handlers

Script commands

Window registers
These can be changed at run time with the set command (or transition for vecs and floats)

Additional user variables may be defined with the 'definevec4', 'definefloat', and 'float' commands. Note you cannot set the initial value for the variable (it will always be 0). There are guis in Doom 3 that specify an initial value, but it is ignored. Example:

windowDef Desktop {
    rect      0, 0, 640, 480
    backcolor 0, 0, 0, 1
    float     myfloat
    definefloat myotherfloat
    definevec4  myvec4
}

Window variables
These can be changed in the file, but cannot be changed at run time

Window variables (editDef)

Window variables (choiceDef)

Window variables (sliderDef)

Window variables (bindDef)

Window variables (listDef)

Window variables (renderDef)