GUI Overlays

GUI overlays are a way to draw GUIs over the player's screen. They're used for things such as the HUD, readables and inventory display. They could also be used for things like fading out the player's vision, adding an in-game shop GUI, popping up hints, asking the player if they really want to leave the level, obscuring their vision with a clunky helmet, adding new elements to the HUD without modifying it, etc.

darkmod_events.script contains documentation about the various script functions used to manipulate GUI overlays, but it might not be helpful unless some basic concepts about GUI overlays are understood. This page aims to explain those concepts. It assumes knowledge of GUIs.

Creating and destroying your first GUI overlay

Let's say you want to draw "guis/mygui.gui" over the player's screen. To do that, you call createOverlay() on the player. For example:

$player1.createOverlay( "guis/mygui.gui", 100 );

The second argument (100) is the layer of the overlay. Overlays are drawn in ascending order by layer; overlays in higher layers are drawn on top of overlays in lower layers. The order in which overlays in the same layer are drawn is undefined. The HUD is in layer 0, so in order to ensure that the GUI is drawn over the HUD, we've put it in layer 100.

So how do you delete the overlay you just created? You need to make use of handles. The createOverlay() function returns a handle that can be used to access the overlay. This handle can then be passed to the destroyOverlay() function. For example, this will flash the GUI on screen for 5 seconds:

float overlayHandle = $player1.createOverlay( "guis/mygui.gui", 100 );
sys.wait(5);
$player1.destroyOverlay( overlayHandle );

If for some reason createOverlay() fails, it'll return GUI_INVALID.

Working with the HUD and entity GUIs

To access the HUD, use the GUI_HUD handle. For example, to call the "foobar" event in the HUD, you would do:

$player1.callGui( GUI_HUD, "foobar" );

Similarly, you can interact with entity GUIs via GUI_ENTITY1, GUI_ENTITY2 and GUI_ENTITY3. To set a GUI parameter for the second GUI on a book, you might do:

$book.setGuiFloat( GUI_ENTITY2, "page", 1 );