LuaUtil.wiki
author Wuzzy
Wed, 18 Sep 2019 00:34:30 +0100
changeset 1977 12b6619171bb
parent 1845 a6be83d2fe45
child 2077 514babfbad9e
permissions -rw-r--r--
BuildingOnMac: More formatting (2)
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1749
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
     1
#summary List of utility functions in the Lua API
1845
a6be83d2fe45 LuaUtil: Add label
Wuzzy
parents: 1811
diff changeset
     2
#labels !LuaFunctions
1749
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
     3
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
     4
= Lua API: Utility functions =
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
     5
This page is a list of utility functions in the [LuaAPI Lua API] and other functions that don't fit anywhere else.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
     6
1801
efa4f04f15eb LuaUtil: Add TOC
Wuzzy
parents: 1763
diff changeset
     7
<wiki:toc max_depth="3" />
efa4f04f15eb LuaUtil: Add TOC
Wuzzy
parents: 1763
diff changeset
     8
1749
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
     9
== File system functions ==
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    10
=== <tt>!HedgewarsScriptLoad(scriptPath [, mustExist])</tt> ===
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    11
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.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    12
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    13
If `mustExist` is `false`, no Lua error will happen even when the script does not exist.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    14
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    15
Returns `true` if the script was loaded successfully, `false` otherwise.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    16
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    17
Example:
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    18
<code language="lua">
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    19
HedgewarsScriptLoad("/Scripts/Locale.lua")  -- loads locale library
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    20
</code>
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    21
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    22
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    23
== Math functions ==
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    24
=== <tt>div(dividend, divisor)</tt> ===
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    25
Performs an integer division and returns the result.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    26
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.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    27
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    28
=== <tt>band(value1, value2)</tt> ===
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    29
Returns the bitwise logical AND of `value1` and `value2`.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    30
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    31
=== <tt>bor(value1, value2)</tt> ===
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    32
Returns the bitwise logical OR of `value1` and `value2`.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    33
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    34
=== <tt>bnot(value)</tt> ===
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    35
Returns the bitwise logical NOT of `value`.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    36
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    37
== Debugging functions ==
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    38
=== <tt>WriteLnToConsole(string)</tt> ===
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    39
Writes `string` to `Logs/game0.log`, found in the user data directory.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    40
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    41
=== <tt>WriteLnToChat(string)</tt> (0.9.24) ===
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    42
Writes `string` into the chat.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    43
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    44
=== <tt>DumpPoint(x, y)</tt> (0.9.23) ===
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    45
Converts the whole numbers `x` and `y` to strings and writes them to `Logs/game0.log`, one line each.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    46
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    47
=== <tt>StartGhostPoints(count)</tt> ===
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    48
Just prints out “GHOST_POINTS” and the argument on the console. This function might change in later versions.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    49
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    50
=== <tt>DeclareAchievement(id, teamname, location, value)</tt> ===
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    51
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.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    52
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    53
Currently, this actually just triggers a console output, but it might be changed later. The idea is to track multiplayer records.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    54
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    55
Example:
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    56
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    57
<code language="lua">DeclareAchievement("height reached", teamname, "ClimbHome", -score)</code>
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    58
Records a team's best height in !ClimbHome.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    59
1805
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    60
=== <tt>!ParseCommand(string)</tt> ===
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    61
Makes the game client parse and execute the specified internal game engine command.
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    62
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    63
The available commands depend on the current engine protocol version. The *engine protocol can (and will) change* between releases.
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    64
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    65
*Important*: If you use `ParseCommand` to overcome a shortcoming in our Lua API (e.g. a missing function), please make sure to [https://issues.hedgewars.org/enter_bug.cgi report the issue].
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    66
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    67
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!
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    68
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    69
There are many available commands, but actual use in scripting is rare, and even then it's discouraged for long-term use. As of 0.9.24, the only command used in official scripts is:
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    70
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    71
 * `"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]
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    72
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    73
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.
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    74
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    75
=== <tt>!EndLuaTest(success)</tt> ===
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    76
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.
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    77
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    78
Calling this function ends an engine test and reports a test result.
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    79
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    80
`success` is either one of `TEST_SUCCESSFUL` to report a successful test or `TEST_FAILED` for a failed test.
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    81
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    82
See [EngineTestCases] to learn more about testing the engine.
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1801
diff changeset
    83
1749
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    84
== Library functions ==
1811
9e4f2d65879e LuaUtil: fix bg
Wuzzy
parents: 1805
diff changeset
    85
For more utility functions, you might want to check out the [LuaLibraries Lua libraries].