GUI Scripting: EditGuis Editor

This page is part of a series. See GUI Scripting Language for overview.

The "EditGuis" Family of GUI Editors for idTech4 Games

Purpose in a Nutshell

This style of editor for a GUI file is designed to let you quickly instantiate basic "guiDef" structures and properties, manipulate their nesting, and provide a visual preview of layout. It simplifies getting aspects of basic syntax correct. It doesn’t provide much help when it comes to commands within event blocks or functionality. Consequently, the general guidance for this tool is to quickly prototype any visual elements, then move the file to a text editor to fill in behavioral aspects.

Availability

WARNING: TDM’s built-in version of "editguis" is not currently usable; see Status below.

You may have installed one of the commercial id games that uses a similar, broadly compatible, version of editguis built-in to the game, e.g.

• Quake 4
• Doom 3
• Enemy Territory: Quake Wars
• Prey

Or other idTech4 games.

Then (assuming these versions of editguis are still working these days) you may be able to use that to start a new .gui file, or tweak an existing one, then move it into TDM. Keep in mind that the editguis family is Windows-specific. Also, there are differences in GUI scripting between TDM and other games. See GUI Scripting: TDM vs Doom 3, Quake 4.

Descriptions

Here's three short descriptions by others of the Doom 3 version, that are general enough to pertain to all versions. Mostly verbatim, but with some light editing.

1) From "Doom3 SDK: Making Doom 3 Mods"

See GUI Scripting: References & Resources for SDK links, and a fuzzy screenshot.

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... The gui editor is a real life saver for making small, simple guis. Raven Software initially created the GUI editor for Quake 4 (which is why it says "Quake IV GUI Editor" in the title bar). The GUI Editor that is in Doom 3 hasn't been updated in a year or two, so when it randomly crashes, it's not their fault.

2) From "Tutorial 2 – Tools and Editors" by Martin Pezlar (Maxell)

where Part 2 mentions the GUI Editor.

To make a GUI, you have to create its images and script its functionality – and that isn’t easy. Therefore Raven Software developed a basic WYSIWYG editor for GUIs. It doesn’t support all features of the GUI system, but it is a very useful editor for creating basic custom GUIs and other tasks, such as setting up the right coordinates of images in your GUI.

When you run "editGUIs", the main window of the GUI editor will appear. On the upper left side there is a typical program menu "File, Edit, View …" and other menu items which are also available under the right-click menu on the main background.

In the main editor window there are 3 smaller tool windows:

• "Transformer" displays the XY coordinates of the selected GUI element and its dimensions. These values can be adjusted instantly through the window.
• "Properties" shows properties of the selected GUI element. All properties are also editable through this window.
• "Navigator" is perhaps the most important tool window. It displays the entire tree of GUI elements - something like layers in Photoshop. When you expand some layer, all its properties will appear. You can directly edit them. Also visibility of each layer can be enabled/disabled.

3) From a Doom 3 Multiplayer Forum

in a 2004 post by nakedape

Here’s a few quick notes to get you going.

• Window > Show Navigator. This is akin to Layers in Adobe Photoshop. It keeps track of your gui windowDefs, lets you hide and show things for easier editing, shows nested windowDefs hierarchies.
• Window > Show Transformer. No Autobots or Decepticons [joke], but you do get some handy dialogs for directly inputting the origin of the windowDef (x,y) and its size (w,h).
• Window > Show Properties. Displays all the key/value combinations for the selected windowDef. You can add keys and edit values.

This is a basic .gui:

windowDef Desktop
{
	rect	0,0,640,480
}

The Desktop windowDef is the main parent to everything else in the .gui. All windowDefs must remain within the Desktops co-ordinates to be visible (much like Macromedia Flash).

If you select Item > New > windowDef, you will get a child within the desktop called "unnamed1". Your .gui will now look like this:

windowDef Desktop
{
	rect	0,0,640,480
	windowDef unnamed1
	{
		rect	0,0,100,100
		visible	1
	}
}

You can manually enter a new origin or dimensions of the windowDef using the Properties window or you can left-click and drag the windowDef to a new position. Use the little square handles to change its dimensions.

Double-clicking on the windowDef (or its name in the Navigator) will open up the Item Properties window where you can set all the different parameters of a windowDef. Use the Keys tab to delete any unwanted key/value pairs.

In the main editing window, you can also right-click to bring up the same options found in the main Item menu.

You can "nest" windows within each other using the Item > Arrange > Make Child option. First select the window to be the parent, then select the window to be the child and click Item > Arrange > Make Child. Note that the origin of the child will change from being relative to the desktop to being relative to its new parent. The Quake IV GUI Editor automatically adjusts the child’s origin co-ordinates without moving the visual position of the child windowDef. This is great for mocking up .gui layouts.

If you manually nest the windowDef in a text editor without the changing the origin, the child will now be offset. The x and y values of the rect key are always relative to its parent (the Desktop being the default parent to all newly created windowDefs).

