#summary List of functions in the Lua API that affect the GUI

= Lua API: GUI functions =

This page is a list of all functios in the [LuaAPI 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:

<code language="lua">

AddCaption("Hello, world!")

</code>

Display an event text in the upper part of the screen with the specified RGBA text [LuaOverview#Color 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:

<code language="lua">

AddCaption("Melon bomb rain in 2 rounds!", 0xFF0000FF, capgrpGameState)

-- Green example message.

</code>

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

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

Example:

<code language="lua">

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

</code>

(Note: `loc` comes from the [LuaLibraryLocale 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.