Jump to: navigation, search


GUI means Graphical User Interface. As far as HeroScript is concerned, this means various tabs, list boxes, popup menus, tree views, forms, and other things which are created and manipulated via HeroScript, for display to the player.

If you are new to things GUI, please start by reading the GUI Controls and GUI Editor pages.

GUI Editor

The GUI Editor allows for the creation of GUI Control Prototypes, in a WYSIWYG visual format. After a prototype has been created, a script can be written which creates nodes based on the prototype. The GUI Editor consists of the GUIXML tab, the list of all GUI Control Prototypes, the GUI Control Tree View, which displays and allows editing of the hierarchy of child GUI Control's for the GUI Control being edited, the GUI Control Properties, the list of all of the properties of the selected GUI Control that change how it looks and behaves and the preview of the GUI Control being edited in the Viewport.

GUI Controls

Each element of the Graphical User Interface is a separate GUI Control. For example, if a popup window appears with a text message and an "OK" button, the window is one control, the part with the text message is another control, and the button is actually several combined controls. There may also be other invisible controls on the window which affect its appearance and behavior.

Each GUI Control is a node, based on a certain class. When the nodes are created, their fields are configured with certain values, and a callback is made to the script baseGUI:onControlBuild().

Controls can be configured to cause certain things to happen, such as when the mouse is used to click on any part of the control. These are called "GUI Events", and are caused by other scripts which were created with functions which take actions based on the desired GUIEvents.

There are 20 or so basic GUI Control Classes. Each of those classes has fields, some of which are subclasses with their own fields. This page is an attempt to document all of the relevant attributes (fields and subclass fields) for each class.

The simplest way to create a Control Prototype, is by using the GUI Editor. Please see that section for a step by step tutorial on creating a new GUI Control prototype.

The way to create a Control is to write a short HSL function that creates a new Control based on an existing prototype, and then displays it in the viewport. For step by step instructions on how to do this, please see GUI Window Tutorial.

GUI Events

GUI Events work hand in hand with GUIControls. Once a control, such as a window or button, is created, a mechanism is then necessary which allows that window or button to be activated by something that the user does, such as clicking on it with the mouse. That "click" event can then trigger a function in a client-side script. GUI Controls are handled via a data node of a class, which contains information on the event. The associated method script is called, and if it has a relevant method within it, the logic is handled there, and the variable args.handled can be set to TRUE, signifying that the GUI Event has been taken care of, and no further controls should do anything. If no exception method is found, or none choose to mark the event as handled, HeroEngine will first attempt to call the original method on the GUI Control's parents. If none of those handle the Event, HeroEngine will move on to the older Procedural Function system.

GUI Layers

GUI Layers are a way to separate out various related interface elements into their own autonomous groups. They may be thought of transparent "slices" or "sheets" onto which all GUI controls are placed. The layer system's biggest strength (and primary use) is the ability to turn on/off entire systems and groups of controls simultaneously, and control which interface elements may be present.

The way to place a control on a layer is to set its layer field in the XML, which can be done via HSE2 or the GUI Editor. There is an automatic callback made by the C++ side of things when a new control is created from a prototype, which automatically attempts to place a control on its proper layer, assuming layers are enabled for that player. If the layer does not exist, it will be created, if it is a valid layer. The list of valid layers is currently hardcoded into the GUILayers script, and an invalid layer name will result in a script error when the control is created. To create a new layer, you first need to add it into the when/is structure in the findMyInitialLayer function and insert it in the proper place in the list created in the reorderLayers function.

Note that ultimately, only the top-level parent control's layer will make any difference. It is therefore unnecessary (and kinda pointless) to set the layer on any control which will be a child of another control.


XML is an HTML-like language which is used to define the primary graphical user interface (also known as "GUI_Controls") of the game. When a window pops up, the XML language was used to define that window, and the buttons, icons, and checkboxes upon it. Each of those buttons or other objects is a separate node, of the archetype GUIControl. Just like other nodes, they have classes and fields, with data in those fields. Scripts can also be attached to these nodes that trigger on GUI Events (such as a KeyPress or MouseClick). So when a user clicks on a button, that button can then call a script which will affect other things in the game, change the window's appearance, or even create other windows.

GUI Animations

GUI Animations are a mechanism for modifying the appearance of a GUI Control over time. This could mean anything from playing actual frames of an animation (like a stick figure walking around), to causing other types of changes such as modifying the texture, position, or size of the GUI Control. Animations can be set to run immediately when the Control is first created, or they can be set to trigger upon certain events such as a mouse click.

Note: It is perfectly legitimate to specify more than one animation on a control, or to set multiple events on a control, each of which has one or more different animations, as long as all of those animations can run at the same time without a conflict.

GUI Window Tutorial

The GUI Window Tutorial is a step by step tutorial on how to create a custom GUI Control - a popup window which says, "Hello World". There is a tutorial for creating a custom GUI Control using the GUI Editor and another tutorial to create the same GUI Control using GUIXML. Both tutorials will result in a GUI Control the looks and behaves the same.

GUI Analysis Tool

The GUI Analysis Tool fills a gap between editing the prototype/XML of a GUI Control in the GUI Editor, and working with an instantiation in the "game". It provides an easy to use interface for viewing and modifying the properties of an instantiation of a GUI Control.

The GUI Analysis Tool is implemented fully in HSL and leverages the Generic Node Property Editor control to display the properties of an instantiated GUI Control.

The GUI Analysis Tool may be invoked only while in HeroBlade's edit mode, with a selection tool active. With the selection tool, hover your mouse over a visible GUI control and press "CTRL-SHIFT-T".

Related information

Personal tools