# Documentation for *_G*

## AddCustomGameNotification

Display a custom on-screen notification.<br>

void **AddCustomGameNotification**(string id, string title, string text, string image, function callback, table params)
string id
: unique identifier of the notification.

string title
: title of the notification.

string text
: body text of the notification.

string image
: path to the notification icon.

function callback
: optional. Function called when the user clicks the notification.

table params
: optional. additional parameters.

Additional parameters are supplied to the translatable texts, but can also be used to tweak the functionality of the notification:<br>
- _'cycle_objs'_ will cause the camera to cycle through a list of _GameObjects_ or _points_ when the user clicks the notification.<br>
- _'priority'_ changes the priority of the notification (choose between _"Normal"_, _"Important"_ and _"Critical"_; default=_"Normal"_).<br>
- _'dismissable'_ dictates the dismissability of the notification (default=_true_)<br>
- _'close_on_read'_ will cause the notification to disappear when the user clicks on it (default=_false_).<br>
- _'expiration'_ is the amount of time (in _milliseconds_) that the notification will stay on the screen (default=_-1_).<br>
- _'game_time'_ decides if the expiration countdown is done in _RealTime_ or _GameTime_ (default=_false_).<br>

## AddCustomOnScreenNotification

Display a custom on-screen notification.<br>

void **AddCustomOnScreenNotification**(string id, string title, string text, string image, function callback, table params)
string id
: unique identifier of the notification.

string title
: title of the notification.

string text
: body text of the notification.

string image
: path to the notification icon.

function callback
: optional. Function called when the user clicks the notification.

table params
: optional. additional parameters.

Additional parameters are supplied to the translatable texts, but can also be used to tweak the functionality of the notification:<br>
- _'cycle_objs'_ will cause the camera to cycle through a list of _GameObjects_ or _points_ when the user clicks the notification.<br>
- _'priority'_ changes the priority of the notification (choose between _"Normal"_, _"Important"_ and _"Critical"_; default=_"Normal"_).<br>
- _'dismissable'_ dictates the dismissability of the notification (default=_true_)<br>
- _'close_on_read'_ will cause the notification to disappear when the user clicks on it (default=_false_).<br>
- _'expiration'_ is the amount of time (in _milliseconds_) that the notification will stay on the screen (default=_-1_).<br>
- _'game_time'_ decides if the expiration countdown is done in _RealTime_ or _GameTime_ (default=_false_).<br>
- _'display_countdown'_ must be _true_ if the _expiration_ countdown will be displayed in the notification texts (will be formatted and supplied to the translatable texts as _'countdown'_ parameter; this requires _'game_time'_ to be _true_).<br>

## AsyncCompress

