author | Wuzzy |
Thu, 14 Nov 2019 17:32:25 +0000 | |
changeset 2105 | 205fc7f87cf4 |
parent 2077 | 514babfbad9e |
child 2108 | 237737e5336c |
permissions | -rw-r--r-- |
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 | 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 | 7 |
<wiki:toc max_depth="3" /> |
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 |
|
2077
514babfbad9e
Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents:
1845
diff
changeset
|
41 |
=== <tt>WriteLnToChat(string)</tt> === |
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
|
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 |
|
2077
514babfbad9e
Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents:
1845
diff
changeset
|
44 |
=== <tt>DumpPoint(x, y)</tt> === |
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
|
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 |
|
2077
514babfbad9e
Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents:
1845
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. The only command used in official scripts is: |
1805
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 == |
2077
514babfbad9e
Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents:
1845
diff
changeset
|
85 |
For more utility functions, you might want to check out the [LuaLibraries Lua libraries]. |