LuaGameplay.wiki
author Wuzzy
Wed, 21 Jun 2023 12:50:32 +0000
changeset 2242 031a5b86e533
parent 2232 09bf7a4d5411
child 2254 6f6f15fb33d5
permissions -rw-r--r--
LuaLibraryAnimate: Say what happens after animation ends
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 gameplay-related functions in the Lua API
1840
37d979124fc4 LuaGameplay: Add label
Wuzzy
parents: 1819
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: Gameplay functions =
2088
a08ac623b597 LuaGameplay: add newline
Wuzzy
parents: 2077
diff changeset
     5
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
     6
This page is a list of all gameplay-related functions in the [LuaAPI Lua API].
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
     7
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
     8
<wiki:toc max_depth="3" />
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
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    10
== `GameFlags` functions ==
1794
7b07726d12f3 LuaGameplay: LuaEvents
Wuzzy
parents: 1779
diff changeset
    11
`GameFlags` are boolean settings of the game. You should call these functions only in the `onGameInit` [LuaEvents event]. See [LuaGlobals#GameFlags].
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    12
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    13
=== <tt>!ClearGameFlags()</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
    14
Disables *all* !GameFlags.
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
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    16
=== <tt>!DisableGameFlags(gameflag, ...)</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
    17
Disables the listed !GameFlags, without changing the status of other !GameFlags.
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
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    19
=== <tt>!EnableGameFlags(gameflag, ...)</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
    20
Enables the listed !GameFlags, without changing the status of other !GameFlags. In missions, no !GameFlags are set initially.
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
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    22
=== <tt>!GetGameFlag(gameflag)</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
    23
Returns `true` if the specified gameflag is enabled, otherwise `false`.
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
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    25
== Turns ==
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
    26
=== <tt>SkipTurn()</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
    27
Forces the current hedgehog to skip its turn.
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
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
    29
=== `EndTurn([noTaunts])` ===
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
    30
Ends the current turn immediately.
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
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
Normally, a “Coward” taunt may be played and an announcer message may be shown (depending on the situation). Set the optional `noTaunts` parameter to `true` to force the engine to never play a taunt or show a message. `noTaunts` is `false` by default.
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
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
    34
=== <tt>Retreat(time [, respectGetAwayTimeFactor)</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
    35
Forces the current turn into the retreating phase, as if the hog made an attack. That is, the current hedgehog is unable to attack or select a weapon, only movement is possible until the retreat time is up.
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
The retreat time must be set with `time` in milliseconds. By default, this time is automatically multiplied with get-away time percentage from the game scheme for seamless integration with schemes. If you want to ignore the game scheme for some reason and set the retreat time no matter what, set `respectGetAwayTimeFactor` to `false`.
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
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
If the current hedgehog was busy doing an attack, the attack is aborted, no shot is made. If this function is called in the ready phase of a turn, the ready phase continues normally, but the turn will begin in the retreat phase instead.
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
Note: If you want the turn to end instantly, it is recommended to use `EndTurn` instead.
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
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
    43
=== <tt>!SetTurnTimeLeft(newTurnTimeLeft)</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
    44
Set the remaining turn time in milliseconds. The current remaining turn time can be read from the variable `TurnTimeLeft`.
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
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
    46
=== <tt>!SetReadyTimeLeft(newReadyTimeLeft)</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
    47
Set the remaining ready time in milliseconds. This function should only be called in onNewTurn. The current remaining ready time can be read from the variable `ReadyTimeLeft`.
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
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
    49
=== <tt>!SetTurnTimePaused(isPaused)</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
    50
Pauses the turn time indefinitely if `isPaused` is set to `true`, disabled the turn time pause if `isPaused` is set to `false`.
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
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
    52
=== <tt>!GetTurnTimePaused()</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
    53
Returns `true` if the turn time is currently paused by `SetTurnTimePaused`, otherwise returns `false`.
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
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    55
=== <tt>!EndGame()</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
    56
Makes the game end.
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
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    58
== Environment ==
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    59
=== <tt>!SetGravity(percent)</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
    60
Changes the current gravity of the game in percent (relative to default, integer 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
    61
Setting it to 100 will set gravity to default gravity of Hedgewars, 200 will double it, etc.
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
    62
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    63
=== <tt>!GetGravity()</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
    64
Returns the current gravity in percent.
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
    65
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    66
=== <tt>!SetWaterLine(waterline)</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
    67
Sets the water level (`WaterLine`) to the specified y-coordinate.
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
    68
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    69
=== <tt>!SetWind(windSpeed)</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
    70
Sets the current wind in the range of -100 to 100 inclusive. Use together with `gfDisableWind` for full control.
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
    71
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
    72
=== <tt>!GetWind()</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
    73
Returns current wind, expressed as a floating point number between -100 to 100 inclusive. Note there may be rounding errors.
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
    74
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    75
=== <tt>!SetMaxBuildDistance(distInPx)</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
    76
Sets the maximum building distance for of girders and rubber bands in pixels to `distInPx`. If `distInPx` is `0`, the limit is disabled. If called without arguments, the distance will be reset to the default 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
    77
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
    78
=== <tt>Explode(x, y, radius[, options])</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
    79
Cause an explosion or erase land, push or damage gears.
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
    80
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
    81
By default, an explosion destroys a circular piece of land and damages and pushes gears in its radius.
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
    82
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
    83
The explosion occurs at coordinates `(x, y)` with the given `radius`. Assuming 100% damage, the explosion damage at the center equals the explosion radius.
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
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
    85
The explosion will also have a visual effect (by spawning an explosion visual gear), unless the radius is very small.
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
    86
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
    87
`options` is a bitmask which can be used to tweak how the explosion behaves:
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
    88
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
    89
|| *Flag* || *Meaning* ||
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
    90
|| `EXPLAutoSound` || Plays an appropriate sound ||
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
    91
|| `EXPLNoDamage` || Deal no damage to gears ||
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
    92
|| `EXPLDoNotTouchHH` || Do not push hedgehogs ||
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
    93
|| `EXPLDoNotTouchAny` || Do not push any gears ||
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
    94
|| `EXPLDontDraw` || Do not destroy land ||
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
    95
|| `EXPLForceDraw` || Destroy land, even if `gfSolidLand` is active ||
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
    96
|| `EXPLNoGfx` || Do not show an explosion animation and do not shake the screen ||
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
    97
|| `EXPLPoisoned` || Poison all hedgehogs in explosion radius ||
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
    98
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
    99
`options` is assumed to be `EXPLAutoSound` by default. Set `options` to 0 to disable all flags.
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
   100
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
   101
Examples:
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
   102
<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
   103
-- Simple explosion at (100, 50) with radius 50
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
   104
Explode(100, 50, 50)
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
   105
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
   106
-- Simple explosion without sound
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
   107
Explode(100, 50, 50, 0)
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
   108
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
   109
-- Fake explosion which only pushes gears but deals no damage to gears and terrain
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
   110
Explode(500, 1000, 50, EXPLAutoSound + EXPLNoDamage + EXPLDontDraw)
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
   111
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
   112
-- Erase a circle of land without side effects
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
   113
Explode(500, 100, 100, EXPLNoDamage + EXPLDoNotTouchAny + EXPLNoGfx)
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
   114
</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
   115
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   116
== Ammo ==
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   117
=== <tt>!SetAmmo(ammoType, count, probability, delay, numberInCrate)</tt> ===
1797
e8c8ffe6e22b LuaGameplay: for links to LuaEvents
Wuzzy
parents: 1796
diff changeset
   118
This updates the settings (initial ammo, crate probability, etc.) for a specified [AmmoTypes ammo type]. This must only be used in the `onAmmoStoreInit()` [LuaEvents event handler]. In other places, this function will not work.
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
   119
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
   120
In Lua missions, for *all* ammo types, the ammo count, probability, delay and number in crates is set to 0 initially. Note: This also includes skip!
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
   121
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
   122
Parameters:
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
   123
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
   124
 * `ammoType`: Ammo type to be set
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
   125
 * `count`: Initial ammo count. 9 = infinite
2188
a6f98b1311f6 LuaGameplay: Max ammo crate probability is 8, not 9
Wuzzy
parents: 2106
diff changeset
   126
 * `probability`: Crate probability. Value between 0 (never) and 8 (highest probability)
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
   127
 * `delay`: Number of rounds this ammo is delayed
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
   128
 * `numberInCrate`: Amount of ammo in a crate
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
   129
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
   130
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
   131
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
   132
<code language="lua">    SetAmmo(amShotgun, 9, 0, 0, 0) -- unlimited amount of shotgun ammo for players
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
   133
    SetAmmo(amGrenade, 0, 0, 0, 3) -- crates should contain always three grenade
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
   134
    SetAmmo(amSkip, 9, 0, 0, 0) -- enable skip</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
   135
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
   136
Hint: It is recommended to always enable skip in missions. Only in exceptional circumstances you should choose to not enable skip.
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
   137
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   138
=== <tt>!GetAmmo(ammoType)</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
   139
Returns ammo settings (initial ammo, crate probability, etc.) for a specified [AmmoTypes ammo type]. This function is analogue to `SetAmmo`.
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
   140
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
   141
This function returns four numbers, in this order: initial ammo count, probability, delay and number in crate. These values correspond to the parameters 2-5 provided in `SetAmmo` and have the same meaning.
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
   142
1974
3a573bba359e LuaGameplay: Mention special case of delay >= 10000
Wuzzy
parents: 1971
diff changeset
   143
The `delay` has a special case. If `delay` is 10000 or greater, then this means you're in the hedgehog placement phase. To get the “true” delay (after the placement phase is over), you must subtract 10000 from this value.
3a573bba359e LuaGameplay: Mention special case of delay >= 10000
Wuzzy
parents: 1971
diff changeset
   144
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
   145
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
   146
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
   147
<code language="lua">count, prob, delay, numberInCrate = GetAmmo(amGrenade) -- Get ammo settings of amGrenade</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
   148
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   149
=== <tt>!SetAmmoDelay(ammoType, delay)</tt> ===
1907
806491e9ef60 LuaGameplay: Delay of 9999
Wuzzy
parents: 1906
diff changeset
   150
Changes the delay of a specified [AmmoTypes Ammo Type]. If `delay` is set to `9999`, the ammo type is disabled indefinitely.
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
   151
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
   152
=== <tt>!SetAmmoTexts(ammoType, name, caption, description [, showExtra])</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
   153
Allows you to overwrite the displayed name and tooltip descriptions of a given ammo type. This function must only be called either inside the `onGameStart` callback function, or after the engine has called `onGameStart`.
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
   154
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
   155
 * `ammoType`: The ammo type to set the text for
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
   156
 * `name`: Name of the ammo type (e.g. “Grenade” for `amGrenade`), affects both name in ammo menu and in the “ticker” message on the screen top.
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
   157
 * `caption`: The second line in the ammo menu (below the title). E.g. “Timed grenade” for `amGrenade`.
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
   158
 * `description`: Description text in ammo menu, below the caption.
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
   159
 * `showExtra`: If `false` the special “extra” text line like “Weapon is not yet available” or “Weapon does not end turn” will be suppressed
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
   160
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
   161
`title`, `caption`, `description` can be `nil`, in which case they will be reverted to the engine default value. This function returns `nil`.
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
   162
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
   163
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
   164
<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
   165
-- Overwrites bazooka name and description
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
   166
SetAmmoTexts(amBazooka, "Spoon Missile", "Crazy weapon", "This crazy weapon looks like a spoon and explodes on impact.|Attack: Hold to launch with more power")</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
   167
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
   168
=== <tt>!SetAmmoDescriptionAppendix(ammoType, descAppend)</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
   169
Will set a string `descAppend` to be appended below the “core” description (ammo tooltip) of the specified `ammoType`, without changing the ordinary description.
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
   170
Note that calling this function always sets the complete appended string, you can't use this function to append multiple texts in row.
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
   171
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
   172
This function is recommended if you have tweaked an existing ammo type only a little and want to keep the original description intact as much as possible.
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
   173
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
   174
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
   175
<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
   176
-- Appends a text to the ammo tooltip of the bazooka but leaves name and main description intact
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
   177
SetAmmoTexts(amBazooka, "This weapon deals double the damage than usually.")</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
   178
1970
c85f6f3bb16c LuaGameplay: Make it clear that AddAmmo can add or set ammo
Wuzzy
parents: 1952
diff changeset
   179
=== <tt>!AddAmmo(gearUid, ammoType [, ammoCount])</tt> ===
c85f6f3bb16c LuaGameplay: Make it clear that AddAmmo can add or set ammo
Wuzzy
parents: 1952
diff changeset
   180
Adds or sets the amount of ammo to the specified hedgehog gear.
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
   181
1971
210ad26e9e94 LuaGameplay: Fix misleading AddAmmo help
Wuzzy
parents: 1970
diff changeset
   182
If `ammoCount` is `nil`, then X ammos of the type `ammoType` will be added to `gearUid`, where X equals the “number in crate” setting of the weapon scheme, or, if `onAmmoStoreInit()` is used, X equals the `numberInCrate` argument passed via `SetAmmo()` in the `onAmmoStoreInit()` [LuaEvents event handler]. Note that if you use `onAmmoStoreInit()`, `numberInCrate` defaults to 0 if `SetAmmo()` was not called for the ammo type before.
1970
c85f6f3bb16c LuaGameplay: Make it clear that AddAmmo can add or set ammo
Wuzzy
parents: 1952
diff changeset
   183
c85f6f3bb16c LuaGameplay: Make it clear that AddAmmo can add or set ammo
Wuzzy
parents: 1952
diff changeset
   184
If `ammoCount` is a number, the ammo will *not* be added, but instead set to `ammoCount`. A value of `0` will remove the ammo, a value of `AMMO_INFINITE` will set it to infinite.
c85f6f3bb16c LuaGameplay: Make it clear that AddAmmo can add or set ammo
Wuzzy
parents: 1952
diff changeset
   185
c85f6f3bb16c LuaGameplay: Make it clear that AddAmmo can add or set ammo
Wuzzy
parents: 1952
diff changeset
   186
Note: By default, ammo is per-team, so calling `AddAmmo` for a hedgehog will add/set the ammo for the whole team. The game flags `gfPerHogAmmo` and `gfSharedAmmo` change how ammo is managed in the game, so these game flags also affect `AddAmmo`.
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
   187
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
   188
=== <tt>!GetAmmoName(ammoType [, ignoreOverwrite ])</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
   189
Returns the localized name for the specified `ammoType`, taking an ammo name overwritten by `SetAmmoTexts` into account. If `ignoreOverwrite` is `true`, this function will always return the original ammo name of the weapon and ignores names which may have been overwritten by `SetAmmoTexts`.
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
   190
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
   191
=== <tt>!SetAmmoSlot(ammoType, slot)</tt> ===
1940
37a2cc377a4f LuaGameplay: Add SetAmmoSlot
Wuzzy
parents: 1938
diff changeset
   192
Sets the slot number of `ammoType` to the given `slot` (counting starts from 1).
37a2cc377a4f LuaGameplay: Add SetAmmoSlot
Wuzzy
parents: 1938
diff changeset
   193
37a2cc377a4f LuaGameplay: Add SetAmmoSlot
Wuzzy
parents: 1938
diff changeset
   194
Use with care! It is your responsibility that each ammo slot does not hold more weapons than the maximum ammo menu width, otherwise, crashes are possible. Test with a full ammo menu to be sure.
37a2cc377a4f LuaGameplay: Add SetAmmoSlot
Wuzzy
parents: 1938
diff changeset
   195
37a2cc377a4f LuaGameplay: Add SetAmmoSlot
Wuzzy
parents: 1938
diff changeset
   196
Use this function only if you absolutely must! For usability reasons and to help the player's muscle memory, we should normally not re-arrange the weapons. This function was actually only created for the “Frenzy” game style in which we needed to re-arrange the ammo slots to give each weapon an unique ammo slot.
37a2cc377a4f LuaGameplay: Add SetAmmoSlot
Wuzzy
parents: 1938
diff changeset
   197
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   198
== Map ==
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   199
=== <tt>!MapHasBorder()</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
   200
Returns `true`/`false` if the map has a border or not.
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
   201
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   202
=== <tt>!TestRectForObstacle(x1, y1, x2, y2, landOnly)</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
   203
Checks the rectangle between the given coordinates for possible collisions. Set `landOnly` to `true` if you don’t want to check for collisions with gears (hedgehogs, etc.).
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
   204
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   205
=== <tt>!PlaceGirder(x, y, frameIdx)</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
   206
Attempts to place a girder with centre points `x`, `y` and a certain length and orientation, specified by `frameIdx`. The girder can only be placed in open space and must not collide with anything so this function may fail. It will return `true` on successful placement and `false` on failure.
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
   207
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
   208
These are the accepted values for `frameIdx`:
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
   209
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
   210
|| *`frameIdx`* || *Length* || *Orientation* ||
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
   211
|| 0 || short || horizontal ||
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
   212
|| 1 || short || decreasing right ||
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
   213
|| 2 || short || vertical ||
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
   214
|| 3 || short || increasing right ||
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
   215
|| 4 || long || horizontal ||
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
   216
|| 5 || long || decreasing right ||
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
   217
|| 6 || long || vertical ||
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
   218
|| 7 || long || increasing right ||
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
   219
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
   220
=== <tt>!PlaceRubber(x, y, frameIdx)</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
   221
Attempts to place a rubber with centre points `x`, `y` and a certain orientation, specified by `frameIdx`. The rubber can only be placed in open space and must not collide with anything so this function may fail. It will return `true` on successful placement and `false` on failure.
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
   222
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
   223
These are the accepted values for `frameIdx`:
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
   224
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
   225
|| *`frameIdx`* || *Orientation* ||
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
   226
|| 0 || horizontal ||
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
   227
|| 1 || decreasing right ||
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
   228
|| 2 || vertical ||
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
   229
|| 3 || increasing right ||
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
   230
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   231
=== <tt>!PlaceSprite(x, y, sprite, frameIdx, tint, behind, flipHoriz, flipVert, [, landFlag, ...])</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
   232
Places a [Sprites sprite] at the specified position (`x`, `y`) on the map, it behaves like terrain then. Unlike `PlaceGirder`, this function does not check for collisions, so the sprite can be placed anywhere within map boundaries. The function returns `true` if the placement was successful, `false` otherwise. `frameIdx` is the frame index starting by 0. `frameIdx` is used if the sprite consists of several sub-images. Only a subset of the sprites is currently supported by this function:
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
   233
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
   234
 * `sprAmGirder`
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
   235
 * `sprAmRubber`
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
   236
 * `sprAMSlot`
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
   237
 * `sprAMAmmos`
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
   238
 * `sprAMAmmosBW`
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
   239
 * `sprAMCorners`
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
   240
 * `sprHHTelepMask`
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
   241
 * `sprTurnsLeft`
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
   242
 * `sprSpeechCorner`
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
   243
 * `sprSpeechEdge`
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
   244
 * `sprSpeechTail`
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
   245
 * `sprTargetBee`
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
   246
 * `sprThoughtCorner`
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
   247
 * `sprThoughtEdge`
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
   248
 * `sprThoughtTail`
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
   249
 * `sprShoutCorner`
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
   250
 * `sprShoutEdge`
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
   251
 * `sprShoutTail`
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
   252
 * `sprBotlevels`
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
   253
 * `sprIceTexture`
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
   254
 * `sprCustom1`
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
   255
 * `sprCustom2`
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
   256
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
   257
`tint` is for an RGBA colouring to apply, this works about the same as `Tint` in gears. If `nil`, the original color is used.
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
   258
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
   259
`behind` indicates the sprite should not replace existing land.
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
   260
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
   261
`flipHoriz` and `flipVert` are for mirroring the sprite vertically and horizontally before placing, respectively.
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
   262
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
   263
The 9th and later arguments specify land flags (see the constants section) to be used for the newly created terrain. If omitted, `lfNormal` is assumed.
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
   264
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
   265
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
   266
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
   267
<code language="lua">PlaceSprite(2836, 634, sprAmGirder, 5)
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
   268
-- Places the girder sprite as normal terrain at (2836, 634). The `frameIdx` 5 is for the long decreasing right girder.</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
   269
<code language="lua">PlaceSprite(1411, 625, sprAmRubber, 1, nil, nil, nil, nil, lfBouncy)
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
   270
-- Places the rubber band sprite as bouncy terrain at (2836, 634). The `frameIdx` 1 is for the decreasing right rubber band.</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
   271
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   272
=== <tt>!EraseSprite(x, y, sprite, frameIdx, eraseOnLFMatch, onlyEraseLF, flipHoriz, flipVert, [, landFlag, ...])</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
   273
Erases a [Sprites sprite] at the specified position (`x`, `y`) on the map. `frameIdx` is the frame index starting by 0. `sprite`, `frameIdx`, `flipHoriz` and `flipVert` behave the same as in `PlaceSprite`. For `sprite`, the same subset of sprites is permitted.
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
   274
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
   275
Set `eraseOnLFMatch` to `true` to erase all land for a pixel that matches any of the passed in land flags.  This is useful if, for example, an `lfBouncy` sprite was placed “behind” land using `PlaceSprite` and you want to remove it without destroying the non-bouncy terrain.
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
   276
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
   277
Set `onlyEraseLF` to `true` to only remove specific land flags. If for example a sprite consists of `lfIndestructible` and `lfBouncy`, and you call `EraseSprite` with `onlyEraseLF` and `lfIndestructible` set, the sprite will remain bouncy but can be destroyed.  You can use this to entirely remove all land flags from a sprite—at this point the sprite will be visual only, painted on the map but with no collision.
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
   278
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
   279
Examples:
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
   280
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
   281
<code language="lua">EraseSprite(2836, 634, sprAmGirder, 5)
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
   282
-- Removes the girder sprite at (2836, 634). The frameIdx 5 is for the long decreasing right girder.</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
   283
<code language="lua">EraseSprite(1411, 625, sprAmRubber, 1, true, true, nil, nil, lfIndestructible)
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
   284
-- Removes indestructibility from a rubber band sprite at (2836, 634). The frameIdx 1 is for the decreasing right rubber band.</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
   285
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   286
=== <tt>!AddPoint(x, y [, width [, erase] ])</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
   287
This function is used to draw your own maps using Lua. The maps drawn with this are of type “hand-drawn”.
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
   288
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
   289
The function takes a `x`,`y` location, a `width` (means start of a new line) and `erase` (if `false`, this function will draw normally, if `true`, this function will erase drawn stuff).
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
   290
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
   291
This function must be called within `onGameInit`, where `MapGen` has been set to `mgDrawn`. You also should call `FlushPoints` when you are finished with drawing.
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
   292
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
   293
See [LuaDrawning] for some examples.
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
   294
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   295
=== <tt>!FlushPoints()</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
   296
Makes sure that all the points/lines specified using `AddPoint` are actually applied to the map. This function must be called within `onGameInit`.
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
   297
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   298
== Current hedgehog ==
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
   299
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   300
=== <tt>!GetCurAmmoType()</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
   301
Returns the currently selected [AmmoTypes Ammo Type].
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
   302
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   303
=== <tt>!SwitchHog(gearUid)</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
   304
This function will switch to the hedgehog with the specifiedd `gearUid`.
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
   305
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   306
=== <tt>!SetWeapon(ammoType)</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
   307
Sets the selected weapon of `CurrentHedgehog` to one of the [AmmoTypes Ammo Type].
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
   308
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
   309
Examples:
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
   310
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
   311
<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
   312
  SetWeapon(amBazooka) -- select the bazooka (if hog has one)
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
   313
</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
   314
<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
   315
  SetWeapon(amNothing) -- unselects the weapon.
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
   316
</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
   317
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   318
=== <tt>!SetNextWeapon()</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
   319
This function makes the current hedgehog switch to the next weapon in list of available weapons. It can be used for example in trainings to pre-select a weapon.
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
   320
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   321
=== <tt>!SetInputMask(mask)</tt> ===
1796
8b10d405a1a0 LuaGameplay: Clarify controls input functions
Wuzzy
parents: 1794
diff changeset
   322
Masks specified player input. `mask` is a gear message bitmask (see [GearMessages]). This means that Hedgewars ignores certain player inputs, such as walking or jumping. However, the controls [LuaEvents event functions] such as `onAttack` or `onLeft` will still be called, even when masked.
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
   323
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
   324
Example: 
1796
8b10d405a1a0 LuaGameplay: Clarify controls input functions
Wuzzy
parents: 1794
diff changeset
   325
<code language="lua">    -- masks the long and high jump commands, making it impossible to jump
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
   326
SetInputMask(band(0xFFFFFFFF, bnot(gmLJump + gmHJump))) 
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
   327
    -- clears input mask, allowing player to take actions
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
   328
    SetInputMask(0xFFFFFFFF) 
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
   329
		</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
   330
*Note*: Using the input mask is an effective way to script uninterrupted cinematics, or create modes such as No Jumping.
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
   331
2104
c5600e75b33c LuaGameplay: Mention AnimSetInputMask
Wuzzy
parents: 2088
diff changeset
   332
*Note*: If you use the [LuaLibraryAnimate Animate library], you should not call `SetInputMask` directly and use `AnimSetInputMask` from the library instead. This is because the Animate library uses `SetInputMask` internally.
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
   333
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
   334
See also [GearMessages].
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
   335
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   336
=== <tt>!GetInputMask()</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
   337
Returns the current input mask of the player.
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
   338
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
   339
=== <tt>!SetVampiric(bool)</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
   340
Toggles vampirism mode for this turn. Set `bool` to `true` to enable (same effect as if the hedgehog has used Vampirism), `false` to disable.
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
   341
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
   342
=== <tt>!GetVampiric()</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
   343
Returns true if vampirism mode is currently active.
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
   344
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
   345
=== <tt>!SetLaserSight(bool)</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
   346
Toggles laser sight for this turn. Set `bool` to `true` to enable (same effect as if the hedgehog has used Laser Sight), `false` to disable.
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
   347
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
   348
=== <tt>!GetLaserSight()</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
   349
Returns true if laser sight (as utility) is currently active. The sniper rifle's built-in laser sight does not count.
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
   350
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
   351
=== <tt>!EnableSwitchHog()</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
   352
Enable hog switching mode for the current hedgehog. This function should be called while the hedgehog is standing on solid ground (`GetFlightTime` returns 0).
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
   353
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
   354
Internally, this tries to spawn a `gtSwitcher` gear which, as long it exists, handles the hog switching. You can delete this gear to stop the hog switching prematurely. If there already is a `gtSwitcher` gear, no additional gear is spawned.
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
   355
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
   356
On success, returns the `gtSwitcher` gear being spawned or, if hog switching mode is already active, returns the exsting gear. On failure, returns `nil`.
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
   357
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   358
== Clans and teams ==
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   359
=== <tt>!AddTeam(teamname, color, grave, fort, voicepack, flag)</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
   360
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
   361
Adds a new team.
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
   362
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
   363
You *must* call it only in `onGameInit`.
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
   364
You *must* add at least one hedgehog with `AddHog` after calling this. The engine does not support empty teams.
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
   365
`AddTeam` is only supported for singleplayer missions. You *must not* call this function in multiplayer.
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
   366
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
   367
Arguments:
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
   368
1917
962f362690be LuaGameplay: Return value of AddTeam / AddMissionTeam
Wuzzy
parents: 1907
diff changeset
   369
 * `teamname`: The name of the team (might be force-changed)
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
   370
 * `color`: Team color, usually a number from -9 to -1 (see below)
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
   371
 * `grave`: The name of the team’s grave (equals file name without the suffix)
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
   372
 * `fort`: The name of the team’s fort (equals file name without the suffix and without the letter “L” or “R” before that suffix)
1951
aaee22e79dd3 LuaGameplay: Fix _qau underscore (2)
Wuzzy
parents: 1950
diff changeset
   373
 * `voicepack`: The name of the team’s voice pack (equals the directory name). Since version 1.0.0, you can append “`_qau`” so Hedgewars will automatically pick the appropriate language version of the voicepack (e.g. instead of “Default”, use “`Default_qau`”). This is preferred.
1906
7891546b4ff8 LuaGameplay: Update `flag` argument description of AddTeam
Wuzzy
parents: 1840
diff changeset
   374
 * `flag`: Optional argument for the name of the team’s flag (equals the file name case-sensitively without the suffix). If set to `nil` or the flag can not be found on the local computer, the flag “hedgewars” is used.
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
   375
1917
962f362690be LuaGameplay: Return value of AddTeam / AddMissionTeam
Wuzzy
parents: 1907
diff changeset
   376
Since version 1.0.0, the team name might be force-changed in case of a naming collision. Since version 1.0.0, this function returns two values: `<real team name>, <team index>`. For functions that need the team name as input (lke `DismissTeam`), you must use this returned `<real team name>`.
962f362690be LuaGameplay: Return value of AddTeam / AddMissionTeam
Wuzzy
parents: 1907
diff changeset
   377
1778
4d4a119f1340 LuaGameplay: Fix clan color indent
Wuzzy
parents: 1777
diff changeset
   378
==== Clan color ====
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
   379
Each team must have a color. The color also determines clan membership: Teams with equal color are in the same clan.
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
   380
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
   381
The team color is specified as a number from -9 to -1. This will select one of the 9 possible team colors as specified in the player's settings. As the actual colors are set by the player, you can't predict them, but you can usually trust these defaults:
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
   382
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
   383
 * `-1`: red
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
   384
 * `-2`: blue
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
   385
 * `-3`: cyan
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
   386
 * `-4`: purple
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
   387
 * `-5`: magenta
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
   388
 * `-6`: green
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
   389
 * `-7`: orange
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
   390
 * `-8`: brown
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
   391
 * `-9`: yellow
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
   392
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
   393
An older (and now discouraged) method of specifying the color is by hardcoding it as an RGB color (i.e. `0xDD0000`). This practice is now strongly discouraged because it will ignore the player-chosen color (which is *bad* for players with color blindness) and in 99% of cases you don't need it anyway. It should be only used for testing and debugging. 
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
   394
1919
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   395
==== Voicepack language ====
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   396
[Voicepacks] can be localized. A localized voicepack has the language code in its name after an underscore, e.g. “Default_pl” is the Polish version of “Default”. If you specify the exact name in `voicepack`, Hedgewars uses this exact language version. But if you replace the language suffix with `_qau`, Hedgewars will try to pick the appropriate localized version of that voicepack, depending on the user's language, if a localized version exists. If not, Hedgewars will pick the version of the voicepack without a language suffix (which is English, normally).
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   397
1952
da4ee30e45f1 LuaGameplay: Remove a pointless backslash
Wuzzy
parents: 1951
diff changeset
   398
For example, if `voicepack` is set to “`Default_qau`”, Hedgewars will pick “Default_pl” if the user language is Polish. If the user language is set to a language for which there is no localize version of the Default voicepack, Hedgewars will pick the “Default” voicepack (which is in English).
1919
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   399
1951
aaee22e79dd3 LuaGameplay: Fix _qau underscore (2)
Wuzzy
parents: 1950
diff changeset
   400
We strongly recommend to always use the “`_qau`” suffix from version 1.0.0 on, unless you really want to force a particular language.
1919
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   401
1778
4d4a119f1340 LuaGameplay: Fix clan color indent
Wuzzy
parents: 1777
diff changeset
   402
==== Example ====
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
   403
1951
aaee22e79dd3 LuaGameplay: Fix _qau underscore (2)
Wuzzy
parents: 1950
diff changeset
   404
<code language="lua">AddTeam("team 1", -1, "Simple", "Tank", "Default_qau", "hedgewars")
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
   405
--[[ Adds a new team with name “team 1”, the first default color (usually red), the grave “Simple”,
1919
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   406
the fort “Tank” the voicepack “Default” (in the appropriate language version) and the flag “hedgewars”. ]]</code>
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
   407
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
   408
=== <tt>!AddMissionTeam(color)</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
   409
Adds a new team using the player-chosen team identity when playing a singleplayer mission. Does not work in multiplayer.
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
   410
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
   411
This function is very similar to `AddTeam`. Team settings like team name and flag will be taken from the player-chosen team.
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
   412
You only need to specify the clan color, which has the same meaning as in `AddTeam`.
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
   413
1942
b36285e8e3f5 LuaGameplay: Fix AddMissionTeam
Wuzzy
parents: 1940
diff changeset
   414
This function returns two values: `<team name>, <team index>`. For functions that need the team name as input (lke `DismissTeam`), you must use this returned `<team name>`.
1917
962f362690be LuaGameplay: Return value of AddTeam / AddMissionTeam
Wuzzy
parents: 1907
diff changeset
   415
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
   416
Use `AddMissionHog` or `AddHog` afterwards to add hedgehogs for this team. You can mix `AddMissionHog` and `AddHog` as you wish.
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
   417
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
   418
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
   419
<code language="lua">-- Add mission team with default clan color
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
   420
AddMissionTeam(-1)</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
   421
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
   422
=== <tt>!GetTeamName(teamIdx)</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
   423
Returns the name of the team with the index `teamIdx`. `teamIdx` is a number between 0 and `TeamsCount-1`.
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
   424
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
   425
=== <tt>!GetTeamIndex(teamname)</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
   426
Returns the team index (number between 0 and `TeamsCount-1`) of the team with the name `teamName`.
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
   427
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
   428
=== <tt>!GetTeamClan(teamname)</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
   429
Returns the clan ID of the team with the given `teamName`.
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
   430
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   431
=== <tt>!DismissTeam(teamname)</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
   432
Vaporizes all the hogs of the team with the given team name in a puff of smoke.
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
   433
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
   434
This function must not be called while it's the team's turn.
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
   435
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
   436
=== <tt>!SetTeamLabel(teamname[, label])</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
   437
Set or remove a label for the team with the given team name. The label is a string and will be displayed next to the team's health bar.
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
   438
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
   439
If `label` is `nil`, the label will be removed.
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
   440
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
   441
There's a special case: If the AI Survival game modifier is active, the AI kill counter will be replaced by the custom team label if it has been set. If `label` is set to `nil`, the default AI counter is shown again.
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
   442
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
   443
Use this to display a score, power value or another important team attribute. There's no hard length limit, but please try to keep it as short as possible to avoid visual clutter.
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
   444
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
   445
=== <tt>SetTeamPassive(teamname, isPassive)</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
   446
Mark a team as passive if `isPassive` is `true`. Passive teams do not participate in the game and are treated like frozen teams. When determining the team order, passive teams are completely ignored.
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
   447
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   448
=== <tt>!GetClanColor(clan)</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
   449
Returns the RGBA color of the chosen clan by its number. The color data type is described in [LuaOverview#Color].
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
   450
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   451
=== <tt>!SetClanColor(clan, color)</tt> ===
1918
6ba186f18a73 LuaGameplay: Update SetClanColor
Wuzzy
parents: 1917
diff changeset
   452
Sets the RGBA color of the chosen clan by its number. The color argument works the same as in `AddTeam`. The new clan color *must* be different from the color of all clans (you can't use this function to change clan memberships of teams).
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
   453
1983
1098683f138f LuaGameplay: clarify SetClanColor
Wuzzy
parents: 1974
diff changeset
   454
Note: The stats graph does not support clan colors that change in mid-game. If the clan colors change in mid-game, the graph might get confused and shows weird stuff. You may want to turn off the graph with if this is the case (see `SendHealthStatsOff`).
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
   455
2106
2835503f0144 LuaGameplay: rename campaign title
Wuzzy
parents: 2104
diff changeset
   456
== Campaign/mission management ==
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   457
=== <tt>!SaveCampaignVar(varname, value)</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
   458
Stores the value `value` (a string) into the campaign variable `varname` (also a string). Campaign variables allow you to save progress of a team in a certain campaign. Campaign variables are saved on a per-team per-campaign basis. They are written into the team file (see [ConfigurationFiles#TeamName.hwt]).
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
   459
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
   460
There are some special campaign variables which are used by Hedgewars to determine which missions to display in the campaign menu. This is described [ConfigurationFiles#%5BCampaign%20%3CCAMPAIGN_NAME%3E%5D here].
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
   461
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   462
=== <tt>!GetCampaignVar(varname)</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
   463
Returns the value of the campaign variable `varname` as a string. See also `SaveCampaignVar`.
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
   464
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
   465
=== <tt>!SaveMissionVar(varname, value)</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
   466
Stores the value `value` (a string) into the mission variable `varname` (also a string). A mission variable is like a campaign variable, but it applies for singleplayer missions only (Training/Challenge/Scenario), excluding campaign missions.
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
   467
2232
09bf7a4d5411 LuaGameplay: remove version numbers
Wuzzy
parents: 2188
diff changeset
   468
=== <tt>!GetMissionVar(varname)</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
   469
Returns the value of the mission variable `varname` as a string. See also `SaveMissionVar`.
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
   470
1779
9cb32a3519ee LuaGameplay: Move GetRandom to bottom
Wuzzy
parents: 1778
diff changeset
   471
== Randomness ==
9cb32a3519ee LuaGameplay: Move GetRandom to bottom
Wuzzy
parents: 1778
diff changeset
   472
=== <tt>!GetRandom(number)</tt> ===
2007
be514c1e3989 LuaGameplay: add paragraph in GetRandom
Wuzzy
parents: 2006
diff changeset
   473
Returns a randomly generated whole number in the range of `0` to `number - 1`. `number` must be a whole number >= 1. This random number uses the game seed, so is synchronised, and thus safe for multiplayer and saved games.
be514c1e3989 LuaGameplay: add paragraph in GetRandom
Wuzzy
parents: 2006
diff changeset
   474
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 2007
diff changeset
   475
Use `GetRandom` for anything that could impact the engine state. For example, a visual gear could simply use Lua’s `math.random`, but adding a regular gear should use `GetRandom`.