If you change the parent windowDef’s visibility to 0, you will also hide the children. The visibility key of the children will not change, but since the parent acts like a "container" for the children if you hide the container then the children won’t be visible as well. Likewise, if you move the parent you take the children along for the ride.

Here is an example of basic windowDef nesting:

windowDef Desktop
{
	rect	0,0,640,480
	windowDef blue
	{
		rect	171,134,434,308
		visible	1
		backcolor	0,0,1,1
		windowDef red
		{
			rect	120,22,209,150
			visible	1
			backcolor	1,0,0,1
		}
	}
}

Use Tools > Viewer to open the GUI Viewer window for a preview of the gui.

I suggest copying some of the Doom3 .gui files, renaming them, and playing about with the editor to see how they are structured. Note that any comments in the .gui will be stripped out by the Quake IV GUI Editor, so it’s wise to not muck about with the raw Doom3 .guis unless you want to risk breaking your game.

Status of EditGuis within TDM

Historically, Raven Studios first created editguis as a built-in GUI editor for Quake 4, using id Studio data types, then integrated a variant of that into Doom 3. TDM inherited that code but, as the code evolved, paid little attention to editguis. When the TDM engine code is compiled, a #define causes tools (e.g., all the custom editors including editguis) to be included in the build.

Currently, trying to use TDM’s editguis productively is futile. If curious, you can at least start it while running TDM. Prerequisites:

• As mentioned above, it is Windows-specific. Attempting to start it under Linux brings forth only a console warning.
• TDM must be in "Windowed" mode, not full screen, for the mouse cursor to be visible. After you start the GUID Editor, you can maximize its Microsoft window size (although it’s perhaps better not to).

Also, there is a config file in <darkmod>, called "run_guieditor.cfg". You could create a Windows shortcut to run this when you start the game; see Zeh's Tutorial #2 below for details. Settings therein may be stale. For instance, there is a gamma correction likely unnecessary with TDM 2.10.

In any event, with prerequisites done, typing "editguis" in the console causes the editor to appear, with its "Quake IV GUI Editor" title. (Prior to around 2.10, it would also show a bleached screen due to gamma problems. This has gone away.) There will be 3 sub-panels open by default in the lower right hand corner.They are atop each other, so it looks like only one. Drag them by the headers to better locations. Surprisingly, they can be dragged outside the editor window frame.

Unfortunately, that’s the end of the line. The File functions New, Open, and Save/Save As don't work – eliciting "File Not Found" popups - because of file path issues. Even if those are fixed (discussed next), the preview is not working. It should show the GUI visual preview as the background of the main editor window, but instead shows the game page with the console open.

So, at the moment, TDM’s editguis should be considered unsupported. There has be some thought to eventually removing it along with other in-game editors. But making a real replacement (standalone or in DR) would be tough.

Possible Partial Fix

In bugtracker #5194, Geep suggested file path code changes to allow creating and editing a .gui file in <FM>/guis/. If those were in effect, then

• As a prerequisite, you would set the correct file path context, by loading a particular FM prior to invoking editguis. The FM needs to be under development, not packed into .pk4 files, for successful file I/O.
• In editguis, file functions New, Open, and Save/Save As would then work (at least for .gui files in the /guis/ directory, but not in subdirectories).

During testing of this, the correct .gui was seen to be parsed in the Visual Studio debugger. Unfortunately, no fix for the failure to render the preview has yet been determined.

More about Using EditGuis in Quake 4

Raven Software/id Studio Documentation

This presentation, last touched by Raven Software’s Matt Vainio in 2005, is perhaps the most organized reference source about both the GUI Editor and GUI scripting. Originally hosted at iddevnet.

https://iddevnet.dhewm3.org/quake4/GUIEditor.html

Book by Guilfoyle

The print-only book by Erik Guilfoyle, "Quake 4 Mods for Dummies", 2007, devotes a chapter.

More about Using EditGuis in Doom 3

Zeh’s "Complete Gui Scripting"

In GUI Scripting: References & Resources, see the section "Zeh’s Doom 3 ‘Complete Gui Scripting’ Tutorials". Most of Zeh's tutorials in that series uses editguis. Of particular note, "Tutorial 2: Using the built-in GUI editor" is most relevant here, and includes how to set up a MS Windows desktop shortcut with specialized .cfg file. Part 3 is also of interest regarding loading and saving files.

Jared Mitchell’s GUI Demo using EditGuis

Within a disparate page describing various projects, Jared Mitchell talks about using Doom 3 with a door that has a gui attached, and when you click on it, shows a light display that varies with "power" level. (It demonstrates the runscript command, not so relevant to TDM).

TDM Forum Discussions about EditGuis

• The need to start editguis in windowing mode, and the idea to turn to other games for a working editguis, are pointed out by freyk. Ultimately, freyk reports in later work just using notepad, guitest-command, and guirefresh-command. See GUI Scripting: Tools.
• A discussion about whether renderDef data structures could be removed from the code base. Answer: No, due to impact on the compass and editguis.
• Another link specifically about the gui editor.
• There was a proposal, not currently active, to add a gui editor to DR.