#summary List of utility functions in the Lua API

= Lua API: Utility functions =
This page is a list of utility functions in the [LuaAPI Lua API] and other functions that don't fit anywhere else.

<wiki:toc max_depth="3" />

== File system functions ==
=== <tt>!HedgewarsScriptLoad(scriptPath [, mustExist])</tt> ===
Loads a script (i.e. a [LuaLibraries library]) from the specified `scriptPath`. The root directory is here Hedgewars’ data directory. There will be a Lua error if the script does not exist.

If `mustExist` is `false`, no Lua error will happen even when the script does not exist.

Returns `true` if the script was loaded successfully, `false` otherwise.

Example:
<code language="lua">
HedgewarsScriptLoad("/Scripts/Locale.lua")  -- loads locale library
</code>


== Math functions ==
=== <tt>div(dividend, divisor)</tt> ===
Performs an integer division and returns the result.
The result is an integer and has the value of the first parameter (an integer) divided by the second parameter (another integer), rounded towards zero.

=== <tt>band(value1, value2)</tt> ===
Returns the bitwise logical AND of `value1` and `value2`.

=== <tt>bor(value1, value2)</tt> ===
Returns the bitwise logical OR of `value1` and `value2`.

=== <tt>bnot(value)</tt> ===
Returns the bitwise logical NOT of `value`.

== Debugging functions ==
=== <tt>WriteLnToConsole(string)</tt> ===
Writes `string` to `Logs/game0.log`, found in the user data directory.

=== <tt>WriteLnToChat(string)</tt> (0.9.24) ===
Writes `string` into the chat.

=== <tt>DumpPoint(x, y)</tt> (0.9.23) ===
Converts the whole numbers `x` and `y` to strings and writes them to `Logs/game0.log`, one line each.

=== <tt>StartGhostPoints(count)</tt> ===
Just prints out “GHOST_POINTS” and the argument on the console. This function might change in later versions.

=== <tt>DeclareAchievement(id, teamname, location, value)</tt> ===
Declares an achievement with the identifier `id` achieved by the team `teamname` on the map `location` with an achievement value (e.g. score) of `value`. `value` must be an integer. You are supposed to call this function inside an `onAchievementsDeclaration` callback.

Currently, this actually just triggers a console output, but it might be changed later. The idea is to track multiplayer records.

Example:

<code language="lua">DeclareAchievement("height reached", teamname, "ClimbHome", -score)</code>
Records a team's best height in !ClimbHome.

== Library functions ==
For more utility functions, you might want to check out the [LuaLibraries Lua libraries].