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, 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.

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.