Back to homepage
List of functions in the Lua API that affect the GUI
Updated Sun, 12 Jan 2020 23:33:37 +0100 by Wuzzy

Lua API: GUI functions

This page is a list of all functios in the Lua API that affect the GUI (graphical user interface).


Display an event text in the upper part of the screen. The text will be white and the caption group will be capgrpMessage .

Example: AddCaption("Hello, world!")

AddCaption(text, color, captiongroup)

Display an event text in the upper part of the screen with the specified RGBA text color and caption group. Although an RBGA color is used, Hedgewars does not actually support transparent or semi-transparent captions, so the fourth byte is ignored. We recommend you to always specify a full opacity ( FF in hexadecimal) for the caption.

captiongroup Meaning
capgrpGameState Used for important global game events, like Sudden Death
capgrpAmmoinfo Used for new weapon crates and some other events
capgrpVolume Used for “local” changes of client settings that don't affect gameplay, like volume change, auto camera on/off, etc.
capgrpMessage Generic message
capgrpMessage2 Generic message
capgrpAmmostate Used to show information about weapon state, i.e. bounce level, timer, remaining shots, etc.

The color can be specified in RGBA format, but you can (but don't have to) use one of the following built-in text color.

Built-in color Meaning
capcolDefault Default caption color
capcolSetting Notification related to a local client setting (audio volume, auto camera on/off)

Example: AddCaption("Melon bomb rain in 2 rounds!", 0xFF0000FF, capgrpGameState) -- Green example message.

ShowMission(caption, subcaption, text, icon, time [, forceDisplay])

This function will open the mission panel and set the texts in it.

Use to tell the player what he/she is supposed to do. If you use this function, a mission panel is shown for the amount of time specified in time (in milliseconds). If time is set to 0, it will be displayed for a default amount of time. This function replaces the entire text of the mission panel. Compare this to the global Goals variable, which adds to the default text without replacing it.

caption is the text displayed in the first line, subcaption is displayed in the second line and text is the text displayed in the third and following lines.

By convention, caption should normally contain the name of the game style or mission and subcaption should normally contain the type of game style or mission, or a witty tagline. But this is only a loose convention which you don't have to follow all the time.

text uses some special characters for formatting:

Special character Meaning
| Line break
: Highlight itself and all text before that character in this line. The colon itself will be written.
:: Like above, except the two colons will not be written.
\| Will be replaced with “|” without triggering a line break (escape sequence)
\: Will be replaced with “:” without triggering highlighting (escape sequence)

icon accepts the following values:

icon What is shown
negative number Icon of an ammo type. It is specified as the negative of an ammo type constant (see AmmoTypes), i.e. -amBazooka for the bazooka icon.
0 Golden crown
1 Target
2 Exclamation mark
3 Question mark
4 Golden star
5 Utility crate
6 Health crate
7 Ammo crate
8 Barrel
9 Dud mine
10 Hedgehog (1.0.0)
11 Flags (1.0.0)

If the optional parameter forceDisplay is true , this mission panel cannot be removed manually by the player. It's false by default.

Example: ShowMission(loc("Nobody Laugh"), loc("User Challenge"), loc("Eliminate the enemy before the time runs out"), 0, 0)

(Note: loc comes from the Locale Lua library.)


Hides the mission panel if it is currently displayed, otherwise, this function does nothing.


Sets the zoom level. The value for maximum zoom is currently 1.0 and for minimum 3.0 The default zoom level is 2.0


Returns the current zoom level.


Turns on or off cinematic mode. Cinematic mode can be used for cutscenes etc. If enable is set to true , cinematic mode is enabled, if it is false , cinematic mode is disabled.