Complete GUI Scripting - 2: Using the built-in GUI editor
Something that's cool with the DOOM 3 engine is that it has several built-in editors, allowing you to edit the game content right out of the box. While this can be pretty wacky - people would have to run the game, *then* the editor to open some content for edition - it means that you can preview whatever you are doing in real time.
This is pretty well know for map editing - the map editor is integrated with the game - but what many people don't know is that many other editors are integrated into the game too - and this include, among many others, a GUI editor.
To launch the GUI editor, the normal thing to do is to fire up the game, and type
Code:
editguis
DOOM 3 will 'close' and the GUI editor will launch.
There is, however, one catch. Like other editors, it launches a new windows-like application, and if you are using some low resolution on the game, you'll be stuck in a unusable resolution, and your mouse cursor will probably be gone for some reason.
That's why it's advisable to create a new shortcut for the game, or use a new DOOM 3 script to launch it. To do this, first, duplicate the "Doom 3" shortcut on your system and give it a new name, like "Doom 3 GUI Editor". Right-click it, edit its properties, and change its target from:
Code:
<whatever>\Doom3.exe
To:
Code:
<whatever>\Doom3.exe +exec run_guieditor.cfg
This allows you to run the game and execute a DOOM 3 script file immediately upon loading. You have to create a this new script file, though: open up notepad, and type this into it:
Code:
seta r_fullscreen "0"
seta r_gamma "1"
seta r_mode "8"
vid_restart
editguis
seta r_gamma "1"
seta r_mode "8"
vid_restart
editguis
And save this as run_guieditor.cfg inside your DOOM 3's "/base" folder.
What this script does is:
1. Turn into windowed mode;
2. Reset gamma (so you'll have the original system gamma);
3. Set a high resolution (1600x1200);
4. Restart video
5. Open up the editor.
A note about step 3: even though r_mode is supposed to be 1600x1200, it looks that in this case it just forces the editor to be on a safe resolution. I use 1152x864 on windows myself, and using this shortcut/script combination, it always opens the GUI editor on my own resolution..
With that said, we're ready to open the editor. Double-click the shortcut you're just created, and the editor is launched.
This is the main window on the GUI editor. The first thing you'll notice is the editor name - "Quake IV GUI Editor". This is because this editor was developed by Raven Software, which is producing Quake IV. It was probably put on the DOOM 3 engine to give mod authors an easier start on designing GUIs. At least that's my theory...
Anyways, it's quite a straightforward program. The first thing you'll want to do is to go to the "View > Options..." menu, make sure the "Ignore Desktop Select" option is off on the "General" tab, and go to the "Grid" tab and set your options as follows:
I'm suggesting this to provide an easier editing interface; if you don't turn the grid on, there's no way to know what's inside the 640x480 editing area and it's easy to get lost. Feel free to skip this step, but be warned.
With that done, go to the menu and select "File > New" (or press CTRL+N) to create a new GUI script. Your editing area is filled with an empty GUI script.
On the right side of the screen (or wherever you moved it) you can see the "Navigator" window, which indicates which elements are visible and how they relate to each other. It works a lot like the way you expect a layer list to work on Photoshop, for example. Look at the list and, sure enough, our brand new GUI has only a Desktop windowDef, and it is visible. Clicking on it...
...selects it. This means two things: there's a selection halo visible on the editing area, and the windowDef attributes are visible on the "properties" window.
The selection halo is useful if you want to move the windowDef around, or resize it: just click and drag on a corner/side handler to resize it (as you'd do with any modern graphic editing package), or click and drag the windowDef itself to move. You can also use the keyboard keys: the arrow keys move the windowDef around one pixel at a time, and SHIFT+arrow keys resize it.
On the properties list, you'll see all the attributes we used on our previous lesson to create a new windowDef. In this case of a simple Desktop windowDef, only the rect is available, and that's all it needs anyway.
Since this is our main Desktop windowDef, we won't be messing around with it too much. It's time to add another windowDef to spice things up.
Go to the "Item > New > windowDef" menu and add a new windowDef. Yes, I know, there a lot of other items on the menu that can be added, but hold on, we'll get to that on later lessons...
Well, after adding our new windowDef, it sits there on the GUI. Double-click it and a nifty new window will open, with several properties to be edited. Type in a name for it (I'm using "Title") then go to the "Text" tab, since we'll be doing a text element like we did in the previous lesson. Here's what I've filled it with...
It's pretty easy and you can see how all properties available here translate to the attributes we manually created on the previous lesson. The good thing here is that you don't have to know all property names by memory or look into a GUI reference (which doesn't exist yet anyways): you can just play with the settings and see the result.
After filling the data, press OK to see it applied.
There it is, quite easy. Be sure to resize the windowDef to see all text, of course, as well as position it somewhere you want. Pretty cool, uh? Really easy, and the real-time preview is a real godsend.
We'll add another windowDef: this time, an image, just like we did in the previous tutorial. Select "Item > New > windowDef" again, double click the windowDef that was created, give it a name (I'm using "pentaImage", since I'm using a pentagram doodle) and then go to the "Image" tab. use this data:
What I'm doing here is giving it a backcolor - since I want the drawing to be fully visible - and assigning a material to it. Again, the "material" here refers to the path and filename used for the material. I'm using "tut2_penta" as a name, so this means "<doom3>/base/tut2penta.tga" (the file is attached to the tutorial source files, you can find the link to download it in the end of this tutorial).
There are other options available, but I'll leave them as is for now. Feel free to try them out, though.
Pressing OK will redraw the screen with our new windowDef options.
Sure enough, the image is applied to it. You can resize and move the windowDef, and see how it works visually.
You can will also notice the new properties - background, matcolor, and so on - were applied to the windowDef and are shown on the property window.
Other thing.. it's important to remember that, even though I made one text windowDef and one image windowDef, it doesn't mean you have to *chose* between one of these functionalities. You can have as many properties as you wish on it, and you could combine a background image with text on it, for example. The windowDefs I created are simple examples, but that doesn't mean they *have* to be like that.
Okey, now comes the cool part. While previewing it in the editor is close enough to seeing it in the game, it still isn't... perfect. It's static, and if you're playing with animations or scripting (we aren't yet), you won't be able to see the results.
But now, remember you are still inside of the DOOM 3 engine, and you are, in fact, able to test it right away without having to run it again and using the "testgui" command on the console. Select the "Tools > Viewer" menu (or press CTRL+T)...
...and a new window pops up, which is the GUI viewer rendered by the engine itself...
...and it works! While we have built an static GUI that doesn't depend that much on the in-game player for testing, the GUI viewer is a powerful tool and will help us a lot in the future, when testing animations and scripts.
And, of course, what the GUI editor has created is the GUI script code itself. Save the GUI into a file - I'm using the "tut2.gui" name myself - and have a look at it. This is the code it generates,
Code:
windowDef Desktop
{
rect 0,0,640,480
windowDef Title
{
rect 15,10,200,50
visible 1
forecolor 1,1,1,1
text "Hello."
textscale 1
font "fonts/english"
}
windowDef pentaImage
{
rect 190,124,260,261
visible 1
background "tut2_penta"
matcolor 1,1,1,1
backcolor 0.50196081,0.25098041,0,1
}
}
{
rect 0,0,640,480
windowDef Title
{
rect 15,10,200,50
visible 1
forecolor 1,1,1,1
text "Hello."
textscale 1
font "fonts/english"
}
windowDef pentaImage
{
rect 190,124,260,261
visible 1
background "tut2_penta"
matcolor 1,1,1,1
backcolor 0.50196081,0.25098041,0,1
}
}
Pure, simple, GUI script code.
This sums it all. To wrap up this lesson, I'd like to say something important. Why didn't I just show how to use the editor in the first place, in the previous lesson, instead of showing how to write scripts from scratch?
Well, to answer that, once again, I'll have to compare GUI scripting to HTML... that is: you can do cool sites on, say, DreamWeaver, but unless you have a wide knowledge of the way HTML code works, you'll never be able to produce quality pages. You know, the same applies to GUI scripts. A WYSIWYG tool is very cool to create GUI files fast and previewing them, but you WILL have to dwell with the code and the way it works deep inside if you want to create GUI scripts that are more than a simple box with text and an image.
Also, sometimes, changing the code itself will be faster and easier than opening a .GUI file on the GUI editor, so keep in mind...: the code is your friend.
On most of the next tutorials, while we'll use the official GUI editor, we'll also get a lot more into technical details, so be sure to play around with this powerful GUI editor in the mean time.
Download source and example files
Bump