Compresses a string using LZ4 or ZSTD compression.<br>
Use [AsyncDecompress](#AsyncDecompress) to get back the original vlaue.<br>

string compressed_data **AsyncCompress**(original_data, pstr, compression_algo)
original_data
: string to be compressed.

pstr
: if the result should be returned as a *pstr* string.

compression_algo
: the compression algorithm to be used - either *"lz4"* or *"zstd"*.

_returns_ compressed_data
: the compressed data as a string.


## AsyncDecompress

Decompresses a string generated using [AsyncCompress](#AsyncCompress) and returns the original value.<br>

string original_data **AsyncDecompress**(compressed_data)
compressed_data
: string to be decompressed.

_returns_ original_data
: the descompressed data as a string.


## Compress

Compresses a string using LZ4 compression.<br>
Use [Decompress](#Decompress) to get back the original vlaue.<br>

string compressed_data **Compress**(original_data)
original_data
: string to be compressed.

_returns_ compressed_data
: the compressed data as a string.


## Decompress

Decompresses a string generated using [Compress](#Compress) and returns the original value.<br>

string original_data **Decompress**(compressed_data)
compressed_data
: string to be decompressed.

_returns_ original_data
: the descompressed data as a string.


## DivRound

DivRound - short for Divide, Round.<br>

ret **DivRound**(value, divisor)
int numerator
: numerator used for the calculation.

int denominator
: denominator used for the calculation.

_returns_ 
: the result from the division, rounded to the nearest integer.


## GetDomeAtHex

Check for a dome at given hex coordinates.<br>
Fast procedure that uses the object grid only.<br>

object, bool **GetDomeAtHex**(q, r)
int q, r
: hex coordinates.

_returns_ object dome
: the dome found.

_returns_ bool interior
: specifies if the pos is located in the interior area (not at the border).


## GetDomeAtPoint

Check for a dome at given object or point location.<br>
Procedure that uses the object grid or a fast surface collision test with the dome glass if the pos is at the dome border.<br>

object **GetDomeAtPoint**(pos)
point pos
: point or object which location to be checked.

_returns_ object dome
: the dome found.


## GetPassablePointNearby

Searches around and returns the nearest passable/walkable point.<br>

point **GetPassablePointNearby**(point pt)
point pt
: original point.

_returns_ point
: nearest passable point or an *invalid* point, if none was found.


## IsDlcAvailable

Returns if the player has a specific DLC installed.<br>

bool **IsDlcAvailable**(string dlc)
dlc
: The ID of a DLC.

_returns_ bool
: If the DLC is available and loaded.


## IsObjInDome

Check if an object is located in a dome.<br>
General purpose procedure that handle all possible cases (buildings, units, etc).<br>

object **IsObjInDome**(obj)
object obj
: object to be checked.

_returns_ object dome
: the dome found.


## IsUnitInDome

Check if an unit is located in a dome.<br>
Specialized procedure for faster checking if a unit is located in a dome (colonists, drones, etc).<br>

object **IsUnitInDome**(unit)
object unit
: unit to be checked.

_returns_ object dome
: the dome found.


## LuaCodeToTuple

Evaluates a string generated using [TupleToLuaCode](#TupleToLuaCode) and returns the original values.<br>

error, values **LuaCodeToTuple**(string code, table env)
string code
: code to be evaluated.

table env
: evaluation environment.

_returns_ error, values
: error string (or nil, if none) and the evaluated tuple.


## MulDivAdd

MulDivAdd - short for Multiply, Divide, Add.<br>

ret **MulDivAdd**(value, numerator, denominator, addend)
int value
: value used for the calculation.

int numerator
: numberator used for the calculation.

int denominator
: denominator used for the calculation.

int addend
: addend used for the calculation.

_returns_ 
: the integer calculation (value*numerator + addend)/denominator.


## MulDivRound

MulDivRound - short for Multiply, Divide, Round.<br>

ret **MulDivRound**(value, numerator, denominator)
value
: value used for the calculation. Both number, point or box values are allowed.

int numerator
: multiplier used for the calculation.

int denominator
: divisor used for the calculation.

_returns_ 
: the result from (value*numerator)/denominator, rounded to the nearest integer.


## MulDivTrunc

MulDivTrunc - short for Multiply, Divide, Truncate.<br>

ret **MulDivTrunc**(value, numerator, denominator)
value
: value used for the calculation. Both number, point or box values are allowed.

int numerator
: multiplier used for the calculation.

int denominator
: divisor used for the calculation.

_returns_ 
: the integer calculation (value*numerator)/denominator.


## Normalize

Returns a point with a vector direction defined by the given two or three coordinates, but with vector length 4096. If only two coordinates are given, returns a 2D point with z = InvalidZ.<br>

point **Normalize**(int x, int y, [int z])
int x, y, z
: two or three coordinates specifying a vector direction.

_returns_ point n
: a point with length 4096 with the same direction as specified with x/y/z.


## RGB

Represent an RGB color in integer format.<br>

int **RGB**(int red, int green, int blue)
int red
: red componnent, ranging from 0 to 255

int green
: green componnent, ranging from 0 to 255

int blue
: blue componnent, ranging from 0 to 255

_returns_ int
: RGB color represented by an integer.


## RGBA

Represent an RGBA color in integer format.<br>

int **RGBA**(int red, int green, int blue, int alpha)
int red
: red componnent, ranging from 0 to 255

int green
: green componnent, ranging from 0 to 255

int blue
: blue componnent, ranging from 0 to 255

int alpha
: alpha componnent (opacity), ranging from 0 to 255

_returns_ int
: RGB color represented by an integer


## ReadModPersistentData

Reads data from a persistent storage, that can be accessed between different game sessions.<br>
This storage is not shared, but is per mod. Anything read here has been previously stored only by the same mod using [WriteModPersistentData](#WriteModPersistentData).<br>

err, data **ReadModPersistentData**()
_returns_ err
: error message or nil, if successful.

_returns_ data
: data previously stored or nil.

See also: [LuaCodeToTuple](#LuaCodeToTuple), [Decompress](#Decompress), [AsyncDecompress](#AsyncDecompress);<br>

## StateIdx

Gets the index of a state (animation) by its name.<br>

int **StateIdx**(int state)
_returns_ int
: state index or -1 if not found.


## StateName

Gets the name of a state (animation) by its index.<br>

string **StateName**(int state)
_returns_ string
: state name or an invalid name if not found.


## TupleToLuaCode

Converts a tuple of values to an executable Lua expression.<br>
Use [LuaCodeToTuple](#LuaCodeToTuple) for evaluating the Lua expression.<br>

string code **TupleToLuaCode**(values...)
values...
: tuple of values to be converted to executable code string.

_returns_ string code
: the supplied tuple, converted to Lua code.


## ValueToLuaCode

Converts a value to an executable Lua expresion.<br>
Use _'LuaCodeToTuple()'_ for evaluating the Lua expression.<br>

string code **ValueToLuaCode**(value, int indent)
value
: value to be converted.

int indent
: initial number of indentations.

_returns_ string code
: the supplied value, converted to Lua code.


## WaitCustomPopup

Displays a custom popup and waits for the players response.<br>
This function should always be called from within a GameTime thread.<br>

int choice **WaitCustomPopup**(string title, string text, table choices, window parent)
string title
: title of the popup.

string text
: body text of the popup.

table choices
: array of up to four choices for the user.

window parent
: parent window (this is optional only ingame).

_returns_ int choice
: The users choice.


## WaitCustomPopupNotification

Displays a custom popup notification and waits for the players response.<br>
This function should always be called from within a GameTime thread.<br>

int choice **WaitCustomPopupNotification**(string title, string text, table choices, window parent)
string title
: title of the popup.

string text
: body text of the popup.

table choices
: array of up to four choices for the user.

window parent
: parent window (this is optional only ingame).

_returns_ int choice
: The users choice.


## WriteModPersistentData

Writes data into a persistent storage, that can be accessed between different game sessions.<br>
The data must be a string, no longer than *const.MaxModDataSize* - make sure to always check if you're exceeding this size.<br>
This storage is not shared, but is per mod. Anything stored here can only be read by the same mod using [ReadModPersistentData](#ReadModPersistentData).<br>

err **WriteModPersistentData**(data)
data
: the data to be stored (as a string).

_returns_ err
: error message or nil, if successful.

See also: [TupleToLuaCode](#TupleToLuaCode), [Compress](#Compress), [AsyncCompress](#AsyncCompress);<br>

## xxhash

Calculates a hash of all its parameters concatenated. Uses [xxhash](http://cyan4973.github.io/xxHash/) for strings.<br>

number **xxhash**(...)
...
: arbitrary number of params of type string, number, bool, nil, grid, userdata

_returns_ number
: hash of the concatenated byte content of all the parameters.


## xxhash64

Calculates a hash of all its parameters. Uses [xxhash64](http://cyan4973.github.io/xxHash/).<br>
No bitshifting or XOR magic, xxhash functions only.<br>

number **xxhash64**(...)
...
: arbitrary number of params of type string, number, bool, nil, grid, userdata

_returns_ number
: hash of the concatenated byte content of all the parameters.





(insert footer.md.html here)
<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style>
<script src="markdeep.min.js"></script>
<script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></script>
<script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>