author | Wuzzy |
Fri, 19 Apr 2019 16:07:50 +0100 | |
changeset 1831 | 365c30b4c669 |
parent 1830 | e562fccced8e |
child 2261 | 55bd0ae9d187 |
permissions | -rw-r--r-- |
1373 | 1 |
#summary Lua library documentation of Utils; contains assorted helper functions |
1345 | 2 |
#labels !LuaLibrary |
1331 | 3 |
= Lua library: `Utils` = |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
4 |
|
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
5 |
This library includes miscellaneous functions to use, they are all independent of each other and can be used everywhere. |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
6 |
|
1331 | 7 |
== `gearIsInBox(gear, x, y, w, h)` == |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
8 |
|
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
9 |
Returns whether the gear is inside (centre point of the gear) a box with x and y as the top left corner and having the width and height of w and h respectively. |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
10 |
|
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
11 |
|
1331 | 12 |
== `gearIsInCircle(gear, x, y, r, useRadius)` == |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
13 |
|
1358 | 14 |
Returns whether the gear is inside a circle with x and y being the centre point and r being the radius of the circle. The boolean useRadius determine whether only the centre point of the gear will be used or the radius of the gear will be checked too. |
15 |
||
1394 | 16 |
== `fillMap([flush])` == |
1358 | 17 |
Completely fill the current map with land. Requires `MapGen` to be set to `mgDrawn`. `FlushPoints()` will be called at the end, unless `flush` is set to `false`. |
18 |
||
1394 | 19 |
== `eraseMap([flush])` == |
1651 | 20 |
Completely erase all land from current map. Requires `MapGen` to be set to `mgDrawn`. `FlushPoints()` will be called at the end, unless `flush` is set to `false`. |
21 |
||
1826 | 22 |
== `updateChallengeRecord(recordType, value[, stat])` (1.0.0) == |
23 |
Report a new team record attempt in a [Missions mission] (preferably challenge missions). In missions, the team file of the mission team (see `AddMissionTeam` for more infos) can store several records (such as highscores) which will be shown in the frontend when the mission is selected. Note this only works for non-campaign missions so far. |
|
24 |
||
25 |
Calling this function means the team has made a record attempt of a given record type (e.g. fastest time or highscore) with a given `value`. If the team's own record has been beaten, or is has set the first record, the team file is being updated. |
|
26 |
||
1830
e562fccced8e
LuaLibraryUtils: Add example for updateChallengeRecord
Wuzzy
parents:
1829
diff
changeset
|
27 |
Usually you want to call this function at the end of a mission, when it has completed and the final score/time/whatever is known. |
e562fccced8e
LuaLibraryUtils: Add example for updateChallengeRecord
Wuzzy
parents:
1829
diff
changeset
|
28 |
|
e562fccced8e
LuaLibraryUtils: Add example for updateChallengeRecord
Wuzzy
parents:
1829
diff
changeset
|
29 |
Parameters: |
e562fccced8e
LuaLibraryUtils: Add example for updateChallengeRecord
Wuzzy
parents:
1829
diff
changeset
|
30 |
|
e562fccced8e
LuaLibraryUtils: Add example for updateChallengeRecord
Wuzzy
parents:
1829
diff
changeset
|
31 |
* `recordType`: Type of record (see [ConfigurationFiles#%5BMission%2520%3CMISSION_NAME%3E%5D here] for a list), as a string |
1826 | 32 |
* `value`: Value that has been achieved by the team |
33 |
* `stat`: If `true` (default), will also write a message in the stats screen (whether record has been beaten, or current record if not). Otherwise, this writes nothing. |
|
34 |
||
1830
e562fccced8e
LuaLibraryUtils: Add example for updateChallengeRecord
Wuzzy
parents:
1829
diff
changeset
|
35 |
Example: |
e562fccced8e
LuaLibraryUtils: Add example for updateChallengeRecord
Wuzzy
parents:
1829
diff
changeset
|
36 |
<code lang="lua"> |
e562fccced8e
LuaLibraryUtils: Add example for updateChallengeRecord
Wuzzy
parents:
1829
diff
changeset
|
37 |
-- Report a team score of 12000 to the game |
e562fccced8e
LuaLibraryUtils: Add example for updateChallengeRecord
Wuzzy
parents:
1829
diff
changeset
|
38 |
updateChallengeRecord("Highscore", 12000) |
e562fccced8e
LuaLibraryUtils: Add example for updateChallengeRecord
Wuzzy
parents:
1829
diff
changeset
|
39 |
</code> |
e562fccced8e
LuaLibraryUtils: Add example for updateChallengeRecord
Wuzzy
parents:
1829
diff
changeset
|
40 |
|
1826 | 41 |
== `getReadableChallengeRecord(recordType)` (1.0.0) == |
1829 | 42 |
Returns a human-readable description of a team record of the mission team (see also: `AddMissionTeam`) for the current challenge [Missions mission]. Team records are read from the team file. `recordType` is a record type. Possible record types are listed [ConfigurationFiles#%5BMission%2520%3CMISSION_NAME%3E%5D here]. This can be useful to display something in `ShowMission`. |
1826 | 43 |
|
44 |
If the team does not have a record for the given record type yet, the empty string is returned. If the record type is invalid, `nil` is returned. |
|
45 |
||
46 |
For example, for `"TimeRecord"`, the returned string is something like `"Team's best time: 14.340s"`. |
|
47 |
||
48 |
Example: |
|
49 |
<code lang="lua"> |
|
50 |
ShowMission("MegaRace", "Race Challenge", "Try to finish the race as fast you can!\n" .. getReadableChallengeRecord("TimeRecord")) |
|
51 |
-- Shows the mission panel and the current time record. |
|
52 |
</code> |
|
53 |
||
54 |
== `integerSqrt(num)` (1.0.0) == |
|
55 |
Calculates the square root of `num`, but rounded to an integer. This function is desync-safe. |
|
56 |
||
57 |
== `integerHypotenuse(x, y)` (1.0.0) == |
|
58 |
Calculates the hypotenuse of a triangle with legs x, y, but rounded to an integer. This function is desync-safe. |
|
59 |
||
1651 | 60 |
== Standardized land tint colors == |
61 |
There are some “standard” tint colors for placed girders and other sprites which are defined to allow more consistency, if it is desired. These values are used in !TechRacer, !HedgeEditor and the basic movement training to colorize girders consistently: |
|
62 |
||
1652 | 63 |
* `U_LAND_TINT_NORMAL`: Normal land |
64 |
* `U_LAND_TINT_ICE`: Icy land |
|
65 |
* `U_LAND_TINT_INDESTRUCTIBLE`: Indestructible land |
|
66 |
* `U_LAND_TINT_BOUNCY`: Bouncy land |