Lua API: Utility functions
This page is a list of utility functions in the Lua API and other functions that don't fit anywhere else.
File system functions
HedgewarsScriptLoad(scriptPath [, mustExist])
Loads a script (i.e. a
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:
HedgewarsScriptLoad("/Scripts/Locale.lua") -- loads locale library
Math functions
div(dividend, divisor)
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.
band(value1, value2)
Returns the bitwise logical AND of
value1
and
value2
.
bor(value1, value2)
Returns the bitwise logical OR of
value1
and
value2
.
bnot(value)
Returns the bitwise logical NOT of
value
.
Debugging functions
WriteLnToConsole(string)
Writes
string
to
Logs/game0.log
, found in the user data directory.
WriteLnToChat(string)
Writes
string
into the chat.
DumpPoint(x, y)
Converts the whole numbers
x
and
y
to strings and writes them to
Logs/game0.log
, one line each.
StartGhostPoints(count)
Just prints out “GHOST_POINTS” and the argument on the console. This function might change in later versions.
DeclareAchievement(id, teamname, location, value)
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:
DeclareAchievement("height reached", teamname, "ClimbHome", -score)
Records a team's best height in ClimbHome.
ParseCommand(string)
Makes the game client parse and execute the specified internal game engine command.
The available commands depend on the current engine protocol version. The engine protocol can (and will) change between releases.
Important: If you use
ParseCommand
to overcome a shortcoming in our Lua API (e.g. a missing function), please make sure to report the issue.
With your report we can fix the shortcoming in future releases. We will try to remove the reliance on
ParseCommand
as good as possible. This will allow scripts to use the previously missing feature in a way that won’t break!
There are many available commands, but actual use in scripting is rare, and even then it's discouraged for long-term use. The only command used in official scripts is:
-
"draw <map>"
: Draws a hand-drawn map.
MapGen
must be
mgDrawn
for this to work.
<map>
is a string which must follow the format specified in DrawnMapFormat
Moreover, the control action names as listed in ConfigurationFiles (under “Binds”) can be used. Note we will eventually try to remove all
ParseCommand
s in the official scripts.
EndLuaTest(success)
This function is used by the Hedgewars developers in testing scripts in order to test the game engine. The testing scripts can be found in the Hedgewars source code under
tests/lua
. This function is useless for anything else.
Calling this function ends an engine test and reports a test result.
success
is either one of
TEST_SUCCESSFUL
to report a successful test or
TEST_FAILED
for a failed test.
See EngineTestCases to learn more about testing the engine.
Library functions
For more utility functions, you might want to check out the
Lua libraries.