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

#labels !LuaFunctions

= Lua API: GUI functions =

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

<wiki:toc max_depth="2" />

== <tt>!AddCaption(text)</tt> ==

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>

== <tt>!AddCaption(text, color, captiongroup)</tt> ==

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>

== <tt>!ShowMission(caption, subcaption, text, icon, time [, forceDisplay])</tt> ==

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:

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

== <tt>!HideMission()</tt> ==

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

== <tt>!SetZoom(zoomLevel)</tt> ==

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

== <tt>!GetZoom()</tt> ==

Returns the current zoom level.

== <tt>!SetCinematicMode(enable)</tt> ==

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.