LuaLibraryUtils.wiki
author Wuzzy
Fri, 12 May 2023 14:37:17 +0000
changeset 2223 4e49d93377fd
parent 1830 e562fccced8e
child 2261 55bd0ae9d187
permissions -rw-r--r--
LuaEvents: Rewrite onNewAmmoStore help
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1373
2eedf1c53951 LuaLibraryUtils: Edited via web interface
Wuzzy
parents: 1359
diff changeset
     1
#summary Lua library documentation of Utils; contains assorted helper functions
1345
673321313201 LuaLibraryUtils: labels
Wuzzy
parents: 1336
diff changeset
     2
#labels !LuaLibrary
1331
fef74f26cab9 LuaLibraryUtils: headings
Wuzzy
parents: 1329
diff changeset
     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
fef74f26cab9 LuaLibraryUtils: headings
Wuzzy
parents: 1329
diff changeset
     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
fef74f26cab9 LuaLibraryUtils: headings
Wuzzy
parents: 1329
diff changeset
    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
a09a11ea67b4 LuaLibraryUtils: add fillMap and eraseMap
Wuzzy
parents: 1345
diff changeset
    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.
a09a11ea67b4 LuaLibraryUtils: add fillMap and eraseMap
Wuzzy
parents: 1345
diff changeset
    15
1394
607ff7beea3d LuaLibraryUtils: optional flush
Wuzzy
parents: 1373
diff changeset
    16
== `fillMap([flush])` ==
1358
a09a11ea67b4 LuaLibraryUtils: add fillMap and eraseMap
Wuzzy
parents: 1345
diff changeset
    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`.
a09a11ea67b4 LuaLibraryUtils: add fillMap and eraseMap
Wuzzy
parents: 1345
diff changeset
    18
1394
607ff7beea3d LuaLibraryUtils: optional flush
Wuzzy
parents: 1373
diff changeset
    19
== `eraseMap([flush])` ==
1651
c1a5d8894bd0 LuaLibraryUtils: Add U_LAND_TINT_*
Wuzzy
parents: 1394
diff changeset
    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`.
c1a5d8894bd0 LuaLibraryUtils: Add U_LAND_TINT_*
Wuzzy
parents: 1394
diff changeset
    21
1826
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    22
== `updateChallengeRecord(recordType, value[, stat])` (1.0.0) ==
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    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.
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    24
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    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.
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    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
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    32
 * `value`: Value that has been achieved by the team
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    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.
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    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
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    41
== `getReadableChallengeRecord(recordType)` (1.0.0) ==
1829
d92951dbb8b6 LuaLibraryUtils: Make links readable
Wuzzy
parents: 1828
diff changeset
    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
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    43
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    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.
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    45
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    46
For example, for `"TimeRecord"`, the returned string is something like `"Team's best time: 14.340s"`.
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    47
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    48
Example:
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    49
<code lang="lua">
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    50
ShowMission("MegaRace", "Race Challenge", "Try to finish the race as fast you can!\n" .. getReadableChallengeRecord("TimeRecord"))
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    51
-- Shows the mission panel and the current time record.
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    52
</code>
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    53
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    54
== `integerSqrt(num)` (1.0.0) ==
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    55
Calculates the square root of `num`, but rounded to an integer. This function is desync-safe.
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    56
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    57
== `integerHypotenuse(x, y)` (1.0.0) ==
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    58
Calculates the hypotenuse of a triangle with legs x, y, but rounded to an integer. This function is desync-safe.
24b348e89a57 LuaLibraryUtils: Add four upcoming 1.0.0 functions
Wuzzy
parents: 1652
diff changeset
    59
1651
c1a5d8894bd0 LuaLibraryUtils: Add U_LAND_TINT_*
Wuzzy
parents: 1394
diff changeset
    60
== Standardized land tint colors ==
c1a5d8894bd0 LuaLibraryUtils: Add U_LAND_TINT_*
Wuzzy
parents: 1394
diff changeset
    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:
c1a5d8894bd0 LuaLibraryUtils: Add U_LAND_TINT_*
Wuzzy
parents: 1394
diff changeset
    62
1652
ff0512443f75 LuaLibraryUtils: missing space added
Wuzzy
parents: 1651
diff changeset
    63
 * `U_LAND_TINT_NORMAL`: Normal land
ff0512443f75 LuaLibraryUtils: missing space added
Wuzzy
parents: 1651
diff changeset
    64
 * `U_LAND_TINT_ICE`: Icy land
ff0512443f75 LuaLibraryUtils: missing space added
Wuzzy
parents: 1651
diff changeset
    65
 * `U_LAND_TINT_INDESTRUCTIBLE`: Indestructible land
ff0512443f75 LuaLibraryUtils: missing space added
Wuzzy
parents: 1651
diff changeset
    66
 * `U_LAND_TINT_BOUNCY`: Bouncy land